Orkas is an open-source (MIT), local-first AI team for your desktop: a Commander turns your goal into to-dos and coordinates 16 built-in specialist agents plus Claude Code, Codex, OpenCode, OpenClaw and Hermes, with projects, scheduled automations and connectors. Free app for macOS & Windows; built-in models or your own keys.
JavaScript agent-collaborationagent-harnessagent-orchestrationagent-teamagent-workflowai-assistantai-automationai-employeeai-productivityai-teamai-workflowautonomous-agentsclaude-code-guiclaude-coworkdesktop-agentlocal-firstmulti-agentmulti-agent-systemself-evolving-agentstask-automation
import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
import fs from "node:fs";
import os from "node:os";
import path from "node:path";
import { PersistentSession } from "../src/agent/persistent-session.js";
import { contextBudget } from "../src/agent/session.js";
import type { Message, MessageContent } from "../src/shared/types.js";
// Mirrors the constant in persistent-session.ts; kept inline (not exported)
// so the heal contract is testable without leaking an internal sentinel.
const INTERRUPTED_TOOL_RESULT =
"[interrupted: previous run aborted before this tool produced a result]";
function tmpFile(name: string): string {
return path.join(os.tmpdir(), `core-agent-psession-${Date.now()}-${Math.random().toString(36).slice(2)}-${name}`);
}
describe("PersistentSession", () => {
let file: string;
beforeEach(() => {
file = tmpFile("t.jsonl");
});
afterEach(() => {
try { fs.unlinkSync(file); } catch { /* ignore */ }
try { fs.unlinkSync(`${file}.tmp`); } catch { /* ignore */ }
try { fs.unlinkSync(`${file}.context.json`); } catch { /* ignore */ }
try { fs.unlinkSync(`${file}.context.json.tmp`); } catch { /* ignore */ }
});
it("restores authoring images after checkpoint/restart without restoring them in the next turn", () => {
const session = new PersistentSession({ sessionFile: file });
session.beginUserTurn([{ type: "text", text: "Create using the reference" }]);
session.addAssistantMessage([{ type: "tool_use", id: "prepare", name: "fixture", input: {} }]);
session.addToolResult("prepare", "Source @ 1s maps to hero", [{ data: "SOURCE_PIXELS", mediaType: "image/png" }], false, undefined, "active_turn");
for (const id of ["read", "list", "author"]) {
session.addAssistantMessage([{ type: "tool_use", id, name: "fixture", input: {} }]);
session.addToolResult(id, "done");
}
session.applyActiveCheckpointSummary("Prepare finished; continue authoring", 6);
const expected = session.getMessagesForModel();
expect(JSON.stringify(expected)).toContain("SOURCE_PIXELS");
const restored = new PersistentSession({ sessionFile: file });
expect(restored.getMessagesForModel()).toEqual(expected);
expect(restored.estimateModelTokens()).toEqual(session.estimateModelTokens());
restored.completeActiveTurn();
restored.beginUserTurn([{ type: "text", text: "Another task" }]);
expect(JSON.stringify(restored.getMessagesForModel())).not.toContain("SOURCE_PIXELS");
expect(fs.readFileSync(file, "utf8")).toContain("SOURCE_PIXELS");
});
it("persists the turn-start history allowance across restart without losing original evidence", () => {
const session = new PersistentSession({ sessionFile: file });
for (let i = 0; i < 7; i++) {
session.beginUserTurn([{ type: "text", text: `INPUT_${i} ${"界".repeat(1000)}` }]);
session.addAssistantMessage([{ type: "text", text: `ANSWER_${i}` }]);
session.completeActiveTurn();
}
session.beginUserTurn([{ type: "text", text: "CURRENT" }]);
session.configureHistoryBudget(24_000, 19_680, 5000);
const expected = session.getMessagesForModel();
const restored = new PersistentSession({ sessionFile: file });
restored.configureHistoryBudget(24_000, 19_680, 18_000);
expect(restored.getMessagesForModel()).toEqual(expected);
expect(JSON.stringify(expected)).toContain("INPUT_6");
expect(JSON.stringify(expected)).not.toContain("INPUT_5");
expect(fs.readFileSync(file, "utf8")).toContain("INPUT_0");
});
it("keeps a clipped long historical reply stable across reload while preserving its original bytes", () => {
const session = new PersistentSession({ sessionFile: file });
const reply = "OLD_REPLY_HEAD " + "界🙂".repeat(25_000) + " LATEST_REPLY_TAIL";
session.beginUserTurn([{ type: "text", text: "Inspect the report" }]);
session.addAssistantMessage([{ type: "text", text: reply }]);
session.completeActiveTurn();
session.beginUserTurn([{ type: "text", text: "Continue" }]);
session.configureHistoryBudget(24_000, 19_680, 5000);
const expected = session.getMessagesForModel();
expect(JSON.stringify(expected)).toContain("LATEST_REPLY_TAIL");
expect(JSON.stringify(expected)).not.toContain("OLD_REPLY_HEAD");
expect(JSON.stringify(expected)).toContain("[Earlier history text omitted]");
expect(session.estimateHistoryTokens()).toBeLessThanOrEqual(2936);
expect(new PersistentSession({ sessionFile: file }).getMessagesForModel()).toEqual(expected);
expect(fs.readFileSync(file, "utf8")).toContain(reply);
});
it("restores the same five-turn window while retaining original older records on disk", () => {
const session = new PersistentSession({ sessionFile: file });
for (let i = 0; i < 9; i++) {
session.beginUserTurn([{ type: "text", text: `ORIGINAL_INPUT_${i}` }]);
session.addAssistantMessage([{ type: "text", text: `ORIGINAL_REPLY_${i}` }]);
session.completeActiveTurn();
}
session.beginUserTurn([{ type: "text", text: "ACTIVE_INPUT" }]);
const expected = session.getMessagesForModel();
const restored = new PersistentSession({ sessionFile: file });
expect(restored.getMessagesForModel()).toEqual(expected);
const text = JSON.stringify(expected);
expect(text).not.toContain("ORIGINAL_INPUT_3");
expect(text).toContain("ORIGINAL_INPUT_4");
expect(text).toContain("ORIGINAL_REPLY_8");
expect(text).toContain("ACTIVE_INPUT");
expect(fs.readFileSync(file, "utf8")).toContain("ORIGINAL_INPUT_0");
restored.applyEmergencyHistoryFold("legacy", restored.getArchivableHistoryTurns());
expect(new PersistentSession({ sessionFile: file }).getMessagesForModel()).toEqual(restored.getMessagesForModel());
});
it("preserves evidence across repeated mixed-size checkpoints and reloads", () => {
let session = new PersistentSession({ sessionFile: file });
session.beginUserTurn([{ type: "text", text: "Finish the repair using the inspected evidence" }]);
const expectedFacts: string[] = [];
for (let epoch = 0; epoch < 2; epoch++) {
[100_000, 80, 168_000, 800].forEach((size, group) => {
const id = `read-${epoch}-${group}`;
const fact = `FACT_${epoch}_${group}`;
expectedFacts.push(fact);
session.addAssistantMessage([{ type: "tool_use", id, name: "read_files", input: {} }]);
session.addToolResult(id, `${fact}\n${"x".repeat(size)}`);
});
const candidate = session.getPendingActiveCheckpoint(contextBudget({
usableInputTokens: 141_952, requestCeilingTokens: Math.floor(141_952 * 0.82), fixedOverheadTokens: 18_286,
}));
expect(candidate).not.toBeNull();
// A deterministic summarizer can retain ONLY facts actually supplied by
// the runtime, including the previous checkpoint. Never inject the oracle.
const suppliedFacts = [...new Set(JSON.stringify(candidate!.messages).match(/FACT_\d+_\d+/g) ?? [])];
session.applyActiveCheckpointSummary(`Observed facts: ${suppliedFacts.join(", ")}`, candidate!.checkpointThroughMessageIndex);
const beforeReload = session.getMessagesForModel();
session = new PersistentSession({ sessionFile: file });
expect(session.getMessagesForModel()).toEqual(beforeReload);
const restoredView = JSON.stringify(session.getMessagesForModel());
for (const fact of expectedFacts) expect(restoredView.includes(fact), `reload lost ${fact}`).toBe(true);
expect(session.activeTurnHasUserMessage([{ type: "text", text: "Finish the repair using the inspected evidence" }])).toBe(true);
}
});
it("persists a capacity-limited whole-group checkpoint with its newer raw suffix", () => {
let session = new PersistentSession({ sessionFile: file });
session.beginUserTurn([{ type: "text", text: "Continue from complete observations" }]);
for (let i = 0; i < 6; i++) {
session.addAssistantMessage([{
type: "tool_use", id: `capacity-${i}`, name: "read_files", input: { path: `source-${i}` },
}]);
session.addToolResult(
`capacity-${i}`,
`HEAD_${i}\n${"x".repeat(20_000)}\nPERSISTED_MIDDLE_${i}=yes\n${"y".repeat(20_000)}\nTAIL_${i}`,
);
}
const candidate = session.selectPendingActiveCheckpoint(undefined, 22_000).candidate!;
expect(candidate.capacityLimited).toBe(true);
expect(candidate.groups).toHaveLength(2);
const supplied = JSON.stringify(candidate.messages).match(/PERSISTED_MIDDLE_\d+=yes/g) ?? [];
session.applyActiveCheckpointSummary(
`Complete facts: ${supplied.join(", ")}`,
candidate.checkpointThroughMessageIndex,
);
const beforeReload = session.getMessagesForModel();
session = new PersistentSession({ sessionFile: file });
expect(session.getMessagesForModel()).toEqual(beforeReload);
const restored = JSON.stringify(session.getMessagesForModel());
expect(restored).toContain("PERSISTED_MIDDLE_0=yes");
expect(restored).toContain("PERSISTED_MIDDLE_1=yes");
expect(restored).toContain("PERSISTED_MIDDLE_2=yes");
expect(restored).not.toContain("HEAD_0");
});
it("starts empty when backing file does not exist", () => {
const s = new PersistentSession({ sessionFile: file });
expect(s.length).toBe(0);
expect(fs.existsSync(file)).toBe(false);
});
it("reloads an oversized parallel checkpoint without altering its persisted raw evidence", () => {
let session = new PersistentSession({ sessionFile: file });
session.beginUserTurn([{ type: "text", text: "Compare the parallel sources" }]);
const ids = Array.from({ length: 8 }, (_, i) => `parallel-${i}`);
session.addAssistantMessage(ids.map(id => ({ type: "tool_use" as const, id, name: "read_files", input: { path: id } })));
for (const id of ids) session.addToolResult(id, `HEAD_${id}\n${"x".repeat(100_000)}\nTAIL_${id}`);
session.addAssistantMessage([{ type: "tool_use", id: "next", name: "read_files", input: {} }]);
session.addToolResult("next", "LATEST_RAW");
// Load-time protocol healing coalesces parallel result messages. Establish
// that canonical transcript before comparing compaction's storage effects.
session = new PersistentSession({ sessionFile: file });
const originalTranscript = fs.readFileSync(file, "utf8");
const candidate = session.selectPendingActiveCheckpoint(undefined, 150_000).candidate!;
expect(candidate).not.toBeNull();
// A restart before summary application must still have every original byte.
session = new PersistentSession({ sessionFile: file });
expect(fs.readFileSync(file, "utf8") === originalTranscript).toBe(true);
expect(JSON.stringify(session.getMessagesForModel())).toContain("x".repeat(100_000));
const supplied = JSON.stringify(candidate.messages).match(/(?:HEAD|TAIL)_parallel-\d/g) ?? [];
expect(new Set(supplied).size).toBe(16);
session.applyActiveCheckpointSummary(supplied.join("\n"), candidate.checkpointThroughMessageIndex);
const view = session.getMessagesForModel();
session = new PersistentSession({ sessionFile: file });
expect(session.getMessagesForModel()).toEqual(view);
expect(JSON.stringify(view)).not.toContain("x".repeat(100_000));
expect(JSON.stringify(view)).toContain("LATEST_RAW");
for (const id of ids) expect(JSON.stringify(view)).toContain(`TAIL_${id}`);
expect(fs.readFileSync(file, "utf8") === originalTranscript).toBe(true);
});
it("protects the latest tool batch after interrupted execution and reload", () => {
let session = new PersistentSession({ sessionFile: file });
session.beginUserTurn([{ type: "text", text: "Inspect both sources" }]);
session.addAssistantMessage([
{ type: "tool_use", id: "returned", name: "inspect", input: {} },
{ type: "tool_use", id: "interrupted", name: "inspect", input: {} },
]);
session.addToolResult("returned", `UNREAD_SOURCE\n${"x".repeat(100_000)}`);
session = new PersistentSession({ sessionFile: file });
expect(session.getPendingActiveCheckpoint()).toBeNull();
expect(session.getFoldableActiveProcess()).toBeNull();
const results = session.getMessagesForModel().flatMap(m => m.content).filter(c => c.type === "tool_result");
expect(results).toEqual(expect.arrayContaining([
expect.objectContaining({ toolUseId: "returned", content: `UNREAD_SOURCE\n${"x".repeat(100_000)}` }),
expect.objectContaining({ toolUseId: "interrupted", content: INTERRUPTED_TOOL_RESULT }),
]));
session.addAssistantMessage([{ type: "tool_use", id: "next", name: "inspect", input: {} }]);
session.addToolResult("next", "LATEST_RESULT");
const candidate = session.getPendingActiveCheckpoint()!;
expect(candidate).not.toBeNull();
session.applyActiveCheckpointSummary("Earlier source inspected", candidate.checkpointThroughMessageIndex);
session = new PersistentSession({ sessionFile: file });
expect(JSON.stringify(session.getMessagesForModel())).toContain("LATEST_RESULT");
expect(session.getFoldableActiveProcess()).toBeNull();
});
it("reloads host observations and native tool images without creating a user turn", () => {
const session = new PersistentSession({ sessionFile: file });
session.beginUserTurn([{ type: "text", text: "Inspect the preview" }]);
session.addAssistantMessage([{ type: "tool_use", id: "image", name: "read_files", input: {} }]);
session.addToolResult("image", "preview", [{ data: "pixels", mediaType: "image/png" }]);
session.addMessage("developer", [{ type: "text", text: "Runtime observation: externally changed." }]);
const before = session.getMessagesForModel();
const restored = new PersistentSession({ sessionFile: file });
expect(restored.getMessagesForModel()).toEqual(before);
expect(restored.activeTurnHasUserMessage([{ type: "text", text: "Inspect the preview" }])).toBe(true);
expect(restored.activeTurnHasUserMessage([{ type: "text", text: "Runtime observation: externally changed." }])).toBe(false);
restored.addUserMessage("A genuine correction");
const again = new PersistentSession({ sessionFile: file });
expect(again.getMessagesForModel().at(-1)).toMatchObject({ role: "user",
content: [{ type: "text", text: "A genuine correction" }] });
});
it("migrates legacy tool image trailers but not a later user's image-only message", () => {
const rows: Message[] = [
{ role: "user", turnId: 1, content: [{ type: "text", text: "Inspect" }] },
{ role: "assistant", turnId: 1, content: [{ type: "tool_use", id: "image", name: "read_files", input: {} }] },
{ role: "user", turnId: 1, content: [{ type: "tool_result", toolUseId: "image", content: "preview" }] },
{ role: "user", turnId: 1, content: [{ type: "image", data: "old-tool-image", mediaType: "image/png" }] },
{ role: "user", turnId: 2, content: [{ type: "image", data: "real-user-image", mediaType: "image/png" }] },
];
fs.writeFileSync(file, rows.map((row) => JSON.stringify(row)).join("\n") + "\n");
const restored = new PersistentSession({ sessionFile: file });
const messages = restored.getMessages();
expect(messages[2].content[0]).toMatchObject({ type: "tool_result", images: [{ data: "old-tool-image" }] });
expect(messages[3]).toMatchObject({ role: "user", turnId: 2, content: [{ type: "image", data: "real-user-image" }] });
expect(new PersistentSession({ sessionFile: file }).getMessages()).toEqual(messages);
});
it.each([false, true])("preserves a same-turn user image after a new receipt (tool image: %s)", (hasToolImage) => {
const session = new PersistentSession({ sessionFile: file });
session.beginUserTurn([{ type: "text", text: "Inspect" }]);
session.addAssistantMessage([{ type: "tool_use", id: "read", name: "read_files", input: {} }]);
session.addToolResult("read", "result", hasToolImage ? [{ data: "tool-pixels", mediaType: "image/png" }] : undefined);
session.addMessage("user", [{ type: "image", data: "real-user-correction", mediaType: "image/png" }]);
const before = session.getMessagesForModel();
expect(session.healAndPersist()).toBe(false);
const restored = new PersistentSession({ sessionFile: file });
expect(restored.getMessagesForModel()).toEqual(before);
expect(restored.getMessagesForModel().at(-1)).toMatchObject({ role: "user",
content: [{ type: "image", data: "real-user-correction" }] });
restored.applyActiveCheckpointSummary("Inspected the earlier report.", restored.length - 1);
expect(restored.getMessagesForModel().at(-1)).toMatchObject({ role: "user",
content: [{ type: "image", data: "real-user-correction" }] });
});
it("keeps a mid-turn correction's frozen plan anchor across restart", () => {
const s1 = new PersistentSession({ sessionFile: file });
s1.beginUserTurn([{ type: "text", text: "Finish the migration" }]);
s1.updateExecutionPlan({ steps: [{ step: "Apply migration", status: "in_progress" }] });
s1.addAssistantMessage([{ type: "tool_use", id: "read", name: "read_file", input: {} }]);
s1.addToolResult("read", "bytes");
s1.addMessage("user", [{ type: "text", text: "Pause and report" }]);
const before = s1.getMessagesForModel();
expect(JSON.stringify(before.at(-1))).toContain("Reconciliation required");
const s2 = new PersistentSession({ sessionFile: file });
expect(s2.getMessagesForModel()).toEqual(before);
// A later plan change after restart appends; the restored anchor stays put.
s2.updateExecutionPlan({ steps: [{ step: "Report", status: "in_progress" }] });
expect(s2.getMessagesForModel()).toEqual(before);
});
it("persists messages to disk on add", () => {
const s = new PersistentSession({ sessionFile: file });
s.addUserMessage("hello");
s.addAssistantMessage([{ type: "text", text: "hi back" }]);
expect(fs.existsSync(file)).toBe(true);
const lines = fs.readFileSync(file, "utf-8").trim().split("\n");
expect(lines).toHaveLength(2);
const first = JSON.parse(lines[0]);
expect(first.role).toBe("user");
expect(first.content[0]).toEqual({ type: "text", text: "hello" });
expect(typeof first.ts).toBe("number");
});
it("resumes prior messages from disk", () => {
const s1 = new PersistentSession({ sessionFile: file });
s1.addUserMessage("msg A");
s1.addAssistantMessage([{ type: "text", text: "reply A" }]);
const s2 = new PersistentSession({ sessionFile: file });
expect(s2.length).toBe(2);
const msgs = s2.getMessages();
expect(msgs[0].role).toBe("user");
expect((msgs[0].content[0] as { text: string }).text).toBe("msg A");
expect(msgs[1].role).toBe("assistant");
});
it("persists the v3 tool-surface marker without dynamic groups", () => {
const s1 = new PersistentSession({ sessionFile: file });
s1.setToolSurfaceState({
version: 3,
mode: "scoped",
loadedGroups: [],
catalogRevision: "6",
});
const s2 = new PersistentSession({ sessionFile: file });
expect(s2.getToolSurfaceState()).toEqual({
version: 3,
mode: "scoped",
loadedGroups: [],
catalogRevision: "6",
});
// A full history rewrite must not disturb the tool-surface sidecar.
// (This step used the legacy whole-session compact() before its removal;
// canonical history replacement is the surviving rewrite operation.)
s2.replaceConversationHistory([
{ role: "user", turnId: 1, content: [{ type: "text", text: "old turn" }] },
{ role: "assistant", turnId: 1, content: [{ type: "text", text: "old reply" }] },
], "group-main-v1:tool-surface-test");
const s3 = new PersistentSession({ sessionFile: file });
expect(s3.getToolSurfaceState()?.loadedGroups).toEqual([]);
s3.clear();
expect(s3.getToolSurfaceState()).toBeUndefined();
});
it("persists one rich steer durability batch with its resource sidecar", () => {
const s1 = new PersistentSession({ sessionFile: file });
s1.withContextMutationBatch(() => {
s1.beginUserTurn([
{ type: "text", text: "inspect this chart" },
{ type: "image", data: "aW1hZ2U=", mediaType: "image/png" },
]);
s1.addHistoryResource({
kind: "attachment",
path: "/workspace/chart.png",
name: "chart.png",
mediaType: "image/png",
});
});
const s2 = new PersistentSession({ sessionFile: file });
expect(s2.getMessages()[0]).toMatchObject({
role: "user",
content: [
{ type: "text", text: "inspect this chart" },
{ type: "image", data: "aW1hZ2U=", mediaType: "image/png" },
],
});
expect(s2.getSerializedContextState()?.resources).toContainEqual(expect.objectContaining({
kind: "attachment",
path: "/workspace/chart.png",
name: "chart.png",
}));
});
it("rebases semantic dialogue from a canonical source while preserving compatible compaction", () => {
const session = new PersistentSession({ sessionFile: file });
session.beginUserTurn([{ type: "text", text: "PRIVATE_TOOL_TRANSCRIPT" }]);
session.addAssistantMessage([{ type: "text", text: "private reply" }]);
session.completeActiveTurn();
session.addHistoryResource({
kind: "final_output",
path: "/workspace/video.mp4",
name: "video.mp4",
});
const canonical: Message[] = [
{ role: "user", turnId: 1, content: [{ type: "text", text: "Make the video" }] },
{ role: "assistant", turnId: 1, content: [{ type: "text", text: "Commander delegated to VideoStudio" }] },
{ role: "user", turnId: 2, content: [{ type: "text", text: "Continue the video task" }] },
{
role: "assistant",
turnId: 2,
content: [{
type: "text",
text: "VideoStudio: E_NARRATION_REPAIR_AUTHORIZATION_NOT_PERSISTED",
}],
},
];
session.replaceConversationHistory(canonical, "group-main-v1:cid-1");
let model = JSON.stringify(session.getMessagesForModel());
expect(model).toContain("VideoStudio");
expect(model).toContain("E_NARRATION_REPAIR_AUTHORIZATION_NOT_PERSISTED");
expect(model).not.toContain("PRIVATE_TOOL_TRANSCRIPT");
expect(session.getSerializedContextState()).toMatchObject({
conversationHistorySource: "group-main-v1:cid-1",
resources: [expect.objectContaining({ name: "video.mp4" })],
});
session.applyHistorySummary(
"Summary of the first canonical turn",
[1],
);
session.replaceConversationHistory([
...canonical,
{ role: "user", turnId: 3, content: [{ type: "text", text: "Third exact request" }] },
{ role: "assistant", turnId: 3, content: [{ type: "text", text: "Third exact response" }] },
], "group-main-v1:cid-1");
expect(session.beginUserTurn([{ type: "text", text: "Fix that blocker." }])).toBe(4);
model = JSON.stringify(session.getMessagesForModel());
expect(model).not.toContain("Summary of the first canonical turn");
expect(model).toContain("Make the video");
expect(model).toContain("E_NARRATION_REPAIR_AUTHORIZATION_NOT_PERSISTED");
expect(model).toContain("Third exact request");
expect(model).toContain("Fix that blocker.");
const restored = new PersistentSession({ sessionFile: file });
expect(restored.getSerializedContextState()?.conversationHistorySource)
.toBe("group-main-v1:cid-1");
expect(JSON.stringify(restored.getMessages())).toContain("Third exact response");
restored.replaceConversationHistory(canonical, "group-main-v2:cid-1");
expect(restored.getSerializedContextState()?.historySummary).toBeUndefined();
expect(JSON.stringify(restored.getMessagesForModel())).toContain("Make the video");
});
it("rewrites only the canonical tail and preserves rolling-compaction state", () => {
const session = new PersistentSession({ sessionFile: file });
const source = "group-main-v1:cid-incremental";
const canonical: Message[] = [
{ role: "user", turnId: 1, content: [{ type: "text", text: "old one" }] },
{ role: "assistant", turnId: 1, content: [{ type: "text", text: "answer one" }] },
{ role: "user", turnId: 2, content: [{ type: "text", text: "old two" }] },
{ role: "assistant", turnId: 2, content: [{ type: "text", text: "answer two" }] },
{ role: "user", turnId: 3, content: [{ type: "text", text: "old three" }] },
{ role: "assistant", turnId: 3, content: [{ type: "text", text: "stale answer" }] },
];
session.replaceConversationHistory(canonical, source, { checkpoint: "cursor-1" });
session.applyHistorySummary("summary stays byte-for-byte", [1]);
const prefixBefore = fs.readFileSync(file, "utf-8").split("\n").slice(0, 4);
const fullSessionRewrite = vi.spyOn(fs, "writeFileSync");
session.replaceConversationHistory([
{ role: "user", turnId: 3, content: [{ type: "text", text: "old three" }] },
{ role: "assistant", turnId: 3, content: [{ type: "text", text: "VideoStudio: E_BLOCKER" }] },
{ role: "user", turnId: 4, content: [{ type: "text", text: "new four" }] },
{ role: "assistant", turnId: 4, content: [{ type: "text", text: "answer four" }] },
], source, {
replaceFromTurnId: 3,
checkpoint: "cursor-2",
});
const prefixAfter = fs.readFileSync(file, "utf-8").split("\n").slice(0, 4);
expect(prefixAfter).toEqual(prefixBefore);
expect(fullSessionRewrite.mock.calls.some(([target]) => target === `${file}.tmp`)).toBe(false);
expect(session.getSerializedContextState()).toMatchObject({
conversationHistorySource: source,
conversationHistoryCheckpoint: "cursor-2",
historySummary: "summary stays byte-for-byte",
summaryThroughTurnId: 1,
});
expect(JSON.stringify(session.getMessagesForModel())).toContain("E_BLOCKER");
fullSessionRewrite.mockRestore();
const restored = new PersistentSession({ sessionFile: file });
expect(restored.getConversationHistoryCheckpoint(source)).toBe("cursor-2");
expect(restored.getSerializedContextState()?.historySummary)
.toBe("summary stays byte-for-byte");
expect(JSON.stringify(restored.getMessagesForModel())).toContain("E_BLOCKER");
expect(JSON.stringify(restored.getMessagesForModel())).toContain("new four");
});
it("rejects an incremental tail that would rewrite an already summarized turn", () => {
const session = new PersistentSession({ sessionFile: file });
const source = "group-main-v1:cid-summary-boundary";
session.replaceConversationHistory([
{ role: "user", turnId: 1, content: [{ type: "text", text: "one" }] },
{ role: "assistant", turnId: 1, content: [{ type: "text", text: "answer" }] },
{ role: "user", turnId: 2, content: [{ type: "text", text: "two" }] },
{ role: "assistant", turnId: 2, content: [{ type: "text", text: "answer two" }] },
], source);
session.applyHistorySummary("existing summary", [1]);
expect(() => session.replaceConversationHistory([
{ role: "user", turnId: 1, content: [{ type: "text", text: "changed" }] },
{ role: "assistant", turnId: 1, content: [{ type: "text", text: "changed answer" }] },
], source, { replaceFromTurnId: 1 })).toThrow("already summarized");
expect(session.getSerializedContextState()?.historySummary).toBe("existing summary");
});
it("invalidates only the sync cursor when restart repair trims raw history", () => {
const source = "group-main-v1:cid-restart-fallback";
const session = new PersistentSession({ sessionFile: file });
const canonical: Message[] = [];
for (let turnId = 1; turnId <= 60; turnId++) {
canonical.push(
{ role: "user", turnId, content: [{ type: "text", text: `user ${turnId}` }] },
{ role: "assistant", turnId, content: [{ type: "text", text: `answer ${turnId}` }] },
);
}
session.replaceConversationHistory(canonical, source, { checkpoint: "stale-after-trim" });
session.applyHistorySummary("retained rolling summary", Array.from({ length: 10 }, (_, i) => i + 1));
const restored = new PersistentSession({ sessionFile: file });
expect(restored.getConversationHistoryCheckpoint(source)).toBeUndefined();
expect(restored.getSerializedContextState()?.historySummary)
.toBe("retained rolling summary");
expect(restored.getSerializedContextState()?.summaryThroughTurnId).toBe(10);
});
it.each([false, true])("persists turn context without replaying raw history (experimental sidecar: %s)", (experimentalSidecar) => {
const s1 = new PersistentSession({ sessionFile: file });
s1.beginUserTurn([{ type: "text", text: "inspect" }]);
s1.addAssistantMessage([{ type: "tool_use", id: "call-1", name: "bash", input: { command: "echo hidden" } }]);
s1.addToolResult("call-1", "hidden output", undefined, false);
s1.addAssistantMessage([{ type: "text", text: "visible final" }]);
s1.completeActiveTurn();
expect(fs.existsSync(`${file}.context.json`)).toBe(true);
const raw = fs.readFileSync(file, "utf-8");
expect(raw).toContain("hidden output");
if (experimentalSidecar) {
const context = JSON.parse(fs.readFileSync(`${file}.context.json`, "utf-8"));
context.previousTurnToolRecords = ["obsolete experimental process"];
fs.writeFileSync(`${file}.context.json`, JSON.stringify(context));
}
const s2 = new PersistentSession({ sessionFile: file });
s2.beginUserTurn([{ type: "text", text: "next" }]);
const model = JSON.stringify(s2.getMessagesForModel());
expect(model).toContain("inspect");
expect(model).toContain("visible final");
expect(model).toContain("next");
expect(model).not.toContain("hidden output");
expect(model).not.toContain("call-1");
expect(model).not.toContain("obsolete experimental process");
expect(JSON.parse(fs.readFileSync(`${file}.context.json`, "utf-8")))
.not.toHaveProperty("previousTurnToolRecords");
expect(fs.readFileSync(file, "utf-8")).toContain("hidden output");
});
it("persists workspace observations immediately in the context sidecar", () => {
const filePath = path.join(os.tmpdir(), "persisted-workspace.ts");
const session = new PersistentSession({ sessionFile: file });
session.beginUserTurn([{ type: "text", text: "track the file" }]);
session.recordToolObservations({
toolCallId: "read-1",
tool: "read_file",
observations: {
fileReads: [{ path: filePath, hash: "sha256:known" }],
},
});
const context = JSON.parse(fs.readFileSync(`${file}.context.json`, "utf8"));
expect(context.workspaceObservations.entries).toHaveLength(1);
expect(context.workspaceObservations.entries[0]).toMatchObject({
toolCallId: "read-1",
tool: "read_file",
});
const restored = new PersistentSession({ sessionFile: file });
expect(restored.getWorkspaceObservations().entries).toHaveLength(1);
});
it("preserves the exact active tool history and workspace ledger across restart", () => {
const s1 = new PersistentSession({ sessionFile: file });
s1.beginUserTurn([{ type: "text", text: "Update the persistent file and inspect it" }]);
s1.addAssistantMessage([{
type: "tool_use",
id: "persistent-change",
name: "edit_file",
input: { path: "/workspace/persistent.ts" },
}]);
s1.recordToolObservations({
toolCallId: "persistent-change",
tool: "edit_file",
observations: {
fileChanges: [{
operation: "update",
sourcePath: "/workspace/persistent.ts",
beforeExists: true,
afterExists: true,
beforeHash: "sha256:persistent-before",
afterHash: "sha256:persistent-after",
coverage: "exact",
}],
},
});
s1.addToolResult("persistent-change", "PERSISTENT_CHANGE_RESULT", undefined, false);
s1.addAssistantMessage([{
type: "tool_use",
id: "persistent-read",
name: "read_file",
input: { path: "/workspace/persistent.ts" },
}]);
s1.addToolResult("persistent-read", "PERSISTENT_READ_RESULT", undefined, false);
const beforeRestart = s1.getMessagesForModel();
const s2 = new PersistentSession({ sessionFile: file });
const modelView = s2.getMessagesForModel();
expect(modelView).toEqual(beforeRestart);
expect(JSON.stringify(modelView)).toContain("PERSISTENT_READ_RESULT");
expect(s2.getWorkspaceObservations().entries).toHaveLength(1);
});
it("coalesces one logical tool completion into one context sidecar rewrite", () => {
const session = new PersistentSession({ sessionFile: file });
session.beginUserTurn([{ type: "text", text: "run one durable tool" }]);
session.addAssistantMessage([{
type: "tool_use",
id: "call-batch",
name: "bash",
input: { command: "npm test" },
}]);
const writeSpy = vi.spyOn(fs, "writeFileSync");
try {
session.withContextMutationBatch(() => {
session.recordToolObservations({
toolCallId: "call-batch",
tool: "bash",
observations: {
execution: {
status: "succeeded",
exitCode: 0,
durationMs: 10,
timedOut: false,
outputLimitExceeded: false,
stdout: { bytes: 2, truncated: false },
stderr: { bytes: 0, truncated: false },
},
},
});
session.addToolResult("call-batch", "ok", undefined, false);
session.recordCompletedWork({
toolCallId: "call-batch",
tool: "bash",
inputDigest: "8:npm-test",
inputSummary: '{"command":"npm test"}',
status: "succeeded",
resultSummary: "ok",
checkpointEpoch: 0,
});
});
const contextWrites = writeSpy.mock.calls.filter(
([target]) => target === `${file}.context.json.tmp`,
);
expect(contextWrites).toHaveLength(1);
const serialized = fs.readFileSync(`${file}.context.json`, "utf8");
expect(serialized).not.toContain("\n ");
expect(JSON.parse(serialized).completedWork).toHaveLength(1);
} finally {
writeSpy.mockRestore();
}
});
it("flushes a context mutation batch before propagating a synchronous interruption", () => {
const session = new PersistentSession({ sessionFile: file });
session.beginUserTurn([{ type: "text", text: "persist before interruption" }]);
session.addAssistantMessage([{
type: "tool_use",
id: "call-interrupted-commit",
name: "read_file",
input: { path: "/workspace/input.txt" },
}]);
const writeSpy = vi.spyOn(fs, "writeFileSync");
try {
expect(() => session.withContextMutationBatch(() => {
session.recordToolObservations({
toolCallId: "call-interrupted-commit",
tool: "read_file",
observations: {
fileReads: [{ path: "/workspace/input.txt", hash: "sha256:stable" }],
},
});
session.addToolResult("call-interrupted-commit", "read ok", undefined, false);
session.recordCompletedWork({
toolCallId: "call-interrupted-commit",
tool: "read_file",
inputDigest: "8:input-txt",
inputSummary: '{"path":"/workspace/input.txt"}',
status: "succeeded",
resultSummary: "read ok",
checkpointEpoch: 0,
});
throw new Error("injected synchronous interruption");
})).toThrow("injected synchronous interruption");
const contextWrites = writeSpy.mock.calls.filter(
([target]) => target === `${file}.context.json.tmp`,
);
expect(contextWrites).toHaveLength(1);
const restored = new PersistentSession({ sessionFile: file });
expect(restored.getSerializedContextState()?.completedWork)
.toHaveLength(1);
expect(restored.getWorkspaceObservations().entries)
.toHaveLength(1);
expect(JSON.stringify(restored.getMessages()))
.toContain("call-interrupted-commit");
} finally {
writeSpy.mockRestore();
}
});
it("keeps one stable turn across parallel-result healing, same-turn steer, and restart", () => {
const s1 = new PersistentSession({ sessionFile: file });
const turnId = s1.beginUserTurn([{ type: "text", text: "Original long-running task" }]);
s1.addAssistantMessage([
{ type: "tool_use", id: "call-a", name: "search", input: { q: "a" } },
{ type: "tool_use", id: "call-b", name: "search", input: { q: "b" } },
]);
s1.addToolResult("call-a", "hidden result a", undefined, false);
s1.addToolResult("call-b", "hidden result b", undefined, false);
s1.addMessage("user", [{ type: "text", text: "Also include the same-turn user steer" }]);
s1.addAssistantMessage([{ type: "text", text: "Final answer for the original task" }]);
s1.completeActiveTurn();
expect(turnId).toBe(1);
expect(s1.getMessages().every((message) => message.turnId === turnId)).toBe(true);
expect(s1.healAndPersist()).toBe(true);
expect(s1.getSerializedContextState()?.completedTurns).toHaveLength(1);
const s2 = new PersistentSession({ sessionFile: file });
const restored = s2.getSerializedContextState();
expect(restored?.completedTurns).toHaveLength(1);
expect(restored?.completedTurns[0]).toMatchObject({
id: turnId,
userMessageIndex: 0,
finalAssistantMessageIndex: 4,
startIndex: 0,
endIndex: 4,
});
s2.beginUserTurn([{ type: "text", text: "Follow-up task" }]);
const model = JSON.stringify(s2.getMessagesForModel());
expect(model).toContain("Original long-running task");
expect(model).toContain("Also include the same-turn user steer");
expect(model).toContain("Final answer for the original task");
expect(model).not.toContain("hidden result a");
expect(model).not.toContain("hidden result b");
expect(s2.getMessagesForModel().some((message) => "turnId" in message)).toBe(false);
});
it("repairs a legacy internal convergence nudge that was persisted as a false user turn", () => {
const legacyNudge = [
"You are approaching the tool loop round limit (8/18; 10 round(s) left).",
"Stop exploratory/retry tool calls now unless one final tool call is strictly necessary.",
].join("\n\n");
fs.writeFileSync(
file,
[
JSON.stringify({ role: "user", content: [{ type: "text", text: "Original research task" }] }),
JSON.stringify({ role: "assistant", content: [{ type: "tool_use", id: "legacy-call", name: "search", input: {} }] }),
JSON.stringify({ role: "user", content: [{ type: "tool_result", toolUseId: "legacy-call", content: "legacy hidden output" }] }),
JSON.stringify({ role: "user", content: [{ type: "text", text: legacyNudge }] }),
JSON.stringify({ role: "assistant", content: [{ type: "text", text: "Legacy final answer" }] }),
].join("\n") + "\n",
"utf-8",
);
fs.writeFileSync(
`${file}.context.json`,
JSON.stringify({
version: 1,
nextTurnId: 3,
completedTurns: [
{ id: 1, userMessageIndex: 0, finalAssistantMessageIndex: 1, startIndex: 0, endIndex: 2 },
{ id: 2, userMessageIndex: 3, finalAssistantMessageIndex: 4, startIndex: 3, endIndex: 4 },
],
resources: [],
}),
"utf-8",
);
const session = new PersistentSession({ sessionFile: file });
const repaired = session.getSerializedContextState();
expect(repaired?.completedTurns).toHaveLength(1);
expect(repaired?.completedTurns[0]).toMatchObject({
id: 1,
userMessageIndex: 0,
finalAssistantMessageIndex: 4,
startIndex: 0,
endIndex: 4,
});
session.beginUserTurn([{ type: "text", text: "Next real user task" }]);
const model = JSON.stringify(session.getMessagesForModel());
expect(model).toContain("Original research task");
expect(model).toContain("Legacy final answer");
expect(model).not.toContain("approaching the tool loop round limit");
expect(model).not.toContain("legacy hidden output");
// Raw audit history remains intact; compatibility changes only the model
// projection and repaired context sidecar.
const rawMessages = fs.readFileSync(file, "utf-8").trim().split("\n").map((line) => JSON.parse(line));
expect(rawMessages.some((message) => message.content?.some(
(content: { type?: string; text?: string }) => content.type === "text" && content.text === legacyNudge,
))).toBe(true);
});
it("persists the execution plan and its frozen checkpoint context across restart", () => {
const s1 = new PersistentSession({ sessionFile: file });
s1.beginUserTurn([{ type: "text", text: "Finish the multi-hour migration" }]);
s1.updateExecutionPlan({
steps: [
{ step: "Inventory callers", status: "completed" },
{ step: "Migrate storage", status: "in_progress" },
{ step: "Verify restart behavior", status: "pending" },
],
});
s1.addAssistantMessage([{ type: "tool_use", id: "call-plan", name: "bash", input: { command: "inspect" } }]);
s1.addToolResult("call-plan", "inspection complete", undefined, false);
s1.applyActiveCheckpointSummary("Inspection complete.", 2);
const rawHistory = fs.readFileSync(file, "utf-8");
const sidecar = fs.readFileSync(`${file}.context.json`, "utf-8");
expect(rawHistory).not.toContain("executionPlan");
expect(sidecar).toContain("executionPlan");
expect(sidecar).toContain("Finish the multi-hour migration");
const s2 = new PersistentSession({ sessionFile: file });
const view = JSON.stringify(s2.getMessagesForModel());
expect(view).toContain("Execution plan anchor");
expect(view).toContain("Finish the multi-hour migration");
expect(view).toContain("Migrate storage");
expect(s2.getExecutionPlan()?.revision).toBe(1);
expect(s2.getExecutionPlan()?.steps.map((step) => step.id)).toEqual([1, 2, 3]);
expect(s2.getExecutionPlan()?.nextStepId).toBe(4);
});
it("does not rewrite the sidecar for an unchanged complete Plan snapshot", () => {
const session = new PersistentSession({ sessionFile: file });
session.beginUserTurn([{ type: "text", text: "Finish the durable migration" }]);
const steps = [
{ step: "Inventory callers", status: "completed" as const },
{ step: "Migrate storage", status: "in_progress" as const },
];
session.updateExecutionPlan({ explanation: "Initial transition", steps });
const writeSpy = vi.spyOn(fs, "writeFileSync");
const replay = session.updateExecutionPlan({
explanation: "A paraphrased explanation is not new progress",
steps,
});
expect(replay.revision).toBe(1);
expect(writeSpy).not.toHaveBeenCalled();
writeSpy.mockRestore();
});
it("migrates persisted plans without step ids and keeps assigned ids stable", () => {
const s1 = new PersistentSession({ sessionFile: file });
s1.beginUserTurn([{ type: "text", text: "Complete the durable migration" }]);
s1.updateExecutionPlan({
steps: [
{ step: "Inspect existing state", status: "in_progress" },
{ step: "Migrate durable state", status: "pending" },
],
});
const legacySidecar = JSON.parse(fs.readFileSync(`${file}.context.json`, "utf-8"));
for (const step of legacySidecar.executionPlan.steps) delete step.id;
delete legacySidecar.executionPlan.nextStepId;
fs.writeFileSync(`${file}.context.json`, JSON.stringify(legacySidecar), "utf-8");
const restored = new PersistentSession({ sessionFile: file });
expect(restored.getExecutionPlan()?.steps.map((step) => step.id)).toEqual([1, 2]);
const updated = restored.updateExecutionPlan({
steps: [
{ step: "Inspect existing state", status: "completed" },
{ step: "Migrate durable state", status: "in_progress" },
{ step: "Verify restored state", status: "pending" },
],
});
expect(updated.steps.map((step) => step.id)).toEqual([1, 2, 3]);
expect(updated.nextStepId).toBe(4);
});
it("persists completed-work evidence and plan audit tombstones across restart", () => {
const s1 = new PersistentSession({ sessionFile: file });
s1.beginUserTurn([{ type: "text", text: "Complete the evidenced migration" }]);
s1.updateExecutionPlan({
steps: [{ step: "Run migration verification", status: "in_progress" }],
});
s1.recordCompletedWork({
toolCallId: "verify-1",
tool: "bash",
inputDigest: "18:verify",
inputSummary: '{"command":"npm test"}',
status: "succeeded",
resultSummary: "121 tests passed",
checkpointEpoch: 1,
});
s1.updateExecutionPlan({
steps: [{ step: "Run migration verification", status: "completed" }],
});
s1.applyActiveCheckpointSummary("Verification complete.", s1.length - 1);
const s2 = new PersistentSession({ sessionFile: file });
expect(s2.getCompletedWorkLedger()).toEqual([expect.objectContaining({
id: 1,
tool: "bash",
status: "succeeded",
})]);
// The plan itself survives the reload; the ledger above is what records
// which calls actually ran.
expect(s2.getExecutionPlan()?.steps[0]).toMatchObject({ status: "completed" });
expect(s2.getExecutionPlanAudit()).toHaveLength(2);
expect(JSON.stringify(s2.getMessagesForModel())).toContain("Completed work ledger");
s2.addMessage("user", [{ type: "text", text: "Verification accepted; clear the plan" }]);
s2.clearExecutionPlan();
const s3 = new PersistentSession({ sessionFile: file });
expect(s3.getExecutionPlan()).toBeUndefined();
expect(s3.getExecutionPlanAudit().at(-1)?.action).toBe("clear");
expect(s3.getCompletedWorkLedger()).toHaveLength(1);
});
it("recomputes completed-work visibility after restart and checkpoint recovery", () => {
const s1 = new PersistentSession({ sessionFile: file });
s1.beginUserTurn([{ type: "text", text: "Continue from the durable tool result" }]);
s1.addAssistantMessage([{
type: "tool_use",
id: "call-durable",
name: "bash",
input: { command: "npm test" },
}]);
s1.addToolResult("call-durable", "DURABLE_RAW_RESULT", undefined, false);
s1.recordCompletedWork({
toolCallId: "call-durable",
tool: "bash",
inputDigest: "durable:1",
inputSummary: "run npm test",
status: "succeeded",
resultSummary: "DURABLE_LEDGER_RESULT",
});
const s2 = new PersistentSession({ sessionFile: file });
let modelView = JSON.stringify(s2.getMessagesForModel());
expect(modelView).toContain("DURABLE_RAW_RESULT");
expect(modelView).not.toContain("DURABLE_LEDGER_RESULT");
expect(s2.getCompletedWorkLedger()).toHaveLength(1);
s2.applyActiveCheckpointSummary("The durable command completed successfully.", 2);
const s3 = new PersistentSession({ sessionFile: file });
modelView = JSON.stringify(s3.getMessagesForModel());
expect(modelView).not.toContain("DURABLE_RAW_RESULT");
expect(modelView).toContain("DURABLE_LEDGER_RESULT");
expect(s3.getCompletedWorkLedger()).toHaveLength(1);
});
it("applies the checkpoint summary hard bound at storage, not only in the preview", () => {
// The runner passes CONTEXT_COMPACTION_SUMMARY_HARD_TOKENS to the
// production session class. An override that drops the bound stores the
// model's unbounded summary and the savings gate is fooled by the bounded
// preview (2026-08-28 review B1-1).
const s1 = new PersistentSession({ sessionFile: file });
s1.beginUserTurn([{ type: "text", text: "Long task with an oversized checkpoint" }]);
s1.addAssistantMessage([{ type: "tool_use", id: "call-1", name: "bash", input: { command: "ls" } }]);
s1.addToolResult("call-1", "listing", undefined, false);
const oversized = Array.from({ length: 400 }, (_, i) => `- fact ${i}: ${"x".repeat(40)}`).join("\n");
const bound = 200;
const preview = s1.previewActiveCheckpointTokens(oversized, 2, bound);
const stored = s1.applyActiveCheckpointSummary(oversized, 2, bound);
expect(stored.length).toBeLessThan(oversized.length);
const reloaded = new PersistentSession({ sessionFile: file });
const modelView = JSON.stringify(reloaded.getMessagesForModel());
expect(modelView).not.toContain("fact 399");
expect(reloaded.estimateModelTokens()).toBeLessThanOrEqual(preview + 50);
});
it("repairs restored turn context when indexes point at tool process rows", () => {
fs.writeFileSync(
file,
[
JSON.stringify({ role: "user", content: [{ type: "text", text: "First task" }] }),
JSON.stringify({ role: "assistant", content: [{ type: "tool_use", id: "call-old", name: "bash", input: { command: "echo hidden" } }] }),
JSON.stringify({ role: "user", content: [{ type: "tool_result", toolUseId: "call-old", content: "old hidden output", isError: false }] }),
JSON.stringify({ role: "assistant", content: [{ type: "text", text: "First final answer" }] }),
JSON.stringify({ role: "user", content: [{ type: "text", text: "Current task" }] }),
JSON.stringify({ role: "assistant", content: [{ type: "tool_use", id: "call-current", name: "bash", input: { command: "echo current" } }] }),
JSON.stringify({ role: "user", content: [{ type: "tool_result", toolUseId: "call-current", content: "current output", isError: false }] }),
].join("\n") + "\n",
"utf-8",
);
fs.writeFileSync(
`${file}.context.json`,
JSON.stringify({
version: 1,
nextTurnId: 99,
historySummary: "older summary",
summaryVersion: 2,
completedTurns: [{
id: 1,
userMessageIndex: 1,
finalAssistantMessageIndex: 3,
startIndex: 1,
endIndex: 3,
archived: false,
}],
activeTurn: {
id: 2,
userMessageIndex: 5,
startIndex: 5,
},
resources: [{ kind: "final_output", path: "/tmp/resource.mov", name: "resource.mov" }],
}),
"utf-8",
);
const s = new PersistentSession({ sessionFile: file });
const model = JSON.stringify(s.getMessagesForModel());
expect(model).not.toContain("older summary");
expect(JSON.stringify(s.getSerializedContextState()?.resources)).toContain("resource.mov");
expect(model).toContain("First task");
expect(model).toContain("First final answer");
expect(model).toContain("Current task");
expect(model).toContain("call-current");
expect(model).toContain("current output");
expect(model).not.toContain("call-old");
expect(model).not.toContain("old hidden output");
const repaired = JSON.parse(fs.readFileSync(`${file}.context.json`, "utf-8"));
expect(repaired.completedTurns[0].userMessageIndex).toBe(0);
expect(repaired.activeTurn.userMessageIndex).toBe(4);
});
it("tolerates corrupt + schema-invalid lines and keeps the valid ones", () => {
// Mix of failure modes that show up in the wild: a half-written line
// (process killed mid-append), an unknown role (older schema /
// tampering), a non-array content (manual edit), plus blank tail.
fs.writeFileSync(
file,
[
JSON.stringify({ role: "user", content: [{ type: "text", text: "good 1" }] }),
"{not valid json",
JSON.stringify({ role: "robot", content: [{ type: "text", text: "wrong role" }] }),
JSON.stringify({ role: "user", content: "string not array" }),
JSON.stringify({ role: "assistant", content: [{ type: "text", text: "good 2" }] }),
"",
].join("\n"),
"utf-8",
);
const s = new PersistentSession({ sessionFile: file });
expect(s.length).toBe(2);
expect(s.getMessages()[0].role).toBe("user");
expect((s.getMessages()[0].content[0] as { text: string }).text).toBe("good 1");
expect(s.getMessages()[1].role).toBe("assistant");
});
it("persistent-block shrink survives a restart via the sidecar", () => {
const s = new PersistentSession({ sessionFile: file });
s.beginUserTurn([{ type: "text", text: "long project" }]);
s.addAssistantMessage([{ type: "text", text: "ack" }]);
s.completeActiveTurn();
s.applyHistorySummary("Original prose before the shrink.", [1]);
s.applyPersistentBlockShrink("Shrunk prose after overflow recovery.");
const reloaded = new PersistentSession({ sessionFile: file });
const restored = reloaded.getSerializedContextState();
expect(restored?.historySummary).toContain("Shrunk prose");
expect(restored?.historySummary).not.toContain("Original prose");
});
it("clear truncates backing file", () => {
const s = new PersistentSession({ sessionFile: file });
s.addUserMessage("x");
expect(fs.statSync(file).size).toBeGreaterThan(0);
s.clear();
expect(s.length).toBe(0);
expect(fs.statSync(file).size).toBe(0);
});
it.each([undefined, "documents"])("paired tool calls preserve optional namespace %s through reload and active-turn projection", (namespace) => {
// A resumed turn must replay the original call identity and result,
// including legacy calls that predate namespace persistence.
const s1 = new PersistentSession({ sessionFile: file });
s1.beginUserTurn([{ type: "text", text: "Read the selected document" }]);
const call = {
type: "tool_use" as const, id: "call-123", name: "test_tool", input: {},
...(namespace !== undefined ? { namespace } : {}),
};
s1.addAssistantMessage([call]);
s1.addToolResult("call-123", "tool output", undefined, false);
const s2 = new PersistentSession({ sessionFile: file });
expect(s2.length).toBe(3);
expect(s2.getMessages()[1].content).toEqual([call]);
expect(s2.getMessagesForModel()).toEqual(s1.getMessagesForModel());
expect(s2.getMessagesForModel()[1].content).toEqual([call]);
const toolResultMsg = s2.getMessages()[2];
expect(toolResultMsg.role).toBe("user");
const c = toolResultMsg.content[0];
expect(c.type).toBe("tool_result");
expect((c as { toolUseId: string }).toolUseId).toBe("call-123");
});
it("orphan tool_result (no preceding tool_use) is dropped at load", () => {
// 锁住 `4773be73` 修的不变量:孤儿 tool_result 在 load 时被
// healOrphanToolUses 丢弃。否则下一次 provider 调用会被拒
// ("No tool call found for function call output with call_id ...")。
// 之前生产报这个错频繁,fix 是在 load 时主动清理;这条测试守住"清"
// 这个动作不能被未来的重构撤回。
const s1 = new PersistentSession({ sessionFile: file });
s1.addToolResult("call-orphan", "tool output", undefined, false);
expect(s1.length).toBe(1); // 写入时不拦,刚 add 还在内存里
const s2 = new PersistentSession({ sessionFile: file });
expect(s2.length).toBe(0); // load 时 healOrphanToolUses 把它丢了
});
it("orphan tool_result mixed with valid pair: orphan dropped, pair kept", () => {
// 一条 user 消息可以同时携带多个 tool_result block——只丢孤儿那个,
// 不要把整条 message 全删掉(否则会误伤同 message 里的合法 result)。
const s1 = new PersistentSession({ sessionFile: file });
s1.addAssistantMessage([
{ type: "tool_use", id: "call-good", name: "t1", input: {} } as MessageContent,
]);
// 手工拼一条同时包含合法 + 孤儿两个 tool_result 的 user 消息
s1.addMessage("user", [
{ type: "tool_result", toolUseId: "call-good", content: "ok", isError: false } as MessageContent,
{ type: "tool_result", toolUseId: "call-orphan", content: "stray", isError: false } as MessageContent,
]);
const s2 = new PersistentSession({ sessionFile: file });
expect(s2.length).toBe(2);
const blocks = s2.getMessages()[1].content;
expect(blocks).toHaveLength(1);
expect((blocks[0] as { toolUseId: string }).toolUseId).toBe("call-good");
});
it("creates parent directories if missing", () => {
const nested = path.join(os.tmpdir(), `core-agent-psess-${Date.now()}`, "sub", "dir", "chat.jsonl");
try {
const s = new PersistentSession({ sessionFile: nested });
s.addUserMessage("hi");
expect(fs.existsSync(nested)).toBe(true);
} finally {
try { fs.rmSync(path.dirname(path.dirname(path.dirname(nested))), { recursive: true, force: true }); } catch { /* ignore */ }
}
});
// ── Heal pass for orphan tool_use ────────────────────────────────────────
// Background: when a prior run aborted (app killed, watchdog, user stop)
// after the provider emitted an assistant `tool_use` but before the runner
// persisted the matching `tool_result`, the session jsonl is left in a
// state the OpenAI/Anthropic API rejects (tool_use must be followed by
// tool_result for that id). The next turn then silently hangs waiting on
// a response the server never produces. loadFromDisk heals these.
describe("orphan tool_use heal on load", () => {
it("synthesizes tool_result for a trailing orphan tool_use", () => {
fs.writeFileSync(
file,
[
JSON.stringify({ role: "user", content: [{ type: "text", text: "run social" }] }),
JSON.stringify({
role: "assistant",
content: [{ type: "tool_use", id: "call-A", name: "some_tool", input: {} }],
}),
].join("\n") + "\n",
"utf-8",
);
const s = new PersistentSession({ sessionFile: file });
const msgs = s.getMessages();
expect(msgs).toHaveLength(3); // user + assistant(tool_use) + synthetic user(tool_result)
const last = msgs[2];
expect(last.role).toBe("user");
expect(last.content[0].type).toBe("tool_result");
expect((last.content[0] as { toolUseId: string }).toolUseId).toBe("call-A");
expect((last.content[0] as { isError: boolean }).isError).toBe(true);
expect((last.content[0] as { content: string }).content).toMatch(/interrupted/i);
expect(s.getLastToolProtocolRepairReport()).toMatchObject({
changed: true,
synthesizedOrphanResults: 1,
droppedUnmatchedResults: 0,
mergedParallelResultMessages: 0,
});
// Disk was rewritten — a fresh load produces the same state without
// re-healing (idempotent).
const s2 = new PersistentSession({ sessionFile: file });
expect(s2.length).toBe(3);
expect(s2.getMessages()[2].content[0].type).toBe("tool_result");
});
it("heals an orphan tool_use followed by an unrelated user text", () => {
// This is the production bug: a long-running tool_use at index N
// (e.g. abort/restart mid-execution), then the user typed a new
// message at N+1 without any tool_result in between. The heal must
// insert the synthetic result *before* the user's text, preserving
// conversational order.
fs.writeFileSync(
file,
[
JSON.stringify({ role: "user", content: [{ type: "text", text: "round 1" }] }),
JSON.stringify({
role: "assistant",
content: [{ type: "tool_use", id: "call-X", name: "some_tool", input: {} }],
}),
JSON.stringify({ role: "user", content: [{ type: "text", text: "round 2" }] }),
].join("\n") + "\n",
"utf-8",
);
const s = new PersistentSession({ sessionFile: file });
const msgs = s.getMessages();
expect(msgs).toHaveLength(4);
expect(msgs[0].role).toBe("user");
expect(msgs[1].role).toBe("assistant");
// Synthetic tool_result sits between the tool_use and the user text.
expect(msgs[2].role).toBe("user");
expect(msgs[2].content[0].type).toBe("tool_result");
expect((msgs[2].content[0] as { toolUseId: string }).toolUseId).toBe("call-X");
expect(msgs[3].role).toBe("user");
expect(msgs[3].content[0].type).toBe("text");
expect((msgs[3].content[0] as { text: string }).text).toBe("round 2");
});
it("drops delayed tool_result after unrelated user text", () => {
fs.writeFileSync(
file,
[
JSON.stringify({ role: "user", content: [{ type: "text", text: "round 1" }] }),
JSON.stringify({
role: "assistant",
content: [{ type: "tool_use", id: "call-late", name: "some_tool", input: {} }],
}),
JSON.stringify({ role: "user", content: [{ type: "text", text: "round 2" }] }),
JSON.stringify({
role: "user",
content: [{ type: "tool_result", toolUseId: "call-late", content: "late result", isError: false }],
}),
].join("\n") + "\n",
"utf-8",
);
const s = new PersistentSession({ sessionFile: file });
const msgs = s.getMessages();
expect(msgs).toHaveLength(4);
expect(msgs[2].role).toBe("user");
expect(msgs[2].content[0].type).toBe("tool_result");
expect((msgs[2].content[0] as { isError: boolean }).isError).toBe(true);
expect(msgs[3].role).toBe("user");
expect(msgs[3].content).toEqual([{ type: "text", text: "round 2" }]);
});
it("removes misplaced tool_result blocks while preserving real user content", () => {
fs.writeFileSync(
file,
[
JSON.stringify({ role: "user", content: [{ type: "text", text: "hello" }] }),
JSON.stringify({
role: "user",
content: [
{ type: "tool_result", toolUseId: "call-missing", content: "stray", isError: false },
{ type: "text", text: "keep me" },
],
}),
].join("\n") + "\n",
"utf-8",
);
const s = new PersistentSession({ sessionFile: file });
const msgs = s.getMessages();
expect(msgs).toHaveLength(2);
expect(msgs[1].content).toEqual([{ type: "text", text: "keep me" }]);
});
it("heals multiple orphan tool_uses in the same assistant message", () => {
// Some providers emit parallel tool calls in one assistant turn. A
// mid-flight abort orphans all of them at once; each needs its own
// tool_result entry in the next message.
fs.writeFileSync(
file,
[
JSON.stringify({
role: "assistant",
content: [
{ type: "tool_use", id: "call-1", name: "a", input: {} },
{ type: "tool_use", id: "call-2", name: "b", input: {} },
],
}),
].join("\n") + "\n",
"utf-8",
);
const s = new PersistentSession({ sessionFile: file });
const msgs = s.getMessages();
expect(msgs).toHaveLength(2);
const results = msgs[1].content;
expect(results).toHaveLength(2);
const ids = results.map((c) => (c as { toolUseId?: string }).toolUseId);
expect(ids.sort()).toEqual(["call-1", "call-2"]);
});
it("heals a partial result set (some ids resolved, others orphaned)", () => {
// Assistant called two tools; only one tool_result came back before
// the crash. Heal must fill in the missing id and leave the existing
// result in place.
fs.writeFileSync(
file,
[
JSON.stringify({
role: "assistant",
content: [
{ type: "tool_use", id: "call-ok", name: "a", input: {} },
{ type: "tool_use", id: "call-orphan", name: "b", input: {} },
],
}),
JSON.stringify({
role: "user",
content: [
{ type: "tool_result", toolUseId: "call-ok", content: "ok", isError: false },
],
}),
].join("\n") + "\n",
"utf-8",
);
const s = new PersistentSession({ sessionFile: file });
const msgs = s.getMessages();
expect(msgs).toHaveLength(2);
const results = msgs[1].content;
expect(results).toHaveLength(2);
const byId = new Map(results.map((c) => [(c as { toolUseId: string }).toolUseId, c]));
expect((byId.get("call-ok") as { isError: boolean }).isError).toBe(false);
expect((byId.get("call-orphan") as { isError: boolean }).isError).toBe(true);
});
it("healAndPersist fixes a cached session mid-lifetime", () => {
// Scenario: PersistentSession is cached (session-store.ts reuses the
// same instance across turns). A turn aborts mid-tool-execution and
// leaves an orphan tool_use in the in-memory Session. Constructor
// heal doesn't re-fire. healAndPersist() must fix both in-memory
// and on-disk state so the *next* turn sees a valid history.
const s = new PersistentSession({ sessionFile: file });
s.addUserMessage("run tool");
s.addAssistantMessage([
{ type: "tool_use", id: "call-mid", name: "some_tool", input: {} },
]);
// Simulate abort: tool_result never written. Session is now in a
// broken state but still cached in memory.
expect(s.length).toBe(2);
expect(s.getMessages()[1].content[0].type).toBe("tool_use");
// Post-turn heal hook runs in the `finally` block of client.ts.
const healed = s.healAndPersist();
expect(healed).toBe(true);
expect(s.length).toBe(3);
expect(s.getMessages()[2].content[0].type).toBe("tool_result");
// Re-run is idempotent — second call shouldn't re-heal.
expect(s.healAndPersist()).toBe(false);
// Disk was persisted → a fresh construction of the same file reads
// back the healed state.
const fresh = new PersistentSession({ sessionFile: file });
expect(fresh.length).toBe(3);
expect(fresh.getMessages()[2].content[0].type).toBe("tool_result");
});
it("heals memory without rewriting the append-only jsonl (P0-1 no truncation)", () => {
// A benign multi-tool turn (2 parallel tool_results) makes heal consolidate
// the two tool_result messages in memory. healAndPersist must NOT flush that
// shorter view over the append-only log — doing so would drop any history
// older than the trimmed in-memory window.
const s = new PersistentSession({ sessionFile: file });
s.beginUserTurn([{ type: "text", text: "go" }]);
s.addAssistantMessage([
{ type: "tool_use", id: "a", name: "a", input: {} },
{ type: "tool_use", id: "b", name: "b", input: {} },
]);
s.addToolResult("a", "ra", undefined, false);
s.addToolResult("b", "rb", undefined, false);
const diskBefore = fs.readFileSync(file, "utf-8").trim().split("\n").length;
expect(diskBefore).toBe(4); // user, assistant, tool_result(a), tool_result(b)
expect(s.healAndPersist()).toBe(true); // merges the two tool_result messages
const mem = s.getMessages();
expect(mem).toHaveLength(3);
expect(
mem[2].content.filter((c) => (c as { type?: string }).type === "tool_result"),
).toHaveLength(2);
// Append log is intact — not rewritten to the merged/trimmed view.
const diskAfter = fs.readFileSync(file, "utf-8").trim().split("\n").length;
expect(diskAfter).toBe(diskBefore);
});
it("preserves the history summary + resource ledger across a multi-tool heal (P0-1)", () => {
const s = new PersistentSession({ sessionFile: file });
// Turn 1, then roll it into a summary + record a produced resource.
s.beginUserTurn([{ type: "text", text: "turn one" }]);
s.addAssistantMessage([{ type: "tool_use", id: "t1", name: "a", input: {} }]);
s.addToolResult("t1", "r1", undefined, false);
s.completeActiveTurn();
s.applyHistorySummary("rolling summary", [1]);
s.addHistoryResource({ kind: "final_output", path: "/w/report.mov", name: "report.mov" });
// Turn 2: two parallel tool_results — the benign heal trigger that used to
// clear() and wipe turnState (summary + resources) on the next turn.
s.beginUserTurn([{ type: "text", text: "turn two" }]);
s.addAssistantMessage([
{ type: "tool_use", id: "t2a", name: "a", input: {} },
{ type: "tool_use", id: "t2b", name: "b", input: {} },
]);
s.addToolResult("t2a", "r2a", undefined, false);
s.addToolResult("t2b", "r2b", undefined, false);
expect(s.getSerializedContextState()?.historySummary).toBe("rolling summary");
expect(s.getSerializedContextState()?.resources).toHaveLength(1);
expect(s.healAndPersist()).toBe(true);
const after = s.getSerializedContextState();
expect(after?.historySummary).toBe("rolling summary");
expect(after?.resources).toHaveLength(1);
expect(after?.resources[0].name).toBe("report.mov");
expect(JSON.stringify(s.getMessagesForModel())).not.toContain("rolling summary");
});
it("merges parallel tool_results split across adjacent user messages", () => {
// The runner's `addToolResult` writes one user message per tool_use_id.
// So an assistant turn with 3 parallel tool_calls produces 3 adjacent
// user messages on disk. Heal must NOT mistake the latter two for
// orphans (the original i+1-only scan did) — it must scan the whole
// contiguous tool_result cluster and consolidate.
fs.writeFileSync(
file,
[
JSON.stringify({ role: "user", content: [{ type: "text", text: "go" }] }),
JSON.stringify({
role: "assistant",
content: [
{ type: "tool_use", id: "p-0", name: "a", input: {} },
{ type: "tool_use", id: "p-1", name: "b", input: {} },
{ type: "tool_use", id: "p-2", name: "c", input: {} },
],
}),
JSON.stringify({ role: "user", content: [{ type: "tool_result", toolUseId: "p-0", content: "r0", isError: false }] }),
JSON.stringify({ role: "user", content: [{ type: "tool_result", toolUseId: "p-1", content: "r1", isError: false }] }),
JSON.stringify({ role: "user", content: [{ type: "tool_result", toolUseId: "p-2", content: "r2", isError: false }] }),
].join("\n") + "\n",
"utf-8",
);
const s = new PersistentSession({ sessionFile: file });
const msgs = s.getMessages();
expect(msgs).toHaveLength(3); // user + assistant + ONE merged tool_result message
expect(msgs[2].role).toBe("user");
expect(msgs[2].content).toHaveLength(3);
const ids = msgs[2].content.map((c) => (c as { toolUseId: string }).toolUseId);
expect(ids).toEqual(["p-0", "p-1", "p-2"]); // order matches assistant's tool_uses
// None of the results are interrupted — all are the real ones.
expect(msgs[2].content.every((c) => (c as { content: string }).content !== INTERRUPTED_TOOL_RESULT)).toBe(true);
expect(s.getLastToolProtocolRepairReport()).toMatchObject({
changed: true,
synthesizedOrphanResults: 0,
droppedUnmatchedResults: 0,
mergedParallelResultMessages: 2,
deduplicatedResults: 0,
});
});
it("dedupes a tool_call_id that appears as both interrupted and real", () => {
// Reproduces the corruption that an earlier heal-with-i+1-only logic
// could produce: assistant has 3 parallel tool_uses, the first user
// message after assistant carried only the first real result, then
// heal mistakenly synthesized "interrupted" markers for the other two
// (because it didn't see the real results in subsequent user
// messages). The corrupt jsonl ended up with each tool_call_id
// having both an interrupted and a real result. DeepSeek 400s on
// duplicate tool_call_id. Heal must dedupe and prefer the real one.
fs.writeFileSync(
file,
[
JSON.stringify({ role: "user", content: [{ type: "text", text: "go" }] }),
JSON.stringify({
role: "assistant",
content: [
{ type: "tool_use", id: "c-0", name: "a", input: {} },
{ type: "tool_use", id: "c-1", name: "b", input: {} },
{ type: "tool_use", id: "c-2", name: "c", input: {} },
],
}),
JSON.stringify({
role: "user",
content: [
{ type: "tool_result", toolUseId: "c-0", content: "r0", isError: false },
{ type: "tool_result", toolUseId: "c-1", content: INTERRUPTED_TOOL_RESULT, isError: true },
{ type: "tool_result", toolUseId: "c-2", content: INTERRUPTED_TOOL_RESULT, isError: true },
],
}),
JSON.stringify({ role: "user", content: [{ type: "tool_result", toolUseId: "c-1", content: "r1", isError: false }] }),
JSON.stringify({ role: "user", content: [{ type: "tool_result", toolUseId: "c-2", content: "r2", isError: false }] }),
].join("\n") + "\n",
"utf-8",
);
const s = new PersistentSession({ sessionFile: file });
const msgs = s.getMessages();
expect(msgs).toHaveLength(3);
const results = msgs[2].content as Array<{ toolUseId: string; content: string; isError: boolean }>;
expect(results).toHaveLength(3);
const byId = new Map(results.map((r) => [r.toolUseId, r]));
// Real results win over earlier-seen interrupted markers.
expect(byId.get("c-0")!.content).toBe("r0");
expect(byId.get("c-1")!.content).toBe("r1");
expect(byId.get("c-2")!.content).toBe("r2");
expect(results.every((r) => !r.content.includes("interrupted"))).toBe(true);
expect(s.getLastToolProtocolRepairReport().deduplicatedResults).toBe(2);
});
it("leaves a well-formed history untouched", () => {
// Regression guard: tool_use followed by tool_result = healthy.
// Heal pass must be a no-op; flush must NOT rewrite the file.
fs.writeFileSync(
file,
[
JSON.stringify({
role: "assistant",
content: [{ type: "tool_use", id: "call-OK", name: "a", input: {} }],
}),
JSON.stringify({
role: "user",
content: [{ type: "tool_result", toolUseId: "call-OK", content: "done", isError: false }],
}),
].join("\n") + "\n",
"utf-8",
);
const mtimeBefore = fs.statSync(file).mtimeMs;
// Sleep a tick so any write would leave a detectable mtime delta.
const s = new PersistentSession({ sessionFile: file });
expect(s.length).toBe(2);
expect(s.getMessages()[1].content).toHaveLength(1);
// No heal fired → no flushToDisk → mtime unchanged within the
// resolution of fs.statSync (ms). We accept equality OR tiny drift.
const mtimeAfter = fs.statSync(file).mtimeMs;
expect(mtimeAfter).toBe(mtimeBefore);
});
});
});
describe("session save recovery", () => {
let dir: string;
beforeEach(() => { dir = fs.mkdtempSync(path.join(os.tmpdir(), "session-recovery-")); vi.useFakeTimers(); });
afterEach(() => { vi.restoreAllMocks(); vi.useRealTimers(); fs.rmSync(dir, { recursive: true, force: true }); });
it("repairs a partially written row and retains every later message in order", async () => {
const file = path.join(dir, "session.jsonl");
const session = new PersistentSession({ sessionFile: file });
session.addUserMessage("earlier history");
const append = fs.appendFileSync;
const fault = vi.spyOn(fs, "appendFileSync").mockImplementationOnce((target, data, options) => {
append(target, String(data).slice(0, 17), options);
throw Object.assign(new Error("private path must not escape"), { code: "ENOSPC" });
});
session.beginUserTurn([{ type: "text", text: "current request" }]);
session.addAssistantMessage([{ type: "text", text: "completed answer" }]);
const flush = session.flushPending();
await vi.advanceTimersByTimeAsync(200);
await flush;
expect(session.hasPendingPersistence()).toBe(false);
const rows = fs.readFileSync(file, "utf8").trim().split("\n").map(line => JSON.parse(line));
expect(rows.map(row => row.content[0].text)).toEqual(["earlier history", "current request", "completed answer"]);
expect(new PersistentSession({ sessionFile: file }).getMessages()).toEqual(session.getMessages());
expect(fault).toHaveBeenCalled();
});
it("retries three times, retains completed evidence, and saves only the newest context on explicit recovery", async () => {
const file = path.join(dir, "session.jsonl");
const session = new PersistentSession({ sessionFile: file });
session.beginUserTurn([{ type: "text", text: "finish the work" }]);
fs.mkdirSync(`${file}.context.json.tmp`);
const writes = vi.spyOn(fs, "writeFileSync");
session.recordCompletedWork({ tool: "test", inputDigest: "a", inputSummary: "a", status: "succeeded", resultSummary: "done", checkpointEpoch: 0 });
session.updateExecutionPlan({ steps: [{ step: "verify", status: "completed" }] });
const failed = expect(session.flushPending()).rejects.toMatchObject({ code: "SESSION_PERSISTENCE_FAILED" });
await vi.advanceTimersByTimeAsync(4_200);
await failed;
expect(writes).toHaveBeenCalledTimes(4); // initial attempt plus three retries
expect(session.getCompletedWorkLedger()).toHaveLength(1);
expect(session.hasPendingPersistence()).toBe(true);
fs.rmdirSync(`${file}.context.json.tmp`);
const repaired = session.flushPending();
await vi.advanceTimersByTimeAsync(200);
await repaired;
const restored = new PersistentSession({ sessionFile: file });
expect(restored.getCompletedWorkLedger()).toEqual(session.getCompletedWorkLedger());
expect(restored.getExecutionPlan()).toEqual(session.getExecutionPlan());
});
it("cancels backoff promptly without dropping pending data or leaving background retries", async () => {
const file = path.join(dir, "session.jsonl");
const session = new PersistentSession({ sessionFile: file });
fs.mkdirSync(file);
const writes = vi.spyOn(fs, "appendFileSync");
session.addUserMessage("keep this request");
const controller = new AbortController();
const aborted = expect(session.flushPending(controller.signal)).rejects.toMatchObject({ code: "ABORT_ERR" });
controller.abort();
await aborted;
await vi.advanceTimersByTimeAsync(10_000);
expect(writes).toHaveBeenCalledTimes(1);
expect(session.hasPendingPersistence()).toBe(true);
fs.rmdirSync(file);
const recovered = session.flushPending();
await vi.advanceTimersByTimeAsync(200);
await recovered;
expect(new PersistentSession({ sessionFile: file }).getMessages()).toEqual(session.getMessages());
});
it("recovers a failed full replacement followed by an append and an explicit clear", async () => {
const file = path.join(dir, "session.jsonl");
const session = new PersistentSession({ sessionFile: file });
session.addUserMessage("old history");
vi.spyOn(fs, "renameSync").mockImplementationOnce(() => { throw Object.assign(new Error("rename fault"), { code: "EACCES" }); });
session.replaceConversationHistory([{ role: "user", content: [{ type: "text", text: "canonical history" }] }], "canonical");
session.beginUserTurn([{ type: "text", text: "next request" }]);
const saved = session.flushPending();
await vi.advanceTimersByTimeAsync(200);
await saved;
expect(new PersistentSession({ sessionFile: file }).getMessages()).toEqual(session.getMessages());
vi.spyOn(fs, "appendFileSync").mockImplementationOnce(() => { throw Object.assign(new Error("append fault"), { code: "EIO" }); });
session.addAssistantMessage([{ type: "text", text: "discard by explicit reset" }]);
session.clear();
const cleared = session.flushPending();
await vi.advanceTimersByTimeAsync(200);
await cleared;
expect(new PersistentSession({ sessionFile: file }).getMessages()).toEqual([]);
});
it("retains the disk prefix outside the memory window when retrying an append", async () => {
const file = path.join(dir, "session.jsonl");
const session = new PersistentSession({ sessionFile: file, maxHistoryTurns: 2 });
for (let i = 0; i < 10; i++) session.addUserMessage(`history-${i}`);
vi.spyOn(fs, "appendFileSync").mockImplementationOnce(() => { throw Object.assign(new Error("fault"), { code: "EIO" }); });
session.addUserMessage("new request");
const recovered = session.flushPending();
await vi.advanceTimersByTimeAsync(200);
await recovered;
expect(fs.readFileSync(file, "utf8").trim().split("\n")).toHaveLength(11);
});
});