diff --git a/.changeset/atomic-assistant-resume.md b/.changeset/atomic-assistant-resume.md new file mode 100644 index 000000000..709a6d608 --- /dev/null +++ b/.changeset/atomic-assistant-resume.md @@ -0,0 +1,5 @@ +--- +"@sapiom/harness": patch +--- + +Commit Assistant Resume intent and lifecycle together so retries preserve the original session. diff --git a/packages/harness/docs/assistant-history.md b/packages/harness/docs/assistant-history.md index a6e4c7e7b..4e4b1beaa 100644 --- a/packages/harness/docs/assistant-history.md +++ b/packages/harness/docs/assistant-history.md @@ -48,6 +48,13 @@ so a successful GET can return an older `capturedAt`. Disposal and authority los cancel capture; opening a retained record never resumes execution. # Selected native availability +Resume commits its operation UUID and exact saved-binding digest atomically with +the lifecycle header. The private proof is excluded from public state. An exact +retry can reconcile a lost acknowledgement; a later lifecycle revision, End or +changed binding invalidates it. A runtime restored after a crash revalidates +native history and original accepted context, then commits a paused lifecycle. +No runtime lease or saved system prompt is persisted in the operation proof. + Open an Assistant entry from Studio's existing session history to read its saved messages and tool excerpts. Mixed Terminal and Assistant entries are grouped by Studio session ID. Sessions that have never started a Terminal remain visible. diff --git a/packages/harness/src/core/assistant-resume-store.test.ts b/packages/harness/src/core/assistant-resume-store.test.ts new file mode 100644 index 000000000..5b6203c8b --- /dev/null +++ b/packages/harness/src/core/assistant-resume-store.test.ts @@ -0,0 +1,256 @@ +import { afterEach, beforeEach, expect, it, vi } from "vitest"; +import * as fs from "node:fs/promises"; +import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises"; +import { join } from "node:path"; +import { tmpdir } from "node:os"; +import { + AssistantSessionStore, + assistantResumeBindingDigest, + type AssistantAssociation, +} from "./assistant-session-store.js"; +import { parseAssistantLifecycle } from "../shared/assistant-session.js"; + +vi.mock("node:fs/promises", async (original) => { + const actual = await original(); + return { ...actual, open: vi.fn(actual.open), rename: vi.fn(actual.rename) }; +}); + +let root: string, store: AssistantSessionStore; +const id = "studio-a"; +const binding: AssistantAssociation = { + version: 1, + harnessSessionId: id, + cwd: "/workspace", + conversationId: "ses_saved", + contextAuthorityScope: "a".repeat(64), + nativeScope: "b".repeat(64), + createdAt: 1, +}; +const request = { + operationId: "f1872aaa-b7c0-44f1-a9bc-3f9613b4a52c", + expectedRevision: 1, + bindingDigest: assistantResumeBindingDigest(binding), +}; +const document = () => join(root, "assistant-sessions", id, "lifecycle.json"); +beforeEach(async () => { + root = await mkdtemp(join(tmpdir(), "assistant-resume-store-")); + store = new AssistantSessionStore(root); + await store.transition(id, 0, { lifecycle: "ended", execution: "paused" }); +}); +afterEach(async () => { + vi.restoreAllMocks(); + await rm(root, { recursive: true, force: true }); +}); + +it("atomically retains Resume proof while exposing only the strict public lifecycle", async () => { + const state = await store.commitResume(id, 1, request, "paused"); + expect(state).toMatchObject({ + lifecycle: "open", + execution: "paused", + revision: 2, + }); + expect(parseAssistantLifecycle(state)).toEqual(state); + const raw = JSON.parse(await readFile(document(), "utf8")); + expect(raw).toEqual({ + ...state, + resumeOperation: { ...request, version: 1, committedRevision: 2 }, + }); + expect(parseAssistantLifecycle(raw)).toBeNull(); + const restarted = new AssistantSessionStore(root); + expect(await restarted.lifecycle(id)).toEqual(state); + expect(await restarted.resumeState(id)).toEqual({ + lifecycle: state, + resumeOperation: raw.resumeOperation, + }); +}); + +it("serializes concurrent duplicate commits and returns their exact committed revision", async () => { + const [a, b] = await Promise.all([ + store.commitResume(id, 1, request, "paused"), + new AssistantSessionStore(root).commitResume(id, 1, request, "paused"), + ]); + expect(a).toEqual(b); + expect(a.revision).toBe(2); + expect(await store.lifecycle(id)).toEqual(a); +}); + +it("reconciles crash-after-commit with a paused CAS from the proved committed revision", async () => { + await store.commitResume(id, 1, request, "paused"); + const restarted = new AssistantSessionStore(root); + const recovered = await restarted.resumeState(id); + const state = await restarted.commitResume( + id, + recovered.resumeOperation!.committedRevision, + request, + "paused", + ); + expect(state).toMatchObject({ revision: 3, execution: "paused" }); + expect((await restarted.resumeState(id)).resumeOperation).toEqual({ + ...request, + version: 1, + committedRevision: 3, + }); +}); + +it.each(["ending", "ended", "enabled"] as const)( + "preserves proof but rejects operation replay after a later %s transition", + async (next) => { + await store.commitResume(id, 1, request, "paused"); + const lifecycle = next === "enabled" ? "open" : next; + const advanced = await store.transition(id, 2, { + lifecycle, + execution: next === "enabled" ? "enabled" : "paused", + }); + expect((await store.resumeState(id)).resumeOperation?.operationId).toBe( + request.operationId, + ); + await expect(store.commitResume(id, 1, request, "paused")).rejects.toThrow( + "changed", + ); + await expect( + store.commitResume(id, advanced.revision, request, "paused"), + ).rejects.toThrow("changed"); + expect(await store.lifecycle(id)).toEqual(advanced); + }, +); + +it.each(["bindingDigest", "expectedRevision"] as const)( + "rejects operation ID reuse with changed %s", + async (field) => { + await store.commitResume(id, 1, request, "paused"); + const changed = { + ...request, + [field]: field === "bindingDigest" ? "c".repeat(64) : 0, + }; + await expect(store.commitResume(id, 2, changed, "paused")).rejects.toThrow( + "changed", + ); + expect((await store.lifecycle(id))?.revision).toBe(2); + }, +); + +it("competing operation IDs cannot both claim the same source revision", async () => { + const outcomes = await Promise.allSettled([ + store.commitResume(id, 1, request, "paused"), + new AssistantSessionStore(root).commitResume( + id, + 1, + { ...request, operationId: "ac243472-d1ef-4926-bf47-2a32bd28e912" }, + "paused", + ), + ]); + expect( + outcomes.filter((outcome) => outcome.status === "fulfilled"), + ).toHaveLength(1); + expect( + outcomes.filter((outcome) => outcome.status === "rejected"), + ).toHaveLength(1); + expect((await store.lifecycle(id))?.revision).toBe(2); +}); + +it("cancellation preserves the prior header and proof together", async () => { + const before = await readFile(document(), "utf8"); + await expect( + store.commitResume(id, 1, request, "paused", AbortSignal.abort()), + ).rejects.toThrow(); + expect(await readFile(document(), "utf8")).toBe(before); + expect((await store.resumeState(id)).resumeOperation).toBeNull(); +}); + +it("rolls back header and proof together after failed publication, then safely retries", async () => { + const previous = await store.resumeState(id); + const actual = await vi.importActual("node:fs/promises"); + let failSync = false; + let injected = false; + vi.mocked(fs.rename).mockImplementation(async (from, to) => { + await actual.rename(from, to); + if (to === document() && !injected) { + failSync = true; + injected = true; + } + }); + vi.mocked(fs.open).mockImplementation(async (path, flags, mode) => { + if (flags === "r" && failSync) { + failSync = false; + throw Object.assign(new Error("post-publication disk failure"), { + code: "EIO", + }); + } + return actual.open(path, flags, mode); + }); + await expect(store.commitResume(id, 1, request, "paused")).rejects.toThrow( + "disk failure", + ); + const restarted = new AssistantSessionStore(root); + expect(await restarted.resumeState(id)).toEqual(previous); + const recovered = await restarted.commitResume(id, 1, request, "paused"); + expect(recovered.revision).toBe(2); + expect((await restarted.resumeState(id)).resumeOperation).toEqual({ + ...request, + version: 1, + committedRevision: 2, + }); +}); + +it("only an already-enabled open lifecycle may preserve enabled execution", async () => { + await expect(store.commitResume(id, 1, request, "enabled")).rejects.toThrow(); + await store.transition(id, 1, { lifecycle: "open", execution: "enabled" }); + expect( + await store.commitResume( + id, + 2, + { ...request, expectedRevision: 2 }, + "enabled", + ), + ).toMatchObject({ revision: 3, execution: "enabled" }); +}); + +it.each([ + { committedRevision: 99 }, + { committedRevision: 1 }, + { bindingDigest: "bad" }, + { operationId: "../escape" }, + { extra: true }, +])( + "rejects malformed or contradictory private operation proof: %j", + async (patch) => { + const lifecycle = await store.commitResume(id, 1, request, "paused"); + await writeFile( + document(), + JSON.stringify({ + ...lifecycle, + resumeOperation: { + ...request, + version: 1, + committedRevision: 2, + ...patch, + }, + }), + ); + await expect(store.lifecycle(id)).rejects.toThrow("storage"); + await expect(store.resumeState(id)).rejects.toThrow("storage"); + }, +); + +it("digests the complete validated association and rejects untrusted extra fields", () => { + for (const [field, value] of Object.entries(binding)) { + if (field === "version") continue; + const replacement = + field === "createdAt" + ? 2 + : field === "cwd" + ? "/other" + : field.endsWith("Scope") + ? "f".repeat(64) + : `${value}_other`; + expect( + assistantResumeBindingDigest({ ...binding, [field]: replacement }), + ).not.toBe(request.bindingDigest); + } + expect(() => + assistantResumeBindingDigest({ + ...binding, + extra: true, + } as AssistantAssociation), + ).toThrow(); +}); diff --git a/packages/harness/src/core/assistant-session-store.ts b/packages/harness/src/core/assistant-session-store.ts index 0490be5c7..4e0e89d95 100644 --- a/packages/harness/src/core/assistant-session-store.ts +++ b/packages/harness/src/core/assistant-session-store.ts @@ -1,4 +1,5 @@ import { readdir } from "node:fs/promises"; +import { createHash } from "node:crypto"; import { isAbsolute, join } from "node:path"; import { z } from "zod"; import { isConversationId } from "../shared/assistant-state.js"; @@ -46,6 +47,43 @@ const associationSchema = z }) .strict(); +const resumeRequestSchema = z + .object({ + operationId: z.string().uuid(), + expectedRevision: z.number().int().nonnegative().safe(), + bindingDigest: z.string().regex(authorityScopePattern), + }) + .strict(); +const resumeOperationSchema = resumeRequestSchema.extend({ + version: z.literal(1), + committedRevision: z.number().int().positive().safe(), +}); +export type AssistantResumeRequest = z.infer; +export type AssistantResumeOperation = z.infer; +const controlSchema = lifecycleSchema + .extend({ resumeOperation: resumeOperationSchema.optional() }) + .refine( + (row) => + !row.resumeOperation || + (row.resumeOperation.expectedRevision < + row.resumeOperation.committedRevision && + row.resumeOperation.committedRevision <= row.revision), + ); +type AssistantControl = z.infer; +const publicLifecycle = ({ + resumeOperation: _private, + ...lifecycle +}: AssistantControl): AssistantLifecycle => lifecycle; + +/** Digest every validated saved-association field, never a client-selected path. */ +export function assistantResumeBindingDigest( + binding: AssistantAssociation, +): string { + return createHash("sha256") + .update(JSON.stringify(associationSchema.parse(binding))) + .digest("hex"); +} + export class AssistantSessionRevisionError extends Error { constructor() { super("Assistant session changed. Please retry."); @@ -57,15 +95,34 @@ export class AssistantSessionStore { constructor(readonly stateRoot: string) {} async lifecycle(id: string): Promise { + const control = await this.control(id); + return control ? publicLifecycle(control) : null; + } + + private async control(id: string): Promise { const directory = await assistantDirectory(this.stateRoot, id); const raw = await readAssistantJson(join(directory, "lifecycle.json")); if (raw === null) return null; - const parsed = lifecycleSchema.safeParse(raw); + const parsed = controlSchema.safeParse(raw); if (!parsed.success || parsed.data.harnessSessionId !== id) throw new AssistantStorageError(); return parsed.data; } + /** Read the public header and private operation proof from one atomic generation. */ + async resumeState( + id: string, + ): Promise<{ + lifecycle: AssistantLifecycle | null; + resumeOperation: AssistantResumeOperation | null; + }> { + const control = await this.control(id); + return { + lifecycle: control ? publicLifecycle(control) : null, + resumeOperation: control?.resumeOperation ?? null, + }; + } + async transition( id: string, expected: number, @@ -78,7 +135,7 @@ export class AssistantSessionStore { ).acquire(); try { signal?.throwIfAborted(); - const current = await this.lifecycle(id); + const current = await this.control(id); if ((current?.revision ?? 0) !== expected) throw new AssistantSessionRevisionError(); const updated = lifecycleSchema.parse({ @@ -88,7 +145,83 @@ export class AssistantSessionStore { ...next, updatedAt: Date.now(), }); - await writeAssistantJson(directory, "lifecycle.json", updated, signal); + await writeAssistantJson( + directory, + "lifecycle.json", + { + ...updated, + ...(current?.resumeOperation + ? { resumeOperation: current.resumeOperation } + : {}), + }, + signal, + ); + return updated; + } finally { + await unlock(); + } + } + + /** Commit Resume and its idempotence proof together. A replay of this exact + * write returns its existing result; a restarted runtime uses the recovered + * committed revision as a new CAS base and must again begin paused. */ + async commitResume( + id: string, + expected: number, + input: AssistantResumeRequest, + execution: AssistantLifecycle["execution"], + signal?: AbortSignal, + ): Promise { + const request = resumeRequestSchema.parse(input); + const directory = await assistantDirectory(this.stateRoot, id); + const unlock = await new DurableFileLock( + join(directory, "lifecycle.json"), + ).acquire(); + try { + signal?.throwIfAborted(); + const current = await this.control(id); + const revision = current?.revision ?? 0; + const proof = current?.resumeOperation; + const retry = proof?.operationId === request.operationId; + if ( + retry && + (proof.expectedRevision !== request.expectedRevision || + proof.bindingDigest !== request.bindingDigest || + proof.committedRevision !== revision || + current?.lifecycle !== "open") + ) + throw new AssistantSessionRevisionError(); + if (retry && expected === request.expectedRevision) + return publicLifecycle(current!); + if ( + revision !== expected || + (!retry && revision !== request.expectedRevision) || + current?.lifecycle === "ending" || + (execution === "enabled" && + (current?.lifecycle !== "open" || current.execution !== "enabled")) + ) + throw new AssistantSessionRevisionError(); + const updated = lifecycleSchema.parse({ + version: 1, + harnessSessionId: id, + revision: revision + 1, + lifecycle: "open", + execution, + updatedAt: Date.now(), + }); + await writeAssistantJson( + directory, + "lifecycle.json", + { + ...updated, + resumeOperation: { + ...request, + version: 1, + committedRevision: updated.revision, + }, + }, + signal, + ); return updated; } finally { await unlock();