Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
39 changes: 39 additions & 0 deletions packages/harness/docs/assistant-history.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,39 @@
# Retained Assistant history

`GET /api/sessions/:id/assistant/record` returns `{ record: AssistantRecord }`
for the currently authorized Studio session and Assistant binding. Supply the
current boot token in `X-Harness-Token`. The server checks current Assistant
eligibility and workspace authority before and after reading. Listing or reading
a retained record does not start OpenCode, create a conversation, or submit work.

| Status | Meaning |
| ------ | -------------------------------------------------------------------------------- |
| 200 | The last successfully retained record, with `Cache-Control: no-store`. |
| 400 | The Studio session ID is invalid. |
| 401 | The boot token is missing or incorrect. |
| 403 | Assistant access, workspace authority, or the binding is unavailable or changed. |
| 404 | This authorized binding has no retained record or native association. |
| 503 | The record or its metadata could not be read or validated. |

The [record schema](../src/shared/assistant-record.ts) includes the exact Studio,
authority, workspace and native-conversation binding; a monotonic revision;
`capturedAt`; `reconstructed: true`; public turns/messages; original counts;
and explicit `limitations`. It is a bounded reconstruction, not native history,
a Resume credential, or a replay log. Available accepted-context references do
not contain their private instruction/source bodies.

Each serialized record is at most 64 KiB. Text fields retain at most 4,000
characters and tool input/output/error fields 512 each. Private reasoning and
instruction parts, attachment contents and unsupported parts are omitted or
marked. Size reduction can drop early turns or message content; counts can exceed
the retained excerpt. Incomplete turns and every omission/truncation remain
visible in the schema. A missing accepted-context reference does not prevent
reading otherwise available public history.

Capture runs under the host's existing observer independently of browser mounts.
Persisted message changes trigger at most one background capture start per second;
raw streamed text deltas do not trigger capture. Explicit acknowledgement,
lifecycle and idle checkpoints can flush immediately. Native reads are capped at
16 MiB and have a three-second timeout. Failure preserves the previous record,
so a successful GET can return an older `capturedAt`. Disposal and authority loss
cancel capture; opening a retained record never resumes execution.
38 changes: 38 additions & 0 deletions packages/harness/src/core/assistant-history-access.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -48,6 +48,44 @@ it("resolves the host's same stable binding without native IO and rechecks autho
store,
});
expect(await resolve("studio-a")).toEqual(saved);
authorize.mockImplementationOnce(async () => {
grant = {
...grant!,
expiresAt: Date.now() + 120000,
environment: { ...grant!.environment },
};
return workspace;
});
expect(await resolve("studio-a")).toEqual(saved);
for (const mutate of [
() => {
grant!.identityRevision = "two";
},
() => {
grant!.userId = "another-user";
},
() => {
grant!.environment.apiURL = "https://changed.example.test";
},
() => {
grant!.expiresAt = Date.now() - 1;
},
]) {
const original: AssistantGrant = {
...grant!,
environment: { ...grant!.environment },
};
authorize.mockImplementationOnce(async () => {
mutate();
return workspace;
});
await expect(resolve("studio-a")).rejects.toThrow("access changed");
grant = original;
}
authorize
.mockImplementationOnce(async () => workspace)
.mockImplementationOnce(async () => ({ ...workspace, cwd: tmpdir() }));
await expect(resolve("studio-a")).rejects.toThrow("access changed");
authorize.mockImplementationOnce(async () => {
grant = null;
return workspace;
Expand Down
24 changes: 19 additions & 5 deletions packages/harness/src/core/assistant-history-access.ts
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
import { realpath } from "node:fs/promises";
import type { AssistantAccess } from "./assistant-access.js";
import type { AssistantAccess, AssistantGrant } from "./assistant-access.js";
import {
contextAuthorityScope,
nativeAuthorityScope,
Expand All @@ -10,6 +10,18 @@ import {
} from "./opencode-host.js";
import type { AssistantSessionStore } from "./assistant-session-store.js";

const authority = (grant: AssistantGrant | null): string | null =>
!grant || grant.expiresAt <= Date.now()
? null
: JSON.stringify([
grant.userId,
grant.tenantId,
grant.identityRevision,
grant.environment.name,
grant.environment.apiURL,
grant.environment.credentials?.apiKey,
]);

/** Resolve the current authorized binding without launching or querying OpenCode. */
export function assistantHistoryAccess(options: {
access: Pick<AssistantAccess, "get">;
Expand All @@ -18,29 +30,31 @@ export function assistantHistoryAccess(options: {
}) {
return async (id: string) => {
const grant = options.access.get();
if (!grant)
const captured = authority(grant);
if (!grant || !captured)
throw new OpenCodeAccessError("Assistant access is unavailable");
const snapshot = { ...grant, environment: { ...grant.environment } };
const workspace = await options.authorize(id);
if (!workspace || workspace.harnessSessionId !== id)
throw new OpenCodeAccessError("Workspace unavailable");
const cwd = await realpath(workspace.cwd);
const key = {
harnessSessionId: id,
cwd,
contextAuthorityScope: contextAuthorityScope(grant, {
contextAuthorityScope: contextAuthorityScope(snapshot, {
harnessSessionId: id,
cwd,
}),
};
const binding = await options.store.associate(
key,
nativeAuthorityScope(grant, key),
nativeAuthorityScope(snapshot, key),
undefined,
);
const current = await options.authorize(id);
const currentCwd = current ? await realpath(current.cwd) : null;
if (
options.access.get() !== grant ||
authority(options.access.get()) !== captured ||
!current ||
current.harnessSessionId !== id ||
currentCwd !== cwd
Expand Down
30 changes: 28 additions & 2 deletions packages/harness/src/core/assistant-record-capture.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -52,10 +52,12 @@ beforeEach(async () => {
afterEach(async () => {
capture.dispose();
abort.abort();
vi.useRealTimers();
vi.restoreAllMocks();
await rm(root, { recursive: true, force: true });
});

it("coalesces arbitrarily many invalidations into one active read and one catch-up", async () => {
it("coalesces concurrent explicit checkpoints into one active read and one catch-up", async () => {
let release!: (value: Response) => void;
fetch.mockImplementationOnce(
() =>
Expand All @@ -65,7 +67,7 @@ it("coalesces arbitrarily many invalidations into one active read and one catch-
);
const first = capture.checkpoint();
await vi.waitFor(() => expect(fetch).toHaveBeenCalledTimes(1));
for (let i = 0; i < 100; i++) capture.invalidate();
for (let i = 0; i < 100; i++) expect(capture.checkpoint()).toBe(first);
expect(fetch).toHaveBeenCalledTimes(1);
release(Response.json(native("Earlier")));
await first;
Expand All @@ -75,6 +77,30 @@ it("coalesces arbitrarily many invalidations into one active read and one catch-
).toMatchObject({ text: "Latest" });
});

it("bounds sustained background capture and lets explicit checkpoints flush without a delayed duplicate", async () => {
vi.spyOn(store, "reserve").mockResolvedValue(1);
vi.spyOn(store, "read").mockResolvedValue(null);
const write = vi.spyOn(store, "write").mockResolvedValue(true);
vi.useFakeTimers({ toFake: ["setTimeout", "clearTimeout", "Date"] });
await capture.checkpoint();
for (let i = 0; i < 40; i++) {
capture.invalidate();
await vi.advanceTimersByTimeAsync(50);
}
expect(fetch).toHaveBeenCalledTimes(3);
expect(write).toHaveBeenCalledTimes(3);
capture.invalidate();
await capture.checkpoint();
expect(fetch).toHaveBeenCalledTimes(4);
await vi.advanceTimersByTimeAsync(1000);
expect(fetch).toHaveBeenCalledTimes(4);
capture.invalidate();
abort.abort();
await vi.advanceTimersByTimeAsync(1000);
expect(fetch).toHaveBeenCalledTimes(4);
expect(vi.getTimerCount()).toBe(0);
});

it("retains a previous checkpoint after native failure and refuses a late retired response", async () => {
await capture.checkpoint();
const previous = await store.read(binding);
Expand Down
29 changes: 27 additions & 2 deletions packages/harness/src/core/assistant-record-capture.ts
Original file line number Diff line number Diff line change
Expand Up @@ -55,6 +55,9 @@ export class AssistantRecordCapture {
private readonly lifetime = new AbortController();
private pending = false;
private running?: Promise<void>;
private invalidated = false;
private timer?: ReturnType<typeof setTimeout>;
private startedAt = 0;
private failed = false;
readonly binding: AssistantRecordBinding;
constructor(
Expand All @@ -77,20 +80,40 @@ export class AssistantRecordCapture {
return this.failed;
}
invalidate = (): void => {
void this.checkpoint();
if (!this.live()) return;
this.invalidated = true;
this.schedule();
};
private schedule(): void {
if (this.timer || this.running || !this.invalidated || !this.live()) return;
this.timer = setTimeout(
() => {
this.timer = undefined;
void this.checkpoint();
},
Math.max(0, this.startedAt + 1000 - Date.now()),
);
this.timer.unref?.();
}
/** Explicit lifecycle/acknowledgement/idle checkpoints bypass background throttling. */
checkpoint(): Promise<void> {
if (!this.live()) return Promise.resolve();
clearTimeout(this.timer);
this.timer = undefined;
this.pending = true;
if (!this.running)
this.running = this.capture().finally(() => {
this.running = undefined;
if (this.pending && this.live()) this.invalidate();
if (this.pending && this.live()) return this.checkpoint();
this.schedule();
});
return this.running;
}
dispose = (): void => {
this.pending = false;
this.invalidated = false;
clearTimeout(this.timer);
this.timer = undefined;
this.lifetime.abort();
this.hosted.signal.removeEventListener("abort", this.dispose);
};
Expand All @@ -104,6 +127,8 @@ export class AssistantRecordCapture {
private async capture(): Promise<void> {
while (this.pending && this.live()) {
this.pending = false;
this.invalidated = false;
this.startedAt = Date.now();
const signal = AbortSignal.any([
this.lifetime.signal,
this.hosted.signal,
Expand Down
93 changes: 93 additions & 0 deletions packages/harness/src/core/opencode-host.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,7 @@ const observers: Array<{
update: (state: AssistantObservation) => void;
dispose: ReturnType<typeof vi.fn>;
start: ReturnType<typeof vi.fn>;
checkpoint?: () => Promise<void>;
}> = [];
const createObserver = vi.fn(
(
Expand Down Expand Up @@ -65,6 +66,17 @@ const revoke = vi.fn();
const close = vi.fn();
const issue = vi.fn();
const neverExited = new Promise<void>(() => {});
async function exitFixture(checkpoint: () => Promise<void>) {
let exit!: () => void;
const exited = new Promise<void>((resolve) => {
exit = resolve;
});
start.mockResolvedValueOnce({ pid: 123, exited, close });
const hosted = await host.ensure("studio-a");
host.observe(hosted, "ses_a");
observers[0]!.checkpoint = checkpoint;
return { hosted, exit };
}
const cleanupProofFor = (stateRoot: string, hex: string) => ({
path: join(stateRoot, `cleanup-${hex.repeat(32)}.json`),
token: hex.repeat(64),
Expand Down Expand Up @@ -131,6 +143,7 @@ beforeEach(async () => {
});
});
afterEach(async () => {
vi.useRealTimers();
if (expectShutdownFailure)
await expect(host.close()).rejects.toThrow("shutdown");
else await host.close();
Expand Down Expand Up @@ -668,6 +681,86 @@ describe("Studio-owned OpenCode lifecycle", () => {
expect(close).toHaveBeenCalledOnce();
});

it("lets an in-flight checkpoint persist before ordinary exit aborts its exact host", async () => {
let release!: () => void;
const held = new Promise<void>((resolve) => {
release = resolve;
});
let pending!: Promise<void>;
const checkpoint = vi.fn(() => pending);
const { hosted, exit } = await exitFixture(checkpoint);
pending = held.then(async () => {
hosted.signal.throwIfAborted();
await writeFile(join(root, "final-checkpoint.json"), "retained");
});
exit();
await vi.waitFor(() => expect(checkpoint).toHaveBeenCalledOnce());
expect(host.current("studio-a")).toBe(hosted);
expect(hosted.signal.aborted).toBe(false);
expect(observers[0]!.dispose).not.toHaveBeenCalled();
expect(close).not.toHaveBeenCalled();
release();
await vi.waitFor(() => expect(hosted.signal.aborted).toBe(true));
expect(await readFile(join(root, "final-checkpoint.json"), "utf8")).toBe(
"retained",
);
expect(createObserver).toHaveBeenCalledOnce();
expect(start).toHaveBeenCalledOnce();
expect(close).toHaveBeenCalledOnce();
});

it("bounds an unresponsive ordinary-exit checkpoint to 750 ms", async () => {
const checkpoint = vi.fn(() => new Promise<void>(() => {}));
const { hosted, exit } = await exitFixture(checkpoint);
vi.useFakeTimers({ toFake: ["setTimeout", "clearTimeout"] });
exit();
await vi.advanceTimersByTimeAsync(749);
expect(checkpoint).toHaveBeenCalledOnce();
expect(hosted.signal.aborted).toBe(false);
await vi.advanceTimersByTimeAsync(1);
expect(hosted.signal.aborted).toBe(true);
expect(observers[0]!.dispose).toHaveBeenCalledOnce();
});

it.each(["End", "access", "workspace", "shutdown"])(
"%s preempts ordinary-exit draining without waiting for the checkpoint or deadline",
async (reason) => {
let release!: () => void;
const held = new Promise<void>((resolve) => {
release = resolve;
});
const checkpoint = vi.fn(() => held);
const { hosted, exit } = await exitFixture(checkpoint);
vi.useFakeTimers({ toFake: ["setTimeout", "clearTimeout"] });
exit();
await Promise.resolve();
expect(checkpoint).toHaveBeenCalledOnce();
if (reason === "End") await host.retire("studio-a");
if (reason === "access") {
grant = null;
changed();
}
if (reason === "workspace") {
authorize.mockResolvedValue(null);
await expect(host.ensure("studio-a")).rejects.toThrow("unavailable");
}
if (reason === "shutdown") host.beginShutdown();
expect(hosted.signal.aborted).toBe(true);
expect(observers[0]!.dispose).toHaveBeenCalledOnce();
await host.retireExact(hosted);
expect(close).toHaveBeenCalledOnce();
expect(vi.getTimerCount()).toBe(0);
if (reason === "End") {
const replacement = await host.ensure("studio-a");
release();
await Promise.resolve();
expect(host.current("studio-a")).toBe(replacement);
expect(replacement.signal.aborted).toBe(false);
expect(close).toHaveBeenCalledOnce();
} else release();
},
);

it("maps only the bounded native startup reason and suppresses expected cancellation", async () => {
start.mockRejectedValueOnce({
code: "permission-denied",
Expand Down
Loading
Loading