diff --git a/packages/harness/docs/assistant-history.md b/packages/harness/docs/assistant-history.md new file mode 100644 index 000000000..439cbaa1c --- /dev/null +++ b/packages/harness/docs/assistant-history.md @@ -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. diff --git a/packages/harness/src/core/assistant-history-access.test.ts b/packages/harness/src/core/assistant-history-access.test.ts index 57e41c986..9dcbc8fca 100644 --- a/packages/harness/src/core/assistant-history-access.test.ts +++ b/packages/harness/src/core/assistant-history-access.test.ts @@ -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; diff --git a/packages/harness/src/core/assistant-history-access.ts b/packages/harness/src/core/assistant-history-access.ts index 3c1403f5e..d116aaa92 100644 --- a/packages/harness/src/core/assistant-history-access.ts +++ b/packages/harness/src/core/assistant-history-access.ts @@ -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, @@ -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; @@ -18,8 +30,10 @@ 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"); @@ -27,20 +41,20 @@ export function assistantHistoryAccess(options: { 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 diff --git a/packages/harness/src/core/assistant-record-capture.test.ts b/packages/harness/src/core/assistant-record-capture.test.ts index d413a0d6b..ed20d6454 100644 --- a/packages/harness/src/core/assistant-record-capture.test.ts +++ b/packages/harness/src/core/assistant-record-capture.test.ts @@ -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( () => @@ -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; @@ -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); diff --git a/packages/harness/src/core/assistant-record-capture.ts b/packages/harness/src/core/assistant-record-capture.ts index 749139861..c6df08763 100644 --- a/packages/harness/src/core/assistant-record-capture.ts +++ b/packages/harness/src/core/assistant-record-capture.ts @@ -55,6 +55,9 @@ export class AssistantRecordCapture { private readonly lifetime = new AbortController(); private pending = false; private running?: Promise; + private invalidated = false; + private timer?: ReturnType; + private startedAt = 0; private failed = false; readonly binding: AssistantRecordBinding; constructor( @@ -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 { 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); }; @@ -104,6 +127,8 @@ export class AssistantRecordCapture { private async capture(): Promise { 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, diff --git a/packages/harness/src/core/opencode-host.test.ts b/packages/harness/src/core/opencode-host.test.ts index 6fc11ed79..52afda0ea 100644 --- a/packages/harness/src/core/opencode-host.test.ts +++ b/packages/harness/src/core/opencode-host.test.ts @@ -29,6 +29,7 @@ const observers: Array<{ update: (state: AssistantObservation) => void; dispose: ReturnType; start: ReturnType; + checkpoint?: () => Promise; }> = []; const createObserver = vi.fn( ( @@ -65,6 +66,17 @@ const revoke = vi.fn(); const close = vi.fn(); const issue = vi.fn(); const neverExited = new Promise(() => {}); +async function exitFixture(checkpoint: () => Promise) { + let exit!: () => void; + const exited = new Promise((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), @@ -131,6 +143,7 @@ beforeEach(async () => { }); }); afterEach(async () => { + vi.useRealTimers(); if (expectShutdownFailure) await expect(host.close()).rejects.toThrow("shutdown"); else await host.close(); @@ -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((resolve) => { + release = resolve; + }); + let pending!: Promise; + 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(() => {})); + 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((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", diff --git a/packages/harness/src/core/opencode-host.ts b/packages/harness/src/core/opencode-host.ts index 8692e819b..d3c59682d 100644 --- a/packages/harness/src/core/opencode-host.ts +++ b/packages/harness/src/core/opencode-host.ts @@ -40,7 +40,10 @@ import { type AssistantStateSnapshot, } from "../shared/assistant-state.js"; -type ObserverHandle = Pick; +type ObserverHandle = Pick & { + /** Complete an in-flight retained checkpoint before an ordinary exit retires its host. */ + checkpoint?: () => Promise; +}; interface ObservationBinding { conversationId: string; observer?: ObserverHandle; @@ -539,6 +542,35 @@ export class OpenCodeHost { } } + private async retireExited(entry: Managed): Promise { + const id = entry.workspace.harnessSessionId; + if (this.entries.get(id) !== entry) return; + const observer = entry.observation?.observer; + if (observer?.checkpoint && entry.hosted?.isCurrent()) { + let timer: ReturnType | undefined; + let interrupted!: () => void; + const deadline = new Promise((resolve) => { + interrupted = resolve; + timer = setTimeout(resolve, 750); + timer.unref?.(); + entry.abort.signal.addEventListener("abort", interrupted, { + once: true, + }); + }); + try { + await Promise.race([observer.checkpoint(), deadline]); + } catch { + // Checkpoint failure preserves the previous record; it cannot prevent cleanup. + } finally { + clearTimeout(timer); + entry.abort.signal.removeEventListener("abort", interrupted); + } + } + // End or revocation may already have retired this entry and admitted a replacement. + if (this.entries.get(id) === entry) + await this.retire(id, openCodeTransportFailure("runtime_exited")); + } + private async start( entry: Managed, grant: AssistantGrant, @@ -605,15 +637,7 @@ export class OpenCodeHost { signal: entry.abort.signal, beforeLaunch: (identity) => release.protectProcess(identity), }); - void server.exited - .then(() => { - if (this.entries.get(entry.workspace.harnessSessionId) === entry) - return this.retire( - entry.workspace.harnessSessionId, - openCodeTransportFailure("runtime_exited"), - ); - }) - .catch(() => {}); + void server.exited.then(() => this.retireExited(entry)).catch(() => {}); await this.validate(entry); const hosted: HostedOpenCode = Object.freeze({ ...entry.workspace, diff --git a/packages/harness/src/core/opencode-observer.test.ts b/packages/harness/src/core/opencode-observer.test.ts index 676a46407..bb0d015fc 100644 --- a/packages/harness/src/core/opencode-observer.test.ts +++ b/packages/harness/src/core/opencode-observer.test.ts @@ -11,7 +11,10 @@ const json = (value: unknown, status = 200) => new Response(JSON.stringify(value), { status }); const wait = (check: () => void) => vi.waitFor(check, { interval: 10, timeout: 2500 }); -function fixture(onHistoryInvalidated?: () => void) { +function fixture( + onHistoryInvalidated?: () => void, + onHistoryCheckpoint?: () => void, +) { const abort = new AbortController(); cleanups.push(() => abort.abort()); const data = new Map([ @@ -66,9 +69,12 @@ function fixture(onHistoryInvalidated?: () => void) { server: { fetch, close }, } as unknown as HostedOpenCode; const updates: AssistantObservation[] = []; - const observer = new OpenCodeObserver(hosted, "ses_a", (state) => - updates.push(state), + const observer = new OpenCodeObserver( + hosted, + "ses_a", + (state) => updates.push(state), onHistoryInvalidated, + onHistoryCheckpoint, ); cleanups.push(observer.dispose); return { @@ -372,14 +378,28 @@ it.each(["dispose", "abort", "retire"])( ); it("invalidates retained history from the existing observer after native message persistence", async () => { - const checkpoint = vi.fn(); - const f = fixture(checkpoint); + const invalidated = vi.fn(), + checkpoint = vi.fn(); + const f = fixture(invalidated, checkpoint); await f.start(); checkpoint.mockClear(); + invalidated.mockClear(); + for (let i = 0; i < 100; i++) + f.send("message.part.delta", { + messageID: "msg_a", + partID: "part_a", + delta: "token", + }); + f.send("session.status", { status: { type: "busy" } }); f.send("message.updated", { info: { id: "msg_a", sessionID: "ses_a" } }); - await wait(() => expect(checkpoint).toHaveBeenCalledTimes(1)); - f.send("message.updated", { sessionID: "ses_b", info: { id: "msg_b", sessionID: "ses_b" } }); + await wait(() => expect(invalidated).toHaveBeenCalledTimes(1)); + expect(checkpoint).not.toHaveBeenCalled(); + f.send("message.updated", { + sessionID: "ses_b", + info: { id: "msg_b", sessionID: "ses_b" }, + }); f.send("session.idle"); - await wait(() => expect(checkpoint).toHaveBeenCalledTimes(2)); + await wait(() => expect(checkpoint).toHaveBeenCalledTimes(1)); + expect(invalidated).toHaveBeenCalledTimes(1); expect(f.streams).toHaveLength(1); }); diff --git a/packages/harness/src/core/opencode-observer.ts b/packages/harness/src/core/opencode-observer.ts index 82426bcc0..c1e79e8d7 100644 --- a/packages/harness/src/core/opencode-observer.ts +++ b/packages/harness/src/core/opencode-observer.ts @@ -48,6 +48,7 @@ export class OpenCodeObserver { private readonly id: string, private readonly onUpdate: (state: AssistantObservation) => void, private readonly onHistoryInvalidated: () => void = () => {}, + private readonly onHistoryCheckpoint: () => void = onHistoryInvalidated, ) {} getState(): AssistantObservation { @@ -256,7 +257,14 @@ export class OpenCodeObserver { } } private event(c: Connection, event: Record): void { - if (typeof event.type === "string" && (event.type.startsWith("message.") || ["session.idle", "session.status"].includes(event.type))) + if ( + [ + "message.updated", + "message.removed", + "message.part.updated", + "message.part.removed", + ].includes(String(event.type)) + ) this.onHistoryInvalidated(); const properties = record(event.properties) ?? {}; if (event.type === "session.deleted") { @@ -275,6 +283,7 @@ export class OpenCodeObserver { ? activity(record(properties.status)?.type) : null; if (next) { + if (next === "idle") this.onHistoryCheckpoint(); c.statusRevision++; c.current.add("status"); this.accepted(c, { activity: next }); diff --git a/packages/harness/src/server/index.ts b/packages/harness/src/server/index.ts index c56546a97..ea5238d79 100644 --- a/packages/harness/src/server/index.ts +++ b/packages/harness/src/server/index.ts @@ -3557,8 +3557,9 @@ export const startServer = async ( createObserver: (hosted, id, update) => { const capture = new AssistantRecordCapture(hosted, id, assistantRecords); recordCaptures.set(hosted, capture); - const observer = new OpenCodeObserver(hosted, id, update, capture.invalidate); - return { start: () => observer.start(), dispose: () => { observer.dispose(); capture.dispose(); } }; + const checkpoint = () => capture.checkpoint(); + const observer = new OpenCodeObserver(hosted, id, update, capture.invalidate, () => { void checkpoint(); }); + return { start: () => observer.start(), checkpoint, dispose: () => { observer.dispose(); capture.dispose(); } }; }, bridge: openCodeBridge, origin: () => `http://127.0.0.1:${actualPort}`, @@ -3585,7 +3586,7 @@ export const startServer = async ( loadSystemPrompt: options.loadSystemPrompt, }), new OpenCodeAssociations(assistantSessions), - new OpenCodeFinalResponse({ onPersisted: async (hosted) => { recordCaptures.get(hosted)?.invalidate(); } }), + new OpenCodeFinalResponse({ onPersisted: async (hosted) => { await recordCaptures.get(hosted)?.checkpoint(); } }), ), );