Skip to content

A desktop coding agent with free access to frontier models.

TypeScript

Serialize GUI turns and retain interrupted capture baselines

Task Builderaf80d8402c7c
diff --git a/apps/app/src/react-app/domains/session/surface/composer/composer.tsx b/apps/app/src/react-app/domains/session/surface/composer/composer.tsx
index d33e5c30..a64f765d 100644
--- a/apps/app/src/react-app/domains/session/surface/composer/composer.tsx
+++ b/apps/app/src/react-app/domains/session/surface/composer/composer.tsx
@@ -360,9 +360,10 @@ export const ReactSessionComposer = memo(function ReactSessionComposer(props: Co
if (escapeTimerRef.current) clearTimeout(escapeTimerRef.current);
}, []);
- // Editor submit (Enter). While idle this sends normally; while busy
- // Enter queues until the agent finishes, and Cmd/Ctrl+Enter steers.
- // Auto-send after dictation waits until the dictated text has reached the draft.
+ // Editor submit (Enter). While idle this sends normally. During a running
+ // turn, keep the draft in the composer until the user stops the turn; this
+ // prevents a queued prompt from creating a premature filesystem baseline.
+ // Auto-send after dictation follows the same admission rule.
const [voiceAutoSendPrompt, setVoiceAutoSendPrompt] = useState<string | null>(null);
const voice = useVoiceDictation({
client: props.voiceClient ?? null,
@@ -384,12 +385,12 @@ export const ReactSessionComposer = memo(function ReactSessionComposer(props: Co
if (!hasContent) return;
if (props.submissionPreparing) return;
if (props.busy) {
- if (options.queue) void props.onSteer();
- else void props.onQueue();
+ // Serialized capture has one logical turn at a time. The draft remains
+ // editable, but it is not dispatched or moved into a background queue.
return;
}
void props.onSend();
- }, [props.busy, props.draft, props.attachments, props.onSend, props.onSteer, props.onQueue, props.submissionPreparing, voice.active, voice.stop]);
+ }, [props.busy, props.draft, props.attachments, props.onSend, props.submissionPreparing, voice.active, voice.stop]);
useEffect(() => {
if (voiceAutoSendPrompt === null || props.draft !== voiceAutoSendPrompt) return;
diff --git a/apps/app/src/react-app/domains/session/surface/session-surface.tsx b/apps/app/src/react-app/domains/session/surface/session-surface.tsx
index 5df18297..cfa096c8 100644
--- a/apps/app/src/react-app/domains/session/surface/session-surface.tsx
+++ b/apps/app/src/react-app/domains/session/surface/session-surface.tsx
@@ -2059,9 +2059,8 @@ export function SessionSurface(props: SessionSurfaceProps) {
}
};
- // Core sender shared by initial send and steered follow-ups. OpenCode
- // accepts follow-up user turns mid-run (steering) — the running loop picks
- // up the new message — so this is safe to call while the agent is busy.
+ // Core sender for a logical turn. A running turn owns its filesystem
+ // baseline until it naturally completes or is stopped and resumed.
const sendDraft = useCallback(async (nextDraft: ComposerDraft, itemId: string, onPrepared?: () => void): Promise<CloudMcpSubmissionResult | { outcome: "unknown" }> => {
const messageId = nextDraft.messageId ?? createPromptMessageID();
const generation = getQueuedSendGeneration(props.sessionId);
@@ -2121,8 +2120,11 @@ export function SessionSurface(props: SessionSurfaceProps) {
const sourceAttachments = sourceComposer?.attachments ?? attachments;
const text = originalDraft.trim();
if (!text && sourceAttachments.length === 0) return;
+ // Editing a prior user message is an additive correction. Do not carry
+ // the destructive revert cursor into a serialized turn: the original
+ // prompt and baseline must remain part of the same captured group.
const nextDraft = {
- ...buildDraft(text, sourceAttachments, sourceComposer),
+ ...withoutRevertTarget(buildDraft(text, sourceAttachments, sourceComposer))!,
messageId: createPromptMessageID(),
};
// Immediate sends and queued sends share the same slot across all panes.
@@ -2240,10 +2242,9 @@ export function SessionSurface(props: SessionSurfaceProps) {
void handleSend();
}, [attachments.length, autoSendPayload, chatStreaming, draft, handleSend, model.transitionState, sessionModelUnavailable, props.sessionId, sessionOwner]);
- const handleSteer = useCallback(async () => {
- setSteering(true);
- await handleSend();
- }, [handleSend]);
+ const handleSteer = useCallback(() => {
+ toast.info("Stop the current turn before sending another message.");
+ }, []);
const handleRetryCloudSubmission = useCallback(() => {
if (draft.trim() || attachments.length > 0) {
@@ -2255,17 +2256,11 @@ export function SessionSurface(props: SessionSurfaceProps) {
setCloudQueueRetryVersion((version) => version + 1);
}, [attachments.length, draft, handleSend, props.sessionId]);
- // Queue: hold the draft locally and clear the composer. The drain effect
- // sends it once the session reports idle.
+ // Kept as a compatibility callback for older composer surfaces. New
+ // prompts are held in the visible draft until the running turn is stopped.
const handleQueue = useCallback(() => {
- if ([...pendingSendsRef.current.values()].includes(sessionOwner)) return;
- const text = draft.trim();
- if (!text && attachments.length === 0) return;
- const queuedDraft = withoutRevertTarget(buildDraft(text, attachments));
- if (!queuedDraft) return;
- appendQueuedDraft(props.sessionId, queuedDraft);
- clearComposer();
- }, [appendQueuedDraft, attachments, buildDraft, clearComposer, draft, props.sessionId, sessionOwner]);
+ toast.info("Stop the current turn before sending another message.");
+ }, []);
const removeQueuedDraft = useCallback((id: string) => {
const target = queuedItems.find((item) => item.id === id);
diff --git a/apps/server/src/capture-client.test.ts b/apps/server/src/capture-client.test.ts
index 80604678..82230f56 100644
--- a/apps/server/src/capture-client.test.ts
+++ b/apps/server/src/capture-client.test.ts
@@ -711,3 +711,27 @@ describe("turns left open: worker restarts and quits", () => {
expect(envelopes.at(-1)?.snapshot_type).toBe("end");
}, 60_000);
});
+
+describe("logical turn worker acknowledgements", () => {
+ for (const worker of [false, true]) {
+ test(`requires explicit capture replies (worker=${worker})`, async () => {
+ const root = await tempDir("turn-ack-workspace");
+ const sink = uploadSink();
+ const capture = service({
+ stateDir: await tempDir("turn-ack-state"), worker,
+ sessionUploader: { upload: sink.upload, context: false },
+ });
+ const sessionId = "session-turn-ack-0001";
+ expect(await capture.promptStartGate(sessionId, "workspace-ack", root)).toBe(true);
+ expect(await capture.hasOpenTurn(sessionId)).toBe(true);
+ await capture.pauseTurn(sessionId);
+ await capture.settleTurn(sessionId);
+ expect(await capture.promptStartGate(sessionId, "workspace-ack", root)).toBe(true);
+ await capture.stop();
+ expect(await capture.promptStartGate(sessionId, "workspace-ack", root)).toBe(false);
+ await expect(capture.pauseTurn(sessionId)).rejects.toThrow("acknowledge");
+ await expect(capture.settleTurn(sessionId)).rejects.toThrow("acknowledge");
+ await expect(capture.hasOpenTurn(sessionId)).rejects.toThrow("unavailable");
+ });
+ }
+});
diff --git a/apps/server/src/capture-client.ts b/apps/server/src/capture-client.ts
index ed63aca0..7a2d59bb 100644
--- a/apps/server/src/capture-client.ts
+++ b/apps/server/src/capture-client.ts
@@ -83,7 +83,12 @@ export type CaptureService = {
finishSession(sessionId: string, finalTrace?: unknown): void;
/** The "engine.request" event of a captured request (its body parsed off the main thread), plus a prompt's attachments. */
recordPrompt(sessionId: string, prompt: Omit<PromptRecord, "body"> & { body: ArrayBuffer | undefined }): void;
- captureSnapshot(sessionId: string, trigger: "prompt" | "turn_completed", outcome?: "aborted"): void;
+ captureSnapshot(sessionId: string, trigger: "prompt" | "turn_completed", outcome?: "aborted" | "error" | "incomplete"): void;
+ /** Resolves true only after the session's original start baseline was accepted or spooled. */
+ promptStartGate(sessionId: string, workspaceId: string, root: string): Promise<boolean>;
+ pauseTurn(sessionId: string, reason?: string): Promise<void>;
+ hasOpenTurn(sessionId: string): Promise<boolean>;
+ settleTurn(sessionId: string): Promise<void>;
/** Whether the visit is recorded (a tracked session and an uploadable URL). */
recordWebVisit(sessionId: string, visit: UploadWebVisit): boolean;
archiveSessionStarted(sessionId: string, root: string, target: EngineTarget): void;
@@ -209,10 +214,33 @@ class CaptureClient implements CaptureService {
this.send({ kind: "call", id: null, method: "recordPrompt", args: [sessionId, { ...prompt, body }] }, body ? [body.buffer] : []);
}
- captureSnapshot(sessionId: string, trigger: "prompt" | "turn_completed", outcome?: "aborted"): void {
+ captureSnapshot(sessionId: string, trigger: "prompt" | "turn_completed", outcome?: "aborted" | "error" | "incomplete"): void {
this.send({ kind: "call", id: null, method: "captureSnapshot", args: outcome ? [sessionId, trigger, outcome] : [sessionId, trigger] });
}
+ async promptStartGate(sessionId: string, workspaceId: string, root: string): Promise<boolean> {
+ if (!this.hasSession(sessionId)) this.startSession(sessionId, workspaceId, root);
+ return (await this.query({ kind: "call", id: null, method: "promptStartGate", args: [sessionId, workspaceId, root] })) === true;
+ }
+
+ async pauseTurn(sessionId: string, reason?: string): Promise<void> {
+ if (await this.query({ kind: "call", id: null, method: "pauseTurn", args: [sessionId, reason] }) !== true) {
+ throw new Error("Capture did not acknowledge the interrupted turn.");
+ }
+ }
+
+ async hasOpenTurn(sessionId: string): Promise<boolean> {
+ const value = await this.query({ kind: "call", id: null, method: "hasOpenTurn", args: [sessionId] });
+ if (typeof value !== "boolean") throw new Error("Capture turn status is unavailable.");
+ return value;
+ }
+
+ async settleTurn(sessionId: string): Promise<void> {
+ if (await this.query({ kind: "call", id: null, method: "settleTurn", args: [sessionId] }) !== true) {
+ throw new Error("Capture did not acknowledge the completed turn.");
+ }
+ }
+
recordWebVisit(sessionId: string, visit: UploadWebVisit): boolean {
if (this.local) return this.local.recordWebVisit(sessionId, visit);
if (!this.hasSession(sessionId) || typeof visit.url !== "string" || !isUploadableWebUrl(visit.url)) return false;
diff --git a/apps/server/src/capture-host.ts b/apps/server/src/capture-host.ts
index bcba2e98..d44d1783 100644
--- a/apps/server/src/capture-host.ts
+++ b/apps/server/src/capture-host.ts
@@ -185,7 +185,7 @@ export class CaptureHost {
/** The "engine.request" event of a captured request and, for a prompt dispatch, one "attachment" event per attached file. */
recordPrompt(sessionId: string, prompt: PromptRecord): void {
- // The turn this prompt follows takes its end snapshot first, ahead of this prompt's own.
+ // Admission has settled the prior turn before this request is forwarded.
if (prompt.dispatchedAt !== undefined) promptDispatched(this.observers, this.sessionUploader, sessionId, prompt.dispatchedAt);
const payload = requestPayload(prompt.body);
this.sessionUploader.recordTrace(sessionId, "engine.request", {
@@ -199,10 +199,31 @@ export class CaptureHost {
}).catch(() => undefined);
}
- captureSnapshot(sessionId: string, trigger: "prompt" | "turn_completed", outcome?: "aborted"): void {
+ captureSnapshot(sessionId: string, trigger: "prompt" | "turn_completed", outcome?: "aborted" | "error" | "incomplete"): void {
this.sessionUploader.captureSnapshot(sessionId, trigger, outcome);
}
+ async promptStartGate(sessionId: string, workspaceId: string, root: string): Promise<boolean> {
+ if (!this.sessionUploader.hasSession(sessionId)) this.startSession(sessionId, workspaceId, root);
+ return this.sessionUploader.beginTurn(sessionId);
+ }
+
+ async pauseTurn(sessionId: string, reason?: string): Promise<boolean> {
+ await this.sessionUploader.pauseTurn(sessionId, reason);
+ return true;
+ }
+
+ async hasOpenTurn(sessionId: string): Promise<boolean> {
+ await this.sessionUploader.sessionCheckpoint(sessionId);
+ return this.sessionUploader.hasOpenTurn(sessionId);
+ }
+
+ async settleTurn(sessionId: string): Promise<boolean> {
+ await this.observers.sessions.get(sessionId)?.done;
+ await this.sessionUploader.idle(sessionId);
+ return true;
+ }
+
recordWebVisit(sessionId: string, visit: UploadWebVisit): boolean {
return this.sessionUploader.recordWebVisit(sessionId, visit);
}
@@ -278,10 +299,7 @@ export class CaptureHost {
/** The session was deleted in the engine. */
sessionDeleted(sessionId: string): void {
this.sessionUploader.recordTrace(sessionId, "session.deleted");
- this.sessionUploader.finishSession(sessionId);
- this.archive.sessionEnded(sessionId);
- this.observers.lastMessageIds.delete(sessionId);
- this.sessionRoots.delete(sessionId);
+ this.finishSession(sessionId);
}
/** The account is gone: queued archives and spooled uploads are deleted, nothing more is archived. */
diff --git a/apps/server/src/capture-protocol.ts b/apps/server/src/capture-protocol.ts
index fea734f9..834aafff 100644
--- a/apps/server/src/capture-protocol.ts
+++ b/apps/server/src/capture-protocol.ts
@@ -21,7 +21,11 @@ export type CaptureCalls = {
flushTrace: [sessionId: string, finalTrace?: unknown];
finishSession: [sessionId: string, finalTrace?: unknown];
recordPrompt: [sessionId: string, prompt: PromptRecord];
- captureSnapshot: [sessionId: string, trigger: "prompt" | "turn_completed", outcome?: "aborted"];
+ captureSnapshot: [sessionId: string, trigger: "prompt" | "turn_completed", outcome?: "aborted" | "error" | "incomplete"];
+ promptStartGate: [sessionId: string, workspaceId: string, root: string];
+ pauseTurn: [sessionId: string, reason?: string];
+ hasOpenTurn: [sessionId: string];
+ settleTurn: [sessionId: string];
recordWebVisit: [sessionId: string, visit: UploadWebVisit];
archiveSessionStarted: [sessionId: string, root: string, target: EngineTarget];
archiveStartGate: [sessionId: string, root: string];
@@ -170,6 +174,14 @@ export function invokeCapture(host: CaptureHost, call: CaptureCall): unknown {
return host.recordPrompt(...call.args);
case "captureSnapshot":
return host.captureSnapshot(...call.args);
+ case "promptStartGate":
+ return host.promptStartGate(...call.args);
+ case "pauseTurn":
+ return host.pauseTurn(...call.args);
+ case "hasOpenTurn":
+ return host.hasOpenTurn(...call.args);
+ case "settleTurn":
+ return host.settleTurn(...call.args);
case "recordWebVisit":
return host.recordWebVisit(...call.args);
case "archiveSessionStarted":
diff --git a/apps/server/src/headless-threads.e2e.test.ts b/apps/server/src/headless-threads.e2e.test.ts
index d285e371..41182864 100644
--- a/apps/server/src/headless-threads.e2e.test.ts
+++ b/apps/server/src/headless-threads.e2e.test.ts
@@ -102,8 +102,9 @@ function startMockOpencode() {
if (url.pathname === "/session" && request.method === "POST") return Response.json(session);
if (url.pathname === "/session" && request.method === "GET") return Response.json([session]);
if (url.pathname === `/session/${SESSION_ID}`) return Response.json(session);
- if (url.pathname === `/session/${SESSION_ID}/message`) return Response.json(current.messages);
+ if (url.pathname === `/session/${SESSION_ID}/message`) return Response.json(prompts.length === 0 ? [] : current.messages);
if (url.pathname === `/session/${SESSION_ID}/todo`) return Response.json([]);
+ if (url.pathname === `/session/${SESSION_ID}/children`) return Response.json([]);
if (url.pathname === "/session/status") {
return Response.json(current.busy ? { [SESSION_ID]: { type: "busy" } } : {});
}
diff --git a/apps/server/src/opencode-proxy.e2e.test.ts b/apps/server/src/opencode-proxy.e2e.test.ts
index 5ddd5461..b866b1d1 100644
--- a/apps/server/src/opencode-proxy.e2e.test.ts
+++ b/apps/server/src/opencode-proxy.e2e.test.ts
@@ -79,7 +79,7 @@ function startMockOpencode(input?: { holdCommand?: Promise<void>; foreignSession
if (url.pathname === "/session/status") return Response.json(input.recovery.active ? { ses_1: { type: "busy" } } : {});
if (["/permission", "/question"].includes(url.pathname)) return Response.json([]);
if (url.pathname === "/api/session/ses_1/permission") return Response.json({ data: [] });
- if (url.pathname === "/session/ses_1/message") return Response.json([
+ if (url.pathname === "/session/ses_1/message") return Response.json(input.recovery.turn === 0 ? [] : [
{ info: { id: `user-${input.recovery.turn}`, role: "user", sessionID: "ses_1", model: { providerID: "test", modelID: "test" } }, parts: [] },
{ info: { id: `assistant-${input.recovery.turn}`, role: "assistant", sessionID: "ses_1", time: {} }, parts: [] },
]);
@@ -113,6 +113,10 @@ function startMockOpencode(input?: { holdCommand?: Promise<void>; foreignSession
return Response.json({ ses_1: { type: "busy" } });
}
+ if (url.pathname === "/session/ses_1/children") {
+ return Response.json([]);
+ }
+
if (url.pathname === "/session/ses_1") {
return Response.json({
id: "ses_1",
@@ -611,7 +615,7 @@ describe("workspace OpenCode proxy", () => {
expect(response.status).toBe(400);
await expect(response.json()).resolves.toMatchObject({
code: "opencode_unconfigured",
- message: "OpenCode base URL is missing for this workspace",
+ message: "OmniRush base URL is missing for this workspace",
});
});
});
diff --git a/apps/server/src/serialized-turn-gate.ts b/apps/server/src/serialized-turn-gate.ts
new file mode 100644
index 00000000..4d626634
--- /dev/null
+++ b/apps/server/src/serialized-turn-gate.ts
@@ -0,0 +1,173 @@
+import { ApiError } from "./errors.js";
+import { latestPromptId, readEngineSessionRoot, readSessionTreeQuiescence, stopEngineSession, turnOutcome, type EngineTarget } from "./session-upload-observer.js";
+
+export type SerializedTurnCapture = {
+ promptStartGate(sessionId: string, workspaceId: string, root: string): Promise<boolean>;
+ pauseTurn(sessionId: string, reason?: string): Promise<void>;
+ hasOpenTurn(sessionId: string): Promise<boolean>;
+ settleTurn(sessionId: string): Promise<void>;
+};
+type Input = {
+ key: string;
+ sessionId: string;
+ workspaceId: string;
+ root: string;
+ target: EngineTarget;
+ capture: SerializedTurnCapture;
+};
+type State = {
+ reserved: boolean;
+ stopping: boolean;
+ blocked: boolean;
+ generation: number;
+ stopped: boolean;
+ pending: Map<string, string | null>;
+};
+export class SerializedTurnError extends ApiError {
+ constructor(message: string, status: 409 | 503 = 409) { super(status, status === 409 ? "turn_active" : "turn_unavailable", message); }
+}
+export type TurnTicket = {
+ check(): void;
+ finish(accepted: boolean | null): Promise<void>;
+};
+const RUNNING = "This turn is still running. Stop it before sending or editing a message.";
+function bounded<T>(operation: () => Promise<T>, ms: number): Promise<T> {
+ let timer: ReturnType<typeof setTimeout>;
+ return Promise.race([
+ Promise.resolve().then(operation),
+ new Promise<never>((_, reject) => {
+ timer = setTimeout(() => reject(new SerializedTurnError("The turn could not be verified in time. Retry Stop.", 503)), ms);
+ }),
+ ]).finally(() => clearTimeout(timer));
+}
+
+/** One reservation per root tree, retained across asynchronous dispatch and Stop. */
+export class SerializedTurnGate {
+ private readonly states = new Map<string, State>();
+ private async resolve(input: Input, signal: AbortSignal): Promise<{ id: string; state: State }> {
+ const id = await readEngineSessionRoot(input.target, input.sessionId, signal).catch(() => {
+ throw new SerializedTurnError("Session ancestry is unavailable. The request was not sent.", 503);
+ });
+ const key = input.key + "\0" + id;
+ let state = this.states.get(key);
+ if (!state) {
+ state = { reserved: false, stopping: false, blocked: false, generation: 0, stopped: false, pending: new Map() };
+ this.states.set(key, state);
+ }
+ return { id, state };
+ }
+
+ async admit(input: Input, edit = false): Promise<TurnTicket> {
+ const signal = AbortSignal.timeout(60_000);
+ const { id, state } = await this.resolve(input, signal);
+ if (state.reserved || state.stopping || state.blocked) throw new SerializedTurnError(RUNNING);
+ state.reserved = true;
+ const generation = state.generation;
+ let baselineStarted = false;
+ const check = () => {
+ if (generation !== state.generation || state.stopping || state.blocked || signal.aborted) {
+ throw new SerializedTurnError("The request was stopped before it could start.");
+ }
+ };
+ try {
+ const tree = await readSessionTreeQuiescence(input.target, id, signal);
+ if (!tree.known) throw new SerializedTurnError("Agent or tool status is unavailable. The message was not sent.", 503);
+ if (tree.busy) throw new SerializedTurnError(RUNNING);
+ if (!state.stopped) {
+ for (const history of tree.histories.values()) {
+ if (["no_reply", "incomplete"].includes(turnOutcome(history) ?? "")) throw new SerializedTurnError(RUNNING);
+ }
+ }
+ for (const [pending, before] of state.pending) {
+ const history = tree.histories.get(pending);
+ if (!history) throw new SerializedTurnError("The prior request could not be verified.", 503);
+ const outcome = turnOutcome(history);
+ if (latestPromptId(history) === before || !["completed", "stopped", "error"].includes(outcome ?? "")) {
+ throw new SerializedTurnError(RUNNING);
+ }
+ }
+ await bounded(async () => {
+ for (const sessionId of tree.sessionIds) await input.capture.settleTurn(sessionId);
+ }, 60_000);
+ check();
+ if (edit) {
+ for (const sessionId of tree.sessionIds) {
+ if (await input.capture.hasOpenTurn(sessionId)) {
+ throw new SerializedTurnError("This turn is paused. Send a correction to continue it; its original prompt and files must remain recorded.");
+ }
+ }
+ } else {
+ baselineStarted = true;
+ if (!await bounded(() => input.capture.promptStartGate(input.sessionId, input.workspaceId, input.root), 60_000)) {
+ throw new SerializedTurnError("The original workspace snapshot is unavailable. The message was not sent.", 503);
+ }
+ }
+ check();
+ const before = latestPromptId(tree.histories.get(input.sessionId) ?? []);
+ let finished = false;
+ return {
+ check,
+ finish: async (accepted) => {
+ if (finished) return;
+ finished = true;
+ if (!edit && accepted === true && generation === state.generation) {
+ state.pending.set(input.sessionId, before); state.stopped = false;
+ }
+ if (accepted === null) state.blocked = true; // Delivery may have succeeded: require verified Stop.
+ try {
+ if (!edit && accepted !== true) await input.capture.pauseTurn(input.sessionId, "dispatch_failed");
+ } finally { state.reserved = false; }
+ },
+ };
+ } catch (error) {
+ if (baselineStarted) await bounded(() => input.capture.pauseTurn(input.sessionId, "dispatch_cancelled"), 20_000).catch(() => { state.blocked = true; });
+ state.reserved = false;
+ throw error instanceof ApiError ? error : new SerializedTurnError("Capture could not verify the turn. The message was not sent.", 503);
+ }
+ }
+
+ async stop(input: Input): Promise<void> {
+ const signal = AbortSignal.timeout(20_000);
+ const { id, state } = await this.resolve(input, signal);
+ if (state.stopping) throw new SerializedTurnError("Stop is still in progress.");
+ state.stopping = true;
+ state.blocked = true;
+ state.generation++;
+ const deadline = Date.now() + 20_000;
+ const wait = <T>(work: () => Promise<T>) => bounded(work, Math.max(1, deadline - Date.now()));
+ let firstError: unknown;
+ try {
+ // Pause capture before cancellation can emit idle/completed events.
+ try { await wait(() => input.capture.pauseTurn(id, "user_stop")); } catch (error) { firstError = error; }
+ try { await stopEngineSession(input.target, id, signal); } catch (error) { firstError ??= error; }
+ const stopped = new Set([id]);
+ let quiet = 0;
+ for (;;) {
+ const tree = await readSessionTreeQuiescence(input.target, id, signal);
+ if (!tree.known) throw new SerializedTurnError("Subagent activity is unavailable. Retry Stop.", 503);
+ for (const sessionId of tree.sessionIds) {
+ if (!stopped.has(sessionId) || tree.busy) {
+ try { await wait(() => input.capture.pauseTurn(sessionId, "user_stop")); } catch (error) { firstError ??= error; }
+ try {
+ await stopEngineSession(input.target, sessionId, signal);
+ stopped.add(sessionId);
+ } catch (error) { firstError ??= error; }
+ }
+ }
+ quiet = !tree.busy && !state.reserved && tree.sessionIds.every(sessionId => stopped.has(sessionId)) ? quiet + 1 : 0;
+ if (quiet >= 2) {
+ for (const sessionId of tree.sessionIds) await wait(() => input.capture.settleTurn(sessionId));
+ if (firstError) throw firstError;
+ state.pending.clear();
+ state.stopped = true;
+ state.blocked = false;
+ return;
+ }
+ if (signal.aborted || Date.now() >= deadline) throw new SerializedTurnError("The agent or a subagent did not stop in time. Retry Stop.", 503);
+ await new Promise(resolve => setTimeout(resolve, 25));
+ }
+ } catch (error) {
+ throw error instanceof ApiError ? error : new SerializedTurnError("Stop could not be verified. Retry Stop before continuing.", 503);
+ } finally { state.stopping = false; }
+ }
+}
diff --git a/apps/server/src/server.ts b/apps/server/src/server.ts
index 814923df..1648c272 100644
--- a/apps/server/src/server.ts
+++ b/apps/server/src/server.ts
@@ -195,6 +195,7 @@ import { createEngineV2Preview, type EngineV2Preview } from "./engine-v2-preview
import { sessionUploaderEnabled } from "./session-uploader.js";
import { startCaptureService, type CaptureService } from "./capture-client.js";
import { buildOpencodeProxyUrl, engineTarget, type EngineTarget } from "./session-upload-observer.js";
+import { SerializedTurnGate, type SerializedTurnCapture, type TurnTicket } from "./serialized-turn-gate.js";
import { OmniRushGatewayBroker } from "./omnirush-gateway-broker.js";
import { awaitOmniRushModelCatalogSettled, startOmniRushModelCatalogSync } from "./omnirush-model-catalog-sync.js";
import { OmniRushVoiceService, voiceProjectContext } from "./omnirush-voice.js";
@@ -222,6 +223,7 @@ const agentDiagnosticsLastRunByServer = new WeakMap<ServerConfig, Map<string, nu
const agentDiagnosticsInFlightByServer = new WeakMap<ServerConfig, Set<string>>();
const commandAdmissionsByServer = new WeakMap<ServerConfig, Map<string, { fingerprint: string; admittedAt: number }>>();
const captureServicesByServer = new WeakMap<ServerConfig, CaptureService>();
+const serializedTurnGatesByServer = new WeakMap<ServerConfig, SerializedTurnGate>();
/** Voice dictation's broker hop (omnirush-voice.ts), per server. */
const voiceServicesByServer = new WeakMap<ServerConfig, OmniRushVoiceService>();
/** The broker's integrity read (rate-limited there), per server, for the checklist bar's "Good session ★". */
@@ -230,6 +232,22 @@ const sessionIntegrityByServer = new WeakMap<ServerConfig, OmniRushGatewayBroker
/** Recent gateway fallbacks per sub-agent session, for the swarm plugin's task-result note. */
const subagentGatewayFallbacks = new WeakMap<ServerConfig, Map<string, Array<Record<string, unknown>>>>();
+function serializedTurnGateFor(config: ServerConfig): SerializedTurnGate {
+ const existing = serializedTurnGatesByServer.get(config);
+ if (existing) return existing;
+ const gate = new SerializedTurnGate();
+ serializedTurnGatesByServer.set(config, gate);
+ return gate;
+}
+
+function supportsSerializedTurns(capture: CaptureService | undefined): capture is CaptureService & SerializedTurnCapture {
+ return Boolean(capture?.uploadEnabled
+ && "promptStartGate" in capture
+ && "pauseTurn" in capture
+ && "hasOpenTurn" in capture
+ && "settleTurn" in capture);
+}
+
/**
* Records a sub-agent model fallback: a "subagent.model_fallback" trace event
* on the main session the session uploader tracks (a gateway fallback also makes the
@@ -810,6 +828,7 @@ function admitSessionCommand(
config: ServerConfig,
scope: string,
admission: { messageId: string; fingerprint: string },
+ reserve = true,
): "accepted" | "duplicate" | "conflict" {
const now = Date.now();
const admissions = commandAdmissionsByServer.get(config) ?? new Map<string, { fingerprint: string; admittedAt: number }>();
@@ -823,6 +842,7 @@ function admitSessionCommand(
const existing = admissions.get(key);
if (existing) return existing.fingerprint === admission.fingerprint ? "duplicate" : "conflict";
+ if (!reserve) return "accepted";
if (admissions.size >= COMMAND_ADMISSION_CAPACITY) {
const oldest = admissions.keys().next().value;
if (oldest) admissions.delete(oldest);
@@ -838,7 +858,7 @@ function isPromptAsyncProxyRequest(method: string, proxyPath: string) {
// A prompt dispatch (v1 prompt_async, v2 prompt, or a slash command) is the
// session uploader's "prompt" milestone: the workspace is captured as the turn begins.
function isUploadPromptDispatch(method: string, proxyPath: string): boolean {
- return method === "POST" && /^\/session\/[^/]+\/(?:prompt_async|prompt|command)$/.test(normalizeOpencodeProxyPath(proxyPath));
+ return method === "POST" && /^\/session\/[^/]+\/(?:prompt_async|prompt|message|command|shell)$/.test(normalizeOpencodeProxyPath(proxyPath));
}
/**
@@ -907,7 +927,7 @@ export function createLocalWorkflowPromptDispatcher(config: ServerConfig): Local
// route path exactly as the engine reads its `:id` parameter. Null when the
// path is not a session request or its identifier is malformed.
function uploadSessionId(proxyPath: string): string | null {
- const match = normalizeOpencodeProxyPath(proxyPath).match(/^\/session\/([^/]+)\/(?:prompt_async|prompt|command|abort|interrupt)$/);
+ const match = normalizeOpencodeProxyPath(proxyPath).match(/^\/session\/([^/]+)\/(?:prompt_async|prompt|message|command|shell|abort|interrupt)$/);
return match?.[1] ? decodeEngineRouteParam(match[1]) : null;
}
@@ -1707,6 +1727,7 @@ export async function proxyOpencodeV2Request(input: {
throw new ApiError(403, "engine_instructions_managed", "OmniRush.ai instructions are managed by the server");
}
+ const prepareV2Instructions = async () => {
if (method === "POST" && sessionId && /^\/api\/session\/[^/]+\/(?:prompt|command|generate)$/.test(routePath)) {
// Session ownership was verified above. Replace one native instruction
// entry immediately before admission; never append to conversation text.
@@ -1733,6 +1754,8 @@ export async function proxyOpencodeV2Request(input: {
if (!synced.ok) throw new ApiError(502, "engine_instruction_sync_failed", "OmniRush.ai instructions could not be updated");
}
+ };
+
const requestBody = method === "GET" || method === "HEAD"
? undefined
: await input.request.arrayBuffer().then((buffer) => buffer.byteLength > 0 ? buffer : undefined);
@@ -1760,19 +1783,43 @@ export async function proxyOpencodeV2Request(input: {
const deletedUploadedSessionId = capture?.uploadEnabled && method === "DELETE" && sessionId && /^\/api\/session\/[^/]+$/.test(routePath)
? sessionId
: null;
- const engine = capture && uploadedSessionId ? engineTarget(input.connection.url, headers, target.search, "v2") : null;
- if (capture && uploadedSessionId && engine) {
- // Capture v2: the session-start manifest is taken before the prompt reaches the engine (at most about 3 s).
- await capture.archiveStartGate(uploadedSessionId, input.workspace.path);
- capture.startSession(uploadedSessionId, input.workspace.id, input.workspace.path);
- capture.recordPrompt(uploadedSessionId, { method, path: routePath, body: requestBody, engine: "v2", root: input.workspace.path, attachments: true, dispatchedAt: Date.now() });
- capture.captureSnapshot(uploadedSessionId, "prompt");
- capture.archiveSessionStarted(uploadedSessionId, input.workspace.path, engine);
- }
- const response = await loopbackFetch(target.toString(), { method, headers, body, signal: input.recoverySignal });
- if (capture && uploadedSessionId && engine) {
- capture.recordTrace(uploadedSessionId, "engine.response", { method, path: routePath, status: response.status });
- if (response.ok) capture.observeSession(uploadedSessionId, engine);
+ const engine = capture && sessionId ? engineTarget(input.connection.url, headers, target.search, "v2") : null;
+ let ticket: TurnTicket | undefined;
+ const mutableSession = method !== "GET" && method !== "HEAD" && sessionId;
+ // Internal task recovery is already serialized by task-recovery.ts and resumes the persisted capture group.
+ if (supportsSerializedTurns(capture) && !input.recoverySignal && mutableSession && engine) {
+ const gate = serializedTurnGateFor(input.config);
+ const admissionInput = {
+ key: input.workspace.id, sessionId, workspaceId: input.workspace.id,
+ root: input.workspace.path, target: engine, capture,
+ };
+ if (/^\/api\/session\/[^/]+\/(?:abort|interrupt)$/.test(routePath)) {
+ await gate.stop(admissionInput);
+ return jsonResponse({ data: true });
+ }
+ const edit = /\/(?:revert|unrevert|message(?:\/|$))/.test(routePath) && !promptDispatch;
+ if (promptDispatch || edit) ticket = await gate.admit(admissionInput, edit);
+ }
+ let response: Response;
+ try {
+ ticket?.check();
+ await prepareV2Instructions();
+ if (capture && uploadedSessionId && engine) {
+ await capture.archiveStartGate(uploadedSessionId, input.workspace.path);
+ ticket?.check();
+ capture.recordPrompt(uploadedSessionId, { method, path: routePath, body: requestBody, engine: "v2", root: input.workspace.path, attachments: true, dispatchedAt: Date.now() });
+ capture.archiveSessionStarted(uploadedSessionId, input.workspace.path, engine);
+ }
+ ticket?.check();
+ response = await loopbackFetch(target.toString(), { method, headers, body, signal: input.recoverySignal });
+ if (capture && uploadedSessionId && engine) {
+ capture.recordTrace(uploadedSessionId, "engine.response", { method, path: routePath, status: response.status });
+ if (response.ok) capture.observeSession(uploadedSessionId, engine);
+ }
+ await ticket?.finish(response.ok);
+ } catch (error) {
+ await ticket?.finish(null);
+ throw error;
}
if (capture && deletedUploadedSessionId && response.ok) capture.sessionDeleted(deletedUploadedSessionId);
if (method === "GET" && /^\/api\/provider(?:\/|$)/.test(decodedPath) && response.ok) {
@@ -2113,33 +2160,61 @@ export async function proxyOpencodeRequest(input: {
const body = method === "GET" || method === "HEAD"
? undefined
: await input.request.arrayBuffer().then((buf) => (buf.byteLength > 0 ? buf : undefined));
+ if (isSessionCommandProxyRequest(method, proxyPath)) {
+ const commandAdmission = commandAdmissionFromBody(body);
+ if (commandAdmission) {
+ const admissionTarget = workspace ? `workspace\0${workspace.id}` : `engine\0${baseUrl}`;
+ const admission = admitSessionCommand(
+ input.config,
+ `${admissionTarget}\0${normalizeOpencodeProxyPath(proxyPath)}`,
+ commandAdmission,
+ false,
+ );
+ if (admission === "duplicate") return jsonResponse({ ok: true, accepted: true });
+ if (admission === "conflict") {
+ return jsonResponse({
+ code: "command_admission_conflict",
+ message: "This command message ID was already admitted with different input",
+ }, 409);
+ }
+ }
+ }
const capture = workspace ? captureServicesByServer.get(input.config) : undefined;
const uploadedSessionId = uploadSessionId(proxyPath);
const deletedUploadedSessionId = uploadDeletedSessionId(method, proxyPath);
- // A chat the engine does not have (a stale tab, a deleted chat) is not
- // started: its prompt is refused, and it would only leave an empty start
- // and end snapshot behind.
- if (capture?.uploadEnabled && uploadedSessionId && workspace && workspace.workspaceType !== "remote"
- && (capture.hasSession(uploadedSessionId) || await engineHasSession(baseUrl, auth, directory, uploadedSessionId))) {
- const promptDispatch = isUploadPromptDispatch(method, proxyPath);
- // Capture v2: the session-start manifest is taken before the prompt reaches the engine (at most about 3 s).
- if (promptDispatch) await capture.archiveStartGate(uploadedSessionId, workspace.path);
- capture.startSession(uploadedSessionId, workspace.id, workspace.path);
- capture.recordPrompt(uploadedSessionId, {
- method,
- path: normalizeOpencodeProxyPath(proxyPath),
- body,
- engine: "v1",
- root: workspace.path,
- attachments: promptDispatch,
- // Taken before the engine sees the prompt: the session's previous turn ends here.
- ...(promptDispatch ? { dispatchedAt: Date.now() } : {}),
- });
- if (promptDispatch) {
- capture.captureSnapshot(uploadedSessionId, "prompt");
- capture.archiveSessionStarted(uploadedSessionId, workspace.path, engineTarget(baseUrl, headers, search));
+ const promptDispatch = isUploadPromptDispatch(method, proxyPath);
+ let ticket: TurnTicket | undefined;
+ const normalizedRoute = normalizeOpencodeProxyPath(proxyPath);
+ const routeSession = normalizedRoute.match(/^\/session\/([^/]+)(?:\/|$)/)?.[1];
+ const mutableSession = routeSession ? decodeEngineRouteParam(routeSession) : null;
+ // Internal task recovery is already serialized by task-recovery.ts and resumes the persisted capture group.
+ if (supportsSerializedTurns(capture) && !input.recoverySignal && mutableSession && workspace && workspace.workspaceType !== "remote"
+ && method !== "GET" && method !== "HEAD") {
+ const gate = serializedTurnGateFor(input.config);
+ const admissionInput = {
+ key: workspace.id, sessionId: mutableSession, workspaceId: workspace.id,
+ root: workspace.path, target: engineTarget(baseUrl, headers, search), capture,
+ };
+ if (/\/(?:abort|interrupt)$/.test(normalizedRoute)) {
+ await gate.stop(admissionInput);
+ return jsonResponse(true);
}
+ const edit = /\/(?:revert|unrevert|message(?:\/|$))/.test(normalizedRoute) && !promptDispatch;
+ if (promptDispatch || edit) ticket = await gate.admit(admissionInput, edit);
}
+ try {
+ if (capture?.uploadEnabled && uploadedSessionId && workspace && workspace.workspaceType !== "remote"
+ && (capture.hasSession(uploadedSessionId) || await engineHasSession(baseUrl, auth, directory, uploadedSessionId))) {
+ if (promptDispatch) await capture.archiveStartGate(uploadedSessionId, workspace.path);
+ ticket?.check();
+ if (!promptDispatch) capture.startSession(uploadedSessionId, workspace.id, workspace.path);
+ capture.recordPrompt(uploadedSessionId, {
+ method, path: normalizedRoute, body, engine: "v1", root: workspace.path,
+ attachments: promptDispatch, ...(promptDispatch ? { dispatchedAt: Date.now() } : {}),
+ });
+ if (promptDispatch) capture.archiveSessionStarted(uploadedSessionId, workspace.path, engineTarget(baseUrl, headers, search));
+ }
+ } catch (error) { await ticket?.finish(false); throw error; }
if (pool && method === "GET" && isEngineEventPath(proxyPath)) {
// An open engine event stream means this workspace is visible somewhere in
// the UI; hold its instance so the idle reaper leaves it alone until the
@@ -2199,25 +2274,15 @@ export async function proxyOpencodeRequest(input: {
const commandAdmission = commandAdmissionFromBody(body);
if (commandAdmission) {
const admissionTarget = workspace ? `workspace\0${workspace.id}` : `engine\0${baseUrl}`;
- const admission = admitSessionCommand(
- input.config,
- `${admissionTarget}\0${normalizeOpencodeProxyPath(proxyPath)}`,
- commandAdmission,
- );
- if (admission === "duplicate") return jsonResponse({ ok: true, accepted: true });
- if (admission === "conflict") {
- return jsonResponse({
- code: "command_admission_conflict",
- message: "This command message ID was already admitted with different input",
- }, 409);
- }
+ admitSessionCommand(input.config, `${admissionTarget}\0${normalizeOpencodeProxyPath(proxyPath)}`, commandAdmission);
}
const release = pool?.beginRequest(baseUrl, { method, proxyPath: decodeEngineRoutePath(proxyPath) });
+ ticket?.check();
void loopbackFetch(targetUrl, {
method,
headers,
body,
- }).finally(() => release?.()).then((response) => {
+ }).finally(() => release?.()).then(async (response) => {
enginePoolForConfig(input.config)?.reportRequestSuccess(baseUrl);
if (capture?.uploadEnabled && uploadedSessionId) {
capture.recordTrace(uploadedSessionId, "engine.response", {
@@ -2226,8 +2291,11 @@ export async function proxyOpencodeRequest(input: {
status: response.status,
});
if (workspace && response.ok) capture.observeSession(uploadedSessionId, engineTarget(baseUrl, headers, search));
+
}
- }).catch((error: unknown) => {
+ await ticket?.finish(response.ok);
+ }).catch(async (error: unknown) => {
+ await ticket?.finish(null);
if (workspace) enginePoolForConfig(input.config)?.reportRequestFailure(baseUrl, error, workspace);
if (capture?.uploadEnabled && uploadedSessionId) {
capture.recordTrace(uploadedSessionId, "engine.error", {
@@ -2243,6 +2311,7 @@ export async function proxyOpencodeRequest(input: {
const forward = async () => {
let response: Response;
for (let attempt = 0; ; attempt += 1) {
+ ticket?.check();
const release = pool?.beginRequest(served.baseUrl, { method, proxyPath: decodeEngineRoutePath(proxyPath) });
try {
response = attempt === 0
@@ -2302,6 +2371,7 @@ export async function proxyOpencodeRequest(input: {
};
const forwardAndUpload = async () => {
+ try {
const response = await forward();
if (capture?.uploadEnabled && uploadedSessionId) {
capture.recordTrace(uploadedSessionId, "engine.response", {
@@ -2310,9 +2380,12 @@ export async function proxyOpencodeRequest(input: {
status: response.status,
});
if (workspace && response.ok) capture.observeSession(uploadedSessionId, engineTarget(served.baseUrl, served.headers, search));
+
}
if (capture?.uploadEnabled && deletedUploadedSessionId && response.ok) capture.sessionDeleted(deletedUploadedSessionId);
+ await ticket?.finish(response.ok);
return response;
+ } catch (error) { await ticket?.finish(null); throw error; }
};
if (deletedUploadedSessionId && workspace && workspace.workspaceType !== "remote") {
diff --git a/apps/server/src/session-upload-observer.ts b/apps/server/src/session-upload-observer.ts
index 7285d736..686bfddf 100644
--- a/apps/server/src/session-upload-observer.ts
+++ b/apps/server/src/session-upload-observer.ts
@@ -123,7 +123,8 @@ export function engineReplaced(observers: SessionObservers, closedBaseUrl: strin
* the new prompt's own snapshot, so both turns keep their turn.diff, and
* the observer settles it with the messages from before this prompt.
*/
-export function promptDispatched(observers: SessionObservers, sessionUploader: Pick<ObservedUploader, "captureSnapshot">, sessionId: string, at: number): void {
+export function promptDispatched(observers: SessionObservers, sessionUploader: Pick<ObservedUploader, "captureSnapshot" | "hasOpenTurn">, sessionId: string, at: number): void {
+ if (sessionUploader.hasOpenTurn?.(sessionId)) return; // Serialized prompts never cut an active baseline.
const turn = observers.sessions.get(sessionId)?.turn;
if (!turn || turn.cutAt !== null) return;
turn.cutAt = at;
@@ -146,7 +147,7 @@ export type ObservedUploader = Pick<
| "noteChildSessionIds"
| "captureSnapshot"
| "flushTrace"
->;
+> & { hasOpenTurn?: (sessionId: string) => boolean; isTurnPaused?: (sessionId: string) => boolean };
/** An engine target from a proxied request's headers, without the body headers of that request. */
export function engineTarget(baseUrl: string, headers: Headers, search: string, engine: "v1" | "v2" = "v1"): EngineTarget {
@@ -299,20 +300,25 @@ async function captureChildSessions(input: {
parentSessionId: string;
depth: number;
fetchEngine: EngineFetch;
+ v2: boolean;
checkpoints: Record<string, string>;
known: Set<string>;
visited: Set<string>;
beforeRecord: (bytes: number) => void;
}): Promise<void> {
if (input.depth > MAX_UPLOAD_CHILD_SESSION_DEPTH) return;
- const children = await readEngineJson(input.fetchEngine, `/session/${encodeURIComponent(input.parentSessionId)}/children`, 1024 * 1024)
- .catch(nullOnErrorStatus);
+ const children = await readChildRecords({ fetchEngine: input.fetchEngine, parentSessionId: input.parentSessionId, v2: input.v2 })
+ .catch(error => { if (input.sessionUploader.hasOpenTurn?.(input.rootSessionId)) throw error; return nullOnErrorStatus(error); });
if (!Array.isArray(children)) return;
for (const child of children.slice(0, 200)) {
- const childId = isRecord(child) && typeof child.id === "string" && child.id ? child.id : null;
+ const childId = sessionRecordId(child);
if (!childId || childId === input.rootSessionId || input.visited.has(childId)) continue;
input.visited.add(childId);
- const history = await readEngineHistory(engineMessages(input.fetchEngine, `/session/${encodeURIComponent(childId)}/message`, true), input.checkpoints[childId])
+ const history = await readEngineHistory(engineMessages(
+ input.fetchEngine,
+ input.v2 ? `/api/session/${encodeURIComponent(childId)}/context` : `/session/${encodeURIComponent(childId)}/message`,
+ !input.v2,
+ ), input.checkpoints[childId])
.catch(nullOnErrorStatus);
const newMessages = history?.delta ?? [];
if (history && history.omitted > 0) {
@@ -324,7 +330,7 @@ async function captureChildSessions(input: {
childSessionId: childId,
parentSessionId: input.parentSessionId,
depth: input.depth,
- title: isRecord(child) ? optionalTraceString(child.title) : null,
+ title: optionalTraceString(sessionRecordInfo(child)?.title),
agent: turnModelFromMessages(history?.outline ?? [])?.agent ?? null,
messages: newMessages,
lastMessageId: traceMessageId(history?.outline.at(-1)),
@@ -339,18 +345,19 @@ async function captureChildSessions(input: {
* at most MAX_UPLOAD_CHILD_SESSION_DEPTH layers down. A layer the engine
* cannot list (an error status) is left out.
*/
-async function childSessionIdsBelow(fetchEngine: EngineFetch, rootSessionId: string): Promise<string[]> {
+async function childSessionIdsBelow(fetchEngine: EngineFetch, rootSessionId: string, v2: boolean): Promise<string[]> {
const ids: string[] = [];
const seen = new Set([rootSessionId]);
let layer = [rootSessionId];
+ const v2Sessions = v2 ? await readV2SessionList(fetchEngine) : undefined;
for (let depth = 1; depth <= MAX_UPLOAD_CHILD_SESSION_DEPTH && layer.length > 0; depth += 1) {
const next: string[] = [];
for (const parent of layer) {
- const children = await readEngineJson(fetchEngine, `/session/${encodeURIComponent(parent)}/children`, 1024 * 1024)
+ const children = await readChildRecords({ fetchEngine, parentSessionId: parent, v2, ...(v2Sessions ? { v2Sessions } : {}) })
.catch(nullOnErrorStatus);
if (!Array.isArray(children)) continue;
for (const child of children.slice(0, 200)) {
- const id = isRecord(child) && typeof child.id === "string" && child.id ? child.id : null;
+ const id = sessionRecordId(child);
if (!id || seen.has(id)) continue;
seen.add(id);
ids.push(id);
@@ -423,6 +430,149 @@ async function readEngineJson(fetchEngine: EngineFetch, path: string, maxBytes?:
return readObservedResponse(response, maxBytes);
}
+function enginePayload(payload: unknown, v2: boolean): unknown {
+ return v2 && isRecord(payload) && "data" in payload ? payload.data : payload;
+}
+
+function sessionRecordInfo(record: unknown): Record<string, unknown> | null {
+ if (!isRecord(record)) return null;
+ return isRecord(record.info) ? record.info : record;
+}
+
+function sessionRecordId(record: unknown): string | null {
+ const info = sessionRecordInfo(record);
+ return typeof info?.id === "string" && info.id ? info.id : null;
+}
+
+function sessionRecordParentId(record: unknown): string | null {
+ const info = sessionRecordInfo(record);
+ const parent = info?.parentID ?? info?.parentId ?? info?.parent_id;
+ return typeof parent === "string" && parent ? parent : null;
+}
+
+async function readStatusPayload(fetchEngine: EngineFetch, v2: boolean): Promise<Record<string, unknown>> {
+ const payload = enginePayload(await readEngineJson(fetchEngine, v2 ? "/api/session/active" : "/session/status", 1024 * 1024), v2);
+ if (!isRecord(payload)) throw new Error("the engine status map could not be read");
+ return payload;
+}
+
+function statusBusy(statuses: Record<string, unknown>, sessionId: string): boolean | null {
+ const status = statuses[sessionId];
+ if (status === undefined) return false;
+ if (!isRecord(status) || typeof status.type !== "string") return null;
+ if (!["idle", "busy", "retry", "running"].includes(status.type)) return null;
+ return status.type !== "idle";
+}
+
+async function readV2SessionList(fetchEngine: EngineFetch): Promise<unknown[]> {
+ const payload = enginePayload(await readEngineJson(fetchEngine, "/api/session", 1024 * 1024), true);
+ if (!Array.isArray(payload)) throw new Error("the engine session list could not be read");
+ return payload;
+}
+
+async function readChildRecords(input: { fetchEngine: EngineFetch; parentSessionId: string; v2: boolean; v2Sessions?: readonly unknown[] }): Promise<unknown[]> {
+ if (input.v2) {
+ const sessions = input.v2Sessions ?? await readV2SessionList(input.fetchEngine);
+ return sessions.filter((record) => sessionRecordParentId(record) === input.parentSessionId).slice(0, 200);
+ }
+ const children = await readEngineJson(input.fetchEngine, `/session/${encodeURIComponent(input.parentSessionId)}/children`, 1024 * 1024);
+ if (!Array.isArray(children)) throw new Error("the engine child session list could not be read");
+ return children.slice(0, 200);
+}
+
+export type SessionTreeQuiescence =
+ | { known: true; busy: boolean; sessionIds: string[]; histories: Map<string, unknown[]> }
+ | { known: false; error: string; sessionIds: string[] };
+
+async function readSessionTreeIds(input: { fetchEngine: EngineFetch; rootSessionId: string; v2: boolean }): Promise<string[]> {
+ const sessions = input.v2 ? await readV2SessionList(input.fetchEngine) : null;
+ const ids = new Set([input.rootSessionId]);
+ const queue = [input.rootSessionId];
+ for (const parent of queue) {
+ const children = sessions
+ ? sessions.filter(record => sessionRecordParentId(record) === parent)
+ : await readEngineJson(input.fetchEngine, `/session/${encodeURIComponent(parent)}/children`, 1024 * 1024);
+ if (!Array.isArray(children)) throw new Error("delegated session list is unavailable");
+ for (const child of children) {
+ const id = sessionRecordId(child);
+ if (!id || sessionRecordParentId(child) !== parent || ids.has(id)) throw new Error("invalid delegated session tree");
+ if (ids.size >= 256) throw new Error("too many delegated sessions to confirm quiescence");
+ ids.add(id); queue.push(id);
+ }
+ }
+ return [...ids];
+}
+
+export async function readEngineSessionRoot(target: EngineTarget, sessionId: string, signal?: AbortSignal): Promise<string> {
+ const fetchEngine = engineFetch(() => target, () => signal ?? AbortSignal.timeout(10_000));
+ const visited = new Set<string>();
+ let id = sessionId;
+ for (;;) {
+ if (visited.has(id) || visited.size >= 256) throw new Error("invalid session ancestry");
+ visited.add(id);
+ const raw = enginePayload(await readEngineJson(fetchEngine,
+ `${target.engine === "v2" ? "/api" : ""}/session/${encodeURIComponent(id)}`, 1024 * 1024), target.engine === "v2");
+ if (sessionRecordId(raw) !== id) throw new Error("session ancestry is unavailable");
+ const parent = sessionRecordParentId(raw);
+ if (!parent) return id;
+ id = parent;
+ }
+}
+
+export async function stopEngineSession(target: EngineTarget, sessionId: string, signal: AbortSignal): Promise<void> {
+ const url = new URL(buildOpencodeProxyUrl(target.baseUrl,
+ `${target.engine === "v2" ? "/api" : ""}/session/${encodeURIComponent(sessionId)}/${target.engine === "v2" ? "interrupt" : "abort"}`, target.search));
+ const response = await loopbackFetch(url.toString(), { method: "POST", headers: new Headers(target.headers), signal });
+ await response.body?.cancel().catch(() => undefined);
+ if (!response.ok) throw new Error("the engine did not acknowledge Stop");
+}
+
+export function latestPromptId(history: readonly unknown[]): string | null {
+ for (const message of [...history].reverse()) {
+ if (isRecord(message) && isPromptMessage(message)) return traceMessageId(message);
+ }
+ return null;
+}
+
+export async function readSessionTreeQuiescence(target: EngineTarget, rootSessionId: string, signal?: AbortSignal): Promise<SessionTreeQuiescence> {
+ const fetchEngine = engineFetch(() => target, () => signal ? AbortSignal.any([signal, AbortSignal.timeout(10_000)]) : AbortSignal.timeout(10_000));
+ let sessionIds = [rootSessionId];
+ try {
+ const v2 = target.engine === "v2";
+ sessionIds = await readSessionTreeIds({ fetchEngine, rootSessionId, v2 });
+ const statuses = await readStatusPayload(fetchEngine, v2);
+ let busy = false;
+ for (const id of sessionIds) {
+ const status = statusBusy(statuses, id);
+ if (status === null) throw new Error("the engine status map had an unknown shape");
+ busy ||= status;
+ }
+ const histories = new Map<string, unknown[]>();
+ // Fast path while running: full histories are only checked at a boundary.
+ if (busy) return { known: true, busy, sessionIds, histories };
+ let bytes = 0;
+ for (const id of sessionIds) {
+ const history: unknown[] = [];
+ for await (const entry of engineMessages(fetchEngine,
+ v2 ? `/api/session/${encodeURIComponent(id)}/context` : `/session/${encodeURIComponent(id)}/message`, !v2)) {
+ if (!entry.whole) throw new Error("tool activity could not be verified from the complete transcript");
+ bytes += JSON.stringify(entry.message).length;
+ if (bytes > 64 * 1024 * 1024) throw new Error("tool activity exceeds the boundary read budget");
+ history.push(entry.message);
+ if (!isRecord(entry.message)) throw new Error("invalid engine message");
+ const info = sessionRecordInfo(entry.message);
+ const parts = Array.isArray(entry.message.parts) ? entry.message.parts : Array.isArray(info?.content) ? info.content : [];
+ if (parts.some(part => isRecord(part) && part.type === "tool" && isRecord(part.state)
+ && ["pending", "running", "streaming"].includes(String(part.state.status)))) busy = true;
+ }
+ histories.set(id, history.reverse());
+ }
+ return { known: true, busy, sessionIds, histories };
+ } catch (error) {
+ return { known: false, error: errorMessage(error), sessionIds };
+ }
+}
+
/**
* The info of a message too large to read whole, from the start of its
* one-message page (`[{"info":{...},"parts":[...]}]`): its id, role and
@@ -568,7 +718,7 @@ export function turnOutcome(outline: readonly unknown[]): TurnOutcome | null {
const name = isRecord(error) ? error.name ?? error.type : error;
return name === "MessageAbortedError" || name === "aborted" ? "stopped" : "error";
}
- return isFinishedAssistantMessage(last) ? "completed" : "incomplete";
+ return info.finish !== "tool-calls" && info.finish !== "unknown" && isFinishedAssistantMessage(last) ? "completed" : "incomplete";
}
async function messageOutlines(messages: AsyncIterable<EngineMessage>): Promise<unknown[]> {
@@ -850,6 +1000,8 @@ export function observeUploadedSession(input: {
...input.timing,
};
const stopped = observer.controller.signal;
+ const serialized = sessionUploader.hasOpenTurn?.(sessionId) === true;
+ let forcedIncomplete = false;
const v2 = input.target.engine === "v2";
const target = () => session.target;
const fetchStatus = engineFetch(target, () => AbortSignal.any([stopped, AbortSignal.timeout(timing.statusTimeoutMs)]));
@@ -867,7 +1019,7 @@ export function observeUploadedSession(input: {
let turnArchived = false;
const turnState = (): FollowedTurn => (session.turn ??= { snapshotTaken: false, cutAt: null });
/** The followed turn's turn_completed snapshot, unless it was taken already ("aborted": the user stopped it). */
- const captureTurnSnapshot = (outcome?: "aborted"): void => {
+ const captureTurnSnapshot = (outcome?: "aborted" | "error" | "incomplete"): void => {
const turn = turnState();
if (turn.snapshotTaken) return;
turn.snapshotTaken = true;
@@ -915,7 +1067,7 @@ export function observeUploadedSession(input: {
try {
history ??= await readHistory();
const cutAt = session.turn?.cutAt ?? null;
- if (cutAt !== null) history = historyBefore(history, cutAt).history;
+ if (!serialized && cutAt !== null) history = historyBefore(history, cutAt).history;
} catch (error) {
if (stopped.aborted) throw error;
if (error instanceof EngineReadError) unavailable = { status: error.status, unavailable: true };
@@ -960,24 +1112,24 @@ export function observeUploadedSession(input: {
}
pending += bytes;
};
- // The v2 daemon has no subagent children route; only its root turn is captured.
- if (!v2) {
- try {
- await captureChildSessions({
- sessionUploader,
- rootSessionId: sessionId,
- parentSessionId: sessionId,
- depth: 1,
- fetchEngine,
- checkpoints: await sessionUploader.childCheckpoints(sessionId),
- known: new Set(await sessionUploader.childSessionIds(sessionId)),
- visited: new Set([sessionId]),
- beforeRecord: room,
- });
- } catch (error) {
- if (stopped.aborted) throw error;
- sessionUploader.recordTrace(sessionId, "session.children_failed", { error: errorMessage(error) });
- }
+ let childCaptureFailed = false;
+ try {
+ await captureChildSessions({
+ sessionUploader,
+ rootSessionId: sessionId,
+ parentSessionId: sessionId,
+ depth: 1,
+ fetchEngine,
+ v2,
+ checkpoints: await sessionUploader.childCheckpoints(sessionId),
+ known: new Set(await sessionUploader.childSessionIds(sessionId)),
+ visited: new Set([sessionId]),
+ beforeRecord: room,
+ });
+ } catch (error) {
+ if (stopped.aborted) throw error;
+ childCaptureFailed = true;
+ sessionUploader.recordTrace(sessionId, "session.children_failed", { error: errorMessage(error) });
}
room(newest.bytes);
// How the turn ended, so a turn stopped with Esc reads as stopped, not as answered.
@@ -988,7 +1140,9 @@ export function observeUploadedSession(input: {
// The turn snapshot runs first so the artifacts it discovers are part of
// the trace flushed right behind it.
// A turn the user stopped (Esc, Stop) says so on its trigger and its turn.completed event too.
- const aborted = outcome === "stopped" ? ("aborted" as const) : undefined;
+ const aborted = outcome === "stopped" || (serialized && sessionUploader.isTurnPaused?.(sessionId)) ? ("aborted" as const)
+ : serialized && (forcedIncomplete || !history || childCaptureFailed || outcome !== "completed") ? ("incomplete" as const)
+ : undefined;
captureTurnSnapshot(aborted);
sessionUploader.flushTrace(sessionId, {
messages: history ? newest.messages : unavailable,
@@ -1004,7 +1158,8 @@ export function observeUploadedSession(input: {
if (history) input.archive.turnMessages?.(sessionId, history.delta);
// Files used: the files the turn's tool calls used, and the end-of-turn snapshot, ahead of its delta.
if (history) input.archive.turnFilesUsed?.(sessionId, history.delta);
- input.archive.turnCompleted(sessionId, history ? history.outline : null);
+ if (serialized && aborted) input.archive.turnIncomplete(sessionId);
+ else input.archive.turnCompleted(sessionId, history ? history.outline : null);
};
/**
@@ -1059,7 +1214,7 @@ export function observeUploadedSession(input: {
sessionUploader.recordTrace(sessionId, "session.engine_recovered", { failures, unavailable_ms: timing.now() - unavailableSince });
}
// A turn a previous process left open: an idle session has nothing more to wait for.
- if (recovering && status === "idle") {
+ if (!serialized && recovering && status === "idle") {
await settle(status);
return session.requests;
}
@@ -1067,7 +1222,7 @@ export function observeUploadedSession(input: {
unavailableSince = null;
unavailableTraced = false;
const cutAt = session.turn?.cutAt ?? null;
- if (cutAt !== null) {
+ if (!serialized && cutAt !== null) {
// The next prompt went out before this turn settled. The turn ends
// with the messages from before that prompt once they are all there:
// its answer finished (the session may be busy with the next turn),
@@ -1093,10 +1248,10 @@ export function observeUploadedSession(input: {
observedBusy = true;
idleReads = 0;
// The v2 daemon has no children route: nothing to list there.
- if (!v2 && timing.now() - childIdsAt >= CHILD_IDS_INTERVAL_MS) {
+ if (timing.now() - childIdsAt >= CHILD_IDS_INTERVAL_MS) {
childIdsAt = timing.now();
try {
- sessionUploader.noteChildSessionIds(sessionId, await childSessionIdsBelow(fetchEngine, sessionId));
+ sessionUploader.noteChildSessionIds(sessionId, await childSessionIdsBelow(fetchEngine, sessionId, v2));
} catch (error) {
if (stopped.aborted) throw error;
}
@@ -1107,6 +1262,14 @@ export function observeUploadedSession(input: {
idleSince = timing.now();
requestsWhenIdle = session.requests;
}
+ if (serialized) {
+ const tree = await readSessionTreeQuiescence(session.target, sessionId, stopped);
+ if (!tree.known || tree.busy) {
+ idleReads = 0;
+ if (!tree.known) failures += 1;
+ continue;
+ }
+ }
idleReads += 1;
if (idleReads < 2 || reads < 4) continue;
// Never seen busy: the turn settled only once its answer ended (the prompt may not have started yet).
@@ -1123,7 +1286,7 @@ export function observeUploadedSession(input: {
// No longer followed, the turn still gets its snapshot and turn.diff: the
// next prompt would otherwise measure its own turn from past these edits.
// Its messages are left after the checkpoint for the next settled turn.
- captureTurnSnapshot();
+ captureTurnSnapshot(serialized ? "incomplete" : undefined);
sessionUploader.flushTrace(sessionId);
// And the project archive its delta, or a final archive of the folder.
turnArchived = true;
@@ -1134,6 +1297,10 @@ export function observeUploadedSession(input: {
session.settleNow = async () => {
if (!session.turn || session.turn.settled) return;
sessionUploader.recordTrace(sessionId, "session.quit_settled", {});
+ if (serialized) {
+ const tree = await readSessionTreeQuiescence(session.target, sessionId, stopped);
+ forcedIncomplete = !tree.known || tree.busy;
+ }
await settle("quit");
};
session.done = (async () => {
@@ -1152,7 +1319,7 @@ export function observeUploadedSession(input: {
})().catch((error: unknown) => {
if (!stopped.aborted) {
sessionUploader.recordTrace(sessionId, "session.observer_failed", { error: errorMessage(error) });
- if (!session.turn?.snapshotTaken) sessionUploader.captureSnapshot(sessionId, "turn_completed");
+ if (!session.turn?.snapshotTaken) sessionUploader.captureSnapshot(sessionId, "turn_completed", serialized ? "incomplete" : undefined);
sessionUploader.flushTrace(sessionId);
// The project archive hears of the turn's end once: its delta, or a final archive of the folder.
if (!turnArchived) input.archive.turnIncomplete(sessionId);
diff --git a/apps/server/src/session-uploader.server.e2e.test.ts b/apps/server/src/session-uploader.server.e2e.test.ts
index 55475f1d..d314f28f 100644
--- a/apps/server/src/session-uploader.server.e2e.test.ts
+++ b/apps/server/src/session-uploader.server.e2e.test.ts
@@ -238,6 +238,7 @@ function startMockV2Engine(input: { provider: string; model: string }) {
return Response.json({ error: "unauthorized" }, { status: 401 });
}
if (pathname === "/api/session/active") return Response.json({ data: busy ? { ses_v2root: { type: "running" } } : {} });
+ if (pathname === "/api/session") return Response.json({ data: [{ id: "ses_v2root" }] });
if (pathname === "/api/mcp" || pathname === "/api/skill") return Response.json({ data: [] });
if (pathname === "/api/session/ses_v2root/instructions/entries/omnirush.context" && request.method === "PUT") return Response.json({ data: {} });
if (pathname === "/api/session/ses_v2root/prompt" && request.method === "POST") {
@@ -524,10 +525,10 @@ describe("session uploader server integration", () => {
expect(childEvents(turnOne)).toEqual([["ses_child", ["child_1"]], ["ses_grandchild", ["grand_1"]], ["ses_great", ["great_1"]]]);
// Turn 2: only the child spoke again, and only its new message is uploaded.
expect(childEvents(turnTwo)).toEqual([["ses_child", ["child_2"]]]);
- expect(events(turnTwo).find((event) => event.type === "turn.completed")?.data).toEqual({
- messages: expect.arrayContaining([expect.objectContaining({ info: expect.objectContaining({ id: "assistant_2" }) })]),
- });
- expect((events(turnTwo).find((event) => event.type === "turn.completed")?.data?.messages as unknown[]).length).toBe(2);
+ const secondMessages = events(turnTwo).find((event) => event.type === "turn.completed")?.data?.messages;
+ expect(Array.isArray(secondMessages)).toBe(true);
+ expect(secondMessages).toHaveLength(2);
+ expect(JSON.stringify(secondMessages)).toContain('"id":"assistant_2"');
// Restart: the ledger carries the root and per-child checkpoints forward.
const second = await startOmniRush({ ...config, startedAt: Date.now() });
diff --git a/apps/server/src/session-uploader.test.ts b/apps/server/src/session-uploader.test.ts
index 5f02ce40..0d6d931f 100644
--- a/apps/server/src/session-uploader.test.ts
+++ b/apps/server/src/session-uploader.test.ts
@@ -4226,3 +4226,83 @@ describe("integrity confirmation", () => {
expect(integrityFindings("nope")).toBeNull();
});
});
+
+describe("serialized logical turns", () => {
+ type ProofEvent = { type: string; data: {
+ group_id?: string; phase?: string; prompt_count?: number; baseline_snapshot?: { segment: number; sequence: number };
+ trigger?: string; files?: Array<{ path: string; status: string; diff?: string }>;
+ messages?: Array<{ info: { id: string; role: string } }>;
+ } };
+ for (const restart of [false, true]) test("preserves the original baseline after Stop" + (restart ? " and restart" : ""), async () => {
+ const root = await mkdtemp(join(tmpdir(), "serialized-gui-project-")); roots.push(root);
+ const stateDir = await mkdtemp(join(tmpdir(), "serialized-gui-state-")); roots.push(stateDir);
+ await writeFile(join(root, "a.txt"), "original\n");
+ const events: ProofEvent[] = [];
+ const options: ConstructorParameters<typeof SessionUploader>[0] = {
+ stateDir, toolchain: false, context: false, confirm: false,
+ upload: async (_id: string, compressed: Uint8Array) => {
+ const envelope: { snapshot_type: string; trace?: ProofEvent[]; files?: Array<{ path: string; content: string }> } =
+ JSON.parse(zstdDecompressSync(Buffer.from(compressed)).toString("utf8"));
+ if (envelope.snapshot_type === "trace") {
+ const trace: { events?: ProofEvent[] } = JSON.parse(envelope.files?.find(file => file.path === "__omnirush__/trace.json")?.content ?? "{}");
+ events.push(...(envelope.trace ?? trace.events ?? []));
+ }
+ return Response.json({}, { status: 201 });
+ },
+ };
+ const id = "ses_serialized_gui_fixture";
+ let uploader = new SessionUploader(options);
+ try {
+ uploader.startSession(id, "workspace", root);
+ expect(await uploader.beginTurn(id)).toBe(true);
+ await writeFile(join(root, "a.txt"), "partial\n");
+ await writeFile(join(root, "cli.py"), "child created this\n");
+ await uploader.pauseTurn(id);
+ uploader.captureSnapshot(id, "turn_completed", "aborted");
+ uploader.flushTrace(id, { messages: [{ info: { id: "u1", role: "user" }, parts: [{ type: "text", text: "original task" }] }] });
+ await uploader.idle(id);
+ if (restart) {
+ await uploader.stop();
+ uploader = new SessionUploader(options);
+ uploader.startSession(id, "workspace", root);
+ }
+ expect(await uploader.beginTurn(id)).toBe(true);
+ await writeFile(join(root, "a.txt"), "finished\n");
+ uploader.captureSnapshot(id, "turn_completed");
+ uploader.flushTrace(id, { messages: [{ info: { id: "u2", role: "user" }, parts: [{ type: "text", text: "correction" }] }] });
+ await uploader.idle(id);
+ const groups = events.filter(event => event.type === "collector.replay_group").map(event => event.data);
+ expect(new Set(groups.map(group => group.group_id)).size).toBe(1);
+ expect(groups.some(group => group.phase === "resumed" && group.prompt_count === 2)).toBe(true);
+ expect(groups.at(-1)?.phase).toBe("completed");
+ expect(groups[0]?.baseline_snapshot?.sequence).toBeGreaterThan(0);
+ expect(groups.at(-1)?.baseline_snapshot).toEqual(groups[0]?.baseline_snapshot);
+ const diff = events.filter(event => event.type === "turn.diff").at(-1)?.data.files;
+ expect(diff?.find(file => file.path === "a.txt")?.diff).toContain("-original");
+ expect(diff?.find(file => file.path === "a.txt")?.diff).toContain("+finished");
+ expect(diff?.find(file => file.path === "cli.py")?.status).toBe("added");
+ expect(events.filter(event => event.type === "collector.trigger" && event.data.trigger === "prompt").length).toBe(1);
+ expect(events.filter(event => event.type === "turn.completed").flatMap(event => event.data.messages ?? []).map(message => message.info.id)).toEqual(["u1", "u2"]);
+ expect(await uploader.beginTurn(id)).toBe(true);
+ uploader.flushTrace(id); await uploader.idle(id);
+ expect(new Set(events.filter(event => event.type === "collector.replay_group").map(event => event.data.group_id)).size).toBe(2);
+ } finally { await uploader.stop(); }
+ });
+
+ test("does not reuse an old accepted snapshot when the new one is refused", async () => {
+ const root = await mkdtemp(join(tmpdir(), "serialized-gui-refused-")); roots.push(root);
+ await writeFile(join(root, "a.txt"), "old");
+ let refuse = false;
+ const uploader = new SessionUploader({
+ toolchain: false, context: false,
+ upload: async () => Response.json({}, { status: refuse ? 400 : 201 }),
+ });
+ const id = "ses_serialized_gui_failure";
+ try {
+ uploader.startSession(id, "workspace", root); await uploader.idle(id);
+ await writeFile(join(root, "a.txt"), "changed before prompt");
+ refuse = true;
+ expect(await uploader.beginTurn(id)).toBe(false);
+ } finally { await uploader.stop(); }
+ });
+});
diff --git a/apps/server/src/session-uploader.ts b/apps/server/src/session-uploader.ts
index dd885915..6527245b 100644
--- a/apps/server/src/session-uploader.ts
+++ b/apps/server/src/session-uploader.ts
@@ -227,7 +227,7 @@ export type UploadTrigger =
| "trace_flush";
/** How a turn ended, when not as answered: "aborted" is a turn the user stopped (Esc, Stop). */
-export type TurnEndOutcome = "aborted";
+export type TurnEndOutcome = "aborted" | "error" | "incomplete";
type ChangeTrigger = Extract<UploadTrigger, "prompt" | "turn_completed" | "fs_change" | "periodic">;
type UploadFile = {
@@ -434,6 +434,23 @@ type SessionLedgerRecord = {
endedAt?: string;
/** The server's word on the chat (GET /me/sessions/{id}/integrity). */
confirmation?: SessionConfirmation;
+ /** A logical turn left open by a pause, error, or process restart. */
+ replayGroup?: ReplayGroupRecord;
+};
+
+type ReplayGroupPhase = "active" | "paused" | "incomplete";
+
+type ReplayGroupRecord = {
+ id: string;
+ phase: ReplayGroupPhase;
+ promptCount: number;
+ startedAt: number;
+ messageIds?: string[];
+ baselineSnapshot?: { segment: number; sequence: number };
+};
+
+type ReplayGroupState = ReplayGroupRecord & {
+ baselineUnavailable: boolean;
};
/** The integrity check's state for one chat: final once the server says good or not good. */
@@ -553,6 +570,12 @@ type SessionState = {
turnStartedAt: number | null;
/** A prompt was dispatched and its turn has not completed (its turn_completed milestone ends it). */
turnInProgress: boolean;
+ replayGroup: ReplayGroupState | null;
+ replayFailure: string | null;
+ replayTail: Promise<void>;
+ startingReplayGroup: boolean;
+ captureVerified: boolean;
+ lastWorkspaceCapture: { segment: number; sequence: number } | null;
/**
* Edits were made on this session's root while it had no turn in progress
* and another session on the root had one: they are that turn's, and this
@@ -630,6 +653,7 @@ type JournalMeta = {
segment: number;
/** A prompt went out and its turn has not ended. */
turn_open: boolean;
+ replay_group?: ReplayGroupRecord;
at: string;
};
@@ -637,6 +661,7 @@ function parseJournalMeta(value: unknown): JournalMeta | null {
if (!isRecord(value) || value.v !== 1 || typeof value.session_id !== "string" || typeof value.workspace_id !== "string"
|| typeof value.root !== "string" || !Number.isSafeInteger(value.segment) || typeof value.turn_open !== "boolean"
|| typeof value.at !== "string") return null;
+ const replayGroup = replayGroupRecord(value.replay_group);
return {
v: 1,
session_id: value.session_id,
@@ -644,6 +669,7 @@ function parseJournalMeta(value: unknown): JournalMeta | null {
root: value.root,
segment: Number(value.segment),
turn_open: value.turn_open,
+ ...(replayGroup ? { replay_group: replayGroup } : {}),
at: value.at,
};
}
@@ -2474,6 +2500,60 @@ function ledgerModel(value: unknown): UploadSessionModel | undefined {
return model.provider_id || model.model_id ? model : undefined;
}
+
+function savedPathTimes(value: unknown): Map<string, number> {
+ const result = new Map<string, number>();
+ if (!Array.isArray(value)) return result;
+ for (const entry of value) {
+ if (Array.isArray(entry) && typeof entry[0] === "string" && typeof entry[1] === "number") result.set(entry[0], entry[1]);
+ }
+ return result;
+}
+
+function savedTurnBaseline(value: unknown): TurnBaseline | null {
+ if (!Array.isArray(value)) return null;
+ const result = new Map<string, HashCacheEntry | null>();
+ for (const entry of value) {
+ if (!Array.isArray(entry) || entry.length !== 2 || typeof entry[0] !== "string" ||
+ nodePath.isAbsolute(entry[0]) || entry[0].split(/[\\/]/).includes("..")) return null;
+ const item = entry[1];
+ if (item === null) { result.set(entry[0], null); continue; }
+ if (!isRecord(item) || typeof item.size !== "number" || typeof item.mtimeMs !== "number" ||
+ typeof item.ctimeMs !== "number" || typeof item.ino !== "number" || typeof item.dev !== "number" ||
+ typeof item.binary !== "boolean" || typeof item.sha256 !== "string" || !SHA256_HEX.test(item.sha256) ||
+ typeof item.bytes !== "number" || typeof item.json !== "number" || typeof item.clean !== "boolean" ||
+ typeof item.uploadPath !== "string") return null;
+ result.set(entry[0], {
+ size: item.size, mtimeMs: item.mtimeMs, ctimeMs: item.ctimeMs, ino: item.ino, dev: item.dev,
+ binary: item.binary, sha256: item.sha256, bytes: item.bytes, json: item.json, clean: item.clean,
+ uploadPath: item.uploadPath, ...(typeof item.mode === "number" ? { mode: item.mode } : {}),
+ });
+ }
+ return result;
+}
+
+function replayGroupRecord(value: unknown): ReplayGroupRecord | undefined {
+ if (!isRecord(value)
+ || typeof value.id !== "string"
+ || (value.phase !== "active" && value.phase !== "paused" && value.phase !== "incomplete")
+ || typeof value.promptCount !== "number"
+ || !Number.isSafeInteger(value.promptCount)
+ || value.promptCount < 1
+ || typeof value.startedAt !== "number"
+ || !Number.isSafeInteger(value.startedAt)
+ || value.startedAt < 0) return undefined;
+ return {
+ id: value.id,
+ phase: value.phase,
+ promptCount: value.promptCount,
+ startedAt: value.startedAt,
+ ...(Array.isArray(value.messageIds) ? { messageIds: value.messageIds.filter((id): id is string => typeof id === "string") } : {}),
+ ...(isRecord(value.baselineSnapshot) && typeof value.baselineSnapshot.segment === "number" && typeof value.baselineSnapshot.sequence === "number" ? {
+ baselineSnapshot: { segment: value.baselineSnapshot.segment, sequence: value.baselineSnapshot.sequence },
+ } : {}),
+ };
+}
+
async function readSessionLedger(path: string | null): Promise<SessionLedger> {
if (!path) return { version: 1, sessions: {} };
try {
@@ -2490,6 +2570,7 @@ async function readSessionLedger(path: string | null): Promise<SessionLedger> {
|| (record.sentBytes !== undefined && (!Number.isSafeInteger(record.sentBytes) || record.sentBytes < 0))
|| typeof record.lastSeenAt !== "string") return [];
const model = ledgerModel(record.model);
+ const replayGroup = replayGroupRecord(record.replayGroup);
const childSessionIds = Array.isArray(record.childSessionIds)
? record.childSessionIds.filter((id): id is string => typeof id === "string" && id.length > 0).slice(0, MAX_CHILD_SESSIONS)
: [];
@@ -2515,6 +2596,7 @@ async function readSessionLedger(path: string | null): Promise<SessionLedger> {
...(Array.isArray(record.refused) ? { refused: record.refused.filter((item): item is string => typeof item === "string").slice(-MAX_REFUSED_SEQUENCES) } : {}),
...(optionalString(record.endedAt) ? { endedAt: record.endedAt } : {}),
...(parseConfirmation(record.confirmation) ? { confirmation: parseConfirmation(record.confirmation)! } : {}),
+ ...(replayGroup ? { replayGroup } : {}),
};
return [[sessionId, cleaned] as const];
}),
@@ -4694,6 +4776,14 @@ export class SessionUploader {
...(state.refused.length > 0 ? { refused: state.refused.slice(-MAX_REFUSED_SEQUENCES) } : {}),
// A new segment is judged again once it ends.
...(state.endedAt ? { endedAt: state.endedAt } : {}),
+ ...(state.replayGroup ? {
+ replayGroup: {
+ id: state.replayGroup.id,
+ phase: state.replayGroup.phase,
+ promptCount: state.replayGroup.promptCount,
+ startedAt: state.replayGroup.startedAt,
+ },
+ } : {}),
};
}
@@ -4725,6 +4815,11 @@ export class SessionUploader {
state.model = state.model ?? previous?.model ?? null;
state.childSessionIds = [...new Set([...(previous?.childSessionIds ?? []), ...state.childSessionIds])];
state.childCheckpoints = new Map([...Object.entries(previous?.childCheckpoints ?? {}), ...state.childCheckpoints]);
+ const replayGroup = replayGroupRecord(previous?.replayGroup);
+ if (replayGroup) {
+ state.replayGroup = { ...replayGroup, baselineUnavailable: true, phase: "incomplete" };
+ state.turnStartedAt = replayGroup.startedAt;
+ }
state.resumed = Boolean(previous);
if (state.resumed) {
this.appendTrace(state, "session.resumed", {
@@ -4926,7 +5021,7 @@ export class SessionUploader {
if (!this.enabled || this.sessions.has(sessionId) || !/^[A-Za-z0-9._:-]{8,128}$/.test(sessionId)) return;
void this.toolchains?.get(root).catch(() => null); // toolchain.ts: collected in the background
const state = this.newSessionState(sessionId, workspaceId, root, this.acquireCache(root));
- state.ready = this.prepareSession(state);
+ state.ready = this.prepareSession(state).then(() => this.restoreReplayGroup(state));
this.sessions.set(sessionId, state);
this.journalMeta(state);
// Capture context collects once the start snapshot is out.
@@ -4934,8 +5029,8 @@ export class SessionUploader {
const startSnapshot = new Promise<void>((resolveStart) => (startSnapshotDone = resolveStart));
this.context?.sessionStarted(sessionId, root, startSnapshot);
this.enqueue(state, async () => {
- await state.ready;
try {
+ await state.ready;
// The watchers go up as soon as the start snapshot's listing is in,
// before any file is read: an edit made during the scan is either
// seen by the scan or reported by a watcher.
@@ -4983,6 +5078,8 @@ export class SessionUploader {
turnManifest: null,
turnStartedAt: null,
turnInProgress: false,
+ replayGroup: null, replayFailure: null, replayTail: Promise.resolve(),
+ startingReplayGroup: false, captureVerified: false, lastWorkspaceCapture: null,
changesHeld: false,
turnSkipped: new Map(),
turnWrittenPaths: new Map(),
@@ -5641,6 +5738,130 @@ export class SessionUploader {
}
}
+
+ isTurnPaused(sessionId: string): boolean {
+ const group = this.sessions.get(sessionId)?.replayGroup;
+ return Boolean(group && group.phase !== "active");
+ }
+
+ hasOpenTurn(sessionId: string): boolean {
+ return Boolean(this.sessions.get(sessionId)?.replayGroup);
+ }
+
+ async beginTurn(sessionId: string): Promise<boolean> {
+ const state = this.sessions.get(sessionId);
+ if (!state || state.finished) return !this.enabled;
+ await state.ready;
+ await this.idle(sessionId);
+ if (state.replayFailure || state.replayGroup?.baselineUnavailable) {
+ this.recordReplayGroup(state, "incomplete", "baseline_restore_failed");
+ return false;
+ }
+ if (state.replayGroup) {
+ if (!state.turnManifest) return false;
+ state.replayGroup.phase = "active";
+ state.replayGroup.promptCount += 1;
+ state.turnInProgress = true;
+ this.recordReplayGroup(state, "resumed");
+ await this.saveReplayGroup(state);
+ return true;
+ }
+ state.replayGroup = {
+ id: "rg_" + randomBytes(16).toString("hex"), phase: "active",
+ promptCount: 1, startedAt: Date.now() + 1, baselineUnavailable: false,
+ messageIds: [],
+ };
+ state.startingReplayGroup = true;
+ this.captureSnapshot(sessionId, "prompt");
+ await this.idle(sessionId);
+ state.startingReplayGroup = false;
+ if (state.replayFailure || !state.turnManifest) return false;
+ if (state.replayGroup.phase !== "active") { await this.saveReplayGroup(state); return false; }
+ if (state.lastWorkspaceCapture) state.replayGroup.baselineSnapshot = { ...state.lastWorkspaceCapture };
+ this.recordReplayGroup(state, "start");
+ await this.saveReplayGroup(state);
+ return true;
+ }
+
+ async pauseTurn(sessionId: string, reason = "interrupted"): Promise<void> {
+ const state = this.sessions.get(sessionId);
+ if (!state?.replayGroup) return;
+ if (state.replayGroup.phase !== "paused") {
+ state.replayGroup.phase = "paused";
+ this.recordReplayGroup(state, "paused", reason);
+ }
+ await this.saveReplayGroup(state);
+ }
+
+ private replayFile(state: SessionState): string | null {
+ return this.stateDir ? join(this.stateDir, "capture-turns", createHash("sha256").update(state.id).digest("hex") + ".json") : null;
+ }
+
+ private async saveReplayGroup(state: SessionState): Promise<void> {
+ const file = this.replayFile(state);
+ if (!file) return;
+ const account = await this.currentAccount();
+ const content = state.replayGroup ? JSON.stringify({
+ schema: 1, session_id: state.id, root: resolve(state.root), account,
+ group: state.replayGroup, started_at: state.turnStartedAt,
+ baseline: state.turnManifest ? [...state.turnManifest] : null,
+ skipped: [...state.turnSkipped], written: [...state.turnWrittenPaths],
+ }) : null;
+ const write = state.replayTail.then(async () => {
+ await mkdir(dirname(file), { recursive: true, mode: 0o700 });
+ if (content === null) await rm(file, { force: true });
+ else await writePrivateFileAtomic(file, content);
+ });
+ state.replayTail = write.catch(() => undefined);
+ await write;
+ await this.persistSession(state);
+ }
+
+ private async restoreReplayGroup(state: SessionState): Promise<void> {
+ const file = this.replayFile(state);
+ if (!file) return;
+ try {
+ const fileStat = await stat(file).catch((error: unknown) => {
+ if (isRecord(error) && error.code === "ENOENT") return null;
+ throw error;
+ });
+ if (!fileStat) return;
+ if (fileStat.size > 64 * 1024 * 1024) throw new Error("saved baseline exceeds metadata budget");
+ const value: unknown = JSON.parse(await readFile(file, "utf8"));
+ if (!isRecord(value) || value.schema !== 1 || value.session_id !== state.id ||
+ value.root !== resolve(state.root) || value.account !== await this.currentAccount()) throw new Error("saved baseline belongs to another project or account");
+ const group = replayGroupRecord(value.group);
+ const baseline = savedTurnBaseline(value.baseline);
+ if (!group || !baseline || (state.replayGroup && state.replayGroup.id !== group.id)) throw new Error("saved baseline is invalid");
+ state.replayGroup = { ...group, phase: "paused", baselineUnavailable: false };
+ state.turnManifest = baseline;
+ state.turnStartedAt = group.startedAt;
+ state.turnSkipped = savedPathTimes(value.skipped);
+ state.turnWrittenPaths = savedPathTimes(value.written);
+ } catch {
+ state.replayFailure = "The interrupted turn's original snapshot cannot be restored. Start a new session.";
+ if (state.replayGroup) state.replayGroup.baselineUnavailable = true;
+ this.appendTrace(state, "collector.replay_group", { schema: 1, phase: "incomplete", reason: "baseline_restore_failed" });
+ }
+ }
+
+ private recordReplayGroup(state: SessionState, phase: "start" | "paused" | "resumed" | "completed" | "incomplete", reason?: string): void {
+ const group = state.replayGroup;
+ if (!group) return;
+ this.appendTrace(state, "collector.replay_group", {
+ schema: 1, group_id: group.id,
+ phase,
+ baseline_at: new Date(group.startedAt).toISOString(),
+ ...(group.baselineSnapshot ? { baseline_snapshot: group.baselineSnapshot } : {}),
+ message_ids: group.messageIds ?? [],
+ prompt_count: group.promptCount,
+ ...(group.baselineUnavailable ? { baseline_unavailable: true } : {}),
+ ...(reason ? { reason } : {}),
+ });
+ this.journalMeta(state, true);
+ void this.persistSession(state).catch(() => undefined);
+ }
+
/**
* Captures a change snapshot for an engine milestone: right as a prompt is
* dispatched, or once a turn completes. When nothing changed since the last
@@ -5650,30 +5871,27 @@ export class SessionUploader {
* MessageAbortedError), recorded on its collector.trigger event (the
* snapshot's own trigger stays turn_completed, which every backend takes).
*/
+
captureSnapshot(sessionId: string, trigger: "prompt" | "turn_completed", outcome?: TurnEndOutcome): void {
const state = this.sessions.get(sessionId);
if (!state || state.finished) return;
+ if (trigger === "prompt" && state.replayGroup && !state.startingReplayGroup) return;
+ if (outcome && state.replayGroup) {
+ state.replayGroup.phase = outcome === "aborted" ? "paused" : "incomplete";
+ this.recordReplayGroup(state, outcome === "aborted" ? "paused" : "incomplete", outcome);
+ }
if (trigger === "prompt") {
state.relevance.clear();
state.turnWrittenPaths.clear();
- // After the turn's artifact baseline (set just below) is listed.
this.context?.turnStarted(sessionId, Promise.resolve().then(() => state.artifactBaseline));
+ state.artifactBaseline = artifactStats(state.root);
+ state.turnStartedAt = state.replayGroup?.startedAt ?? Date.now() + 1;
} else {
this.context?.turnEnded(sessionId);
}
- // The artifact baseline must reflect the workspace as the turn begins, not
- // once the queued start snapshot has finished uploading.
- if (trigger === "prompt") state.artifactBaseline = artifactStats(state.root);
- // So must the turn's start: what the agent writes while an earlier upload
- // still holds the queue belongs to this turn. It is the first whole
- // millisecond after the prompt: Date.now() rounds down, and a file written
- // just before may carry a later fraction of the same millisecond.
- if (trigger === "prompt") state.turnStartedAt = Date.now() + 1;
const startedAt = state.turnStartedAt;
state.turnInProgress = trigger === "prompt";
- // A crash from here on leaves the turn open in the journal (or no longer).
this.journalMeta(state, true);
- // The milestone carries whatever edits were held back for another session's turn.
state.changesHeld = false;
if (state.changeTimer) {
clearTimeout(state.changeTimer);
@@ -5682,22 +5900,34 @@ export class SessionUploader {
}
this.enqueue(state, async () => {
const previous = state.manifest;
- await this.captureChange(state, trigger, false, trigger === "turn_completed" && outcome === "aborted" ? outcome : undefined);
+ const captured = await this.captureChange(state, trigger, false, trigger === "turn_completed" ? outcome : undefined);
const current = state.manifest;
+ if (trigger === "prompt" && state.replayGroup && !captured) {
+ state.replayFailure = "The starting snapshot could not be captured or queued.";
+ this.recordReplayGroup(state, "incomplete", "snapshot_failed");
+ return;
+ }
+ if (trigger === "turn_completed" && state.replayGroup) {
+ const complete = !outcome && state.replayGroup.phase === "active" && captured;
+ if (!complete) {
+ if (!captured) state.replayGroup.phase = "incomplete";
+ this.recordReplayGroup(state, state.replayGroup.phase === "paused" ? "paused" : "incomplete", outcome ?? "capture_not_complete");
+ }
+ await this.recordTurnDiff(state, current, null, complete);
+ if (complete) { this.recordReplayGroup(state, "completed"); state.replayGroup = null; state.turnStartedAt = null; }
+ await this.saveReplayGroup(state);
+ return;
+ }
if (trigger === "turn_completed") {
- // A prompt sent since the turn ended (this job waited behind an
- // upload) began the next turn: what it wrote belongs to that one.
const next = state.turnStartedAt !== startedAt ? state.turnStartedAt : null;
if (!current || next === null) return this.recordTurnDiff(state, current, null);
const taken = turnBaseline(current, next, [previous, state.turnManifest]);
- // A file nothing saw from before the next turn keeps its entry here.
return this.recordTurnDiff(state, new Map([...taken].map(([path, entry]) => [path, entry ?? current.get(path)!])), next);
}
- // The turn is measured from the workspace as its prompt found it.
const forcePaths = new Set(
[...state.turnWrittenPaths].filter(([, at]) => startedAt === null || at >= startedAt).map(([path]) => path),
);
- state.turnManifest = current && turnBaseline(current, startedAt, [previous, state.turnManifest], forcePaths);
+ state.turnManifest = current && (state.replayGroup ? new Map(current) : turnBaseline(current, startedAt, [previous, state.turnManifest], forcePaths));
for (const [path, at] of state.turnSkipped) if (startedAt !== null && at < startedAt) state.turnSkipped.delete(path);
});
}
@@ -5712,12 +5942,14 @@ export class SessionUploader {
* skipped files of a next turn already under way (written since `next`,
* its prompt) are left to it.
*/
- private async recordTurnDiff(state: SessionState, after: Manifest | null, next: number | null): Promise<void> {
+ private async recordTurnDiff(state: SessionState, after: Manifest | null, next: number | null, advance = true): Promise<void> {
const before = state.turnManifest;
const skipped = state.turnSkipped;
- state.turnManifest = after;
- state.turnSkipped = new Map(next === null ? [] : [...skipped].filter(([, at]) => at >= next));
- state.turnWrittenPaths = new Map(next === null ? [] : [...state.turnWrittenPaths].filter(([, at]) => at >= next));
+ if (advance) {
+ state.turnManifest = after;
+ state.turnSkipped = new Map(next === null ? [] : [...skipped].filter(([, at]) => at >= next));
+ state.turnWrittenPaths = new Map(next === null ? [] : [...state.turnWrittenPaths].filter(([, at]) => at >= next));
+ }
if (state.finished || !before || !after) return;
const changes: TurnChange[] = [];
if (before !== after) {
@@ -5742,7 +5974,7 @@ export class SessionUploader {
if (input) builder.add(input);
await yielder.pause();
}
- this.appendTrace(state, "turn.diff", builder.finish());
+ this.appendTrace(state, "turn.diff", { ...builder.finish(), ...(state.replayGroup ? { replay_group_id: state.replayGroup.id } : {}) });
}
/** The entry `change` makes, with its texts when `texts` is set (without, it only needs a status). */
@@ -5793,6 +6025,11 @@ export class SessionUploader {
finishSession(sessionId: string, finalTrace?: unknown): void {
const state = this.sessions.get(sessionId);
if (!state || state.finished) return;
+ if (state.replayGroup) {
+ state.replayGroup.phase = "paused";
+ this.recordReplayGroup(state, "paused", "session_closed");
+ this.enqueue(state, () => this.saveReplayGroup(state));
+ }
const pendingTrace = state.trace.splice(0);
if (finalTrace !== undefined) {
for (const evidence of knownToolPathEvidence("session.completed", finalTrace)) {
@@ -5844,7 +6081,17 @@ export class SessionUploader {
}
// Capture context: the turn's last messages (its tool calls) arrive here, not as turn.messages.
if (isRecord(finalTrace)) this.context?.turnMessages(sessionId, finalTrace.messages, true);
- pendingTrace.push({ at: new Date().toISOString(), type: "turn.completed", data: finalTrace });
+ if (state.replayGroup && isRecord(finalTrace) && Array.isArray(finalTrace.messages)) {
+ const ids = new Set(state.replayGroup.messageIds ?? []);
+ for (const message of finalTrace.messages) {
+ if (!isRecord(message)) continue;
+ const info = isRecord(message.info) ? message.info : message;
+ if (info.role === "user" && typeof info.id === "string") ids.add(info.id);
+ }
+ state.replayGroup.messageIds = [...ids];
+ }
+ const data = state.replayGroup && isRecord(finalTrace) ? { ...finalTrace, replay_group_id: state.replayGroup.id } : finalTrace;
+ pendingTrace.push({ at: new Date().toISOString(), type: "turn.completed", data });
}
if (pendingTrace.length === 0) return;
this.enqueue(state, async () => {
@@ -5883,6 +6130,7 @@ export class SessionUploader {
}
// A spooled upload in flight stays spooled for the next start.
this.draining?.controller.abort();
+ await this.idleAll();
for (const sessionId of [...this.sessions.keys()]) this.finishSession(sessionId);
await Promise.allSettled([...this.sessions.values()].map((state) => state.tail));
await this.draining?.run.catch(() => undefined);
@@ -5928,7 +6176,7 @@ export class SessionUploader {
* interval since the last change snapshot is deferred and merged with
* whatever else arrives before the interval elapses.
*/
- private async captureChange(state: SessionState, trigger: ChangeTrigger, deferred = false, outcome?: TurnEndOutcome): Promise<void> {
+ private async captureChange(state: SessionState, trigger: ChangeTrigger, deferred = false, outcome?: TurnEndOutcome): Promise<boolean> {
await state.ready;
const milestone = trigger === "prompt" || trigger === "turn_completed";
if (milestone && state.watchMode === "watching") await new Promise((resolvePromise) => setTimeout(resolvePromise, MILESTONE_SETTLE_MS));
@@ -5937,10 +6185,10 @@ export class SessionUploader {
await state.changeCaptureTail;
// A finished session is about to upload its end snapshot, which already
// carries everything a queued change capture would.
- if (state.finished) return;
+ if (state.finished) return false;
if (!milestone && this.changesLeftToOthers(state)) {
this.metrics.capturesHeld += 1;
- return;
+ return false;
}
if (trigger === "turn_completed") {
await this.captureArtifacts(state).catch((error: unknown) => {
@@ -5953,15 +6201,16 @@ export class SessionUploader {
if (!(await this.hasPendingChanges(state))) {
this.metrics.capturesSkipped += 1;
if (milestone) this.appendTrace(state, "collector.trigger", { trigger, captured: false, ...(outcome ? { outcome } : {}) });
- return;
+ return state.manifest !== null;
}
const wait = !milestone && !deferred && state.lastChangeAt > 0 ? this.minChangeIntervalMs - (Date.now() - state.lastChangeAt) : 0;
if (wait > 0) {
this.deferChange(state, trigger, wait);
- return;
+ return false;
}
const captured = await this.uploadWorkspace(state, "change", trigger);
if (milestone) this.appendTrace(state, "collector.trigger", { trigger, captured, ...(outcome ? { outcome } : {}) });
+ return captured || state.captureVerified;
}
/** Whether another live session on `state`'s root has a turn in progress. */
@@ -6137,8 +6386,9 @@ export class SessionUploader {
}
}
- private enqueue(state: SessionState, operation: () => Promise<void>): void {
- state.tail = state.tail.then(operation).catch((error: unknown) => {
+ private enqueue(state: SessionState, operation: () => Promise<unknown>): void {
+ state.tail = state.tail.then(operation).then(() => undefined).catch((error: unknown) => {
+ if (state.startingReplayGroup) state.replayFailure = "The starting snapshot failed.";
this.log("warn", "OmniRush session upload operation failed", {
sessionId: state.id,
error: error instanceof Error ? error.message : "unknown",
@@ -6162,6 +6412,7 @@ export class SessionUploader {
* out.
*/
private async uploadWorkspace(state: SessionState, type: Exclude<SnapshotType, "trace">, trigger: UploadTrigger): Promise<boolean> {
+ state.captureVerified = false;
const cache = state.cache;
// Paths reported from here on belong to the next capture.
const dirty = state.dirty;
@@ -6230,6 +6481,7 @@ export class SessionUploader {
if (type === "change" && scan.changed !== null && scan.changed.size === 0 && scan.removed === 0 && !this.journalHasChanges(state)
&& (await gitHead(state.root)) === state.lastHead) {
accepted = true;
+ state.captureVerified = previous !== null;
return false;
}
// Its status and diff name the files a capped snapshot must keep.
@@ -6372,9 +6624,13 @@ export class SessionUploader {
// The baseline is the last *accepted* manifest (uploaded or spooled): the
// next change snapshot reports exactly what moved since this one.
accepted = true;
+ state.captureVerified = true;
+ state.lastWorkspaceCapture = { segment: state.segment, sequence: state.sequence };
state.manifest = manifest;
state.extras = extraEntries;
- state.turnManifest ??= turnBaseline(manifest, state.turnStartedAt, [previous]);
+ if (!state.replayGroup?.baselineUnavailable) {
+ state.turnManifest ??= turnBaseline(manifest, state.turnStartedAt, [previous]);
+ }
state.listing = { denied: scan.deniedCount, truncated: scan.manifestTruncated };
state.lastHead = git?.commit ?? null;
if (journal.length > 0) this.acknowledgeJournal(state, journal);
@@ -6932,6 +7188,14 @@ export class SessionUploader {
root: state.root,
segment: state.segment,
turn_open: state.turnInProgress,
+ ...(state.replayGroup ? {
+ replay_group: {
+ id: state.replayGroup.id,
+ phase: state.replayGroup.phase,
+ promptCount: state.replayGroup.promptCount,
+ startedAt: state.replayGroup.startedAt,
+ },
+ } : {}),
at: new Date().toISOString(),
};
return JSON.stringify({ m: meta });
@@ -7087,6 +7351,7 @@ export class SessionUploader {
private async recoverJournal(journal: { path: string; meta: JournalMeta; events: TraceEvent[] }): Promise<void> {
const { meta, events } = journal;
const record = this.ledger.sessions[meta.session_id];
+ const replayGroup = replayGroupRecord(meta.replay_group) ?? replayGroupRecord(record?.replayGroup);
if (events.length > 0) {
// The segment the events were recorded in, numbered after what it already sent.
const state = this.newSessionState(meta.session_id, meta.workspace_id, meta.root, new FileHashCache());
@@ -7104,6 +7369,10 @@ export class SessionUploader {
state.refused = [...(record?.refused ?? [])];
state.endedAt = record?.endedAt;
state.resumed = state.segment > 1;
+ if (replayGroup) {
+ state.replayGroup = { ...replayGroup, phase: "incomplete", baselineUnavailable: true };
+ state.turnStartedAt = replayGroup.startedAt;
+ }
for (const event of events) {
for (const evidence of knownToolPathEvidence(event.type, event.data)) {
const path = workspaceRelativePath(state.root, evidence.path.replaceAll("\\", "/"));
@@ -7115,6 +7384,18 @@ export class SessionUploader {
type: "collector.recovered",
data: { reason: "restart", turn_open: meta.turn_open, events: events.length, journal_at: meta.at, session_segment: state.segment },
};
+ if (replayGroup) {
+ events.unshift({
+ at: marker.at,
+ type: "collector.replay_group",
+ data: {
+ group_id: replayGroup.id,
+ phase: "paused",
+ prompt_count: replayGroup.promptCount,
+ reason: "process_restarted",
+ },
+ });
+ }
try {
await this.uploadTrace(state, [marker, ...events]);
} catch (error) {
@@ -7122,8 +7403,17 @@ export class SessionUploader {
this.log("warn", "OmniRush session journal upload refused; kept for the next start", { sessionId: meta.session_id, error: error instanceof Error ? error.message : "unknown" });
return;
}
+ await this.persistSession(state).catch(() => undefined);
this.log("info", "OmniRush session journal recovered", { sessionId: meta.session_id, events: events.length, turnOpen: meta.turn_open });
}
+ if (events.length === 0 && replayGroup && record) {
+ this.ledger.sessions[meta.session_id] = {
+ ...record,
+ replayGroup: { ...replayGroup, phase: "incomplete" },
+ lastSeenAt: new Date().toISOString(),
+ };
+ await this.saveLedger().catch(() => undefined);
+ }
await rm(journal.path, { force: true });
// The open turn's messages are still in the engine: the host settles it once this chat's recovery is done.
if (meta.turn_open && this.onRecoveredTurn) {
diff --git a/docs/serialized-turns.md b/docs/serialized-turns.md
new file mode 100644
index 00000000..c2cd31c9
--- /dev/null
+++ b/docs/serialized-turns.md
@@ -0,0 +1,46 @@
+# Serialized turns and interrupted capture
+
+A logical turn begins when a prompt is admitted. Its starting workspace capture
+is ready before the request reaches the engine. The root and its tracked
+delegated sessions must settle before another prompt can start a new turn.
+
+Stopping pauses that logical turn. A continuation or correction uses the same
+original baseline. The trace preserves every submitted message and tool result;
+it does not rewrite or delete the first prompt. Only natural completion advances
+the baseline. Failed or unverifiable cancellation must keep admission closed.
+
+## Capture records
+
+The existing message and tool records, upload schemas, privacy rules, archive
+layout and engine turn counts remain compatible. Additive metadata describes the
+logical replay unit:
+
+- `collector.replay_group`: `schema: 1`, `group_id`, `phase`,
+ `prompt_count`, `message_ids`, `baseline_at`, and, when available,
+ `baseline_snapshot: {segment, sequence}`.
+- Phases: `start`, `paused`, `resumed`, `completed`, `incomplete`.
+- `turn.diff` and `turn.completed` carry `replay_group_id` while grouped.
+
+The original manifest and group identity are saved atomically in private local
+capture state. Restart restores that baseline only for the same project and
+account. A missing or corrupt required baseline prevents continuation; the
+collector must not silently replace it with the current files.
+
+A consumer that builds independent replay tasks must use this grouping and the
+original baseline. Existing backend displays may still count individual engine
+messages until they consume the new metadata.
+
+## Boundaries
+
+This coordinates tracked engine sessions through this app's admission surface.
+It cannot freeze writes from unrelated editors, another app process, or detached
+background services. It does not make a filesystem snapshot atomic, expand file
+capture limits, collect credentials, or guarantee that every external dependency
+is reproducible.
+
+## Validation
+
+The PR evidence records public boundary/journey results separately from unit
+checks, including any missing infrastructure. Focused collector checks cover
+Stop/resume, app restart, refused replacement snapshots, worker acknowledgements,
+and the existing upload/spool/recovery paths.
diff --git a/evals/packages/labs/src/capture-efficiency.ts b/evals/packages/labs/src/capture-efficiency.ts
index 9b536b7e..db6bd1bb 100644
--- a/evals/packages/labs/src/capture-efficiency.ts
+++ b/evals/packages/labs/src/capture-efficiency.ts
@@ -28,6 +28,7 @@ export type CaptureEfficiencyAttempt = {
traceFileEventTypes: string[];
traceFileCount: number;
actorMarkers: string[];
+ events: Array<{ type: string; data: unknown }>;
};
export type CaptureEfficiencyWitness = {
@@ -98,6 +99,12 @@ function authorized(request: IncomingMessage, token: string): boolean {
return request.headers.authorization === `Bearer ${token}`;
}
+function traceEvents(value: unknown): Array<{ type: string; data: unknown }> {
+ if (isRecord(value) && Array.isArray(value.events)) return traceEvents(value.events);
+ if (!Array.isArray(value)) return [];
+ return value.flatMap(event => isRecord(event) && typeof event.type === "string" ? [{ type: event.type, data: event.data }] : []);
+}
+
function traceSummary(value: unknown): { types: string[]; actors: string[] } {
if (isRecord(value) && Array.isArray(value.events)) return traceSummary(value.events);
if (!Array.isArray(value)) return { types: [], actors: [] };
@@ -125,7 +132,8 @@ function summarizeEnvelope(sessionId: string, status: number, envelope: JsonReco
const workspace = isRecord(envelope.workspace) ? envelope.workspace : null;
const workspaceRoot = workspace ? optionalString(workspace.root_name) : null;
const files = filePaths(envelope.files);
- const trace = traceSummary(envelope.trace);
+ let events = traceEvents(envelope.trace);
+ let trace = traceSummary(envelope.trace);
const traceFiles = files.filter((file) => file.path === "__omnirush__/trace.json");
let traceFileEventTypes: string[] = [];
for (const traceFile of traceFiles) {
@@ -133,6 +141,7 @@ function summarizeEnvelope(sessionId: string, status: number, envelope: JsonReco
try {
const parsed: unknown = JSON.parse(traceFile.content);
traceFileEventTypes = traceSummary(parsed).types;
+ if (events.length === 0) { events = traceEvents(parsed); trace = traceSummary(parsed); }
} catch {
traceFileEventTypes = [];
}
@@ -148,6 +157,7 @@ function summarizeEnvelope(sessionId: string, status: number, envelope: JsonReco
traceFileEventTypes,
traceFileCount: traceFiles.length,
actorMarkers: trace.actors,
+ events,
};
}
@@ -186,7 +196,7 @@ async function startCaptureEfficiencyLabRuntime(): Promise<CaptureEfficiencyLab>
const attempts: CaptureEfficiencyAttempt[] = [];
const capabilityCalls: Record<Actor, number> = { "actor-a": 0, "actor-b": 0 };
- const sessions = new Map<string, { actor: Actor; service: CaptureService }>();
+ const sessions = new Map<string, { actor: Actor; service: CaptureService; root: string; workspace: string }>();
const rejectedSchema3 = new Set(["session-a-0001"]);
let collectorUrl = "";
let stopped = false;
@@ -258,7 +268,7 @@ async function startCaptureEfficiencyLabRuntime(): Promise<CaptureEfficiencyLab>
const root = join(workspaceRoot, actor, workspace);
await mkdir(root, { recursive: true });
await writeFile(join(root, `notes-${actor.slice(-1)}.txt`), `synthetic ${actor}\n`, "utf8");
- sessions.set(requestedSessionId, { actor, service });
+ sessions.set(requestedSessionId, { actor, service, root, workspace });
service.startSession(requestedSessionId, workspace, root);
await service.idle();
sendJson(response, 202, { ok: true });
@@ -270,6 +280,31 @@ async function startCaptureEfficiencyLabRuntime(): Promise<CaptureEfficiencyLab>
sendJson(response, 404, { error: "unknown synthetic session" });
return;
}
+ if (path === "/control/write") {
+ // A fixed synthetic path: the test control cannot escape its workspace.
+ await writeFile(join(session.root, "cli.py"), stringValue(body, "content"), "utf8");
+ sendJson(response, 202, { ok: true });
+ return;
+ }
+ if (path === "/control/turn") {
+ const action = stringValue(body, "action");
+ if (action === "begin") {
+ if (!await session.service.promptStartGate(requestedSessionId, session.workspace, session.root)) {
+ sendJson(response, 503, { error: "baseline unavailable" });
+ return;
+ }
+ } else if (action === "pause") {
+ await session.service.pauseTurn(requestedSessionId);
+ session.service.captureSnapshot(requestedSessionId, "turn_completed", "aborted");
+ } else if (action === "complete") {
+ session.service.captureSnapshot(requestedSessionId, "turn_completed");
+ } else throw new Error("unknown turn action");
+ const finalTrace = isRecord(body) ? body.finalTrace : undefined;
+ session.service.flushTrace(requestedSessionId, finalTrace);
+ await session.service.idle();
+ sendJson(response, 202, { ok: true });
+ return;
+ }
if (path === "/control/trace") {
const type = stringValue(body, "type");
const data = isRecord(body) && Object.hasOwn(body, "data") ? body.data : undefined;
@@ -387,6 +422,7 @@ async function readWitness(baseUrl: string, controlToken: string): Promise<Captu
: [],
traceFileCount: numberValue(attempt, "traceFileCount") ?? 0,
actorMarkers: Array.isArray(attempt.actorMarkers) ? attempt.actorMarkers.filter((actor): actor is string => typeof actor === "string") : [],
+ events: traceEvents(attempt.events),
});
}
const calls: Record<Actor, number> = {
diff --git a/evals/packages/labs/src/index.ts b/evals/packages/labs/src/index.ts
index 64e81ee5..01431ec2 100644
--- a/evals/packages/labs/src/index.ts
+++ b/evals/packages/labs/src/index.ts
@@ -11,3 +11,5 @@ export * from "./mock-planetscale.ts";
export * from "./mock-atlassian.ts";
export * from "./mock-inference.ts";
export * from "./capture-efficiency.ts";
+
+export * from "./serialized-turns.ts";
diff --git a/evals/packages/labs/src/serialized-turns.ts b/evals/packages/labs/src/serialized-turns.ts
new file mode 100644
index 00000000..be8c0b24
--- /dev/null
+++ b/evals/packages/labs/src/serialized-turns.ts
@@ -0,0 +1,169 @@
+import { spawn } from "node:child_process";
+import { mkdtemp, mkdir, writeFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { zstdDecompressSync } from "node:zlib";
+
+export type SerializedTurnLab = {
+ baseUrl: string;
+ controlUrl: string;
+ token: string;
+ stop(): Promise<void>;
+};
+const TOKEN = "owt_synthetic_serialized_turn";
+const ROOT = "ses_serialized_root";
+const CHILD = "ses_serialized_child";
+const GRANDCHILD = "ses_serialized_grandchild";
+function record(value: unknown): value is Record<string, unknown> {
+ return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+async function runtime(): Promise<SerializedTurnLab> {
+ const { serve } = await import("bun");
+ const { startServer } = await import("../../../../apps/server/src/server.js");
+ const dir = await mkdtemp(join(tmpdir(), "serialized-turn-lab-"));
+ const root = join(dir, "project");
+ await mkdir(root);
+ await writeFile(join(root, "README.md"), "Synthetic project\n");
+ process.env.OMNIRUSH_DATA_DIR = join(dir, "data");
+ process.env.OMNIRUSH_CAPTURE_CONTEXT = "0";
+ const ids = [ROOT, CHILD, GRANDCHILD];
+ const parents = new Map([[CHILD, ROOT], [GRANDCHILD, CHILD]]);
+ const histories = new Map<string, unknown[]>(ids.map(id => [id, []]));
+ const busy = new Set<string>();
+ const aborts: string[] = [];
+ const prompts: Array<{ sessionId: string; body: unknown }> = [];
+ const envelopes: unknown[] = [];
+ let failStop: string | null = null;
+ let hideActivity = false;
+ let delayedPrompt = false;
+ const engine = serve({ hostname: "127.0.0.1", port: 0, async fetch(request) {
+ const url = new URL(request.url);
+ if (url.pathname.startsWith("/control/")) {
+ if (request.headers.get("authorization") !== "Bearer " + TOKEN) return Response.json({}, { status: 401 });
+ const action = url.pathname.slice("/control/".length);
+ const body: unknown = request.method === "POST" ? await request.json() : {};
+ if (action === "state" && record(body)) {
+ if (Array.isArray(body.busy)) { busy.clear(); for (const id of body.busy) if (typeof id === "string") busy.add(id); }
+ if ("failStop" in body) failStop = typeof body.failStop === "string" ? body.failStop : null;
+ if ("hideActivity" in body) hideActivity = body.hideActivity === true;
+ if ("delayedPrompt" in body) delayedPrompt = body.delayedPrompt === true;
+ if (body.runningTool === true) histories.set(GRANDCHILD, [{
+ info: { id: "tool-message", role: "assistant" },
+ parts: [{ type: "tool", tool: "write", state: { status: "running" } }],
+ }]);
+ return Response.json({ ok: true });
+ }
+ if (action === "complete") {
+ for (const id of ids) {
+ const history = histories.get(id)!;
+ const last = history.at(-1);
+ if (record(last) && record(last.info) && last.info.role === "user") {
+ history.push({ info: { id: "answer-" + prompts.length, role: "assistant", parentID: last.info.id, finish: "stop", time: { completed: Date.now() } }, parts: [{ type: "text", text: "Done." }] });
+ }
+ }
+ busy.clear();
+ return Response.json({ ok: true });
+ }
+ if (action === "witness") return Response.json({ prompts, aborts, envelopes });
+ return Response.json({}, { status: 404 });
+ }
+ if (url.pathname === "/session/status") return hideActivity
+ ? Response.json({}, { status: 503 })
+ : Response.json(Object.fromEntries([...busy].map(id => [id, { type: "busy" }])));
+ const match = url.pathname.match(/^\/session\/([^/]+)(?:\/(.+))?$/);
+ if (match) {
+ const id = match[1]!;
+ if (!ids.includes(id)) return Response.json({}, { status: 404 });
+ const action = match[2];
+ if (!action) return Response.json({ id, directory: root, ...(parents.has(id) ? { parentID: parents.get(id) } : {}) });
+ if (action === "children") return Response.json(ids.filter(child => parents.get(child) === id).map(child => ({ id: child, parentID: id, directory: root })));
+ if (action === "message" && request.method === "GET") return Response.json(histories.get(id));
+ if (action === "abort") {
+ aborts.push(id);
+ if (failStop === id) return Response.json({}, { status: 500 });
+ busy.delete(id);
+ const history = histories.get(id)!;
+ for (const item of history) if (record(item) && Array.isArray(item.parts)) {
+ for (const part of item.parts) if (record(part) && part.type === "tool" && record(part.state)) part.state.status = "error";
+ }
+ const last = history.at(-1);
+ if (record(last) && record(last.info) && last.info.role === "user") history.push({
+ info: { id: "stopped-" + prompts.length, role: "assistant", parentID: last.info.id, error: { name: "MessageAbortedError" } }, parts: [],
+ });
+ return Response.json(true);
+ }
+ if (["prompt", "prompt_async", "command", "shell", "message"].includes(action ?? "")) {
+ const body: unknown = await request.json();
+ prompts.push({ sessionId: id, body });
+ if (!delayedPrompt) {
+ histories.get(id)!.push({ info: { id: "user-" + prompts.length, role: "user" }, parts: record(body) && Array.isArray(body.parts) ? body.parts : [] });
+ busy.add(id);
+ }
+ return new Response(null, { status: 204 });
+ }
+ if (action === "revert") return Response.json({ id });
+ }
+ return Response.json({});
+ } });
+ const gateway = serve({ hostname: "127.0.0.1", port: 0, async fetch(request) {
+ if (new URL(request.url).pathname === "/omnirush/collect") {
+ envelopes.push(JSON.parse(zstdDecompressSync(Buffer.from(await request.arrayBuffer())).toString("utf8")));
+ return Response.json({ ok: true }, { status: 201 });
+ }
+ return Response.json({}, { status: 404 });
+ } });
+ const server = await startServer({
+ host: "127.0.0.1", port: 0, token: TOKEN, hostToken: "synthetic_host_token",
+ configPath: join(dir, "server.json"), approval: { mode: "auto", timeoutMs: 1000 },
+ corsOrigins: ["*"], workspaces: [{ id: "ws_serialized", name: "Synthetic", path: root, preset: "starter", workspaceType: "local", baseUrl: engine.url.origin }],
+ authorizedRoots: [root], readOnly: false, startedAt: Date.now(), tokenSource: "cli", hostTokenSource: "cli",
+ logFormat: "json", logRequests: false,
+ omnirushGatewayCredentials: { gatewayUrl: gateway.url.origin + "/omnirush/v1", accessToken: "synthetic_access", refreshToken: "synthetic_refresh" },
+ omnirushEngineToken: "synthetic_engine",
+ });
+ return {
+ baseUrl: "http://127.0.0.1:" + server.port, controlUrl: engine.url.origin, token: TOKEN,
+ stop: async () => { await server.stop(true); engine.stop(true); gateway.stop(true); await rm(dir, { recursive: true, force: true }); },
+ };
+}
+export async function startSerializedTurnLab(): Promise<SerializedTurnLab> {
+ if (process.versions.bun) return runtime();
+ const modulePath = fileURLToPath(import.meta.url);
+ const child = spawn("bun", ["--conditions=development", "--eval", `
+ import { startSerializedTurnLab } from ${JSON.stringify(modulePath)};
+ const lab = await startSerializedTurnLab();
+ console.log(JSON.stringify({ serializedLab: true, baseUrl: lab.baseUrl, controlUrl: lab.controlUrl, token: lab.token }));
+ process.on("SIGTERM", async () => { await lab.stop(); process.exit(0); });
+ `], { stdio: ["ignore", "pipe", "pipe"] });
+ let stderr = "";
+ child.stderr.on("data", chunk => { stderr = (stderr + String(chunk)).slice(-16000); });
+ const exited = new Promise<void>(resolve => child.once("exit", () => resolve()));
+ const stop = async () => {
+ if (child.exitCode !== null || child.signalCode !== null) return;
+ child.kill("SIGTERM");
+ const timer = setTimeout(() => child.kill("SIGKILL"), 15_000);
+ try { await exited; } finally { clearTimeout(timer); }
+ };
+ try {
+ const ready = await new Promise<Omit<SerializedTurnLab, "stop">>((resolve, reject) => {
+ let pending = "";
+ const timer = setTimeout(() => reject(new Error("Serialized server lab startup timed out: " + stderr)), 30_000);
+ child.once("error", error => { clearTimeout(timer); reject(error); });
+ child.once("exit", () => { clearTimeout(timer); reject(new Error("Serialized server lab exited: " + stderr)); });
+ child.stdout.on("data", chunk => {
+ pending += String(chunk);
+ const lines = pending.split("\n"); pending = lines.pop()!;
+ for (const line of lines) {
+ try {
+ const value: unknown = JSON.parse(line);
+ if (record(value) && value.serializedLab === true && typeof value.baseUrl === "string" && typeof value.controlUrl === "string" && typeof value.token === "string") {
+ clearTimeout(timer); resolve({ baseUrl: value.baseUrl, controlUrl: value.controlUrl, token: value.token });
+ }
+ } catch {}
+ }
+ });
+ });
+ return { ...ready, stop };
+ } catch (error) { await stop(); throw error; }
+}
diff --git a/evals/specs/capture-efficiency.test.ts b/evals/specs/capture-efficiency.test.ts
index 525171ab..ca9be0a1 100644
--- a/evals/specs/capture-efficiency.test.ts
+++ b/evals/specs/capture-efficiency.test.ts
@@ -85,23 +85,22 @@ test("capture worker uploads ordered, scoped trace artifacts at the HTTP collect
within: 20_000,
intervalMs: 100,
label: "capture worker collector requests",
- until: (current) => current.attempts.length === 7
- && current.attempts.filter((attempt) => attempt.status === 201).length === 6,
+ until: (current) => [SESSION_A, SESSION_B].every(id => current.attempts.some(attempt => attempt.sessionId === id && attempt.snapshotType === "end" && attempt.status === 201)),
});
expect(witness.modes).toEqual(["worker", "worker"]);
const traceA = acceptedTrace(witness, SESSION_A);
const traceB = acceptedTrace(witness, SESSION_B);
- const traceAttemptsA = attemptsFor(witness, SESSION_A).filter((attempt) => attempt.snapshotType === "trace");
- const traceAttemptsB = attemptsFor(witness, SESSION_B).filter((attempt) => attempt.snapshotType === "trace");
+ const traceAttemptsA = attemptsFor(witness, SESSION_A).filter((attempt) => attempt.snapshotType === "trace" && attempt.traceTypes.includes("engine.request"));
+ const traceAttemptsB = attemptsFor(witness, SESSION_B).filter((attempt) => attempt.snapshotType === "trace" && attempt.traceTypes.includes("engine.request"));
expect(traceAttemptsA.map((attempt) => [attempt.status, attempt.schemaVersion])).toEqual([[422, 3], [201, 2]]);
expect(traceAttemptsB.map((attempt) => [attempt.status, attempt.schemaVersion])).toEqual([[201, 3]]);
expect(traceB.filePaths).toEqual([]);
expect(traceB.traceFileCount).toBe(0);
- expect(traceB.traceTypes).toEqual(["engine.request", "turn.completed"]);
+ expect(traceB.traceTypes.filter(type => ["engine.request", "turn.completed"].includes(type))).toEqual(["engine.request", "turn.completed"]);
expect(traceA.schemaVersion).toBe(2);
- expect(traceA.traceTypes).toEqual(["engine.request", "turn.messages", "turn.completed"]);
+ expect(traceA.traceTypes.filter(type => ["engine.request", "turn.messages", "turn.completed"].includes(type))).toEqual(["engine.request", "turn.messages", "turn.completed"]);
expect(traceA.traceFileCount).toBe(1);
expect(traceA.traceFileEventTypes).toEqual(traceA.traceTypes);
evidence.recordAssertionEvidence(
@@ -117,8 +116,11 @@ test("capture worker uploads ordered, scoped trace artifacts at the HTTP collect
const actorAAttempts = attemptsFor(witness, SESSION_A).filter((attempt) => attempt.status === 201);
const actorBAttempts = attemptsFor(witness, SESSION_B).filter((attempt) => attempt.status === 201);
- expect(actorAAttempts.map((attempt) => attempt.snapshotType)).toEqual(["start", "trace", "end"]);
- expect(actorBAttempts.map((attempt) => attempt.snapshotType)).toEqual(["start", "trace", "end"]);
+ for (const attempts of [actorAAttempts, actorBAttempts]) {
+ expect(attempts[0]?.snapshotType).toBe("start");
+ expect(attempts.at(-1)?.snapshotType).toBe("end");
+ expect(attempts.slice(1, -1).every(attempt => attempt.snapshotType === "trace")).toBe(true);
+ }
expect(actorAAttempts.every((attempt) => attempt.workspaceRoot === "workspace-a")).toBe(true);
expect(actorBAttempts.every((attempt) => attempt.workspaceRoot === "workspace-b")).toBe(true);
expect(actorAAttempts.every((attempt) => attempt.actorMarkers.every((actor) => actor === "actor-a"))).toBe(true);
@@ -132,10 +134,64 @@ test("capture worker uploads ordered, scoped trace artifacts at the HTTP collect
expect(witness.capabilityCalls).toEqual({ "actor-a": 1, "actor-b": 1 });
evidence.recordAssertionEvidence(
"Capture records preserve completion order and actor/workspace scope",
- "Each synthetic session produced start, trace, and end in order; trace markers and workspace roots stayed within their owning actor, with one capability probe per worker.",
+ "Each synthetic session produced start, trace batches, and end in order; trace markers and workspace roots stayed within their owning actor, with one capability probe per worker.",
true,
);
} finally {
await lab.stop();
}
});
+
+
+test("capture worker retains the original turn baseline across Stop and correction", { timeout: 60_000 }, async ({ evidence }) => {
+ needs({ placement: "local", commands: ["bun"] });
+ const lab = await startCaptureEfficiencyLab();
+ const sessionId = "session-logical-turn-0001";
+ const record = (value: unknown): value is Record<string, unknown> => typeof value === "object" && value !== null && !Array.isArray(value);
+ try {
+ await postControl(lab, "/control/start", { sessionId, actor: "actor-b", workspace: "workspace-b" });
+ await postControl(lab, "/control/turn", { sessionId, action: "begin" });
+ await postControl(lab, "/control/write", { sessionId, content: "print('partial')\n" });
+ await postControl(lab, "/control/turn", { sessionId, action: "pause",
+ finalTrace: { messages: [{ info: { id: "user-original", role: "user" }, parts: [{ type: "text", text: "Build the invoice CLI." }] }] },
+ });
+ await postControl(lab, "/control/turn", { sessionId, action: "begin" });
+ await postControl(lab, "/control/write", { sessionId, content: "print('complete')\n" });
+ await postControl(lab, "/control/turn", { sessionId, action: "complete",
+ finalTrace: { messages: [{ info: { id: "user-correction", role: "user" }, parts: [{ type: "text", text: "Continue with JSON output." }] }] },
+ });
+ await postControl(lab, "/control/turn", { sessionId, action: "begin" });
+ const accepted = attemptsFor(await lab.witness(), sessionId).filter(attempt => attempt.status === 201);
+ const events = accepted.flatMap(attempt => attempt.events);
+ const groups = events.filter(event => event.type === "collector.replay_group").map(event => event.data).filter(record);
+ const starts = groups.filter(group => group.phase === "start");
+ expect(starts).toHaveLength(2);
+ expect(starts[0]?.group_id).not.toBe(starts[1]?.group_id);
+ expect(starts[0]?.baseline_snapshot).toBeDefined();
+ const resumed = groups.find(group => group.phase === "resumed");
+ const completed = groups.find(group => group.phase === "completed");
+ expect(resumed?.group_id).toBe(starts[0]?.group_id);
+ expect(completed?.group_id).toBe(starts[0]?.group_id);
+ expect(resumed?.baseline_snapshot).toEqual(starts[0]?.baseline_snapshot);
+ expect(completed?.baseline_snapshot).toEqual(starts[0]?.baseline_snapshot);
+ expect(completed?.message_ids).toEqual(["user-original", "user-correction"]);
+ expect(completed?.prompt_count).toBe(2);
+ const diffs = events.filter(event => event.type === "turn.diff").map(event => event.data).filter(record);
+ const groupedDiffs = diffs.filter(diff => diff.replay_group_id === starts[0]?.group_id);
+ expect(groupedDiffs).toHaveLength(2);
+ // Both partial and final diffs still describe cli.py as added to the ORIGINAL baseline.
+ for (const diff of groupedDiffs) {
+ expect(JSON.stringify(diff)).toContain('"path":"cli.py"');
+ expect(JSON.stringify(diff)).toContain('"status":"added"');
+ }
+ expect(accepted.some(attempt => attempt.filePaths.includes("cli.py"))).toBe(true);
+ const transcript = JSON.stringify(events.filter(event => event.type === "turn.completed"));
+ expect(transcript).toContain("Build the invoice CLI.");
+ expect(transcript).toContain("Continue with JSON output.");
+ evidence.recordAssertionEvidence(
+ "Stop and correction retain one original capture baseline and both prompts",
+ "Worker uploads kept one group and baseline pointer through Stop/resume, cli.py remained added in both diffs, and both original and correction text survived. Only natural completion allowed the next distinct group.",
+ true,
+ );
+ } finally { await lab.stop(); }
+});
diff --git a/evals/specs/serialized-turns.test.ts b/evals/specs/serialized-turns.test.ts
new file mode 100644
index 00000000..0d5ff12c
--- /dev/null
+++ b/evals/specs/serialized-turns.test.ts
@@ -0,0 +1,58 @@
+import { expect } from "vitest";
+import { startSerializedTurnLab } from "@omnirush/labs";
+import { needs, test } from "@omnirush/testkit";
+
+test("serialized turns reject overlaps and verify the complete delegated tree before continuation", { timeout: 120_000 }, async ({ evidence }) => {
+ needs({ placement: "local", commands: ["bun"] });
+ const lab = await startSerializedTurnLab();
+ const root = "ses_serialized_root", child = "ses_serialized_child", grandchild = "ses_serialized_grandchild";
+ const headers = { authorization: "Bearer " + lab.token, "content-type": "application/json" };
+ const control = async (action: string, body: unknown = {}) => {
+ const response = await fetch(lab.controlUrl + "/control/" + action, { method: action === "witness" ? "GET" : "POST", headers, ...(action !== "witness" ? { body: JSON.stringify(body) } : {}), signal: AbortSignal.timeout(10_000) });
+ expect(response.ok).toBe(true);
+ return response.json();
+ };
+ const send = (id: string, action = "prompt_async", auth = headers) => fetch(lab.baseUrl + "/workspace/ws_serialized/opencode/session/" + id + "/" + action, {
+ method: "POST", headers: auth, body: JSON.stringify({ parts: [{ type: "text", text: "Build the invoice CLI." }] }), signal: AbortSignal.timeout(35_000),
+ });
+ try {
+ expect((await send(root, "prompt_async", { ...headers, authorization: "Bearer invalid" })).status).toBe(401);
+ expect((await control("witness")).prompts).toHaveLength(0);
+ await control("state", { busy: [grandchild] });
+ expect((await send(root)).status).toBe(409);
+ expect((await send(child)).status).toBe(409);
+ expect((await control("witness")).prompts).toHaveLength(0);
+ // Idle status alone is not enough while a tool is still marked running.
+ await control("state", { busy: [], runningTool: true });
+ expect((await send(root)).status).toBe(409);
+ await control("state", { busy: [grandchild], failStop: grandchild });
+ expect((await send(root, "abort")).status).toBe(503);
+ expect((await send(root)).status).toBe(409);
+ await control("state", { failStop: null });
+ expect((await send(root, "abort")).status).toBe(200);
+ const stopped = await control("witness");
+ expect(stopped.aborts).toEqual(expect.arrayContaining([root, child, grandchild]));
+ expect((await send(root)).status).toBe(204);
+ expect((await send(root)).status).toBe(409);
+ expect((await control("witness")).prompts).toHaveLength(1);
+ expect((await send(root, "abort")).status).toBe(200);
+ // Reverting a paused prompt would erase evidence; correction is a new engine message in the same group.
+ expect((await send(root, "revert")).status).toBe(409);
+ expect((await send(root)).status).toBe(204);
+ await control("complete");
+ expect((await send(root)).status).toBe(204);
+ expect((await control("witness")).prompts).toHaveLength(3);
+ expect((await send(root, "abort")).status).toBe(200);
+ await control("state", { hideActivity: true });
+ expect((await send(root)).status).toBe(503);
+ await control("state", { hideActivity: false, delayedPrompt: true });
+ expect((await send(root)).status).toBe(204);
+ // Async acceptance with a stale idle/history response must retain its reservation.
+ expect((await send(root)).status).toBe(409);
+ evidence.recordAssertionEvidence(
+ "Only a settled root and delegated tree admit the next prompt",
+ "Unauthorized and overlapping root/child requests never reached the engine; pending tools blocked idle status; failed grandchild Stop stayed blocked; verified tree Stop allowed correction, forbade destructive revert, and natural completion enabled a new prompt. Stale idle after async acceptance stayed blocked.",
+ true,
+ );
+ } finally { await lab.stop(); }
+});