A desktop coding agent with free access to frontier models.
TypeScript
import { afterEach, describe, expect, jest, test } from "bun:test";
import { execFile } from "node:child_process";
import { mkdir, symlink, writeFile } from "node:fs/promises";
import { join } from "node:path";
import { promisify } from "node:util";
import { FakeArchiveServer } from "./fake-archive-server.js";
import { SessionArchiver, type CaptureResult, type DrainResult, type FinalReason } from "./index.js";
import {
completedTurnCount,
projectArchiveEnabled,
ProjectArchiveLifecycle,
type ArchiveEngineReads,
type ProjectArchiver,
} from "./lifecycle.js";
import { cleanupTempDirs, manifestOf, openArchive, tempDir } from "./test-helpers.js";
const execFileAsync = promisify(execFile);
afterEach(cleanupTempDirs);
const queued = (kind: "base" | "delta", sequence = 0): CaptureResult => ({ status: "queued", archiveId: `archive-${kind}-${sequence}`, kind, sequence, size: 1 });
const skipped = (reason: Extract<CaptureResult, { status: "skipped" }>["reason"]): CaptureResult => ({ status: "skipped", reason });
const drained: DrainResult = { uploaded: 0, pending: 0, dropped: 0, blocked: null, disabled: false };
/** Records every call; each result can be swapped per test. */
class FakeArchiver implements ProjectArchiver {
readonly calls: string[] = [];
base: (sessionId: string, turn: number) => Promise<CaptureResult> = async () => queued("base");
delta: (sessionId: string, turn: number | null) => Promise<CaptureResult> = async (_sessionId, turn) => queued("delta", turn ?? 0);
final: (sessionId: string, reason: FinalReason, signal?: AbortSignal) => Promise<CaptureResult> = async () => skipped("unchanged");
drainResult: () => Promise<DrainResult> = async () => drained;
/** What startFinalCandidates answers (not recorded as a call). */
startFinals: string[] = [];
/** The options of each stop() call. */
readonly stops: Array<{ finals?: readonly string[]; budgetMs?: number }> = [];
/** recordTouched and forgetTouched calls (not in `calls`). */
readonly touched: string[] = [];
/** What touchedBaseDue answers (a touched-files chain still without its base). */
baseDue = false;
async touchedBaseDue(_sessionId: string): Promise<boolean> {
return this.baseDue;
}
async captureBase(sessionId: string, root: string, turn = 0): Promise<CaptureResult> {
this.calls.push(`base ${sessionId} ${root} ${turn}`);
return this.base(sessionId, turn);
}
async captureDelta(sessionId: string, root: string, turn: number | null, _options: { before?: number | (() => number | undefined) } = {}): Promise<CaptureResult> {
this.calls.push(`delta ${sessionId} ${root} ${turn}`);
return this.delta(sessionId, turn);
}
async captureFinal(sessionId: string, reason: FinalReason, options: { signal?: AbortSignal } = {}): Promise<CaptureResult> {
this.calls.push(`final ${sessionId} ${reason}`);
return this.final(sessionId, reason, options.signal);
}
async startFinalCandidates(): Promise<string[]> {
return this.startFinals;
}
recordTouched(sessionId: string, path: string): void {
this.touched.push(`record ${sessionId} ${path}`);
}
forgetTouched(sessionId: string): void {
this.touched.push(`forget ${sessionId}`);
}
async drain(): Promise<DrainResult> {
this.calls.push("drain");
return this.drainResult();
}
async signOut(): Promise<void> {
this.calls.push("signOut");
}
async stop(options: { finals?: readonly string[]; budgetMs?: number } = {}): Promise<void> {
this.calls.push("stop");
this.stops.push(options);
}
captures(): string[] {
return this.calls.filter((call) => call.startsWith("base") || call.startsWith("delta"));
}
finals(): string[] {
return this.calls.filter((call) => call.startsWith("final"));
}
}
type Message = { info: Record<string, unknown>; parts: unknown[] };
/** A v1 engine message list: `completed` answered prompts, then optionally one still running. */
function messages(completed: number, running = false): Message[] {
const list: Message[] = [];
for (let turn = 1; turn <= completed + (running ? 1 : 0); turn += 1) {
list.push({ info: { id: `user_${turn}`, role: "user", time: { created: turn } }, parts: [] });
if (turn <= completed) list.push({ info: { id: `assistant_${turn}`, role: "assistant", time: { created: turn, completed: turn + 1 } }, parts: [] });
}
return list;
}
/** Engine reads for one session, counting how often each route is read. */
function engine(input: { parentID?: string; messages?: () => unknown; session?: () => unknown } = {}) {
const reads = { session: 0, messages: 0 };
const reader: ArchiveEngineReads = {
session: async () => {
reads.session += 1;
return input.session ? input.session() : { id: "ses_root_0001", ...(input.parentID ? { parentID: input.parentID } : {}) };
},
messages: async () => {
reads.messages += 1;
return input.messages ? input.messages() : [];
},
};
return { reader, reads };
}
function lifecycle(archiver: ProjectArchiver, options: { enabled?: boolean; accountMissing?: boolean; now?: () => number; concurrency?: number; finalIdleMs?: number; quitBudgetMs?: number; turnDeltaWaitMs?: number; touchedBaseDelayMs?: number } = {}) {
const logs: Array<{ level: string; message: string; attributes?: Record<string, unknown> }> = [];
const subject = new ProjectArchiveLifecycle({
archiver,
enabled: options.enabled ?? true,
...(options.accountMissing ? { accountMissing: true } : {}),
log: (level, message, attributes) => logs.push({ level, message, ...(attributes ? { attributes } : {}) }),
consentRecheckMs: 60_000,
...(options.now ? { now: options.now } : {}),
...(options.concurrency ? { concurrency: options.concurrency } : {}),
...(options.finalIdleMs !== undefined ? { finalIdleMs: options.finalIdleMs } : {}),
...(options.quitBudgetMs !== undefined ? { quitBudgetMs: options.quitBudgetMs } : {}),
...(options.turnDeltaWaitMs !== undefined ? { turnDeltaWaitMs: options.turnDeltaWaitMs } : {}),
...(options.touchedBaseDelayMs !== undefined ? { touchedBaseDelayMs: options.touchedBaseDelayMs } : {}),
});
return { subject, logs };
}
function deferred<T>() {
let resolve!: (value: T) => void;
const promise = new Promise<T>((resolvePromise) => { resolve = resolvePromise; });
return { promise, resolve };
}
describe("completedTurnCount", () => {
test("counts prompts answered by an assistant message that ended, v1 and v2 shapes", () => {
expect(completedTurnCount(messages(0))).toBe(0);
expect(completedTurnCount(messages(3))).toBe(3);
// The running turn is not complete yet.
expect(completedTurnCount(messages(2, true))).toBe(2);
// Several assistant steps of one turn count once; a finish part or an error also ends a turn.
expect(completedTurnCount([
{ info: { role: "user" } },
{ info: { role: "assistant", finish: "tool-calls" } },
{ info: { role: "assistant", time: { completed: 5 } } },
{ info: { role: "user" } },
{ info: { role: "assistant" }, parts: [{ type: "step-finish" }] },
{ info: { role: "user" } },
{ info: { role: "assistant", error: { name: "MessageAbortedError" } } },
])).toBe(3);
// v2 context entries carry the role as `type`.
expect(completedTurnCount([
{ id: "u1", type: "user" },
{ id: "a1", type: "assistant", time: { created: 1, completed: 2 } },
{ id: "c1", type: "compaction" },
{ id: "u2", type: "user" },
{ id: "a2", type: "assistant", content: [{ type: "text" }] },
])).toBe(1);
expect(completedTurnCount(null)).toBeNull();
expect(completedTurnCount({ status: 500, unavailable: true })).toBeNull();
});
test("a compaction and synthetic notices are no turn: the count follows the prompts", () => {
const prompt = (id: string) => ({ info: { id, role: "user" }, parts: [{ type: "text" }] });
const answer = (id: string) => ({ info: { id, role: "assistant", time: { completed: 1 } } });
expect(completedTurnCount([
prompt("u1"), answer("a1"),
prompt("u2"), answer("a2"),
// An automatic compaction inside turn 2 (1.x: a "compaction" part; the 2.x adapter: its compaction agent)...
{ info: { id: "c1", role: "user", agent: "build" }, parts: [{ type: "compaction" }] },
{ info: { id: "s1", role: "assistant", summary: true, mode: "compaction", finish: "stop" } },
{ info: { id: "c2", role: "user", agent: "compaction" }, parts: [] },
{ info: { id: "s2", role: "assistant", summary: true, agent: "compaction", finish: "stop" } },
// ...the engine's continue nudge and its reply...
{ info: { id: "n1", role: "user" }, parts: [{ type: "text", synthetic: true }] },
answer("a3"),
// ...a user-run shell command, an activated skill (synthetic text alone).
{ info: { id: "sh", role: "user" }, parts: [{ type: "text", synthetic: true }] },
{ info: { id: "sh-a", role: "assistant", time: { completed: 2 } }, parts: [{ type: "tool" }] },
prompt("u3"), answer("a4"),
])).toBe(3);
// A prompt with a synthetic note beside what was typed (an attachment path) is one.
expect(completedTurnCount([
{ info: { role: "user" }, parts: [{ type: "text", synthetic: true }, { type: "text" }] },
answer("a1"),
{ info: { role: "user" }, parts: [{ type: "text", synthetic: true }, { type: "file" }] },
answer("a2"),
])).toBe(2);
});
test("a prompt stopped before any answer is a turn once the next prompt follows it", () => {
const prompt = { info: { role: "user" }, parts: [{ type: "text" }] };
const answer = { info: { role: "assistant", time: { completed: 1 } } };
// Stopped with Esc before the engine answered: still the running turn...
expect(completedTurnCount([prompt, answer, prompt])).toBe(1);
// ...and a turn once the next prompt was sent, so turn numbers keep matching the prompts.
expect(completedTurnCount([prompt, answer, prompt, prompt, answer])).toBe(3);
});
});
describe("projectArchiveEnabled", () => {
test("is on by default and off only when OMNIRUSH_ARCHIVE_ENABLED says so", () => {
expect(projectArchiveEnabled({})).toBe(true);
expect(projectArchiveEnabled({ OMNIRUSH_ARCHIVE_ENABLED: "1" })).toBe(true);
expect(projectArchiveEnabled({ OMNIRUSH_ARCHIVE_ENABLED: "" })).toBe(true);
for (const off of ["0", "false", "FALSE", " no ", "off"]) expect(projectArchiveEnabled({ OMNIRUSH_ARCHIVE_ENABLED: off })).toBe(false);
});
});
describe("ProjectArchiveLifecycle", () => {
test("app start resumes the queue; a root session gets one base per app run at its real path and completed turns", async () => {
const archiver = new FakeArchiver();
const { subject, logs } = lifecycle(archiver);
subject.start();
await subject.settled();
expect(archiver.calls).toEqual(["drain"]);
const real = await tempDir("root");
const link = join(await tempDir("links"), "project");
await symlink(real, link);
const reads = engine({ messages: () => messages(2, true) });
subject.sessionStarted({ sessionId: "ses_root_0001", root: link, engine: reads.reader });
// Every prompt dispatch calls this; only the first one reaches the archiver.
subject.sessionStarted({ sessionId: "ses_root_0001", root: link, engine: reads.reader });
await subject.settled();
subject.sessionStarted({ sessionId: "ses_root_0001", root: link, engine: reads.reader });
await subject.settled();
expect(archiver.captures()).toEqual([`base ses_root_0001 ${real} 2`]);
expect(reads.reads).toEqual({ session: 1, messages: 1 });
// A queued base is uploaded right away.
expect(archiver.calls.slice(1)).toEqual([`base ses_root_0001 ${real} 2`, "drain"]);
expect(logs).toEqual([]);
});
test("child (sub-agent) sessions are never archived", async () => {
const archiver = new FakeArchiver();
const { subject } = lifecycle(archiver);
const root = await tempDir("root");
const child = engine({ parentID: "ses_root_0001", messages: () => messages(1) });
subject.sessionStarted({ sessionId: "ses_child_0001", root, engine: child.reader });
await subject.settled();
subject.turnCompleted("ses_child_0001", messages(1));
subject.sessionStarted({ sessionId: "ses_child_0001", root, engine: child.reader });
await subject.settled();
// v2 session records nest the fields under `info`.
const v2Child = engine({ session: () => ({ info: { id: "ses_child_0002", parentID: "ses_root_0001" } }) });
subject.sessionStarted({ sessionId: "ses_child_0002", root, engine: v2Child.reader });
await subject.settled();
expect(archiver.captures()).toEqual([]);
// Known to be a child: the engine is not asked again, and its messages are never read.
expect(child.reads).toEqual({ session: 1, messages: 0 });
});
test("touched paths reach the archiver only for a session this run started that may be archived", async () => {
const archiver = new FakeArchiver();
const { subject } = lifecycle(archiver);
const root = await tempDir("root");
// Before its first prompt, the session is not known here.
subject.pathTouched("ses_touch_0001", "early.txt");
subject.sessionStarted({ sessionId: "ses_touch_0001", root, engine: engine().reader });
// While its start step waits, and once it is resolved with a root.
subject.pathTouched("ses_touch_0001", "brief.pdf");
await subject.settled();
subject.pathTouched("ses_touch_0001", "out/render.png");
// Not archivable: nothing more.
archiver.base = async () => skipped("not_archivable");
subject.sessionStarted({ sessionId: "ses_touch_0002", root, engine: engine().reader });
await subject.settled();
subject.pathTouched("ses_touch_0002", "x.txt");
// A child session: what it reported goes, and nothing more is passed on.
subject.sessionStarted({ sessionId: "ses_touch_child", root, engine: engine({ parentID: "ses_touch_0001" }).reader });
subject.pathTouched("ses_touch_child", "child.txt");
await subject.settled();
subject.pathTouched("ses_touch_child", "later.txt");
// Deleted: forgotten.
subject.sessionEnded("ses_touch_0001");
subject.pathTouched("ses_touch_0001", "after.txt");
await subject.settled();
expect(archiver.touched).toEqual([
"record ses_touch_0001 brief.pdf",
"record ses_touch_0001 out/render.png",
"record ses_touch_child child.txt",
"forget ses_touch_child",
]);
// Signed out: nothing.
await subject.signOut();
subject.pathTouched("ses_touch_0001", "signed-out.txt");
expect(archiver.touched).toHaveLength(4);
});
test("a touched-files base is taken soon after the first touched path, not at the turn's end", async () => {
const archiver = new FakeArchiver();
archiver.base = async () => skipped("unchanged");
archiver.baseDue = true;
archiver.final = async () => queued("base");
const { subject } = lifecycle(archiver, { touchedBaseDelayMs: 10 });
const root = await tempDir("root");
subject.sessionStarted({ sessionId: "ses_touch_0003", root, engine: engine().reader });
await subject.settled();
subject.pathTouched("ses_touch_0003", "a.py");
subject.pathTouched("ses_touch_0003", "b.py");
await new Promise((resolve) => setTimeout(resolve, 40));
await subject.settled();
// One ask per session and run, though two paths came.
expect(archiver.finals()).toEqual(["final ses_touch_0003 first_touch"]);
// A chain that has its base (a git or project folder, or a base taken since): no extra capture.
archiver.baseDue = false;
subject.sessionStarted({ sessionId: "ses_touch_0004", root, engine: engine().reader });
await subject.settled();
subject.pathTouched("ses_touch_0004", "c.py");
await new Promise((resolve) => setTimeout(resolve, 40));
await subject.settled();
expect(archiver.finals()).toEqual(["final ses_touch_0003 first_touch"]);
});
test("a path touched while the start is unresolved gets one base, timed from that touch", async () => {
const archiver = new FakeArchiver();
archiver.base = async () => skipped("unchanged");
archiver.baseDue = true;
archiver.final = async () => queued("base");
let clock = 1_000;
const { subject } = lifecycle(archiver, { touchedBaseDelayMs: 30, now: () => clock });
const root = await tempDir("root");
let release: () => void = () => {};
const slow = new Promise<void>((resolve) => { release = resolve; });
subject.sessionStarted({ sessionId: "ses_touch_0005", root, engine: engine({ session: async () => { await slow; return { id: "ses_touch_0005" }; } }).reader });
// Exactly one touch while the engine read is pending: no root yet.
subject.pathTouched("ses_touch_0005", "early.py");
// Resolution comes after the base delay has already passed since that touch.
clock += 30;
release();
await subject.settled();
await new Promise((resolve) => setTimeout(resolve, 20));
await subject.settled();
expect(archiver.finals()).toEqual(["final ses_touch_0005 first_touch"]);
});
test("a stop or a deletion while the touched-files base is being asked for captures nothing late", async () => {
for (const end of ["stop", "deleted"] as const) {
const archiver = new FakeArchiver();
archiver.base = async () => skipped("unchanged");
archiver.final = async () => queued("base");
const sessionId = end === "stop" ? "ses_touch_0006" : "ses_touch_0007";
const { subject } = lifecycle(archiver, { touchedBaseDelayMs: 5 });
let answer: (due: boolean) => void = () => {};
let asked = false;
archiver.touchedBaseDue = () => { asked = true; return new Promise<boolean>((resolve) => { answer = resolve; }); };
const root = await tempDir("root");
subject.sessionStarted({ sessionId, root, engine: engine().reader });
await subject.settled();
subject.pathTouched(sessionId, "a.py");
await new Promise((resolve) => setTimeout(resolve, 20));
expect(asked).toBe(true);
if (end === "stop") await subject.stop({ finals: false });
else subject.sessionEnded(sessionId);
answer(true);
await subject.settled();
expect(archiver.finals().filter((call) => call.endsWith("first_touch"))).toEqual([]);
}
});
test("delta turn numbers come from the engine's completed turns, in order after the base", async () => {
const archiver = new FakeArchiver();
const { subject } = lifecycle(archiver);
const root = await tempDir("root");
const baseGate = deferred<CaptureResult>();
archiver.base = () => baseGate.promise;
subject.sessionStarted({ sessionId: "ses_turns_0001", root, engine: engine({ messages: () => messages(0, true) }).reader });
// The turn ends while the base is still packing: its delta waits for the base.
subject.turnCompleted("ses_turns_0001", messages(1));
subject.turnCompleted("ses_turns_0001", messages(2));
// Unreadable messages still get their delta, with no turn: the archiver numbers it after the last one.
subject.turnCompleted("ses_turns_0001", null);
// Unknown sessions (never started in this app run) are left alone.
subject.turnCompleted("ses_unknown_0001", messages(4));
baseGate.resolve(queued("base"));
await subject.settled();
expect(archiver.captures()).toEqual([
`base ses_turns_0001 ${root} 0`,
`delta ses_turns_0001 ${root} 1`,
`delta ses_turns_0001 ${root} 2`,
`delta ses_turns_0001 ${root} null`,
]);
});
test("a prompt right after a turn ended waits for the observer's settle and that turn's delta, then goes out", async () => {
const archiver = new FakeArchiver();
const { subject } = lifecycle(archiver);
const root = await tempDir("root");
const reads = engine({ messages: () => messages(0) });
subject.sessionStarted({ sessionId: "ses_gate_0001", root, engine: reads.reader });
await subject.settled();
const order: string[] = [];
archiver.delta = async (_sessionId, turn) => { order.push(`delta ${turn}`); return queued("delta", turn ?? 0); };
// Turn 1 ended in the engine; the next prompt comes before the observer settled it.
const gate = subject.startGate("ses_gate_0001", root, { previousEnded: true }).then(() => order.push("prompt"));
await Bun.sleep(30);
expect(order).toEqual([]);
subject.turnCompleted("ses_gate_0001", messages(1), 1_000);
await gate;
expect(order).toEqual(["delta 1", "prompt"]);
// The turn before is archived now: the next gate waits for nothing and reads nothing.
const before = { ...reads.reads };
const started = Date.now();
await subject.startGate("ses_gate_0001", root, { previousEnded: true });
expect(Date.now() - started).toBeLessThan(50);
expect(reads.reads).toEqual(before);
expect(archiver.captures()).toEqual([`base ses_gate_0001 ${root} 0`, `delta ses_gate_0001 ${root} 1`]);
});
test("a prompt into a running turn, or a first prompt, waits for nothing", async () => {
const archiver = new FakeArchiver();
const { subject } = lifecycle(archiver);
const root = await tempDir("root");
const started = Date.now();
await subject.startGate("ses_gate_0002", root, { previousEnded: true });
subject.sessionStarted({ sessionId: "ses_gate_0002", root, engine: engine({ messages: () => messages(0) }).reader });
await subject.settled();
await subject.startGate("ses_gate_0002", root, { previousEnded: false });
await subject.startGate("ses_gate_0002", root);
expect(Date.now() - started).toBeLessThan(200);
});
test("the wait ends after turnDeltaWaitMs; a delta that runs after the next prompt went out is cut at that prompt", async () => {
const archiver = new FakeArchiver();
let clock = 10_000;
const { subject, logs } = lifecycle(archiver, { turnDeltaWaitMs: 100, now: () => clock });
const root = await tempDir("root");
const reads = engine({ messages: () => messages(0) });
subject.sessionStarted({ sessionId: "ses_gate_0003", root, engine: reads.reader });
await subject.settled();
const cuts: Array<number | undefined> = [];
const deltaGate = deferred<CaptureResult>();
archiver.delta = () => deltaGate.promise;
const capture = archiver.captureDelta.bind(archiver);
archiver.captureDelta = async (sessionId, root2, turn, options = {}) => {
const result = await capture(sessionId, root2, turn, options);
// The archiver reads the cut when its scan ends: here, once the capture finished.
cuts.push(typeof options.before === "function" ? options.before() : options.before);
return result;
};
// Turn 1 went idle at 10_500 and settled; its delta is slow. The next prompt waits 100 ms, then goes out at 11_000.
clock = 10_600;
subject.turnCompleted("ses_gate_0003", messages(1), 10_500);
const started = Date.now();
await subject.startGate("ses_gate_0003", root, { previousEnded: true });
expect(Date.now() - started).toBeLessThan(1_000);
expect(logs.some((line) => line.message.includes("cut at the prompt"))).toBe(true);
clock = 11_000;
subject.sessionStarted({ sessionId: "ses_gate_0003", root, engine: reads.reader });
deltaGate.resolve(queued("delta", 1));
await subject.settled();
// The delta read its cut when it ran: the prompt at 11_000, the first one after the turn went idle.
expect(cuts).toEqual([11_000]);
});
test("a turn the next prompt cut before the observer saw it end: the delta is cut at the first prompt after the turn's own", async () => {
const archiver = new FakeArchiver();
let clock = 1_000;
const { subject } = lifecycle(archiver, { now: () => clock });
const root = await tempDir("root");
const turn1 = [
{ info: { id: "user_1", role: "user", time: { created: 1_010 } }, parts: [] },
{ info: { id: "assistant_1", role: "assistant", time: { created: 1_020, completed: 1_500 }, finish: "stop" }, parts: [] },
];
const reads = engine({ messages: () => [] });
subject.sessionStarted({ sessionId: "ses_gate_0005", root, engine: reads.reader });
await subject.settled();
const cuts: Array<number | undefined> = [];
const deltaGate = deferred<CaptureResult>();
archiver.delta = () => deltaGate.promise;
const capture = archiver.captureDelta.bind(archiver);
archiver.captureDelta = async (sessionId, root2, turn, options = {}) => {
const result = await capture(sessionId, root2, turn, options);
cuts.push(typeof options.before === "function" ? options.before() : options.before);
return result;
};
// No idle time (the observer saw the turn cut by the next prompt); the next prompt went out at 1_600.
clock = 1_550;
subject.turnCompleted("ses_gate_0005", turn1, null);
clock = 1_600;
subject.sessionStarted({ sessionId: "ses_gate_0005", root, engine: reads.reader });
deltaGate.resolve(queued("delta", 1));
await subject.settled();
expect(cuts).toEqual([1_600]);
});
test("the cut skips a prompt sent while the turn still answered, and falls back to the idle time for a turn opened before this run", async () => {
const cutFor = async (turn: Message[], promptsAt: number[], idleAt: number | null) => {
const archiver = new FakeArchiver();
let clock = promptsAt[0]!;
const { subject } = lifecycle(archiver, { now: () => clock });
const root = await tempDir("root");
const reads = engine({ messages: () => [] });
subject.sessionStarted({ sessionId: "ses_gate_0006", root, engine: reads.reader });
await subject.settled();
const cuts: Array<number | undefined> = [];
const deltaGate = deferred<CaptureResult>();
archiver.delta = () => deltaGate.promise;
const capture = archiver.captureDelta.bind(archiver);
archiver.captureDelta = async (sessionId, root2, number, options = {}) => {
const result = await capture(sessionId, root2, number, options);
cuts.push(typeof options.before === "function" ? options.before() : options.before);
return result;
};
subject.turnCompleted("ses_gate_0006", turn, idleAt);
for (const at of promptsAt.slice(1)) {
clock = at;
subject.sessionStarted({ sessionId: "ses_gate_0006", root, engine: reads.reader });
}
deltaGate.resolve(queued("delta", 1));
await subject.settled();
return cuts[0];
};
const steered = [
{ info: { id: "user_1", role: "user", time: { created: 1_010 } }, parts: [] },
{ info: { id: "assistant_1", role: "assistant", time: { created: 1_020, completed: 1_300 }, finish: "tool-calls" }, parts: [] },
// Sent at 1_200 while the turn still answered: a steer, part of turn 1.
{ info: { id: "user_2", role: "user", time: { created: 1_205 } }, parts: [] },
{ info: { id: "assistant_2", role: "assistant", time: { created: 1_310, completed: 1_500 }, finish: "stop" }, parts: [] },
];
// Prompts went out at 1_000 (turn 1), 1_200 (the steer) and 1_600 (the next turn): the cut is 1_600.
expect(await cutFor(steered, [1_000, 1_200, 1_600], null)).toBe(1_600);
// A turn opened before this run (its prompt is older than every prompt time here): the idle time decides.
const older = [
{ info: { id: "user_1", role: "user", time: { created: 500 } }, parts: [] },
{ info: { id: "assistant_1", role: "assistant", time: { created: 510, completed: 900 }, finish: "stop" }, parts: [] },
];
expect(await cutFor(older, [1_000, 2_000], 1_500)).toBe(2_000);
expect(await cutFor(older, [1_000, 2_000], null)).toBeUndefined();
});
test("a delta that runs before the next prompt has no cut; an aborted prompt still gets its final archive", async () => {
const archiver = new FakeArchiver();
const { subject } = lifecycle(archiver);
const root = await tempDir("root");
const reads = engine({ messages: () => messages(1) });
subject.sessionStarted({ sessionId: "ses_gate_0004", root, engine: reads.reader });
await subject.settled();
const cuts: Array<number | undefined> = [];
const capture = archiver.captureDelta.bind(archiver);
archiver.captureDelta = async (sessionId, root2, turn, options = {}) => {
const result = await capture(sessionId, root2, turn, options);
// The archiver reads the cut when its scan ends: here, once the capture finished.
cuts.push(typeof options.before === "function" ? options.before() : options.before);
return result;
};
subject.turnCompleted("ses_gate_0004", messages(1), Date.now());
await subject.settled();
await subject.startGate("ses_gate_0004", root, { previousEnded: true });
subject.sessionStarted({ sessionId: "ses_gate_0004", root, engine: reads.reader });
// The prompt is stopped before any answer: the count did not move, so the archiver answers stale_turn and a final follows.
archiver.delta = async () => skipped("stale_turn");
subject.turnCompleted("ses_gate_0004", messages(1), Date.now());
await subject.settled();
expect(cuts).toEqual([undefined, undefined]);
expect(archiver.finals()).toEqual(["final ses_gate_0004 turn_incomplete"]);
});
test("after a restart, a resumed session continues from the engine's turn count", async () => {
const archiver = new FakeArchiver();
const root = await tempDir("root");
// The first app run archived turns 0 to 3 of this session; the archiver's state says so.
archiver.base = async () => skipped("exists");
const { subject } = lifecycle(archiver);
subject.start();
subject.sessionStarted({ sessionId: "ses_resumed_0001", root, engine: engine({ messages: () => messages(3, true) }).reader });
subject.turnCompleted("ses_resumed_0001", messages(4));
await subject.settled();
expect(archiver.calls).toEqual(["drain", `base ses_resumed_0001 ${root} 3`, `delta ses_resumed_0001 ${root} 4`, "drain"]);
});
test("without an account the queue a previous run left waits for it (a refused refresh never clears it) and nothing is captured", async () => {
const archiver = new FakeArchiver();
const { subject } = lifecycle(archiver, { enabled: false, accountMissing: true });
subject.start();
const root = await tempDir("root");
subject.sessionStarted({ sessionId: "ses_retired_0001", root, engine: engine().reader });
subject.turnCompleted("ses_retired_0001", messages(1));
await subject.settled();
expect(archiver.calls).toEqual([]);
});
test("with an account, start first claims the queue for it, then drains", async () => {
const archiver = new FakeArchiver();
const calls = archiver.calls;
const claiming = Object.assign(archiver, { claimAccount: async () => { calls.push("claim"); } });
const { subject } = lifecycle(claiming);
subject.start();
await subject.settled();
expect(calls.slice(0, 2)).toEqual(["claim", "drain"]);
});
test("with archiving turned off on this device start clears what a previous run left and nothing is captured", async () => {
const archiver = new FakeArchiver();
const { subject } = lifecycle(archiver, { enabled: false });
subject.start();
const root = await tempDir("root");
subject.sessionStarted({ sessionId: "ses_signed_out_01", root, engine: engine().reader });
subject.turnCompleted("ses_signed_out_01", messages(1));
subject.sessionEnded("ses_signed_out_01");
await subject.settled();
expect(archiver.calls).toEqual(["signOut"]);
});
test("sign-out stops the archiver: queued steps never run and nothing is captured or uploaded afterwards", async () => {
const archiver = new FakeArchiver();
const { subject } = lifecycle(archiver);
const root = await tempDir("root");
const first = deferred<CaptureResult>();
archiver.base = (sessionId) => (sessionId === "ses_first_0001" ? first.promise : Promise.resolve(queued("base")));
subject.sessionStarted({ sessionId: "ses_first_0001", root, engine: engine().reader });
// One capture at a time: the second session waits behind the first.
subject.sessionStarted({ sessionId: "ses_second_001", root, engine: engine().reader });
await Bun.sleep(5);
expect(archiver.captures()).toEqual([`base ses_first_0001 ${root} 0`]);
await subject.signOut();
first.resolve(queued("base"));
subject.sessionStarted({ sessionId: "ses_third_0001", root, engine: engine().reader });
subject.turnCompleted("ses_first_0001", messages(1));
subject.sessionEnded("ses_first_0001");
await subject.settled();
expect(archiver.calls).toEqual([`base ses_first_0001 ${root} 0`, "signOut"]);
});
test("428 (archive consent missing) turns archiving off quietly until the consent recheck", async () => {
let now = 1_000;
const archiver = new FakeArchiver();
const { subject, logs } = lifecycle(archiver, { now: () => now });
const root = await tempDir("root");
archiver.base = async () => skipped("disabled");
subject.sessionStarted({ sessionId: "ses_consent_001", root, engine: engine().reader });
await subject.settled();
// Off: no capture, no consent check and no upload for any session.
subject.sessionStarted({ sessionId: "ses_consent_001", root, engine: engine().reader });
subject.sessionStarted({ sessionId: "ses_consent_002", root, engine: engine().reader });
subject.turnCompleted("ses_consent_001", messages(1));
subject.sessionEnded("ses_consent_003");
await subject.settled();
expect(archiver.calls).toEqual([`base ses_consent_001 ${root} 0`]);
// Past the recheck time the session's next prompt checks consent again, which is now given.
now += 60_001;
archiver.base = async () => queued("base");
subject.sessionStarted({ sessionId: "ses_consent_001", root, engine: engine({ messages: () => messages(1, true) }).reader });
await subject.settled();
expect(archiver.calls.slice(1)).toEqual([`base ses_consent_001 ${root} 1`, "drain"]);
// Consent withdrawn while uploading: the drain turns archiving off the same way.
archiver.drainResult = async () => ({ ...drained, dropped: 1, disabled: true });
subject.turnCompleted("ses_consent_001", messages(2));
await subject.settled();
subject.turnCompleted("ses_consent_001", messages(3));
subject.sessionStarted({ sessionId: "ses_consent_004", root, engine: engine().reader });
await subject.settled();
expect(archiver.calls.slice(3)).toEqual([`delta ses_consent_001 ${root} 2`, "drain"]);
expect(logs).toEqual([]);
});
test("failures never reach the caller: one warn line each, and archiving carries on", async () => {
const archiver = new FakeArchiver();
const { subject, logs } = lifecycle(archiver);
const root = await tempDir("root");
archiver.base = async (sessionId) => {
if (sessionId === "ses_throws_0001") throw new Error("disk full");
return queued("base");
};
archiver.drainResult = async () => { throw new Error("drain exploded"); };
subject.sessionStarted({ sessionId: "ses_throws_0001", root, engine: engine().reader });
// The engine could not be read: skipped now, tried again on the next prompt.
let engineUp = false;
const flaky = engine({ session: () => { if (!engineUp) throw new Error("ECONNREFUSED"); return { id: "ses_flaky_00001" }; } });
subject.sessionStarted({ sessionId: "ses_flaky_00001", root, engine: flaky.reader });
// A root that no longer exists is not archivable; nothing to warn about.
subject.sessionStarted({ sessionId: "ses_gone_000001", root: join(root, "missing"), engine: engine().reader });
await subject.settled();
expect(archiver.captures()).toEqual([`base ses_throws_0001 ${root} 0`]);
expect(logs.map((log) => [log.level, log.message, log.attributes?.step ?? log.attributes?.reason])).toEqual([
["warn", "OmniRush project archive step failed", "base"],
["warn", "OmniRush project archive could not read the engine for a session; its next prompt or turn tries again", "the engine session could not be read"],
]);
engineUp = true;
subject.sessionStarted({ sessionId: "ses_flaky_00001", root, engine: flaky.reader });
await subject.settled();
expect(archiver.captures().at(-1)).toBe(`base ses_flaky_00001 ${root} 0`);
expect(logs.at(-1)).toMatchObject({ level: "warn", message: "OmniRush project archive step failed", attributes: { step: "drain", error: "Error: drain exploded" } });
// Resolved once: later prompts do not read the engine again.
subject.sessionStarted({ sessionId: "ses_flaky_00001", root, engine: flaky.reader });
await subject.settled();
expect(flaky.reads).toEqual({ session: 2, messages: 1 });
});
test("after a restart the engine can still be starting: the session is resolved when its turn completes, and the turn's delta is not lost", async () => {
const archiver = new FakeArchiver();
const { subject, logs } = lifecycle(archiver);
const root = await tempDir("root");
// The previous app run archived the base and turns 1 to 7.
archiver.base = async () => skipped("exists");
let engineUp = false;
const slow = engine({
session: () => {
if (!engineUp) throw new Error("TimeoutError: the engine did not answer");
return { id: "ses_restart_0001" };
},
messages: () => messages(7, true),
});
subject.start();
subject.sessionStarted({ sessionId: "ses_restart_0001", root, engine: slow.reader });
await subject.settled();
expect(archiver.captures()).toEqual([]);
expect(logs.map((log) => log.attributes?.reason)).toEqual(["the engine session could not be read"]);
// The engine came up and ran turn 8; the observer read its messages.
engineUp = true;
subject.turnCompleted("ses_restart_0001", messages(8));
await subject.settled();
expect(archiver.captures()).toEqual([`base ses_restart_0001 ${root} 8`, `delta ses_restart_0001 ${root} 8`]);
// The observer's messages give the count: the message list is not read again.
expect(slow.reads).toEqual({ session: 2, messages: 0 });
// Resolved: the next turn is an ordinary delta, with no engine read.
subject.turnCompleted("ses_restart_0001", messages(9));
subject.sessionStarted({ sessionId: "ses_restart_0001", root, engine: slow.reader });
await subject.settled();
expect(archiver.captures().slice(2)).toEqual([`delta ses_restart_0001 ${root} 9`]);
expect(slow.reads).toEqual({ session: 2, messages: 0 });
});
test("a base whose folder policy could not be asked is tried again at the next turn, not skipped for the session", async () => {
const archiver = new FakeArchiver();
const { subject, logs } = lifecycle(archiver);
const root = await tempDir("root");
const outage: CaptureResult = { status: "skipped", reason: "unavailable", detail: "policy_unavailable" };
let serverUp = false;
archiver.base = async () => (serverUp ? queued("base") : outage);
subject.sessionStarted({ sessionId: "ses_policy_0001", root, engine: engine().reader });
await subject.settled();
expect(archiver.captures()).toEqual([`base ses_policy_0001 ${root} 0`]);
expect(logs.map((log) => log.attributes?.reason)).toEqual(["the folder policy could not be asked"]);
// The server answers again by the turn's end: the base is taken then, the turn's delta after it.
serverUp = true;
subject.turnCompleted("ses_policy_0001", messages(1));
await subject.settled();
expect(archiver.captures()).toEqual([`base ses_policy_0001 ${root} 0`, `base ses_policy_0001 ${root} 1`, `delta ses_policy_0001 ${root} 1`]);
await subject.stop({ finals: false });
});
test("a path touched while the folder policy is unavailable gets its base once the policy answers", async () => {
const archiver = new FakeArchiver();
archiver.baseDue = true;
archiver.final = async () => queued("base");
const { subject } = lifecycle(archiver, { touchedBaseDelayMs: 10 });
const root = await tempDir("root");
const outage: CaptureResult = { status: "skipped", reason: "unavailable", detail: "policy_unavailable" };
let serverUp = false;
archiver.base = async () => (serverUp ? skipped("unchanged") : outage);
subject.sessionStarted({ sessionId: "ses_policy_0003", root, engine: engine().reader });
await subject.settled();
subject.pathTouched("ses_policy_0003", "a.py");
// The delay passes while the base is still unresolved: nothing is asked yet.
await new Promise((resolve) => setTimeout(resolve, 30));
await subject.settled();
expect(archiver.finals()).toEqual([]);
// The policy answers at the next turn: the base resolves, then the touched-files base follows at once.
serverUp = true;
subject.turnCompleted("ses_policy_0003", messages(1));
await subject.settled();
await new Promise((resolve) => setTimeout(resolve, 20));
await subject.settled();
expect(archiver.finals()).toEqual(["final ses_policy_0003 first_touch"]);
await subject.stop({ finals: false });
});
test("a folder policy that is really off still ends the session's archiving: no base asked again", async () => {
const archiver = new FakeArchiver();
const { subject } = lifecycle(archiver);
const root = await tempDir("root");
archiver.base = async () => ({ status: "skipped", reason: "not_archivable", detail: "no_git_folder_policy_off" });
subject.sessionStarted({ sessionId: "ses_policy_0002", root, engine: engine().reader });
await subject.settled();
subject.turnCompleted("ses_policy_0002", messages(1));
await subject.settled();
expect(archiver.captures()).toEqual([`base ses_policy_0002 ${root} 0`]);
await subject.stop({ finals: false });
});
test("a session still unreadable when its turn completes stays pending; a child resolved at turn end is never archived", async () => {
const archiver = new FakeArchiver();
const { subject, logs } = lifecycle(archiver);
const root = await tempDir("root");
let engineUp = false;
const down = engine({ session: () => { if (!engineUp) throw new Error("ECONNREFUSED"); return { id: "ses_down_000001" }; } });
subject.sessionStarted({ sessionId: "ses_down_000001", root, engine: down.reader });
subject.turnCompleted("ses_down_000001", messages(1));
await subject.settled();
expect(archiver.captures()).toEqual([]);
expect(logs).toHaveLength(2);
// The changes are not lost: the first turn that can resolve the session captures the folder.
engineUp = true;
subject.turnCompleted("ses_down_000001", messages(2));
await subject.settled();
expect(archiver.captures()).toEqual([`base ses_down_000001 ${root} 2`, `delta ses_down_000001 ${root} 2`]);
let childUp = false;
const child = engine({ session: () => { if (!childUp) throw new Error("ECONNREFUSED"); return { id: "ses_child_0003", parentID: "ses_down_000001" }; } });
subject.sessionStarted({ sessionId: "ses_child_0003", root, engine: child.reader });
await subject.settled();
childUp = true;
subject.turnCompleted("ses_child_0003", messages(1));
subject.turnCompleted("ses_child_0003", messages(2));
await subject.settled();
expect(archiver.captures()).toHaveLength(2);
expect(child.reads).toEqual({ session: 2, messages: 0 });
});
test("an engine too slow to answer at session start is read again a minute later, so a session whose first turn runs for hours still gets its base", async () => {
jest.useFakeTimers();
try {
const archiver = new FakeArchiver();
const { subject, logs } = lifecycle(archiver);
const root = await tempDir("root");
let engineUp = false;
const slow = engine({
session: () => {
if (!engineUp) throw new Error("TimeoutError: the engine did not answer");
return { id: "ses_retried_0001" };
},
messages: () => messages(2, true),
});
subject.sessionStarted({ sessionId: "ses_retried_0001", root, engine: slow.reader });
await subject.settled();
expect(archiver.captures()).toEqual([]);
expect(logs.map((log) => [log.attributes?.reason, log.attributes?.retryInMs])).toEqual([["the engine session could not be read", 60_000]]);
// The engine answers by the time the retry runs, with the first turn of this app run still going.
engineUp = true;
jest.advanceTimersByTime(59_999);
await subject.settled();
expect(slow.reads.session).toBe(1);
jest.advanceTimersByTime(1);
await subject.settled();
expect(archiver.captures()).toEqual([`base ses_retried_0001 ${root} 2`]);
// Resolved: no further retry, and the turn's delta follows the base.
jest.advanceTimersByTime(60 * 60_000);
subject.turnCompleted("ses_retried_0001", messages(3));
await subject.settled();
expect(archiver.captures()).toEqual([`base ses_retried_0001 ${root} 2`, `delta ses_retried_0001 ${root} 3`]);
expect(slow.reads).toEqual({ session: 2, messages: 1 });
} finally {
jest.useRealTimers();
}
});
test("an engine that stays unreadable is read again after 1, 2, 5 and 10 minutes, then at the session's next prompt or turn", async () => {
jest.useFakeTimers();
try {
const archiver = new FakeArchiver();
const { subject, logs } = lifecycle(archiver);
const root = await tempDir("root");
let engineUp = false;
const down = engine({ session: () => { if (!engineUp) throw new Error("ECONNREFUSED"); return { id: "ses_down_retry_01" }; } });
subject.sessionStarted({ sessionId: "ses_down_retry_01", root, engine: down.reader });
await subject.settled();
// A prompt while a retry is waiting reads the engine at once but does not add another retry.
subject.sessionStarted({ sessionId: "ses_down_retry_01", root, engine: down.reader });
await subject.settled();
expect(down.reads.session).toBe(2);
for (const minutes of [1, 2, 5, 10]) {
const reads = down.reads.session;
jest.advanceTimersByTime(minutes * 60_000 - 1);
await subject.settled();
expect(down.reads.session).toBe(reads);
jest.advanceTimersByTime(1);
await subject.settled();
expect(down.reads.session).toBe(reads + 1);
}
jest.advanceTimersByTime(24 * 60 * 60_000);
await subject.settled();
expect(down.reads.session).toBe(6);
expect(logs.map((log) => log.attributes?.retryInMs)).toEqual([60_000, undefined, 120_000, 300_000, 600_000, undefined]);
// Past the retries, the next completed turn still resolves it.
engineUp = true;
subject.turnCompleted("ses_down_retry_01", messages(1));
await subject.settled();
expect(archiver.captures()).toEqual([`base ses_down_retry_01 ${root} 1`, `delta ses_down_retry_01 ${root} 1`]);
// A retry never runs once archiving stopped.
const stopped = engine({ session: () => { throw new Error("ECONNREFUSED"); } });
subject.sessionStarted({ sessionId: "ses_stopped_0001", root, engine: stopped.reader });
await subject.settled();
await subject.stop();
jest.advanceTimersByTime(60_000);
await subject.settled();
expect(stopped.reads.session).toBe(1);
} finally {
jest.useRealTimers();
}
});
test("with the real archiver: base at session start, a delta per changed turn, and the next app run resumes the upload", async () => {
const server = new FakeArchiveServer();
const root = await tempDir("project");
const git = (...args: string[]) => execFileAsync("git", ["-C", root, "-c", "user.name=t", "-c", "[email protected]", "-c", "commit.gpgsign=false", ...args]);
await git("init", "-q", "-b", "main");
await writeFile(join(root, "app.ts"), "export const app = 1;\n");
await git("add", "app.ts");
await git("commit", "-q", "-m", "initial");
const state = await tempDir("state");
const archiverFor = (now?: () => Date) => new SessionArchiver({
gatewayUrl: server.gatewayUrl,
accessToken: server.token,
fetch: server.respond,
stateDir: state,
retry: { baseMs: 1, maxMs: 2, attempts: 2 },
...(now ? { now } : {}),
});
const first = lifecycle(archiverFor());
first.subject.start();
first.subject.sessionStarted({ sessionId: "ses_real_000001", root, engine: engine({ messages: () => messages(0, true) }).reader });
await first.subject.settled();
// Nothing changed during turn 1: no delta.
first.subject.turnCompleted("ses_real_000001", messages(1));
await first.subject.settled();
expect(server.objects().map((archive) => [archive.request.kind, archive.request.turn])).toEqual([["base", 0]]);
// Turn 2 changes the folder, but S3 is unreachable until the app restarts.
await mkdir(join(root, "src"));
await writeFile(join(root, "src/feature.ts"), "export const feature = true;\n");
server.putHook = () => "network";
first.subject.turnCompleted("ses_real_000001", messages(2));
await first.subject.settled();
await first.subject.stop();
expect(server.objects()).toHaveLength(1);
// The next app run, after the failed job's backoff.
server.putHook = null;
const later = new Date(Date.now() + 2 * 60_000);
const second = lifecycle(archiverFor(() => later));
second.subject.start();
await second.subject.settled();
const archives = server.objects();
expect(archives.map((archive) => [archive.request.kind, archive.request.sequence, archive.request.turn])).toEqual([["base", 0, 0], ["delta", 1, 2]]);
const delta = await openArchive(archives[1]!.object!);
expect(delta.map((member) => member.name)).toContain("src/feature.ts");
expect(manifestOf(delta)).toMatchObject({ kind: "delta", turn: 2 });
expect([...first.logs, ...second.logs].filter((log) => log.level === "warn" && !log.message.includes("deferred"))).toEqual([]);
});
test("with the real archiver: after an app restart whose engine is still starting, the first turn's change is archived with its turn", async () => {
const server = new FakeArchiveServer();
const root = await tempDir("project");
const git = (...args: string[]) => execFileAsync("git", ["-C", root, "-c", "user.name=t", "-c", "[email protected]", "-c", "commit.gpgsign=false", ...args]);
await git("init", "-q", "-b", "main");
await writeFile(join(root, "app.ts"), "export const app = 1;\n");
await git("add", "app.ts");
await git("commit", "-q", "-m", "initial");
const state = await tempDir("state");
const archiverFor = () => new SessionArchiver({ gatewayUrl: server.gatewayUrl, accessToken: server.token, fetch: server.respond, stateDir: state, retry: { baseMs: 1, maxMs: 2, attempts: 2 } });
const first = lifecycle(archiverFor());
first.subject.start();
first.subject.sessionStarted({ sessionId: "ses_restarted_01", root, engine: engine({ messages: () => messages(0, true) }).reader });
await first.subject.settled();
await writeFile(join(root, "after.txt"), "after restart\n");
first.subject.turnCompleted("ses_restarted_01", messages(1));
await first.subject.settled();
await first.subject.stop();
// The next app run: the engine does not answer the session start's reads.
const second = lifecycle(archiverFor());
second.subject.start();
let engineUp = false;
const reads = engine({
session: () => {
if (!engineUp) throw new Error("TimeoutError: the engine did not answer");
return { id: "ses_restarted_01" };
},
messages: () => messages(1, true),
});
second.subject.sessionStarted({ sessionId: "ses_restarted_01", root, engine: reads.reader });
await second.subject.settled();
engineUp = true;
await writeFile(join(root, "after.txt"), "after restart 2\n");
second.subject.turnCompleted("ses_restarted_01", messages(2));
await second.subject.settled();
// A turn whose messages the observer could not read follows the last archived turn.
await writeFile(join(root, "after.txt"), "unread turn\n");
second.subject.turnCompleted("ses_restarted_01", null);
await second.subject.settled();
const archives = server.objects();
expect(archives.map((archive) => [archive.request.kind, archive.request.sequence, archive.request.turn])).toEqual([["base", 0, 0], ["delta", 1, 1], ["delta", 2, 2], ["delta", 3, 3]]);
const latest = await openArchive(archives[2]!.object!);
expect(latest.find((member) => member.name === "after.txt")!.content.toString()).toBe("after restart 2\n");
expect(manifestOf(latest)).toMatchObject({ kind: "delta", turn: 2 });
expect(manifestOf(await openArchive(archives[3]!.object!))).toMatchObject({ kind: "delta", turn: 3 });
});
});
describe("ProjectArchiveLifecycle base quiet period", () => {
const sleep = (ms: number) => new Promise((resolvePromise) => setTimeout(resolvePromise, ms));
function deferring(archiver: ProjectArchiver, baseIdleMs: number, baseMaxDeferMs: number) {
return new ProjectArchiveLifecycle({ archiver, enabled: true, log: () => undefined, consentRecheckMs: 60_000, baseIdleMs, baseMaxDeferMs });
}
test("bases wait until no prompt has been dispatched for baseIdleMs", async () => {
const archiver = new FakeArchiver();
const packedAt = new Map<string, number>();
archiver.base = async (sessionId) => {
packedAt.set(sessionId, Date.now());
return queued("base");
};
const subject = deferring(archiver, 300, 5_000);
const [first, second] = [await tempDir("first"), await tempDir("second")];
subject.sessionStarted({ sessionId: "ses_first_00001", root: first, engine: engine().reader });
await sleep(200);
const lastPromptAt = Date.now();
subject.sessionStarted({ sessionId: "ses_second_0001", root: second, engine: engine().reader });
await sleep(200);
// The first prompt is 400 ms old, but the second only 200 ms: nothing packed yet.
expect(archiver.captures()).toEqual([]);
await subject.settled();
expect(archiver.captures().map((call) => call.split(" ")[1]).sort()).toEqual(["ses_first_00001", "ses_second_0001"]);
for (const at of packedAt.values()) expect(at - lastPromptAt).toBeGreaterThanOrEqual(290);
});
test("a steady stream of prompts delays a base by at most baseMaxDeferMs", async () => {
const archiver = new FakeArchiver();
let packedAt = 0;
archiver.base = async () => {
packedAt = Date.now();
return queued("base");
};
const subject = deferring(archiver, 200, 600);
const startedAt = Date.now();
subject.sessionStarted({ sessionId: "ses_busy_000001", root: await tempDir("busy"), engine: engine().reader });
const other = await tempDir("other");
for (let prompt = 0; prompt < 10 && packedAt === 0; prompt += 1) {
await sleep(100);
subject.sessionStarted({ sessionId: "ses_other_00001", root: other, engine: engine().reader });
}
await subject.settled();
expect(packedAt - startedAt).toBeGreaterThanOrEqual(590);
expect(packedAt - startedAt).toBeLessThan(1_000);
});
test("stop and sign-out end the wait without packing", async () => {
for (const end of ["stop", "signOut"] as const) {
const archiver = new FakeArchiver();
const subject = deferring(archiver, 60_000, 120_000);
subject.sessionStarted({ sessionId: "ses_waiting_0001", root: await tempDir("waiting"), engine: engine().reader });
await sleep(50);
const endedAt = Date.now();
await subject[end]();
await subject.settled();
expect(Date.now() - endedAt).toBeLessThan(1_000);
expect(archiver.captures()).toEqual([]);
}
});
});
describe("ProjectArchiveLifecycle final archives", () => {
const sleep = (ms: number) => new Promise((resolvePromise) => setTimeout(resolvePromise, ms));
/** Turn deltas numbered like the real archiver: a count that did not move is stale. */
function turnArchiver(): FakeArchiver {
const archiver = new FakeArchiver();
const lastTurn = new Map<string, number>();
archiver.base = async (sessionId, turn) => {
lastTurn.set(sessionId, turn);
return queued("base");
};
archiver.delta = async (sessionId, turn) => {
const next = turn ?? (lastTurn.get(sessionId) ?? 0) + 1;
if (next <= (lastTurn.get(sessionId) ?? -1)) return skipped("stale_turn");
lastTurn.set(sessionId, next);
return queued("delta", next);
};
return archiver;
}
test("a session quiet after its turn gets one idle final archive; a new prompt cancels the pending one", async () => {
const archiver = turnArchiver();
const { subject } = lifecycle(archiver, { finalIdleMs: 300 });
const root = await tempDir("root");
const reads = engine({ messages: () => messages(0, true) }).reader;
subject.sessionStarted({ sessionId: "ses_idle_000001", root, engine: reads });
await subject.settled();
// The next prompt comes within the quiet window: no final archive.
subject.turnCompleted("ses_idle_000001", messages(1));
await sleep(30);
subject.sessionStarted({ sessionId: "ses_idle_000001", root, engine: reads });
await sleep(400);
await subject.settled();
expect(archiver.finals()).toEqual([]);
// Turn 2 ends and nothing follows: one final archive, however long the quiet lasts.
subject.turnCompleted("ses_idle_000001", messages(2));
await sleep(400);
await subject.settled();
expect(archiver.finals()).toEqual(["final ses_idle_000001 idle"]);
await sleep(400);
await subject.settled();
expect(archiver.finals()).toHaveLength(1);
expect(archiver.captures()).toEqual([`base ses_idle_000001 ${root} 0`, `delta ses_idle_000001 ${root} 1`, `delta ses_idle_000001 ${root} 2`]);
// A prompt while the idle final is packing cancels it.
let signal: AbortSignal | undefined;
archiver.final = (_sessionId, _reason, given) => new Promise((resolvePromise) => {
signal = given;
given?.addEventListener("abort", () => resolvePromise(skipped("cancelled")), { once: true });
});
subject.turnCompleted("ses_idle_000001", messages(3));
await sleep(400);
expect(archiver.finals()).toHaveLength(2);
expect(signal?.aborted).toBe(false);
subject.sessionStarted({ sessionId: "ses_idle_000001", root, engine: reads });
await subject.settled();
expect(signal?.aborted).toBe(true);
});
test("a turn the observer follows keeps the idle final archive off until it ends, even when its prompt came before the previous turn's end", async () => {
const archiver = turnArchiver();
const { subject } = lifecycle(archiver, { finalIdleMs: 100 });
const root = await tempDir("root");
const reads = engine().reader;
subject.sessionStarted({ sessionId: "ses_followed_001", root, engine: reads });
await subject.settled();
// The next prompt went out while turn 1 settled: its session start comes first, then turn 1's end,
// then the observer follows turn 2.
subject.sessionStarted({ sessionId: "ses_followed_001", root, engine: reads });
subject.turnCompleted("ses_followed_001", messages(1));
subject.turnFollowed("ses_followed_001");
await sleep(250);
await subject.settled();
expect(archiver.finals()).toEqual([]);
// Turn 2 ends: its quiet window gets the idle final archive.
subject.turnCompleted("ses_followed_001", messages(2));
await sleep(250);
await subject.settled();
expect(archiver.finals()).toEqual(["final ses_followed_001 idle"]);
expect(archiver.captures()).toEqual([`base ses_followed_001 ${root} 0`, `delta ses_followed_001 ${root} 1`, `delta ses_followed_001 ${root} 2`]);
// An idle final already packing when a turn is followed is cancelled like one a prompt ends.
let signal: AbortSignal | undefined;
archiver.final = (_sessionId, _reason, given) => new Promise((resolvePromise) => {
signal = given;
given?.addEventListener("abort", () => resolvePromise(skipped("cancelled")), { once: true });
});
subject.turnCompleted("ses_followed_001", messages(3));
await sleep(250);
expect(signal?.aborted).toBe(false);
subject.turnFollowed("ses_followed_001");
await subject.settled();
expect(signal?.aborted).toBe(true);
// A session this run does not know is left alone.
subject.turnFollowed("ses_unknown_0002");
await subject.settled();
expect(archiver.finals()).toHaveLength(2);
});
test("a session deleted, a sign-out and a shutdown clear both an idle final archive and an unresolved start's retry; neither runs afterwards", async () => {
const root = await tempDir("root");
jest.useFakeTimers();
try {
for (const end of ["sessionEnded", "signOut", "stop"] as const) {
const archiver = turnArchiver();
const { subject } = lifecycle(archiver);
// One session's turn ended: its idle final archive waits for FINAL_IDLE_MS.
subject.sessionStarted({ sessionId: "ses_timer_idle01", root, engine: engine().reader });
await subject.settled();
subject.turnCompleted("ses_timer_idle01", messages(1));
await subject.settled();
// Another's engine could not be read at its start: its retry waits a minute.
const down = engine({ session: () => { throw new Error("ECONNREFUSED"); } });
subject.sessionStarted({ sessionId: "ses_timer_retry1", root, engine: down.reader });
await subject.settled();
expect(jest.getTimerCount()).toBe(2);
if (end === "sessionEnded") {
subject.sessionEnded("ses_timer_idle01");
subject.sessionEnded("ses_timer_retry1");
} else if (end === "signOut") {
await subject.signOut();
} else {
await subject.stop();
}
await subject.settled();
expect(jest.getTimerCount()).toBe(0);
jest.advanceTimersByTime(24 * 60 * 60_000);
await subject.settled();
expect(down.reads.session).toBe(1);
// Only a deleted session gets its own (session_deleted) final archive; shutdown hands its finals to the archiver.
expect(archiver.finals().sort()).toEqual(end === "sessionEnded"
? ["final ses_timer_idle01 session_deleted", "final ses_timer_retry1 session_deleted"]
: []);
expect(archiver.captures()).toEqual([`base ses_timer_idle01 ${root} 0`, `delta ses_timer_idle01 ${root} 1`]);
}
} finally {
jest.useRealTimers();
}
});
test("a start read still running when the session is deleted, at a sign-out or at shutdown arms no retry when it fails", async () => {
const root = await tempDir("root");
jest.useFakeTimers();
try {
for (const end of ["sessionEnded", "signOut", "stop"] as const) {
const archiver = turnArchiver();
const { subject, logs } = lifecycle(archiver);
const read = deferred<unknown>();
const slow = engine({ session: () => read.promise });
subject.sessionStarted({ sessionId: "ses_inflight_001", root, engine: slow.reader });
for (let tick = 0; tick < 100 && slow.reads.session === 0; tick += 1) await Promise.resolve();
expect(slow.reads.session).toBe(1);
if (end === "sessionEnded") subject.sessionEnded("ses_inflight_001");
else if (end === "signOut") await subject.signOut();
else await subject.stop();
// The engine gives up only now.
read.resolve(null);
await subject.settled();
expect(logs.filter((log) => log.attributes?.reason === "the engine session could not be read").map((log) => log.attributes?.retryInMs)).toEqual([undefined]);
expect(jest.getTimerCount()).toBe(0);
jest.advanceTimersByTime(24 * 60 * 60_000);
await subject.settled();
expect(slow.reads.session).toBe(1);
expect(archiver.captures()).toEqual([]);
}
} finally {
jest.useRealTimers();
}
});
test("a turn that ends without completing: its delta when the engine's count moved, else a final archive", async () => {
const archiver = turnArchiver();
const { subject } = lifecycle(archiver, { finalIdleMs: 60_000 });
const root = await tempDir("root");
let count: number | null = 0;
const reads = engine({ messages: () => (count === null ? Promise.reject(new Error("ECONNREFUSED")) : messages(count)) });
subject.sessionStarted({ sessionId: "ses_abnormal_001", root, engine: reads.reader });
await subject.settled();
// The observer gave up (or failed) after the turn had completed in the engine.
count = 1;
subject.turnIncomplete("ses_abnormal_001");
await subject.settled();
// Aborted before any answer: the count did not move.
subject.turnIncomplete("ses_abnormal_001");
await subject.settled();
// The engine went away: no count to go by.
count = null;
subject.turnIncomplete("ses_abnormal_001");
await subject.settled();
// A settled turn whose count did not move (a prompt aborted at once) is final too.
subject.turnCompleted("ses_abnormal_001", messages(1, true));
await subject.settled();
expect(archiver.calls.filter((call) => call !== "drain")).toEqual([
`base ses_abnormal_001 ${root} 0`,
`delta ses_abnormal_001 ${root} 1`,
`delta ses_abnormal_001 ${root} 1`,
"final ses_abnormal_001 turn_incomplete",
"final ses_abnormal_001 turn_incomplete",
`delta ses_abnormal_001 ${root} 1`,
"final ses_abnormal_001 turn_incomplete",
]);
// Unknown sessions are left alone.
subject.turnIncomplete("ses_unknown_0001");
await subject.settled();
expect(archiver.finals()).toHaveLength(3);
});
test("a deleted session gets a final archive before it is forgotten; a child never, an unknown one if the archiver has its base", async () => {
const archiver = turnArchiver();
const { subject } = lifecycle(archiver);
const root = await tempDir("root");
subject.sessionStarted({ sessionId: "ses_deleted_0001", root, engine: engine().reader });
subject.sessionStarted({ sessionId: "ses_child_00001", root, engine: engine({ parentID: "ses_deleted_0001" }).reader });
await subject.settled();
subject.turnCompleted("ses_deleted_0001", messages(1));
subject.sessionEnded("ses_deleted_0001");
subject.sessionEnded("ses_child_00001");
// A session this app run has not seen (the archiver answers no_base when it never had one).
subject.sessionEnded("ses_earlier_0001");
await subject.settled();
expect(archiver.finals().sort()).toEqual(["final ses_deleted_0001 session_deleted", "final ses_earlier_0001 session_deleted"]);
// Forgotten: its pending turn step was dropped, and later calls are ignored.
subject.turnCompleted("ses_deleted_0001", messages(2));
await subject.settled();
expect(archiver.captures()).toEqual([`base ses_deleted_0001 ${root} 0`]);
});
test("shutdown hands this run's sessions to the archiver's final archives, most recent first, within the budget", async () => {
let now = 1_000;
const archiver = turnArchiver();
const { subject } = lifecycle(archiver, { now: () => now });
const root = await tempDir("root");
subject.sessionStarted({ sessionId: "ses_quit_old_001", root, engine: engine().reader });
now += 1_000;
subject.sessionStarted({ sessionId: "ses_quit_new_001", root, engine: engine().reader });
subject.sessionStarted({ sessionId: "ses_quit_child_1", root, engine: engine({ parentID: "ses_quit_new_001" }).reader });
await subject.settled();
now += 1_000;
subject.turnCompleted("ses_quit_old_001", messages(1));
await subject.settled();
await subject.stop();
expect(archiver.stops).toEqual([{ finals: ["ses_quit_old_001", "ses_quit_new_001"], budgetMs: 5_000 }]);
// No budget, consent off, or the account gone (a user sign-out restarts the server): a plain stop.
const noBudget = turnArchiver();
const off = lifecycle(noBudget, { quitBudgetMs: 0 });
off.subject.sessionStarted({ sessionId: "ses_quit_none_01", root, engine: engine().reader });
await off.subject.settled();
await off.subject.stop();
const refused = turnArchiver();
refused.base = async () => skipped("disabled");
const consent = lifecycle(refused);
consent.subject.sessionStarted({ sessionId: "ses_quit_none_02", root, engine: engine().reader });
await consent.subject.settled();
await consent.subject.stop();
const gone = turnArchiver();
const signedOut = lifecycle(gone);
signedOut.subject.sessionStarted({ sessionId: "ses_quit_none_03", root, engine: engine().reader });
await signedOut.subject.settled();
await signedOut.subject.stop({ finals: false });
expect([...noBudget.stops, ...refused.stops, ...gone.stops]).toEqual([{}, {}, {}]);
});
test("app start: the sessions the archiver names get a final archive, behind every other waiting step", async () => {
const archiver = turnArchiver();
const { subject } = lifecycle(archiver);
const root = await tempDir("root");
const first = deferred<CaptureResult>();
archiver.base = (sessionId) => (sessionId === "ses_start_first1" ? first.promise : Promise.resolve(queued("base")));
// A base is packing when the app-start check comes back.
subject.sessionStarted({ sessionId: "ses_start_first1", root, engine: engine().reader });
await sleep(10);
expect(archiver.captures()).toEqual([`base ses_start_first1 ${root} 0`]);
archiver.startFinals = ["ses_start_final1", "ses_start_final2"];
subject.start();
await sleep(10);
subject.sessionStarted({ sessionId: "ses_start_next01", root, engine: engine().reader });
first.resolve(queued("base"));
await subject.settled();
expect(archiver.calls.filter((call) => call !== "drain")).toEqual([
`base ses_start_first1 ${root} 0`,
`base ses_start_next01 ${root} 0`,
"final ses_start_final1 app_start",
"final ses_start_final2 app_start",
]);
});
test("with the real archiver: after the last turn, the folder is archived when the chat goes quiet, when the app quits and at the next start", async () => {
const server = new FakeArchiveServer();
const root = await tempDir("project");
const git = (...args: string[]) => execFileAsync("git", ["-C", root, "-c", "user.name=t", "-c", "[email protected]", "-c", "commit.gpgsign=false", ...args]);
await git("init", "-q", "-b", "main");
await writeFile(join(root, "app.ts"), "export const app = 1;\n");
await git("add", "app.ts");
await git("commit", "-q", "-m", "initial");
const state = await tempDir("state");
const archiverFor = () => new SessionArchiver({ gatewayUrl: server.gatewayUrl, accessToken: server.token, fetch: server.respond, stateDir: state, retry: { baseMs: 1, maxMs: 2, attempts: 2 } });
const id = "ses_final_real_1";
const first = lifecycle(archiverFor(), { finalIdleMs: 100 });
first.subject.start();
first.subject.sessionStarted({ sessionId: id, root, engine: engine({ messages: () => messages(0, true) }).reader });
await first.subject.settled();
await writeFile(join(root, "turn.txt"), "turn 1\n");
first.subject.turnCompleted(id, messages(1));
await first.subject.settled();
// The user edits after the turn; the chat stays quiet.
await writeFile(join(root, "idle.txt"), "after the turn\n");
await sleep(200);
await first.subject.settled();
// More edits, then the app quits.
await writeFile(join(root, "quit.txt"), "before quitting\n");
await first.subject.stop();
// And edits while it is closed.
await writeFile(join(root, "closed.txt"), "while closed\n");
const second = lifecycle(archiverFor());
second.subject.start();
await second.subject.settled();
second.subject.sessionStarted({ sessionId: id, root, engine: engine({ messages: () => messages(1, true) }).reader });
await second.subject.settled();
await writeFile(join(root, "turn.txt"), "turn 2\n");
second.subject.turnCompleted(id, messages(2));
await second.subject.settled();
await second.subject.stop();
const objects = server.objects();
expect(objects.map((object) => [object.request.kind, object.request.sequence, object.request.turn])).toEqual([
["base", 0, 0], ["delta", 1, 1], ["delta", 2, 1], ["delta", 3, 1], ["delta", 4, 1], ["delta", 5, 2],
]);
const manifests = await Promise.all(objects.map(async (object) => {
const members = await openArchive(object.object!);
return { manifest: manifestOf(members), names: members.slice(1).map((member) => member.name) };
}));
expect(manifests.slice(1).map(({ manifest }) => [manifest.trigger, manifest.reason])).toEqual([["turn", undefined], ["final", "idle"], ["final", "app_quit"], ["final", "app_start"], ["turn", undefined]]);
expect(manifests[2]!.names).toContain("idle.txt");
expect(manifests[3]!.names).toContain("quit.txt");
expect(manifests[4]!.names).toContain("closed.txt");
expect(manifests[5]!.names).toContain("turn.txt");
expect([...first.logs, ...second.logs].filter((log) => log.level === "warn")).toEqual([]);
});
});