A local-first multi-agent app development platform, built on PenguinHarness
/**
* stream-controller.ts unit tests: buffer/replay phase machine, task_state as the
* authoritative state while streaming (history-closing decision), the generation guard
* against rebuild re-entrancy during replay, resync rebuild (clears the pending table +
* keeps localDecisions), approval re-delivery keyed by origin composite key + missing
* card backfill, the local answer time an optimistic resolveApproval stamps, and history
* load failure/retry.
*
* Windowed history: a conversation opens on its newest 20 Q&A pairs and each scroll to the top
* asks for 20 more; a page the server cut short at its byte budget still offers the history
* before it; a user image the page carries by reference and the stream's inline copy of it
* draw one picture.
*
* Memory updates when session_meta falls before the window:
* - Given a completed tail, loading it shows one update per topic, excluding the index.
* - Given a running tail, edits received live show the same updates when the Task finishes.
* - Given an older page, loading it adds that page's updates without mixing them into the tail.
* - Given a reconnect, rebuilding the tail preserves its updates without duplicating them.
*/
import { describe, expect, it } from "vitest";
import {
approvalDecision,
assistantText,
compactionBegin,
compactionEnd,
imageUrlMessage,
partialText,
partialToolCallOutput,
sessionMeta,
tokenUsage,
toolCall,
toolCallOutput,
userText,
withOrigin,
} from "@adelie/core/omnimessage";
import type { OmniMessage, TokenCounts } from "@adelie/core/omnimessage";
import type {
MessagesLiveTail,
MessagesPageInfo,
PendingFollowUpInfo,
PendingSteeringInfo,
ServerEvent,
SessionStatus,
} from "@adelie/server/api";
import { OLDER_UNITS, TAIL_UNITS, createStreamController } from "../src/lib/omni/stream-controller";
import type { MessagesPageQuery, StreamController } from "../src/lib/omni/stream-controller";
import { approvalKey, findToolCard } from "../src/lib/omni/stream-model";
import type {
AssistantTextItem,
ChatItem,
TaskStatsItem,
ToolCallItem,
UserImageItem,
} from "../src/lib/omni/stream-model";
/** Override a message timestamp (constructor defaults to the current time). */
function at<M extends OmniMessage>(msg: M, ts: string): M {
return { ...msg, timestamp: ts };
}
function counts(total: number): TokenCounts {
return { cache_read: 0, cache_write: 0, output: 0, total };
}
/** Flush microtasks/macrotasks: let async loads started inside rebuild finish. */
const flush = () => new Promise<void>((resolve) => setTimeout(resolve, 0));
interface Harness {
controller: StreamController;
states: SessionStatus[];
pendingSteering: PendingSteeringInfo[][];
returnedSteering: PendingSteeringInfo[][];
pendingFollowUps: PendingFollowUpInfo[][];
errors: Array<string | null>;
loadings: boolean[];
loadCalls: () => number;
/** The `page` argument of each loadMessages call, in order (undefined = the legacy full read). */
pageArgs: Array<MessagesPageQuery | undefined>;
resolveLoad: (
messages: OmniMessage[],
live?: MessagesLiveTail,
serverNowMs?: number | null,
page?: MessagesPageInfo,
) => void;
rejectLoad: (err: Error) => void;
}
function createHarness(): Harness {
const pendingLoads: Array<{
resolve: (m: {
messages: OmniMessage[];
live?: MessagesLiveTail;
serverNowMs?: number | null;
page?: MessagesPageInfo;
}) => void;
reject: (e: unknown) => void;
}> = [];
const states: SessionStatus[] = [];
const pendingSteering: PendingSteeringInfo[][] = [];
const returnedSteering: PendingSteeringInfo[][] = [];
const pendingFollowUps: PendingFollowUpInfo[][] = [];
const errors: Array<string | null> = [];
const loadings: boolean[] = [];
const pageArgs: Array<MessagesPageQuery | undefined> = [];
let calls = 0;
const controller = createStreamController({
sessionId: "s1",
loadMessages: (page) =>
new Promise<{
messages: OmniMessage[];
live?: MessagesLiveTail;
serverNowMs?: number | null;
page?: MessagesPageInfo;
}>((resolve, reject) => {
calls += 1;
pageArgs.push(page);
pendingLoads.push({ resolve, reject });
}),
onTaskState: (s) => states.push(s),
onPendingSteering: (items) => pendingSteering.push(items),
onReturnedSteering: (items) => returnedSteering.push(items),
onPendingFollowUps: (items) => pendingFollowUps.push(items),
onLoading: (l) => loadings.push(l),
onError: (e) => errors.push(e),
onModelChange: () => {},
onPendingChange: () => {},
now: () => 1_000_000,
});
return {
controller,
states,
pendingSteering,
returnedSteering,
pendingFollowUps,
errors,
loadings,
loadCalls: () => calls,
pageArgs,
resolveLoad: (messages, live, serverNowMs, page) =>
pendingLoads.shift()!.resolve({
messages,
...(live !== undefined ? { live } : {}),
...(serverNowMs !== undefined ? { serverNowMs } : {}),
...(page !== undefined ? { page } : {}),
}),
rejectLoad: (err) => pendingLoads.shift()!.reject(err),
};
}
/** Shorthand for a page envelope (zeroed priors unless overridden). */
function pageInfo(over: Partial<MessagesPageInfo> = {}): MessagesPageInfo {
return {
earlierTurns: 0,
prior: {
subagentTokens: 0,
elapsedMs: 0,
apiMs: 0,
toolMs: 0,
sessionTokens: 0,
contextTokens: 0,
},
...over,
};
}
const HISTORY_TASK: OmniMessage[] = [
at(userText("question"), "2026-07-05T00:00:00.000Z"),
at(assistantText("answer"), "2026-07-05T00:00:03.000Z"),
at(tokenUsage(counts(1000), counts(1000)), "2026-07-05T00:00:05.000Z"),
];
describe("the running Task's live anchor is back-dated from the server's clock at read time", () => {
it("counts an event still in flight, which the Trace's own span cannot see", async () => {
const h = createHarness();
const p = h.controller.load();
// Still running, so the Task stays open. Its last Trace entry is 5s in, but the server's
// clock says 300s have passed — a tool has been executing throughout, appending nothing.
h.controller.handleServer({ type: "task_state", state: "running" });
h.resolveLoad(HISTORY_TASK, undefined, Date.parse("2026-07-05T00:05:00.000Z"));
await p;
expect(h.controller.model.taskOpen).toBe(true);
// The harness's local clock is 1_000_000, nothing like the server's: the anchor is
// back-dated by the full 300s the server reports, not by the 5s the Trace shows.
expect(1_000_000 - h.controller.model.taskStartLocalMs).toBe(300_000);
});
it("falls back to the Trace's span when no Date header came back", async () => {
const h = createHarness();
const p = h.controller.load();
h.controller.handleServer({ type: "task_state", state: "running" });
h.resolveLoad(HISTORY_TASK, undefined, null);
await p;
expect(1_000_000 - h.controller.model.taskStartLocalMs).toBe(5_000);
});
});
describe("in-stream task_state is the authoritative running state (history-closing decision)", () => {
it("subscription snapshot idle: history closes, producing the last Task's stats row", async () => {
const h = createHarness();
const p = h.controller.load();
// Connection comes first: the snapshot arrives before history, so it's buffered.
h.controller.handleServer({ type: "task_state", state: "idle" });
h.resolveLoad(HISTORY_TASK);
await p;
expect(h.states).toContain("idle");
expect(h.controller.model.items.map((i) => i.kind)).toEqual([
"user_text",
"assistant_text",
"task_stats",
]);
});
it("subscription snapshot running: no early close; only the later idle event closes", async () => {
const h = createHarness();
const p = h.controller.load();
h.controller.handleServer({ type: "task_state", state: "running" });
h.resolveLoad(HISTORY_TASK);
await p;
expect(h.controller.model.items.some((i) => i.kind === "task_stats")).toBe(false);
// The real flip event arrives (live phase) → closes out.
h.controller.handleServer({ type: "task_state", state: "idle" });
expect(h.controller.model.items.some((i) => i.kind === "task_stats")).toBe(true);
});
it("no close on the list snapshot while the stream snapshot is missing; a late idle snapshot completes the same close", async () => {
const h = createHarness();
const p = h.controller.load();
h.resolveLoad(HISTORY_TASK);
await p;
// No in-stream state at all → doesn't close out (list snapshot isn't trusted).
expect(h.controller.model.items.some((i) => i.kind === "task_stats")).toBe(false);
h.controller.handleServer({ type: "task_state", state: "idle" });
expect(h.controller.model.items.some((i) => i.kind === "task_stats")).toBe(true);
});
it("task_state during buffering reports to the input area immediately (without waiting for history replay)", async () => {
const h = createHarness();
void h.controller.load();
h.controller.handleServer({ type: "task_state", state: "running" });
// History hasn't returned yet, but state is already reported.
expect(h.states).toEqual(["running"]);
});
it("reports the pending-steering mirror from task_state, and its absence as empty", async () => {
const h = createHarness();
void h.controller.load();
h.controller.handleServer({
type: "task_state",
state: "running",
pendingSteering: [{ id: "st-1", text: "hold on", images: 0, videos: 1, files: 1 }],
});
// A later event without the field means "none left" — reported as empty, not skipped.
h.controller.handleServer({ type: "task_state", state: "running" });
expect(h.pendingSteering).toEqual([
[{ id: "st-1", text: "hold on", images: 0, videos: 1, files: 1 }],
[],
]);
});
it("reports steering the run handed back, so the composer can take it into its draft", async () => {
const h = createHarness();
void h.controller.load();
// The interrupt case: the run went idle and reported the message it never delivered.
h.controller.handleServer({
type: "task_state",
state: "idle",
returnedSteering: [{ id: "st-1", text: "wait", images: 0, videos: 0, files: 1 }],
});
// Once the composer has taken it, the next event omits the field — reported as empty.
h.controller.handleServer({ type: "task_state", state: "idle" });
expect(h.returnedSteering).toEqual([
[{ id: "st-1", text: "wait", images: 0, videos: 0, files: 1 }],
[],
]);
});
it("reports the queued follow-up list from task_state, and its absence as empty", async () => {
const h = createHarness();
void h.controller.load();
h.controller.handleServer({
type: "task_state",
state: "running",
queued: 1,
pendingFollowUps: [{ id: "fu-1", text: "next up", images: 1, videos: 0, files: 0 }],
});
h.controller.handleServer({ type: "task_state", state: "running" });
expect(h.pendingFollowUps).toEqual([
[{ id: "fu-1", text: "next up", images: 1, videos: 0, files: 0 }],
[],
]);
});
it("closes the current Task before an auto-started queued follow-up begins", async () => {
const h = createHarness();
const p = h.controller.load();
h.controller.handleServer({ type: "task_state", state: "running", queued: 1 });
h.resolveLoad(HISTORY_TASK);
await p;
// Server ordering for a queued follow-up: current run flips idle, then launchTask publishes
// the queued user input before its running state. The first idle must seal Task 1 before that.
h.controller.handleServer({ type: "task_state", state: "idle", queued: 1 });
h.controller.handleOmni(at(userText("follow-up"), "2026-07-05T00:01:00.000Z"));
h.controller.handleServer({ type: "task_state", state: "running", queued: 0 });
h.controller.handleOmni(at(assistantText("follow-up answer"), "2026-07-05T00:01:03.000Z"));
h.controller.handleOmni(at(tokenUsage(counts(1400), counts(400)), "2026-07-05T00:01:05.000Z"));
h.controller.handleServer({ type: "task_state", state: "idle", queued: 0 });
const stats = h.controller.model.items.filter(
(item) => item.kind === "task_stats",
) as TaskStatsItem[];
expect(stats.map((item) => item.assistantText)).toEqual(["answer", "follow-up answer"]);
});
});
describe("approval re-delivery (origin composite key + missing-card backfill)", () => {
it("child-session approval re-delivery: builds the nested card from toolCall when none is found; repeated re-delivery builds no duplicate", async () => {
const h = createHarness();
const p = h.controller.load();
h.resolveLoad([]);
await p;
const tc = withOrigin(
toolCall({ name: "exec_command", arguments: '{"cmd":"rm -rf x"}', toolCallId: "t1" }),
"c1",
);
const ev: ServerEvent = { type: "approval_request", toolCall: tc, origin: ["c1"] };
h.controller.handleServer(ev);
// The pending table is keyed by origin composite key.
expect(h.controller.pendingApprovals.has(approvalKey(["c1"], "t1"))).toBe(true);
expect(h.controller.pendingApprovals.has(approvalKey(undefined, "t1"))).toBe(false);
// The nested card is backfilled (child-session messages aren't in the parent Trace;
// without this mechanism, the approval button has nowhere to render).
const card = findToolCard(h.controller.model, ["c1"], "t1");
expect(card).not.toBeNull();
expect((card as ToolCallItem).name).toBe("exec_command");
// Repeated re-delivery (reconnect) doesn't create a duplicate card.
h.controller.handleServer(ev);
const sub = h.controller.model.subagents.get("c1")!;
expect(sub.items.filter((i) => i.kind === "tool_call")).toHaveLength(1);
});
it("main-session approval re-delivery: no duplicate card when history already has one", async () => {
const h = createHarness();
const p = h.controller.load();
const tc = toolCall({ name: "write_file", arguments: "{}", toolCallId: "t2" });
h.resolveLoad([at(tc, "2026-07-05T00:00:00.000Z")]);
await p;
h.controller.handleServer({ type: "approval_request", toolCall: tc });
expect(h.controller.model.items.filter((i) => i.kind === "tool_call")).toHaveLength(1);
expect(h.controller.pendingApprovals.has(approvalKey(undefined, "t2"))).toBe(true);
});
it("approval_decision events remove the matching pending entry by origin composite key", async () => {
const h = createHarness();
const p = h.controller.load();
h.resolveLoad([]);
await p;
const tc = withOrigin(toolCall({ name: "x", arguments: "{}", toolCallId: "t1" }), "c1");
h.controller.handleServer({ type: "approval_request", toolCall: tc, origin: ["c1"] });
expect(h.controller.pendingApprovals.size).toBe(1);
h.controller.handleOmni(withOrigin(approvalDecision("allow", "t1"), "c1"));
expect(h.controller.pendingApprovals.size).toBe(0);
});
it("an optimistic resolveApproval stamps this end's answer time, and the later approval_decision fills approvalAtMs without moving it", async () => {
const h = createHarness();
const p = h.controller.load();
const tc = toolCall({
name: "exec_command",
arguments: '{"cmd":"pnpm dev"}',
toolCallId: "t1",
});
h.resolveLoad([at(tc, "2026-07-05T00:00:00.000Z")]);
await p;
h.controller.handleServer({ type: "approval_request", toolCall: tc });
h.controller.resolveApproval(approvalKey(undefined, "t1"));
const card = findToolCard(h.controller.model, undefined, "t1") as ToolCallItem;
// The injected clock: clicking removes the pending entry a broadcast before the decision
// event, and the card carries the moment this end answered for that whole window.
expect(card.localApprovalAtMs).toBe(1_000_000);
expect(card.approvalAtMs).toBeUndefined();
// The event arrives afterwards. approvalAtMs takes the server timestamp — noteApprovalWait
// subtracts another server time from it, so it must never be handed a local clock — while
// the local stamp stays put, which is what keeps an elapsed-time gate reading it
// local-first from seeing its start time move and restarting.
h.controller.handleOmni(at(approvalDecision("allow", "t1"), "2026-07-05T00:00:05.000Z"));
expect(card.approvalAtMs).toBe(Date.parse("2026-07-05T00:00:05.000Z"));
expect(card.localApprovalAtMs).toBe(1_000_000);
});
});
describe("resync rebuild", () => {
it("rebuild clears the pending-approval table; still-pending requests the server re-delivers afterwards rebuild naturally (#28)", async () => {
const h = createHarness();
const p = h.controller.load();
h.resolveLoad([]);
await p;
const tc = toolCall({ name: "x", arguments: "{}", toolCallId: "t1" });
h.controller.handleServer({ type: "approval_request", toolCall: tc });
expect(h.controller.pendingApprovals.size).toBe(1);
h.controller.handleServer({ type: "resync_required" });
// Approvals already decided during the disconnect leave no residual button.
expect(h.controller.pendingApprovals.size).toBe(0);
// The server re-delivers the still-pending request on the same connection
// (buffered during rebuild, rebuilt after replay).
h.controller.handleServer({ type: "approval_request", toolCall: tc });
h.resolveLoad([at(tc, "2026-07-05T00:00:00.000Z")]);
await flush();
expect(h.controller.pendingApprovals.size).toBe(1);
});
it("rebuild keeps localDecisions: approvals clicked locally still show as manual after replay (#22)", async () => {
const h = createHarness();
const p = h.controller.load();
const tc = at(
toolCall({ name: "x", arguments: "{}", toolCallId: "t1" }),
"2026-07-05T00:00:00.000Z",
);
h.resolveLoad([tc]);
await p;
h.controller.markLocalDecision("t1");
h.controller.handleServer({ type: "resync_required" });
h.resolveLoad([tc, at(approvalDecision("allow", "t1"), "2026-07-05T00:00:01.000Z")]);
await flush();
const card = h.controller.model.items.find((i) => i.kind === "tool_call") as ToolCallItem;
expect(card.decision).toBe("allow");
expect(card.decisionSource).toBe("manual");
});
it("resync during replay: the current round is voided and the remaining buffer moves to the new round, with no reordering or duplication (#21/#26)", async () => {
const h = createHarness();
const p = h.controller.load();
// Buffer: old event A → resync_required → task_state:idle (server re-delivery order).
h.controller.handleOmni(at(assistantText("old event A"), "2026-07-05T00:00:01.000Z"));
h.controller.handleServer({ type: "resync_required" });
h.controller.handleServer({ type: "task_state", state: "idle" });
// First round of history returns: replaying up to resync_required invalidates this round.
h.resolveLoad([at(userText("question"), "2026-07-05T00:00:00.000Z")]);
await p;
expect(h.loadCalls()).toBe(2);
// The old replay must not reset phase back to live: events arriving during rebuild are still
// buffered, not fed to a model. And with the atomic swap the OLD transcript stays visible until
// the rebuild's history load returns — mid-rebuild the model still shows the pre-resync content
// (the question + "old event A"), never a blank, and the live event is not yet in it (feeding it
// here as a third item would fail this assertion).
const live = at(assistantText("output during rebuild"), "2026-07-05T00:00:02.000Z");
h.controller.handleOmni(live);
expect(h.controller.model.items.map((i) => i.kind)).toEqual(["user_text", "assistant_text"]);
// Second round of history (authoritative) returns: the transferred task_state and
// buffered events replay in order.
h.resolveLoad([
at(userText("question"), "2026-07-05T00:00:00.000Z"),
at(tokenUsage(counts(500), counts(500)), "2026-07-05T00:00:01.500Z"),
]);
await flush();
expect(h.controller.model.items.map((i) => i.kind)).toEqual([
"user_text",
"task_stats",
"assistant_text",
]);
expect(h.controller.model.items.filter((i) => i.kind === "user_text")).toHaveLength(1);
});
});
describe("live-tail seeding (reload mid-stream)", () => {
it("drops buffered partials at/before the cursor and seeds fragments; later partials continue on top", async () => {
const h = createHarness();
const p = h.controller.load();
h.controller.handleServer({ type: "task_state", state: "running" }, "e1-3");
// Already covered by the fragment snapshot (seq <= cursor): must be dropped, or the
// seeded prefix would double.
h.controller.handleOmni(partialText("start", "Hel"), "e1-4");
h.controller.handleOmni(partialText("delta", "lo"), "e1-5");
// After the cursor: continues the seeded fragment.
h.controller.handleOmni(partialText("delta", " world"), "e1-6");
h.resolveLoad([at(userText("question"), "2026-07-05T00:00:00.000Z")], {
cursor: "e1-5",
fragments: [at(partialText("start", "Hello"), "2026-07-05T00:00:01.000Z")],
});
await p;
const texts = h.controller.model.items.filter((i) => i.kind === "assistant_text");
expect(texts).toHaveLength(1);
expect((texts[0] as AssistantTextItem).text).toBe("Hello world");
expect((texts[0] as AssistantTextItem).streaming).toBe(true);
});
it("tool-output fragment seeds onto the history-built card and keeps streaming", async () => {
const h = createHarness();
const p = h.controller.load();
h.controller.handleServer({ type: "task_state", state: "running" }, "e1-7");
h.controller.handleOmni(
partialToolCallOutput({ eventType: "delta", output: "line 2\n", toolCallId: "t1" }),
"e1-9",
);
h.resolveLoad(
[
at(userText("run it"), "2026-07-05T00:00:00.000Z"),
at(
toolCall({ name: "exec_command", arguments: '{"cmd":"x"}', toolCallId: "t1" }),
"2026-07-05T00:00:01.000Z",
),
],
{
cursor: "e1-8",
fragments: [
at(
partialToolCallOutput({ eventType: "start", output: "line 1\n", toolCallId: "t1" }),
"2026-07-05T00:00:02.000Z",
),
],
},
);
await p;
const cards = h.controller.model.items.filter((i) => i.kind === "tool_call");
expect(cards).toHaveLength(1);
const card = cards[0] as ToolCallItem;
expect(card.output).toBe("line 1\nline 2\n");
expect(card.outputStreaming).toBe(true);
expect(card.outputComplete).toBe(false);
});
it("epoch mismatch: neither drops nor seeds (buffered partials replay as-is)", async () => {
const h = createHarness();
const p = h.controller.load();
h.controller.handleOmni(partialText("start", "He"), "old-4");
h.controller.handleOmni(partialText("delta", "llo"), "old-5");
h.resolveLoad([], {
cursor: "new-9",
fragments: [partialText("start", "Hello")],
});
await p;
// The buffered start+delta applied normally; the fragment was NOT seeded (a seed on
// top of the applied start would produce a second item).
const texts = h.controller.model.items.filter((i) => i.kind === "assistant_text");
expect(texts).toHaveLength(1);
expect((texts[0] as AssistantTextItem).text).toBe("Hello");
});
it("complete messages at/before the cursor are never cursor-dropped: overlap dedup decides", async () => {
const h = createHarness();
const p = h.controller.load();
const inHistory = at(assistantText("done"), "2026-07-05T00:00:01.000Z");
// Trace append still in flight at read time: the buffered copy is the only copy.
const diskLagged = at(assistantText("lagged"), "2026-07-05T00:00:02.000Z");
h.controller.handleOmni(inHistory, "e1-4");
h.controller.handleOmni(diskLagged, "e1-5");
h.resolveLoad([at(userText("q"), "2026-07-05T00:00:00.000Z"), inHistory], {
cursor: "e1-6",
fragments: [],
});
await p;
const texts = h.controller.model.items.filter((i) => i.kind === "assistant_text");
expect(texts.map((i) => (i as AssistantTextItem).text)).toEqual(["done", "lagged"]);
});
it("subagent fragments preserve origin and land on the nested model", async () => {
const h = createHarness();
const p = h.controller.load();
h.controller.handleServer({ type: "task_state", state: "running" }, "e1-2");
h.resolveLoad([], {
cursor: "e1-2",
fragments: [withOrigin(partialText("start", "sub progress"), "c1")],
});
await p;
const sub = h.controller.model.subagents.get("c1");
expect(sub).toBeDefined();
const texts = sub!.items.filter((i) => i.kind === "assistant_text");
expect(texts).toHaveLength(1);
expect((texts[0] as AssistantTextItem).text).toBe("sub progress");
expect((texts[0] as AssistantTextItem).streaming).toBe(true);
});
});
describe("windowed history: tail-first load + scroll-up backfill", () => {
const OLD_TURN: OmniMessage[] = [
at(userText("old question"), "2026-07-04T00:00:00.000Z"),
at(assistantText("old answer"), "2026-07-04T00:00:02.000Z"),
at(tokenUsage(counts(400), counts(400)), "2026-07-04T00:00:04.000Z"),
];
it("a conversation opens on its newest 20 Q&A pairs, and each scroll to the top asks for 20 more", async () => {
const h = createHarness();
const p = h.controller.load();
h.controller.handleServer({ type: "task_state", state: "idle" });
h.resolveLoad(HISTORY_TASK, undefined, null, pageInfo({ before: "2:10", earlierTurns: 40 }));
await p;
const first = h.controller.loadOlder();
h.resolveLoad(OLD_TURN, undefined, null, pageInfo({ before: "1:30", earlierTurns: 20 }));
await first;
const second = h.controller.loadOlder();
h.resolveLoad(OLD_TURN, undefined, null, pageInfo({ earlierTurns: 0 }));
await second;
// The Q&A-pair counts the server is asked for: what the person sees first and per scroll.
expect(h.pageArgs).toEqual([
{ kind: "tail", limit: 20 },
{ kind: "before", cursor: "2:10", limit: 20 },
{ kind: "before", cursor: "1:30", limit: 20 },
]);
expect(h.controller.older.hasMore).toBe(false);
});
it("a page the server cut short of its limit still offers the history before it, on both ends", async () => {
const h = createHarness();
const p = h.controller.load();
h.controller.handleServer({ type: "task_state", state: "idle" });
// One unit where twenty were asked for: the byte budget cut the tail, and its cursor says so.
h.resolveLoad(HISTORY_TASK, undefined, null, pageInfo({ before: "2:40", earlierTurns: 30 }));
await p;
expect(h.controller.older).toEqual({ hasMore: true, loading: false, error: null });
// A backfill cut short the same way keeps the way back open at its own cursor.
const first = h.controller.loadOlder();
h.resolveLoad(OLD_TURN, undefined, null, pageInfo({ before: "2:12", earlierTurns: 29 }));
await first;
expect(h.controller.older.hasMore).toBe(true);
expect(h.controller.outlineOffset).toBe(29);
const second = h.controller.loadOlder();
expect(h.pageArgs[2]).toEqual({ kind: "before", cursor: "2:12", limit: OLDER_UNITS });
h.resolveLoad(OLD_TURN, undefined, null, pageInfo({ earlierTurns: 0 }));
await second;
expect(h.controller.older.hasMore).toBe(false);
});
it("a user image the page carries by reference and the stream's inline copy of it draw one picture", async () => {
const h = createHarness();
const p = h.controller.load();
const bytes = "data:image/png;base64,iVBORw0KGgo=";
const ref = "/api/sessions/s1/trace-image?file=2&ordinal=8";
const prompt = at(userText("what is this?"), "2026-07-05T00:00:00.000Z");
const sent = at(imageUrlMessage(bytes), "2026-07-05T00:00:00.000Z");
// The stream delivered the image while the page was being read: the buffered copy has its bytes.
h.controller.handleOmni(prompt, "e1-1");
h.controller.handleOmni(sent, "e1-2");
h.controller.handleServer({ type: "task_state", state: "idle" });
// The page's copies: positioned Trace records, the image's bytes replaced by its route URL.
const pagePrompt = { ...prompt, tracePosition: { fileIndex: 2, ordinal: 7 } };
const pageImage = {
...sent,
payload: { ...sent.payload, image_url: ref },
tracePosition: { fileIndex: 2, ordinal: 8 },
};
h.resolveLoad([pagePrompt, pageImage, ...HISTORY_TASK.slice(1)], undefined, null, pageInfo());
await p;
const images = h.controller.model.items.filter((i) => i.kind === "user_image");
expect(images.map((i) => (i as UserImageItem).imageUrl)).toEqual([ref]);
expect(h.controller.model.items.filter((i) => i.kind === "user_text")).toHaveLength(1);
});
it("initial load requests the TAIL window and seeds the prior stats into the tracker", async () => {
const h = createHarness();
const p = h.controller.load();
expect(h.pageArgs[0]).toEqual({ kind: "tail", limit: TAIL_UNITS });
h.controller.handleServer({ type: "task_state", state: "idle" });
h.resolveLoad(
HISTORY_TASK,
undefined,
null,
pageInfo({
before: "2:10",
earlierTurns: 7,
prior: {
subagentTokens: 500,
elapsedMs: 60_000,
apiMs: 25_000,
toolMs: 20_000,
sessionTokens: 900,
contextTokens: 800,
},
}),
);
await p;
expect(h.controller.outlineOffset).toBe(7);
expect(h.controller.older).toEqual({ hasMore: true, loading: false, error: null });
// Header basis: prior elapsed + the loaded turn's own span (usage at +5s of a turn
// starting at 0s); token cumulative = in-window session.total + prior subagent total.
expect(h.controller.model.stats.sessionElapsedMs).toBe(60_000 + 5_000);
// The breakdown reloads with its total, so a windowed load never shows a full elapsed time
// beside components covering only the window.
expect(h.controller.model.stats.sessionLlmMs).toBe(25_000);
expect(h.controller.model.stats.sessionToolMs).toBe(20_000);
const stats = h.controller.model.items.find((i) => i.kind === "task_stats") as TaskStatsItem;
expect(stats.stats!.tokens).toBe(1000 + 500);
});
it("loadOlder prepends the previous window: frozen items ahead of the live model, unique ids, closed stats row", async () => {
const h = createHarness();
const p = h.controller.load();
h.controller.handleServer({ type: "task_state", state: "idle" });
h.resolveLoad(HISTORY_TASK, undefined, null, pageInfo({ before: "1:8", earlierTurns: 1 }));
await p;
const older = h.controller.loadOlder();
expect(h.pageArgs[1]).toEqual({ kind: "before", cursor: "1:8", limit: OLDER_UNITS });
// Reaches the beginning: no cursor, offset drops to 0.
h.resolveLoad(OLD_TURN, undefined, null, pageInfo({ earlierTurns: 0 }));
await older;
// The prepended window renders BEFORE the live model, with its last Task closed
// (finalizeHistory — a newer window follows, so the Task is complete by construction).
expect(h.controller.prefixItems.map((i) => i.kind)).toEqual([
"user_text",
"assistant_text",
"task_stats",
]);
expect(h.controller.older).toEqual({ hasMore: false, loading: false, error: null });
expect(h.controller.outlineOffset).toBe(0);
// Ids stay unique across the concatenated view (negative prefix base vs. positive live ids).
const ids = [...h.controller.prefixItems, ...h.controller.model.items].map((i) => i.id);
expect(new Set(ids).size).toBe(ids.length);
expect(h.controller.prefixItems.every((i) => i.id < 0)).toBe(true);
// Its cumulative stats column carries on into the live window's figures.
const oldStats = h.controller.prefixItems.find((i) => i.kind === "task_stats") as TaskStatsItem;
expect(oldStats.stats!.tokens).toBe(400);
});
it("a window is seeded with the model of the context it starts in: its first Tasks name it and a switch further down is marked, in the tail and in a backfilled window alike", async () => {
const metaOn = (provider: string, modelId: string): OmniMessage =>
sessionMeta({
session_id: "s1",
provider,
model_id: modelId,
model_context_window: 1000,
system_prompt: "",
agent_state: "/tmp/a",
workspace: "/tmp/w",
source: "user",
});
const A = { provider: "anthropic", modelId: "a-1" };
const B = { provider: "openai", modelId: "b-2" };
const h = createHarness();
const p = h.controller.load();
h.controller.handleServer({ type: "task_state", state: "idle" });
// The tail starts partway into a context on a-1 — no meta of it in the window — and crosses
// a switch: an ordinary manual compaction, then the next context's meta on b-2.
h.resolveLoad(
[
...HISTORY_TASK,
at(
compactionBegin({ reason: "manual", mode: "summarize", context: 1000, turns: 1 }),
"2026-07-05T00:01:00.000Z",
),
at(
compactionEnd({ reason: "manual", mode: "summarize", status: "completed" }),
"2026-07-05T00:01:05.000Z",
),
at(metaOn(B.provider, B.modelId), "2026-07-05T00:01:06.000Z"),
at(userText("next question"), "2026-07-05T00:02:00.000Z"),
at(assistantText("next answer"), "2026-07-05T00:02:03.000Z"),
at(tokenUsage(counts(300), counts(300)), "2026-07-05T00:02:05.000Z"),
],
undefined,
null,
pageInfo({ before: "1:8", earlierTurns: 1, contextModel: A }),
);
await p;
const items = h.controller.model.items;
const stats = items.filter((i) => i.kind === "task_stats") as TaskStatsItem[];
expect(stats.map((s) => s.model)).toEqual([A, B]);
expect(items.filter((i) => i.kind === "model_change")).toMatchObject([{ from: A, to: B }]);
// The running context is the one the window ends in, under the Session the stream is of.
expect(h.controller.model.contextModel).toEqual({ sessionId: "s1", ...B });
// The window before starts in an earlier context of its own.
const C = { provider: "zhipu", modelId: "c-0" };
const older = h.controller.loadOlder();
h.resolveLoad(OLD_TURN, undefined, null, pageInfo({ earlierTurns: 0, contextModel: C }));
await older;
const oldStats = h.controller.prefixItems.find((i) => i.kind === "task_stats") as TaskStatsItem;
expect(oldStats.model).toEqual(C);
});
it("loadOlder without more history, while loading, or before the initial load is a no-op", async () => {
const h = createHarness();
const early = h.controller.loadOlder(); // buffering phase: ignored
await early;
const p = h.controller.load();
h.controller.handleServer({ type: "task_state", state: "idle" });
h.resolveLoad(HISTORY_TASK, undefined, null, pageInfo()); // no before cursor: beginning already loaded
await p;
await h.controller.loadOlder();
expect(h.loadCalls()).toBe(1);
});
it("a failed backfill surfaces on older.error and can be retried", async () => {
const h = createHarness();
const p = h.controller.load();
h.controller.handleServer({ type: "task_state", state: "idle" });
h.resolveLoad(HISTORY_TASK, undefined, null, pageInfo({ before: "1:8", earlierTurns: 1 }));
await p;
const older = h.controller.loadOlder();
h.rejectLoad(new Error("boom"));
await older;
expect(h.controller.older).toEqual({ hasMore: true, loading: false, error: "boom" });
expect(h.controller.prefixItems).toHaveLength(0);
const again = h.controller.loadOlder();
h.resolveLoad(OLD_TURN, undefined, null, pageInfo());
await again;
expect(h.controller.older.error).toBeNull();
expect(h.controller.prefixItems.length).toBeGreaterThan(0);
});
});
describe("memory updates in paginated history", () => {
const agentState = "/recorded/agents/memory-agent/agent_state";
const page = pageInfo({ before: "1:8", earlierTurns: 1, agentState });
const changes = (items: readonly ChatItem[]) =>
items.flatMap((item) => (item.kind === "task_stats" ? (item.memoryChanges ?? []) : []));
function memoryTurn(file: string, day = "05"): OmniMessage[] {
const stamp = (message: OmniMessage, second: number) =>
at(message, `2026-07-${day}T00:00:${String(second).padStart(2, "0")}.000Z`);
return [
stamp(userText("remember this"), 0),
...[file, file, "MEMORY.md"].flatMap((name, i) => [
stamp(
toolCall({
name: "edit_file",
arguments: JSON.stringify({ file_path: `${agentState}/memory/user/${name}` }),
toolCallId: `${file}-${i}`,
}),
1 + i * 2,
),
stamp(toolCallOutput({ output: "updated", toolCallId: `${file}-${i}` }), 2 + i * 2),
]),
stamp(assistantText("remembered"), 7),
];
}
it.each(["idle", "running"] as const)(
"a %s tail without session_meta shows one update for repeated topic edits",
async (state) => {
const h = createHarness();
const pending = h.controller.load();
h.controller.handleServer({ type: "task_state", state });
const messages = memoryTurn("local-dev-instance.md");
h.resolveLoad(state === "idle" ? messages : messages.slice(0, 1), undefined, null, page);
await pending;
if (state === "running") {
for (const message of messages.slice(1)) h.controller.handleOmni(message);
h.controller.handleServer({ type: "task_state", state: "idle" });
}
expect(changes(h.controller.model.items)).toMatchObject([
{ scope: "user", file: "local-dev-instance.md", op: "edit" },
]);
},
);
it("an older page restores its own memory updates without mixing them into the tail", async () => {
const h = createHarness();
const pending = h.controller.load();
h.controller.handleServer({ type: "task_state", state: "idle" });
h.resolveLoad(memoryTurn("recent.md"), undefined, null, page);
await pending;
const older = h.controller.loadOlder();
h.resolveLoad(
memoryTurn("older.md", "04"),
undefined,
null,
pageInfo({ before: "1:2", agentState }),
);
await older;
expect(changes(h.controller.prefixItems)).toMatchObject([
{ scope: "user", file: "older.md", op: "edit" },
]);
expect(changes(h.controller.model.items)).toMatchObject([
{ scope: "user", file: "recent.md", op: "edit" },
]);
});
it("reconnecting preserves the tail's memory updates without duplicating them", async () => {
const h = createHarness();
const pending = h.controller.load();
h.controller.handleServer({ type: "task_state", state: "idle" });
const messages = memoryTurn("local-dev-instance.md");
h.resolveLoad(messages, undefined, null, page);
await pending;
h.controller.handleServer({ type: "resync_required" });
h.resolveLoad(messages, undefined, null, page);
await flush();
expect(changes(h.controller.model.items)).toMatchObject([
{ scope: "user", file: "local-dev-instance.md", op: "edit" },
]);
});
});
describe("resync decision tree (windowed history)", () => {
const tailPage = pageInfo({ before: "2:10", earlierTurns: 1 });
/** Boots a controller with a tail window + one backfilled prefix window. */
async function withPrefix(): Promise<Harness> {
const h = createHarness();
const p = h.controller.load();
h.controller.handleServer({ type: "task_state", state: "idle" });
h.resolveLoad(HISTORY_TASK, undefined, null, tailPage);
await p;
const older = h.controller.loadOlder();
h.resolveLoad(
[at(userText("old question"), "2026-07-04T00:00:00.000Z")],
undefined,
null,
pageInfo(),
);
await older;
expect(h.controller.prefixItems.length).toBeGreaterThan(0);
return h;
}
it("no prefix: resync refetches the TAIL window (initial-load shape)", async () => {
const h = createHarness();
const p = h.controller.load();
h.controller.handleServer({ type: "task_state", state: "idle" });
h.resolveLoad(HISTORY_TASK, undefined, null, pageInfo({ before: "2:10", earlierTurns: 3 }));
await p;
h.controller.handleServer({ type: "resync_required" });
expect(h.pageArgs[1]).toEqual({ kind: "tail", limit: TAIL_UNITS });
h.resolveLoad(HISTORY_TASK, undefined, null, pageInfo({ before: "2:10", earlierTurns: 3 }));
await flush();
expect(h.loadCalls()).toBe(2);
expect(h.controller.outlineOffset).toBe(3);
expect(h.controller.model.items.some((i) => i.kind === "user_text")).toBe(true);
});
it("prefix + provable continuity (identical window-start cursor): splice — prefix retained, one fetch", async () => {
const h = await withPrefix();
h.controller.handleServer({ type: "resync_required" });
// The refetched tail starts at the SAME cursor the current tail started at: no new
// units since — the new window abuts the prefix exactly.
h.resolveLoad(HISTORY_TASK, undefined, null, tailPage);
await flush();
expect(h.loadCalls()).toBe(3); // initial + backfill + one resync fetch
expect(h.controller.prefixItems.length).toBeGreaterThan(0);
expect(h.controller.older.hasMore).toBe(false); // backfill already reached the beginning
expect(h.controller.model.items.some((i) => i.kind === "user_text")).toBe(true);
});
it("prefix + moved cursor (new units arrived): doubt — falls back to the FULL refetch, prefix dropped", async () => {
const h = await withPrefix();
h.controller.handleServer({ type: "resync_required" });
// The tail window slid forward: splicing would leave a gap between prefix and tail.
h.resolveLoad([], undefined, null, pageInfo({ before: "3:0", earlierTurns: 9 }));
await flush();
// The fallback full read (no page argument) is issued within the same rebuild.
expect(h.pageArgs[h.pageArgs.length - 1]).toBeUndefined();
h.resolveLoad([at(userText("old question"), "2026-07-04T00:00:00.000Z"), ...HISTORY_TASK]);
await flush();
expect(h.controller.prefixItems).toHaveLength(0);
expect(h.controller.outlineOffset).toBe(0);
expect(h.controller.older.hasMore).toBe(false);
// The full transcript lives in the single model now.
expect(h.controller.model.items.filter((i) => i.kind === "user_text")).toHaveLength(2);
});
it("prefix + tail reaching the beginning: prefix superseded without a second fetch", async () => {
const h = await withPrefix();
h.controller.handleServer({ type: "resync_required" });
h.resolveLoad(
[at(userText("old question"), "2026-07-04T00:00:00.000Z"), ...HISTORY_TASK],
undefined,
null,
pageInfo({ earlierTurns: 0 }),
);
await flush();
expect(h.loadCalls()).toBe(3);
expect(h.controller.prefixItems).toHaveLength(0);
expect(h.controller.model.items.filter((i) => i.kind === "user_text")).toHaveLength(2);
});
it("a legacy full response during resync (no page envelope) resets the windowed state", async () => {
const h = await withPrefix();
h.controller.handleServer({ type: "resync_required" });
// A server without windowing support answers the tail request with the full
// transcript and no envelope: doubt — the full-fallback branch also covers it
// (the second fetch returns the same full transcript).
h.resolveLoad([...HISTORY_TASK]);
await flush();
h.resolveLoad([at(userText("old question"), "2026-07-04T00:00:00.000Z"), ...HISTORY_TASK]);
await flush();
expect(h.controller.prefixItems).toHaveLength(0);
expect(h.controller.older.hasMore).toBe(false);
expect(h.controller.outlineOffset).toBe(0);
});
});
describe("history load failure and retry (#6)", () => {
it("failure surfaces the error and stops loading; retry keeps the buffer (snapshot and initial events are not lost)", async () => {
const h = createHarness();
const p = h.controller.load();
h.controller.handleServer({ type: "task_state", state: "idle" });
h.rejectLoad(new Error("network error"));
await p;
expect(h.errors[h.errors.length - 1]).toBe("network error");
expect(h.loadings[h.loadings.length - 1]).toBe(false);
const retryP = h.controller.retry();
h.resolveLoad(HISTORY_TASK);
await retryP;
expect(h.errors[h.errors.length - 1]).toBeNull();
// The idle snapshot in the buffer isn't lost: the history-closing stats row is produced.
expect(h.controller.model.items.some((i) => i.kind === "task_stats")).toBe(true);
});
it("retry without a failure is a no-op (history is not replayed twice)", async () => {
const h = createHarness();
const p = h.controller.load();
h.resolveLoad(HISTORY_TASK);
await p;
await h.controller.retry();
expect(h.loadCalls()).toBe(1);
});
it("retry after a FAILED resync rebuild rebuilds into a fresh model (no transcript duplication)", async () => {
// A successful initial load leaves the transcript populated; a mid-stream resync whose refetch
// then fails deliberately keeps that old transcript on screen (the atomic swap only replaces it
// on success). Retry must therefore push the refetched history into a FRESH model — pushing it
// onto the retained one would duplicate the whole conversation (regression guard).
const h = createHarness();
const p = h.controller.load();
h.resolveLoad([
at(userText("q1"), "2026-07-05T00:00:00.000Z"),
at(assistantText("a1"), "2026-07-05T00:00:01.000Z"),
]);
await p;
expect(h.controller.model.items.map((i) => i.kind)).toEqual(["user_text", "assistant_text"]);
// Resync mid-session, but the rebuild's history refetch fails.
h.controller.handleServer({ type: "resync_required" });
h.rejectLoad(new Error("network error"));
await flush();
expect(h.errors[h.errors.length - 1]).toBe("network error");
// The old transcript is retained (not blanked) while the error/Retry state is shown.
expect(h.controller.model.items.map((i) => i.kind)).toEqual(["user_text", "assistant_text"]);
// Retry succeeds: the identical history must land in a fresh model, not be appended onto the retained one.
const retryP = h.controller.retry();
h.resolveLoad([
at(userText("q1"), "2026-07-05T00:00:00.000Z"),
at(assistantText("a1"), "2026-07-05T00:00:01.000Z"),
]);
await retryP;
expect(h.controller.model.items.map((i) => i.kind)).toEqual(["user_text", "assistant_text"]);
expect(h.controller.model.items.filter((i) => i.kind === "user_text")).toHaveLength(1);
});
});
describe("refresh (the page keeping itself current while the live stream is stalled)", () => {
const PRESENT = ["user_text", "tool_call", "assistant_text"];
const TC = at(
toolCall({ name: "x", arguments: "{}", toolCallId: "t1" }),
"2026-07-05T00:00:01.000Z",
);
const TAIL: OmniMessage[] = [
at(userText("q1"), "2026-07-05T00:00:00.000Z"),
TC,
at(assistantText("a1"), "2026-07-05T00:00:02.000Z"),
];
it("refetches the tail in place, keeping a pending approval no resync would have resent", async () => {
const h = createHarness();
const p = h.controller.load();
h.resolveLoad(TAIL, undefined, undefined, pageInfo());
await p;
h.controller.handleServer({ type: "approval_request", toolCall: TC });
expect(h.controller.pendingApprovals.size).toBe(1);
const r = h.controller.refresh();
// The transcript stays exactly as it is until the refetch lands — a reader watching a
// stalled stream must not see the conversation blank out once a minute.
expect(h.controller.model.items.map((i) => i.kind)).toEqual(PRESENT);
expect(h.pageArgs.at(-1)).toEqual({ kind: "tail", limit: TAIL_UNITS });
h.resolveLoad(TAIL, undefined, undefined, pageInfo());
await r;
// The refetched history lands in a fresh model (no duplication), and the approval is still
// answerable: the table survives a refresh, which is what tells it apart from a resync rebuild.
expect(h.controller.model.items.map((i) => i.kind)).toEqual(PRESENT);
expect(h.controller.pendingApprovals.size).toBe(1);
});
it("is a no-op while a load is in flight, after a failed one, and once disposed", async () => {
const h = createHarness();
// In flight (the initial load holds the pipeline): a second fetch would race its epoch.
const p = h.controller.load();
await h.controller.refresh();
expect(h.loadCalls()).toBe(1);
h.rejectLoad(new Error("network error"));
await p;
// Failed: the page shows the error and its Retry entry point, not a silent retry loop.
await h.controller.refresh();
expect(h.loadCalls()).toBe(1);
h.controller.dispose();
await h.controller.refresh();
expect(h.loadCalls()).toBe(1);
});
});