Skip to content

A local-first multi-agent app development platform, built on PenguinHarness

perf(server,web): cursor-paginate session history with tail-first loading (#202)

Yaowei Zhengdd8ddbb69be2
diff --git a/packages/server/src/api/types.ts b/packages/server/src/api/types.ts
index 31ffed5d..852d5a2c 100644
--- a/packages/server/src/api/types.ts
+++ b/packages/server/src/api/types.ts
@@ -661,15 +661,58 @@ export interface MessagesLiveTail {
fragments: OmniMessage[];
}
+/**
+ * Pagination envelope of a windowed `GET /messages` (`tailLimit` / `before` requests
+ * only; the parameterless full read never carries it). A window is a run of whole
+ * message-bearing units — one unit = one Task in the Web reducer's sense, opened by a
+ * main-session user prompt — cut so that no pairing (tool_call/output), compaction span
+ * or steering group ever splits across windows.
+ */
+export interface MessagesPageInfo {
+ /**
+ * Cursor of this window's first unit (`<shardIndex>:<ordinal>`): pass it back as
+ * `before=` to fetch the previous window. Stable across requests and compaction —
+ * rotation opens a NEW shard and closed shards are immutable. Absent = this window
+ * reaches the very beginning of the transcript (no older history).
+ */
+ before?: string;
+ /**
+ * Outline turns (the Web conversation outline's entry rule) opened BEFORE this
+ * window: the client offsets its global `第 N 轮` numbering by this, so a partial
+ * window never mis-numbers. 0 when the window starts at the beginning.
+ */
+ earlierTurns: number;
+ /**
+ * Cumulative stats accrued before this window, seeded into the client's stats
+ * tracker so header chips and per-turn cumulative rows equal a full load:
+ * finished-Task elapsed, subagent token totals, and the last main-session
+ * session/context token readings.
+ */
+ prior: {
+ subagentTokens: number;
+ elapsedMs: number;
+ sessionTokens: number;
+ contextTokens: number;
+ };
+}
+
/** Message history: the full messages and events from concatenating all of this Session's Trace files in order (excludes partial_*). */
export interface MessagesResponse {
messages: OmniMessage[];
/**
* Present only while the Session is running/compacting: the in-progress stream tail
* (open streaming fragments + the channel cursor they cover), so a client joining
- * mid-stream can render the currently streaming message. Omitted when idle.
+ * mid-stream can render the currently streaming message. Omitted when idle. On
+ * windowed requests it rides TAIL pages only — a `before` page is immutable history
+ * and never carries it.
*/
live?: MessagesLiveTail;
+ /**
+ * Present exactly on windowed requests (`tailLimit` / `before`): `messages` is then
+ * the requested window (subagent pointers inside it expanded as usual) rather than
+ * the full transcript. See MessagesPageInfo.
+ */
+ page?: MessagesPageInfo;
}
// ---------------------------------------------------------------------------
diff --git a/packages/server/src/db/database.ts b/packages/server/src/db/database.ts
index fc83ca34..07341102 100644
--- a/packages/server/src/db/database.ts
+++ b/packages/server/src/db/database.ts
@@ -30,6 +30,7 @@ export function openDatabase(dbPath: string): DatabaseSync {
ensureColumn(db, "sessions", "client", "TEXT");
ensureColumn(db, "sessions", "has_trace", "INTEGER NOT NULL DEFAULT 0");
ensureColumn(db, "auth_sessions", "via", "TEXT");
+ ensureColumn(db, "trace_files", "page_stats", "TEXT");
return db;
}
diff --git a/packages/server/src/db/repos/trace-index.ts b/packages/server/src/db/repos/trace-index.ts
index 76db3b13..cd269449 100644
--- a/packages/server/src/db/repos/trace-index.ts
+++ b/packages/server/src/db/repos/trace-index.ts
@@ -62,17 +62,22 @@ export class TraceIndexRepo {
constructor(private readonly db: DatabaseSync) {}
upsertFile(row: TraceFileRow): void {
+ // page_stats is a derivation of the shard's CONTENT: any observed size change voids
+ // it (an unchanged size keeps the cached scan — reconcile passes re-upsert rows).
this.db
.prepare(
`INSERT INTO trace_files (project_id, agent_id, session_id, file_index, date, size_bytes)
VALUES (?, ?, ?, ?, ?, ?)
ON CONFLICT(project_id, agent_id, session_id, file_index)
- DO UPDATE SET date = excluded.date, size_bytes = excluded.size_bytes`,
+ DO UPDATE SET date = excluded.date,
+ page_stats = CASE WHEN excluded.size_bytes = trace_files.size_bytes
+ THEN trace_files.page_stats ELSE NULL END,
+ size_bytes = excluded.size_bytes`,
)
.run(row.projectId, row.agentId, row.sessionId, row.fileIndex, row.date, row.sizeBytes);
}
- /** Refreshes one shard's last-observed size (listings write back their page stats). */
+ /** Refreshes one shard's last-observed size (listings write back their page stats); a changed size voids the cached window scan. */
updateFileSize(
projectId: string,
agentId: string,
@@ -82,10 +87,45 @@ export class TraceIndexRepo {
): void {
this.db
.prepare(
- `UPDATE trace_files SET size_bytes = ?
+ `UPDATE trace_files SET
+ page_stats = CASE WHEN size_bytes = ? THEN page_stats ELSE NULL END,
+ size_bytes = ?
WHERE project_id = ? AND agent_id = ? AND session_id = ? AND file_index = ?`,
)
- .run(sizeBytes, projectId, agentId, sessionId, fileIndex);
+ .run(sizeBytes, sizeBytes, projectId, agentId, sessionId, fileIndex);
+ }
+
+ /** Cached message-window prefix record of one shard (see services/message-window.ts); null = none. */
+ getPageStats(
+ projectId: string,
+ agentId: string,
+ sessionId: string,
+ fileIndex: number,
+ ): string | null {
+ const r = this.db
+ .prepare(
+ `SELECT page_stats FROM trace_files
+ WHERE project_id = ? AND agent_id = ? AND session_id = ? AND file_index = ?`,
+ )
+ .get(projectId, agentId, sessionId, fileIndex);
+ return r ? ((r.page_stats as string | null) ?? null) : null;
+ }
+
+ /** Stores a shard's message-window prefix record, guarded on the size it was computed for (a concurrent append voids the write). */
+ setPageStats(
+ projectId: string,
+ agentId: string,
+ sessionId: string,
+ fileIndex: number,
+ sizeBytes: number,
+ pageStats: string,
+ ): void {
+ this.db
+ .prepare(
+ `UPDATE trace_files SET page_stats = ?
+ WHERE project_id = ? AND agent_id = ? AND session_id = ? AND file_index = ? AND size_bytes = ?`,
+ )
+ .run(pageStats, projectId, agentId, sessionId, fileIndex, sizeBytes);
}
deleteFile(projectId: string, agentId: string, sessionId: string, fileIndex: number): void {
diff --git a/packages/server/src/db/schema.ts b/packages/server/src/db/schema.ts
index 7b504f3d..a1f54128 100644
--- a/packages/server/src/db/schema.ts
+++ b/packages/server/src/db/schema.ts
@@ -128,6 +128,7 @@ CREATE TABLE IF NOT EXISTS trace_files ( -- DERIVED CACHE of the on-disk T
file_index INTEGER NOT NULL, -- shard index NNN of <session_id>_NNN.jsonl (name/path are reconstructed from the row, never stored: the data root may move)
date TEXT NOT NULL, -- date directory name (local yyyy-mm-dd)
size_bytes INTEGER NOT NULL, -- last observed size (listings stat-refresh the returned page and write back; an actively-appended shard may lag in between)
+ page_stats TEXT, -- cached message-window scan state at this shard's END (services/message-window.ts ShardPrefixRecord JSON); immutable shards only, NULL = not yet computed, nulled whenever size_bytes changes
PRIMARY KEY (project_id, agent_id, session_id, file_index)
);
CREATE INDEX IF NOT EXISTS idx_trace_files_agent_date ON trace_files(project_id, agent_id, date);
diff --git a/packages/server/src/http/routes/sessions.ts b/packages/server/src/http/routes/sessions.ts
index 435ed2c1..8a9c5220 100644
--- a/packages/server/src/http/routes/sessions.ts
+++ b/packages/server/src/http/routes/sessions.ts
@@ -17,6 +17,7 @@ import type {
FilesStatResponse,
GoalResponse,
MessagesLiveTail,
+ MessagesPageInfo,
MessagesResponse,
ServerEvent,
SessionCategory,
@@ -26,6 +27,8 @@ import type {
RetryNowResponse,
TaskCreateResponse,
} from "../../api/types.js";
+import { decodeCursor } from "../../services/message-window.js";
+import type { MessagesPageRequest } from "../../services/trace-service.js";
import { PREVIEW_TOKEN_TTL_MS, resolvePreviewTarget } from "../../services/preview-token.js";
import type { AppEnv } from "../../auth/middleware.js";
import type { SessionRow } from "../../db/repos/sessions.js";
@@ -72,6 +75,51 @@ export const APPROVAL_MODES: readonly ApprovalMode[] = [
/** The five valid per-turn thinking level names (TaskCreateRequest.thinkingLevel). */
const THINKING_LEVELS: readonly ThinkingLevelName[] = ["none", "low", "medium", "high", "xhigh"];
+/** Unit-count bounds for windowed history reads (`tailLimit` / `limit`), and the `before` page's default. */
+const MESSAGES_PAGE_LIMIT_MAX = 1000;
+const MESSAGES_PAGE_LIMIT_DEFAULT = 200;
+
+/** Parse one windowed-read unit-count param (positive integer, capped). */
+function pageLimit(raw: string, name: string): number {
+ if (!/^\d{1,4}$/.test(raw)) throw badRequest(`${name} must be a positive integer.`);
+ const v = Number.parseInt(raw, 10);
+ if (v < 1 || v > MESSAGES_PAGE_LIMIT_MAX) {
+ throw badRequest(`${name} must be an integer between 1 and ${MESSAGES_PAGE_LIMIT_MAX}.`);
+ }
+ return v;
+}
+
+/**
+ * Parse GET /messages windowed-read params. No params → null: the legacy full-transcript
+ * read, byte-identical to the pre-pagination response (other consumers depend on it).
+ * `tailLimit=<n>` → the newest n units; `before=<cursor>[&limit=<n>]` → the n units
+ * preceding the cursor. The two forms are mutually exclusive, and `limit` belongs to
+ * `before` alone — mixing them is a caller bug worth a loud 400 rather than a guess.
+ */
+function messagesPageQuery(c: Context): MessagesPageRequest | null {
+ const rawTail = c.req.query("tailLimit");
+ const rawBefore = c.req.query("before");
+ const rawLimit = c.req.query("limit");
+ if (rawTail === undefined && rawBefore === undefined) {
+ if (rawLimit !== undefined) throw badRequest("limit requires before.");
+ return null;
+ }
+ if (rawTail !== undefined) {
+ if (rawBefore !== undefined) throw badRequest("tailLimit and before are mutually exclusive.");
+ if (rawLimit !== undefined) throw badRequest("limit only applies to before requests.");
+ return { kind: "tail", limit: pageLimit(rawTail, "tailLimit") };
+ }
+ const cursor = decodeCursor(rawBefore!);
+ if (cursor === null) {
+ throw badRequest("before must be a cursor of the form <shardIndex>:<ordinal>.");
+ }
+ return {
+ kind: "before",
+ cursor,
+ limit: rawLimit !== undefined ? pageLimit(rawLimit, "limit") : MESSAGES_PAGE_LIMIT_DEFAULT,
+ };
+}
+
/** Accepted `category` query values of the list endpoint (SessionCategory, spelled out for validation). */
const SESSION_CATEGORIES: readonly SessionCategory[] = [
"active",
@@ -494,6 +542,7 @@ export function sessionsRoutes(deps: AppDeps): Hono<AppEnv> {
app.get("/:sessionId/messages", async (c) => {
const row = resolveSession(c);
+ const page = messagesPageQuery(c);
// Live tail (running/compacting sessions only): capture the channel cursor and the
// open-fragment snapshot together, synchronously — no await between the two, and both
// BEFORE the trace read starts. That ordering is what makes the client contract safe
@@ -504,13 +553,41 @@ export function sessionsRoutes(deps: AppDeps): Hono<AppEnv> {
// cursor — the client's overlap dedup against `messages` decides for them — so a
// complete message whose trace append is still in flight when the read starts is not
// lost either.
+ //
+ // Windowed reads keep the same contract on TAIL pages only: a tail page ends at the
+ // transcript's live edge, so the attachment's semantics are identical. A `before`
+ // page is immutable history — attaching in-flight fragments to it would seed them at
+ // the wrong position — so it never carries `live`.
let live: MessagesLiveTail | undefined;
- if (deps.manager.statusOf(row.sessionId) !== "idle") {
+ if (page?.kind !== "before" && deps.manager.statusOf(row.sessionId) !== "idle") {
live = {
cursor: deps.channels.get(row.sessionId).lastEventId,
fragments: deps.manager.liveFragments(row.sessionId),
};
}
+ if (page !== null) {
+ const result = await deps.traceService.readMessagesPage(
+ row.projectId,
+ row.agentId,
+ row.sessionId,
+ page,
+ );
+ const info: MessagesPageInfo = {
+ ...(result.before !== undefined ? { before: result.before } : {}),
+ earlierTurns: result.prior.turns,
+ prior: {
+ subagentTokens: result.prior.subagentTokens,
+ elapsedMs: result.prior.elapsedMs,
+ sessionTokens: result.prior.sessionTokens,
+ contextTokens: result.prior.contextTokens,
+ },
+ };
+ return c.json({
+ messages: result.messages,
+ ...(live !== undefined ? { live } : {}),
+ page: info,
+ } satisfies MessagesResponse);
+ }
const messages = await deps.traceService.readMessages(
row.projectId,
row.agentId,
diff --git a/packages/server/src/services/message-window.ts b/packages/server/src/services/message-window.ts
new file mode 100644
index 00000000..e2551198
--- /dev/null
+++ b/packages/server/src/services/message-window.ts
@@ -0,0 +1,430 @@
+/**
+ * Message-window scanner: the pure logic behind cursor pagination of
+ * `GET /api/sessions/:id/messages` (TraceService.readMessagesPage).
+ *
+ * A window **unit** is one Task in the Web reducer's sense: it opens at a main-session
+ * user prompt (text or image) and runs until the next such prompt. Cutting only at these
+ * boundaries is what keeps every stream-model invariant intact inside a window — a
+ * tool_call is never separated from its tool_call_output (outputs land before the next
+ * user prompt), a compaction_begin/end span never splits (compaction-internal messages
+ * stay skippable), a steering chip keeps the images that ride behind it, and a
+ * mid-Task shard rotation (auto compaction with carry-over) stays glued to its Task.
+ *
+ * The scanner walks one shard's RAW messages (no subagent expansion — origin-carrying
+ * messages never appear in a shard) and mirrors, decision for decision, the Web reducer
+ * in web/src/lib/omni/stream-model.ts (pushMessage/startTask/finalizeOpenTask) plus the
+ * outline-entry rule in web/src/features/chat/outline-model.ts (buildOutline) — the four
+ * implementations of "what is one turn" (this file, stream-model, outline-model, and
+ * trace-service.analyze) must stay in step; tests on both sides pin the shared cases.
+ *
+ * Two distinct counts come out of one pass:
+ * - **unit boundaries** — the safe cut points described above (banner-only prompts and
+ * goal-round re-sends included: they start Tasks in the reducer);
+ * - **outline turns** — the subset that opens an entry in the Web's conversation
+ * outline (`第 N 轮` numbering). Machine-only prompts (handoff / model-switch
+ * blocks), goal rounds past 1, steering chips and compaction injections do NOT open
+ * entries, and consecutive user messages of one send merge into one entry — the
+ * count must match buildOutline exactly, or a paginated outline would mis-number.
+ *
+ * The pass also accumulates the **prior stats** a partial window needs seeded into the
+ * Web's stats tracker so header chips and per-turn cumulative rows keep telling the
+ * truth (see task-stats.ts `seedPriorStats`): elapsed time of finished Tasks, subagent
+ * token totals (via the caller-provided child expander), and the last main-session
+ * session/context token readings.
+ *
+ * Scan state is carried across shards (a Task can span a rotation). Cached per-shard
+ * prefix records (trace_files.page_stats) persist the carry so old shards are read at
+ * most once ever; bump CACHE_VERSION whenever any rule in this file changes.
+ */
+import { parseUserSteeringText } from "@prismshadow/penguin-core";
+import {
+ parseGoalMessage,
+ parseHandoffMessage,
+ parseModelSwitchMessage,
+} from "@prismshadow/penguin-core/markers";
+import type { OmniMessage } from "@prismshadow/penguin-core";
+
+/** Bump when any counting/boundary rule changes: cached page_stats records with an older version are recomputed. */
+export const CACHE_VERSION = 1;
+
+/** Cumulative totals at a point in the trace (all values are "before this point"). */
+export interface WindowPriorStats {
+ /** Outline entries opened before this point (the Web outline's global numbering offset). */
+ turns: number;
+ /** Sum of subagent token_usage request totals (all descendant sessions) before this point. */
+ subagentTokens: number;
+ /** Sum of finished Tasks' elapsed time before this point (the Web's sessionElapsedMs basis). */
+ elapsedMs: number;
+ /** The last main-session token_usage `session.total` seen before this point (0 = none). */
+ sessionTokens: number;
+ /** The last main-session NON-compaction token_usage `request.total` before this point (context occupancy basis). */
+ contextTokens: number;
+}
+
+/** Open-Task bookkeeping carried across messages (mirrors StreamModel.task* fields). */
+interface TaskCarry {
+ open: boolean;
+ /** Task first/latest message timestamps (ms; the degenerate-round elapsed fallback). */
+ firstTsMs: number;
+ lastTsMs: number;
+ /** Last non-compaction request_end (ms); the Task's true end when present. */
+ lastReqEndMs: number | null;
+ /** Whether this Task saw main usage / non-blank assistant text — decides whether a stats row would be emitted at its close (which breaks a user-item run). */
+ sawUsage: boolean;
+ sawReply: boolean;
+ /** Compaction usage held pending (committed to the Task by a later non-compaction request_end — mirrors task-stats.ts pendingCompaction*). */
+ pendingCompactionUsage: boolean;
+}
+
+/** Full scanner state, serializable into a shard's cached prefix record. */
+export interface ScanState {
+ totals: WindowPriorStats;
+ task: TaskCarry;
+ /** Between a main-session compaction_begin and its compaction_end. */
+ compactionActive: boolean;
+ /** A steering chip is still collecting its trailing images (mirrors StreamModel.openSteering). */
+ steeringOpen: boolean;
+ /**
+ * Inside an unbroken, entry-carrying run of user items — buildOutline's `lastWasUser`,
+ * tracked at the item level: true after an entry-eligible user item, false after any
+ * non-user item (a stats row included) AND after banner/goal-round texts (which open no
+ * entry and break the run in buildOutline). Both the window-cut and the merge decision
+ * key off it, so a cut can never split what the outline merges.
+ */
+ runOpen: boolean;
+}
+
+export function initialScanState(): ScanState {
+ return {
+ totals: { turns: 0, subagentTokens: 0, elapsedMs: 0, sessionTokens: 0, contextTokens: 0 },
+ task: {
+ open: false,
+ firstTsMs: 0,
+ lastTsMs: 0,
+ lastReqEndMs: null,
+ sawUsage: false,
+ sawReply: false,
+ pendingCompactionUsage: false,
+ },
+ compactionActive: false,
+ steeringOpen: false,
+ runOpen: false,
+ };
+}
+
+/** One safe cut point: `ordinal` indexes into the shard's parsed message array; `stats` is the cumulative prior AT the cut (the unit itself not included). */
+export interface UnitBoundary {
+ ordinal: number;
+ stats: WindowPriorStats;
+}
+
+/**
+ * Aggregate a subagent pointer's child subtree without materializing its messages:
+ * the token sum feeds `subagentTokens`, the max timestamp advances the open Task's
+ * lastTs exactly as routeNested's touchTask would for every expanded child message.
+ * Null = child trace missing (the pointer event stays a plain event, contributing nothing).
+ */
+export interface ChildAggregate {
+ requestTokens: number;
+ maxTsMs: number | null;
+}
+
+function tsMs(timestamp: string): number | null {
+ const ms = Date.parse(timestamp);
+ return Number.isFinite(ms) ? ms : null;
+}
+
+/** Mirrors stream-model touchTask: advance the open Task's latest timestamp (compaction-internal messages excluded). */
+function touchTask(state: ScanState, ms: number | null): void {
+ if (!state.task.open || state.compactionActive || ms === null) return;
+ if (ms > state.task.lastTsMs) state.task.lastTsMs = ms;
+}
+
+/** Mirrors stream-model finalizeOpenTask + task-stats endTask: settle the open Task's elapsed into the cumulative. */
+function finalizeTask(state: ScanState): void {
+ const t = state.task;
+ if (!t.open) return;
+ t.open = false;
+ const endMs = t.lastReqEndMs ?? t.lastTsMs;
+ state.totals.elapsedMs += Math.max(0, endMs - t.firstTsMs);
+ t.pendingCompactionUsage = false;
+}
+
+/** Mirrors stream-model startTask: finalize the previous Task and open a new one at `ms`. */
+function startTask(state: ScanState, ms: number | null): void {
+ finalizeTask(state);
+ const t = state.task;
+ t.open = true;
+ t.firstTsMs = ms ?? 0;
+ t.lastTsMs = t.firstTsMs;
+ t.lastReqEndMs = null;
+ t.sawUsage = false;
+ t.sawReply = false;
+ t.pendingCompactionUsage = false;
+}
+
+/** A non-user item entered the stream: the user-item run breaks (buildOutline's lastWasUser = false). */
+function breakRuns(state: ScanState): void {
+ state.runOpen = false;
+}
+
+/**
+ * Handle one Task-starting user message (prompt text or non-steering image).
+ * `entryEligible` says whether the message would open an outline entry (buildOutline's
+ * rule); ineligible messages (banner blocks, goal rounds > 1) still start Tasks — and
+ * still cut when the run is broken — but never count and always break the run, exactly
+ * as buildOutline resets lastWasUser for them.
+ */
+function onTaskStart(
+ state: ScanState,
+ ms: number | null,
+ entryEligible: boolean,
+ onBoundary: (stats: WindowPriorStats) => void,
+): void {
+ // A stats row emitted while closing the previous Task lands BEFORE this user item and
+ // breaks the item run (finalizeOpenTask inserts it ahead of the new prompt) — mirror
+ // that so two sends merged by the outline are never cut apart, while two sends
+ // separated by a stats row cut (and count) as two.
+ if (state.task.open && (state.task.sawUsage || state.task.sawReply)) breakRuns(state);
+ const boundary = !state.runOpen;
+ startTask(state, ms);
+ if (boundary) onBoundary({ ...state.totals });
+ if (entryEligible) {
+ if (boundary) state.totals.turns += 1;
+ state.runOpen = true;
+ } else {
+ state.runOpen = false;
+ }
+}
+
+/** buildOutline's eligibility for a user prompt TEXT: machine-only source blocks and goal rounds past 1 open no entry. */
+function outlineEligibleText(text: string): boolean {
+ if (parseHandoffMessage(text) || parseModelSwitchMessage(text)) return false;
+ const goal = parseGoalMessage(text);
+ return !(goal !== null && goal.round > 1);
+}
+
+/**
+ * Scan one shard's raw messages, mutating `state` in place and reporting every unit
+ * boundary through `onBoundary` (with the cumulative priors AT the cut). `expandChild`
+ * resolves a subagent pointer's aggregate (may hit a per-request memo); pass null to
+ * skip child reads when the caller does not need subagent totals for this span.
+ */
+export async function scanMessages(
+ state: ScanState,
+ messages: readonly OmniMessage[],
+ onBoundary: (ordinal: number, stats: WindowPriorStats) => void,
+ expandChild: ((sessionId: string) => Promise<ChildAggregate | null>) | null,
+ fromOrdinal = 0,
+ toOrdinal = messages.length,
+): Promise<void> {
+ for (let i = fromOrdinal; i < toOrdinal; i++) {
+ const msg = messages[i]!;
+ // Shards never contain origin-carrying messages (core's Writer filters them);
+ // defensively skip any that appear rather than mis-shaping the counts.
+ if (msg.origin !== undefined && msg.origin.length > 0) continue;
+ const ms = tsMs(msg.timestamp);
+ const p = msg.payload as Record<string, unknown> & { type?: string; role?: string };
+
+ // Mirrors pushMessage's first step: anything that is not a complete user image
+ // closes the steering-images window (session_meta and events included).
+ const isUserImage = msg.type === "model_msg" && p.type === "image_url";
+ if (!isUserImage) state.steeringOpen = false;
+
+ if (msg.type === "model_msg") {
+ // Compaction-internal model messages: never rendered, never counted (stream-model
+ // returns before any item/Task logic; only touchTask advances).
+ if (state.compactionActive) {
+ touchTask(state, ms);
+ continue;
+ }
+ if (p.type === "text" && p.role === "user" && typeof p.text === "string") {
+ const text = p.text;
+ // Compaction-summary injection: no item, no Task, no run change.
+ if (text.startsWith("[context_summary]") || text.startsWith("<context_summary>")) {
+ touchTask(state, ms);
+ continue;
+ }
+ // Mid-run steering: rendered as a user_steering item (not user_text) — it breaks
+ // the outline's user-item run but never starts a Task or cuts a window.
+ if (parseUserSteeringText(text) !== null) {
+ touchTask(state, ms);
+ breakRuns(state);
+ state.steeringOpen = true;
+ continue;
+ }
+ onTaskStart(state, ms, outlineEligibleText(text), (stats) => onBoundary(i, stats));
+ continue;
+ }
+ if (p.type === "image_url") {
+ // An image riding behind a steering chip folds into it: no item, no Task.
+ if (state.steeringOpen) {
+ touchTask(state, ms);
+ continue;
+ }
+ onTaskStart(state, ms, true, (stats) => onBoundary(i, stats));
+ continue;
+ }
+ if (p.type === "text" && p.role === "assistant" && typeof p.text === "string") {
+ touchTask(state, ms);
+ // Blank fidelity-only messages produce no item (stream-model discards them).
+ if (p.text.trim() !== "") {
+ state.task.sawReply = true;
+ breakRuns(state);
+ }
+ continue;
+ }
+ if (p.type === "thinking") {
+ touchTask(state, ms);
+ if (typeof p.thinking === "string" && p.thinking.trim() !== "") breakRuns(state);
+ continue;
+ }
+ if (p.type === "tool_call") {
+ touchTask(state, ms);
+ breakRuns(state);
+ continue;
+ }
+ // tool_call_output updates an existing card (no new item); inline_* render nothing.
+ touchTask(state, ms);
+ continue;
+ }
+
+ if (msg.type === "event_msg") {
+ touchTask(state, ms);
+ const t = p.type;
+ if (t === "compaction_begin") {
+ state.compactionActive = true;
+ breakRuns(state); // the compaction banner is an item
+ continue;
+ }
+ if (t === "compaction_end") {
+ // Closes the banner opened by the begin (no new item mid-window).
+ state.compactionActive = false;
+ continue;
+ }
+ if (t === "abort") {
+ breakRuns(state); // the interruption marker is an item
+ continue;
+ }
+ if (t === "request_end") {
+ if (state.compactionActive) continue; // compaction requests render nothing
+ if (ms !== null) state.task.lastReqEndMs = ms;
+ // Pending compaction usage commits at a later non-compaction request_end
+ // (compaction mid-Task) — from then on the Task WILL show a stats row.
+ if (state.task.pendingCompactionUsage) {
+ state.task.sawUsage = true;
+ state.task.pendingCompactionUsage = false;
+ }
+ const status = p.status;
+ // A retryable end renders a reconnect-hint item.
+ if (status === "failed" || status === "timeout" || status === "malformed") {
+ breakRuns(state);
+ }
+ continue;
+ }
+ if (t === "token_usage") {
+ const request = p.request as { total?: number } | undefined;
+ const session = p.session as { total?: number } | undefined;
+ // The session cumulative tracks the provider even during compaction
+ // (task-stats trackMainUsage does the same).
+ if (typeof session?.total === "number") state.totals.sessionTokens = session.total;
+ if (state.compactionActive) {
+ state.task.pendingCompactionUsage = true;
+ } else {
+ if (typeof request?.total === "number") state.totals.contextTokens = request.total;
+ state.task.sawUsage = true;
+ }
+ continue;
+ }
+ if (t === "subagent" && typeof p.session_id === "string" && expandChild !== null) {
+ // The pointer expands to the child's messages in the served transcript: their
+ // token_usage feeds the parent's subagent totals at every depth, and their
+ // timestamps advance the open Task exactly as routeNested's touchTask would.
+ const agg = await expandChild(p.session_id);
+ if (agg !== null) {
+ state.totals.subagentTokens += agg.requestTokens;
+ touchTask(state, agg.maxTsMs);
+ }
+ continue;
+ }
+ // approval_decision / request_begin / unexpanded pointers: no items, no run change.
+ continue;
+ }
+ // session_meta: no item (steering window already closed above).
+ }
+}
+
+/** Finalize the trailing open Task (end of the whole trace): the cumulative then covers every finished Task. */
+export function finalizeScan(state: ScanState): void {
+ finalizeTask(state);
+}
+
+// ---------------------------------------------------------------------------
+// Cursor encoding
+// ---------------------------------------------------------------------------
+
+/** A window cursor: shard file index + message ordinal within that shard's parsed array. */
+export interface MessageCursor {
+ fileIndex: number;
+ ordinal: number;
+}
+
+/**
+ * `<fileIndex>:<ordinal>` — stable across requests and compaction: rotation always
+ * opens a NEW shard, closed shards are immutable, and the active shard is append-only,
+ * so a (shard, ordinal) pair never moves.
+ */
+export function encodeCursor(c: MessageCursor): string {
+ return `${c.fileIndex}:${c.ordinal}`;
+}
+
+/** Strict parse of a cursor string; null when malformed (callers turn that into a 400). */
+export function decodeCursor(raw: string): MessageCursor | null {
+ const m = /^(\d{1,9}):(\d{1,9})$/.exec(raw);
+ if (!m) return null;
+ return { fileIndex: Number(m[1]), ordinal: Number(m[2]) };
+}
+
+// ---------------------------------------------------------------------------
+// Cached per-shard prefix records
+// ---------------------------------------------------------------------------
+
+/**
+ * The persisted shape of trace_files.page_stats: the scan state at the END of a shard
+ * (cumulative from the very beginning of the session). Only immutable shards are cached
+ * — the newest shard still grows. `v` gates rule evolution: a record from an older
+ * CACHE_VERSION is recomputed as if absent.
+ */
+export interface ShardPrefixRecord {
+ v: number;
+ state: ScanState;
+}
+
+export function serializePrefix(state: ScanState): string {
+ return JSON.stringify({ v: CACHE_VERSION, state } satisfies ShardPrefixRecord);
+}
+
+/** Parse a cached record; null when absent, unparseable, or from another CACHE_VERSION. */
+export function deserializePrefix(raw: string | null): ScanState | null {
+ if (raw === null) return null;
+ try {
+ const rec = JSON.parse(raw) as ShardPrefixRecord;
+ if (rec.v !== CACHE_VERSION || typeof rec.state !== "object" || rec.state === null) {
+ return null;
+ }
+ return rec.state;
+ } catch {
+ return null;
+ }
+}
+
+/** Deep-copy a scan state (cached records must not be mutated by a later scan). */
+export function cloneScanState(state: ScanState): ScanState {
+ return {
+ totals: { ...state.totals },
+ task: { ...state.task },
+ compactionActive: state.compactionActive,
+ steeringOpen: state.steeringOpen,
+ runOpen: state.runOpen,
+ };
+}
diff --git a/packages/server/src/services/trace-service.ts b/packages/server/src/services/trace-service.ts
index fa446ac3..8125f64b 100644
--- a/packages/server/src/services/trace-service.ts
+++ b/packages/server/src/services/trace-service.ts
@@ -40,6 +40,21 @@ import type { TraceFileRow, TraceSessionRow } from "../db/repos/trace-index.js";
import { HttpError } from "../http/errors.js";
import { formatLocalDate } from "../internal/dates.js";
import type { SessionSources } from "../runtime/session-sources.js";
+import {
+ cloneScanState,
+ deserializePrefix,
+ encodeCursor,
+ finalizeScan,
+ initialScanState,
+ scanMessages,
+ serializePrefix,
+} from "./message-window.js";
+import type {
+ ChildAggregate,
+ MessageCursor,
+ ScanState,
+ WindowPriorStats,
+} from "./message-window.js";
import { TraceIndexService, traceFilePath } from "./trace-index.js";
const TRACE_FILE_RE = /^(.+)_(\d{3})\.jsonl$/;
@@ -58,6 +73,34 @@ interface LocatedFile {
path: string;
date: string;
index: number;
+ /** Last observed size from the index row (the page-stats cache write guard). */
+ sizeBytes: number;
+}
+
+/** A windowed history read's request shape (see readMessagesPage). */
+export type MessagesPageRequest =
+ { kind: "tail"; limit: number } | { kind: "before"; cursor: MessageCursor; limit: number };
+
+/** A windowed history read's result (route maps it onto MessagesResponse.page). */
+export interface MessagesPageResult {
+ messages: OmniMessage[];
+ /** Cursor of the window's first unit; absent = the window reaches the beginning. */
+ before?: string;
+ /** Cumulative stats before the window (earlierTurns = prior.turns). */
+ prior: WindowPriorStats;
+}
+
+/**
+ * Per-request expansion context: `projectScanned` caps the miss-path force reconcile at
+ * one per request; `ancestry` guards cycles; `raw` memoizes each child session's
+ * concatenated shard messages so the window expansion and the subagent-token
+ * aggregation never read the same child twice within one request.
+ */
+interface ExpandCtx {
+ projectScanned: boolean;
+ ancestry: Set<string>;
+ depth: number;
+ raw: Map<string, OmniMessage[] | null>;
}
/**
@@ -92,6 +135,12 @@ export interface TraceServiceDeps {
sessions?: TraceSessionIndex;
/** Optional (narrow tests may omit): the shared in-process Session-origin registry (single source of truth for `source`). */
sources?: SessionSources;
+ /**
+ * Test observability: called with the path of every Trace shard this service reads
+ * from disk (windowed-read tests assert an old-window request never touches the
+ * newest shard and vice versa). Production wiring omits it.
+ */
+ observeShardRead?: (path: string) => void;
}
/** One Session's classification result (see classify): its sidebar category + Workspace path ("" = unknown). */
@@ -127,9 +176,16 @@ export class TraceService {
path: traceFilePath(this.root, r),
date: r.date,
index: r.fileIndex,
+ sizeBytes: r.sizeBytes,
}));
}
+ /** All shard reads funnel through here (deps.observeShardRead is the windowed-read tests' proof of which files were touched). */
+ private async readShard(path: string): Promise<OmniMessage[]> {
+ this.deps.observeShardRead?.(path);
+ return readTraceTolerant(path);
+ }
+
/** Deletes all of this Session's Trace files (called when the Session is deleted); the index rows go with them. */
async deleteSessionTraces(projectId: string, agentId: string, sessionId: string): Promise<void> {
const files = await this.locateAll(projectId, agentId, sessionId);
@@ -160,11 +216,18 @@ export class TraceService {
agentId: string,
sessionId: string,
): Promise<OmniMessage[]> {
- return this.readMessagesExpanded(projectId, agentId, sessionId, {
+ const ctx: ExpandCtx = {
projectScanned: false,
ancestry: new Set([sessionId]),
depth: 0,
- });
+ raw: new Map(),
+ };
+ const files = await this.locateAll(projectId, agentId, sessionId);
+ const out: OmniMessage[] = [];
+ for (const file of files) {
+ out.push(...(await this.expandMessages(projectId, await this.readShard(file.path), ctx)));
+ }
+ return out;
}
/**
@@ -186,44 +249,249 @@ export class TraceService {
return this.deps.index.repo.findAgentBySession(projectId, childSid);
}
- private async readMessagesExpanded(
+ /** A child session's concatenated raw shard messages, memoized per request; null = no Trace located. */
+ private async readChildRaw(
projectId: string,
- agentId: string,
- sessionId: string,
- ctx: { projectScanned: boolean; ancestry: Set<string>; depth: number },
+ childSid: string,
+ ctx: ExpandCtx,
+ ): Promise<OmniMessage[] | null> {
+ const cached = ctx.raw.get(childSid);
+ if (cached !== undefined) return cached;
+ const childAgent = await this.resolveChildAgent(projectId, childSid, ctx);
+ let raw: OmniMessage[] | null = null;
+ if (childAgent) {
+ const files = await this.locateAll(projectId, childAgent, childSid);
+ if (files.length > 0) {
+ raw = [];
+ for (const file of files) raw.push(...(await this.readShard(file.path)));
+ }
+ }
+ ctx.raw.set(childSid, raw);
+ return raw;
+ }
+
+ /**
+ * Expand subagent pointers within one message span (the whole transcript on the full
+ * path, one window on the paged path — same recursive shape either way).
+ */
+ private async expandMessages(
+ projectId: string,
+ messages: readonly OmniMessage[],
+ ctx: ExpandCtx,
): Promise<OmniMessage[]> {
- const files = await this.locateAll(projectId, agentId, sessionId);
const out: OmniMessage[] = [];
- for (const file of files) {
- for (const msg of await readTraceTolerant(file.path)) {
- // The depth cap guards against runaway recursion; ancestry guards against a
- // cyclic pointer (a tampered Trace pointing to itself/an ancestor is not expanded).
- const childSid = ctx.depth < MAX_SUBAGENT_DEPTH ? subagentPointer(msg) : null;
- if (!childSid || ctx.ancestry.has(childSid)) {
- out.push(msg);
- continue;
- }
- const childAgent = await this.resolveChildAgent(projectId, childSid, ctx);
- let nested: OmniMessage[] = [];
- if (childAgent) {
- ctx.ancestry.add(childSid);
- nested = await this.readMessagesExpanded(projectId, childAgent, childSid, {
- ...ctx,
- depth: ctx.depth + 1,
- });
- ctx.ancestry.delete(childSid);
- }
- // Child Trace missing (deleted): keep the pointer event, since the sub-session's content can't be recovered.
- if (nested.length === 0) {
- out.push(msg);
- continue;
- }
- for (const m of nested) out.push({ ...m, origin: [childSid, ...(m.origin ?? [])] });
+ for (const msg of messages) {
+ // The depth cap guards against runaway recursion; ancestry guards against a
+ // cyclic pointer (a tampered Trace pointing to itself/an ancestor is not expanded).
+ const childSid = ctx.depth < MAX_SUBAGENT_DEPTH ? subagentPointer(msg) : null;
+ if (!childSid || ctx.ancestry.has(childSid)) {
+ out.push(msg);
+ continue;
+ }
+ const raw = await this.readChildRaw(projectId, childSid, ctx);
+ let nested: OmniMessage[] = [];
+ if (raw !== null) {
+ ctx.ancestry.add(childSid);
+ nested = await this.expandMessages(projectId, raw, { ...ctx, depth: ctx.depth + 1 });
+ ctx.ancestry.delete(childSid);
+ }
+ // Child Trace missing (deleted): keep the pointer event, since the sub-session's content can't be recovered.
+ if (nested.length === 0) {
+ out.push(msg);
+ continue;
}
+ for (const m of nested) out.push({ ...m, origin: [childSid, ...(m.origin ?? [])] });
}
return out;
}
+ /**
+ * A subagent pointer's subtree aggregate for the window scanner (message-window.ts):
+ * descendant token_usage request totals plus the subtree's max timestamp — the same
+ * contributions the expanded messages make to the Web's parent-level stats tracker.
+ * The recursion mirrors expandMessages' depth/ancestry rules exactly, so an
+ * unexpandable pointer contributes nothing on both paths.
+ */
+ private async aggregateChild(
+ projectId: string,
+ childSid: string,
+ ctx: ExpandCtx,
+ ): Promise<ChildAggregate | null> {
+ if (ctx.depth >= MAX_SUBAGENT_DEPTH || ctx.ancestry.has(childSid)) return null;
+ const raw = await this.readChildRaw(projectId, childSid, ctx);
+ if (raw === null || raw.length === 0) return null;
+ let requestTokens = 0;
+ let maxTsMs: number | null = null;
+ ctx.ancestry.add(childSid);
+ for (const msg of raw) {
+ const ms = Date.parse(msg.timestamp);
+ if (Number.isFinite(ms) && (maxTsMs === null || ms > maxTsMs)) maxTsMs = ms;
+ const p = msg.payload as { type?: string; request?: { total?: number } };
+ if (msg.type === "event_msg" && p.type === "token_usage") {
+ requestTokens += typeof p.request?.total === "number" ? p.request.total : 0;
+ continue;
+ }
+ const grandchild = subagentPointer(msg);
+ if (grandchild !== null) {
+ const agg = await this.aggregateChild(projectId, grandchild, {
+ ...ctx,
+ depth: ctx.depth + 1,
+ });
+ if (agg !== null) {
+ requestTokens += agg.requestTokens;
+ if (agg.maxTsMs !== null && (maxTsMs === null || agg.maxTsMs > maxTsMs)) {
+ maxTsMs = agg.maxTsMs;
+ }
+ }
+ }
+ }
+ ctx.ancestry.delete(childSid);
+ return { requestTokens, maxTsMs };
+ }
+
+ /**
+ * End-of-shard scan states for files[0..upto] (cumulative from the transcript's
+ * beginning), served from the trace_files.page_stats cache. A missing/stale record
+ * costs one read of THAT shard — once ever: every shard here is immutable (rotation
+ * opens a new shard; the newest shard never appears in a prefix, because windows are
+ * suffixes and their first shard is always read anyway). The write-back is guarded on
+ * the indexed size, so an externally rewritten shard can only invalidate, never
+ * poison, the cache.
+ */
+ private async prefixStates(
+ projectId: string,
+ agentId: string,
+ sessionId: string,
+ files: LocatedFile[],
+ upto: number,
+ ctx: ExpandCtx,
+ ): Promise<ScanState[]> {
+ const states: ScanState[] = [];
+ for (let j = 0; j <= upto; j++) {
+ const file = files[j]!;
+ const cached = deserializePrefix(
+ this.deps.index.repo.getPageStats(projectId, agentId, sessionId, file.index),
+ );
+ if (cached !== null) {
+ states.push(cached);
+ continue;
+ }
+ const state = cloneScanState(j === 0 ? initialScanState() : states[j - 1]!);
+ const messages = await this.readShard(file.path);
+ await scanMessages(
+ state,
+ messages,
+ () => {},
+ (sid) => this.aggregateChild(projectId, sid, ctx),
+ );
+ this.deps.index.repo.setPageStats(
+ projectId,
+ agentId,
+ sessionId,
+ file.index,
+ file.sizeBytes,
+ serializePrefix(state),
+ );
+ states.push(state);
+ }
+ return states;
+ }
+
+ /**
+ * Windowed history read (the `tailLimit` / `before` forms of GET /messages). The
+ * window is a run of whole units — cut points and unit semantics live in
+ * message-window.ts — assembled by reading ONLY the shards the window overlaps
+ * (plus, once ever per old shard, the prefix-cache backfill above). Subagent
+ * pointers are expanded exactly as the full path expands them, but only within the
+ * window: children referenced by older windows load when those windows do.
+ */
+ async readMessagesPage(
+ projectId: string,
+ agentId: string,
+ sessionId: string,
+ req: MessagesPageRequest,
+ ): Promise<MessagesPageResult> {
+ const files = await this.locateAll(projectId, agentId, sessionId);
+ const empty = (): MessagesPageResult => ({
+ messages: [],
+ prior: initialScanState().totals,
+ });
+ if (files.length === 0) return empty();
+ const ctx: ExpandCtx = {
+ projectScanned: false,
+ ancestry: new Set([sessionId]),
+ depth: 0,
+ raw: new Map(),
+ };
+
+ // The window's exclusive end: the newest shard's end (tail), or the cursor (before).
+ let endPos: number;
+ let endOrdinal: number | null = null; // null = to the shard's end
+ if (req.kind === "tail") {
+ endPos = files.length - 1;
+ } else {
+ endPos = files.findIndex((f) => f.index === req.cursor.fileIndex);
+ // Cursor shard no longer on disk (external deletion — locateAll already
+ // force-retried): the history it pointed into is gone; report end-of-history
+ // rather than a guess at what used to precede it.
+ if (endPos < 0) return empty();
+ endOrdinal = req.cursor.ordinal;
+ }
+
+ const prefixes = await this.prefixStates(projectId, agentId, sessionId, files, endPos - 1, ctx);
+
+ // Walk backward from the end, scanning whole shards (each from its cached carry-in)
+ // until the window has more units than requested or the beginning is reached.
+ const shardMessages = new Map<number, OmniMessage[]>();
+ let boundaries: Array<{ pos: number; ordinal: number; stats: WindowPriorStats }> = [];
+ let startPos = endPos + 1;
+ while (boundaries.length <= req.limit && startPos > 0) {
+ startPos -= 1;
+ const messages = await this.readShard(files[startPos]!.path);
+ shardMessages.set(startPos, messages);
+ const state = cloneScanState(startPos === 0 ? initialScanState() : prefixes[startPos - 1]!);
+ const shardBoundaries: Array<{ pos: number; ordinal: number; stats: WindowPriorStats }> = [];
+ const to = startPos === endPos && endOrdinal !== null ? endOrdinal : messages.length;
+ await scanMessages(
+ state,
+ messages,
+ (ordinal, stats) => shardBoundaries.push({ pos: startPos, ordinal, stats }),
+ (sid) => this.aggregateChild(projectId, sid, ctx),
+ 0,
+ Math.min(to, messages.length),
+ );
+ boundaries = [...shardBoundaries, ...boundaries];
+ }
+
+ // Window start: the last `limit` units, or the very beginning (preamble included)
+ // when the whole remaining history fits — then there is no `before` cursor.
+ let start: { pos: number; ordinal: number };
+ let before: string | undefined;
+ let prior: WindowPriorStats;
+ if (boundaries.length > req.limit) {
+ const wb = boundaries[boundaries.length - req.limit]!;
+ start = { pos: wb.pos, ordinal: wb.ordinal };
+ before = encodeCursor({ fileIndex: files[wb.pos]!.index, ordinal: wb.ordinal });
+ prior = wb.stats;
+ } else {
+ start = { pos: 0, ordinal: 0 };
+ prior = initialScanState().totals;
+ }
+
+ const windowRaw: OmniMessage[] = [];
+ for (let pos = start.pos; pos <= endPos; pos++) {
+ const messages = shardMessages.get(pos) ?? (await this.readShard(files[pos]!.path));
+ const from = pos === start.pos ? start.ordinal : 0;
+ const to =
+ pos === endPos && endOrdinal !== null
+ ? Math.min(endOrdinal, messages.length)
+ : messages.length;
+ for (let i = from; i < to; i++) windowRaw.push(messages[i]!);
+ }
+ const expanded = await this.expandMessages(projectId, windowRaw, ctx);
+ return { messages: expanded, ...(before !== undefined ? { before } : {}), prior };
+ }
+
/** List of Trace files (index / date / size / mtime). */
async listTraceFiles(
projectId: string,
diff --git a/packages/server/test/helpers.ts b/packages/server/test/helpers.ts
index 3155d42e..12e092b7 100644
--- a/packages/server/test/helpers.ts
+++ b/packages/server/test/helpers.ts
@@ -164,17 +164,21 @@ export function makeTraceHarness(
traceIndex: TraceIndexService;
service: TraceService;
sources: SessionSources;
+ /** Paths of every Trace shard the service read from disk (windowed-read IO assertions); reset freely between calls. */
+ shardReads: string[];
close: () => void;
} {
const db = openDatabase(":memory:");
const sources = opts.sources ?? new SessionSources();
const traceIndex = new TraceIndexService(root, new TraceIndexRepo(db), sources);
+ const shardReads: string[] = [];
const service = new TraceService(root, {
index: traceIndex,
...(opts.sessions !== undefined ? { sessions: opts.sessions } : {}),
sources,
+ observeShardRead: (p) => shardReads.push(p),
});
- return { traceIndex, service, sources, close: () => db.close() };
+ return { traceIndex, service, sources, shardReads, close: () => db.close() };
}
/** Writes a Trace JSONL file directly (for building historical / discovery scenarios). */
diff --git a/packages/server/test/messages-live.test.ts b/packages/server/test/messages-live.test.ts
index 05ed2b87..6ef86333 100644
--- a/packages/server/test/messages-live.test.ts
+++ b/packages/server/test/messages-live.test.ts
@@ -85,8 +85,8 @@ describe("messages live tail", () => {
await t.cleanup();
});
- const getMessages = async (): Promise<MessagesResponse> => {
- const res = await apiClient(t.app, cookie).get(`/api/sessions/${SID}/messages`);
+ const getMessages = async (query = ""): Promise<MessagesResponse> => {
+ const res = await apiClient(t.app, cookie).get(`/api/sessions/${SID}/messages${query}`);
expect(res.status).toBe(200);
return (await res.json()) as MessagesResponse;
};
@@ -134,4 +134,58 @@ describe("messages live tail", () => {
const after = await getMessages();
expect(after.live).toBeUndefined();
});
+
+ it("windowed reads: `live` rides TAIL pages with identical semantics and never rides `before` pages", async () => {
+ t.deps.manager.adopt(row, midStreamFakeSession(SID));
+ await t.deps.manager.startTask(SID, [userText("go")]);
+ await waitFor(() => t.deps.manager.pendingApprovalCount(SID) === 1);
+
+ const full = await getMessages();
+ const tail = await getMessages("?tailLimit=5");
+ expect(tail.page).toBeDefined();
+ expect(tail.live).toBeDefined();
+ // Same capture as the full read: cursor shape and open-fragment snapshot.
+ expect(tail.live!.cursor).toMatch(/^[0-9a-f]{8}-\d+$/);
+ expect(tail.live!.fragments.map((f) => (f.payload as { type: string }).type)).toEqual(
+ full.live!.fragments.map((f) => (f.payload as { type: string }).type),
+ );
+
+ // A `before` page is immutable history: never a live attachment, even mid-run.
+ const before = await getMessages("?before=1:0&limit=5");
+ expect(before.page).toBeDefined();
+ expect(before.live).toBeUndefined();
+
+ expect(t.deps.manager.decideApproval(SID, "tc-lv", "deny")).toBe(true);
+ await waitFor(() => t.deps.manager.statusOf(SID) === "idle");
+ });
+
+ it("the parameterless read stays byte-identical to the pre-pagination contract (no page envelope)", async () => {
+ t.deps.manager.adopt(row, midStreamFakeSession(SID));
+ await t.deps.manager.startTask(SID, [userText("go")]);
+ await waitFor(() => t.deps.manager.pendingApprovalCount(SID) === 1);
+ expect(t.deps.manager.decideApproval(SID, "tc-lv", "deny")).toBe(true);
+ await waitFor(() => t.deps.manager.statusOf(SID) === "idle");
+
+ const res = await apiClient(t.app, cookie).get(`/api/sessions/${SID}/messages`);
+ expect(res.status).toBe(200);
+ const raw = await res.text();
+ const body = JSON.parse(raw) as MessagesResponse;
+ expect(Object.keys(body)).toEqual(["messages"]);
+ // Exactly the legacy serialization: the full transcript and nothing else.
+ const expected = JSON.stringify({
+ messages: await t.deps.traceService.readMessages(row.projectId, row.agentId, row.sessionId),
+ });
+ expect(raw).toBe(expected);
+ // Windowed-param validation stays loud rather than guessy.
+ const bad = await apiClient(t.app, cookie).get(
+ `/api/sessions/${SID}/messages?tailLimit=5&before=1:0`,
+ );
+ expect(bad.status).toBe(400);
+ const badLimit = await apiClient(t.app, cookie).get(`/api/sessions/${SID}/messages?limit=5`);
+ expect(badLimit.status).toBe(400);
+ const badCursor = await apiClient(t.app, cookie).get(
+ `/api/sessions/${SID}/messages?before=xyz`,
+ );
+ expect(badCursor.status).toBe(400);
+ });
});
diff --git a/packages/server/test/messages-page.test.ts b/packages/server/test/messages-page.test.ts
new file mode 100644
index 00000000..15fb6df1
--- /dev/null
+++ b/packages/server/test/messages-page.test.ts
@@ -0,0 +1,454 @@
+/**
+ * Windowed history reads (TraceService.readMessagesPage + GET /messages paging params).
+ *
+ * Covers: tail/before window slicing mid-shard and across shard boundaries, cursor
+ * round-trips, pairing-safe cut points (a window never separates a tool_call from its
+ * output, a compaction span, or a steering group), subagent expansion happening only
+ * for pointers inside the window, outline-turn counting (`earlierTurns`) staying in
+ * step with the Web's buildOutline rule (its twin fixtures live in
+ * web/test/outline-model.test.ts and stream-model.test.ts — keep the two sides
+ * agreeing), prior stats (elapsed / subagent tokens / session tokens / context), the
+ * shard-read discipline (an old-window request never reads the newest shard and vice
+ * versa, once the per-shard prefix cache is primed), and the no-params full read
+ * staying byte-identical with no `page` envelope.
+ */
+import fs from "node:fs/promises";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import {
+ assistantText,
+ compactionBegin,
+ compactionEnd,
+ imageUrlMessage,
+ requestBegin,
+ requestEnd,
+ sessionMeta,
+ subagentEvent,
+ tokenUsage,
+ toolCall,
+ toolCallOutput,
+ userText,
+} from "@prismshadow/penguin-core";
+import { buildHandoffMessage } from "@prismshadow/penguin-core/markers";
+import type { OmniMessage, SessionMetaPayload, TokenCounts } from "@prismshadow/penguin-core";
+import { decodeCursor, encodeCursor } from "../src/services/message-window.js";
+import type { TraceService } from "../src/services/trace-service.js";
+import { makeTempRoot, makeTraceHarness, writeTraceFile } from "./helpers.js";
+
+const P = "project-w";
+const A = "agent-w";
+const S = "session-2026-07-20-10-00-00-aabb0001";
+const CHILD = "session-2026-07-20-10-00-05-ccdd0002";
+
+function at(ts: string, msg: OmniMessage): OmniMessage {
+ return { ...msg, timestamp: ts };
+}
+
+function counts(total: number): TokenCounts {
+ return { cache_read: 0, cache_write: 0, output: total, total };
+}
+
+function metaPayload(over: Partial<SessionMetaPayload> = {}): SessionMetaPayload {
+ return {
+ session_id: S,
+ model_id: "m1",
+ provider: "custom",
+ model_context_window: 1000,
+ system_prompt: "sp",
+ tools: [],
+ agent_state: "/tmp/a",
+ workspace: "/tmp/w",
+ ...over,
+ };
+}
+
+/** One complete turn (prompt → request → reply → usage), 4 messages, spaced inside one minute `mm`. */
+function turn(mm: number, n: number, sessionTotal: number): OmniMessage[] {
+ const t = (s: string) => `2026-07-20T10:${String(mm).padStart(2, "0")}:${s}Z`;
+ return [
+ at(t("00.000"), userText(`q${n}`)),
+ at(t("01.000"), requestBegin()),
+ at(t("02.000"), assistantText(`a${n}`)),
+ at(t("03.000"), requestEnd("completed")),
+ at(t("03.500"), tokenUsage(counts(sessionTotal), counts(100 + n))),
+ ];
+}
+
+const textOf = (m: OmniMessage): string | undefined => (m.payload as { text?: string }).text;
+const userTexts = (ms: OmniMessage[]): string[] =>
+ ms
+ .filter(
+ (m) =>
+ m.type === "model_msg" &&
+ (m.payload as { type?: string; role?: string }).type === "text" &&
+ (m.payload as { role?: string }).role === "user",
+ )
+ .map((m) => textOf(m)!);
+
+describe("messages windowed reads", () => {
+ let root: string;
+ let service: TraceService;
+ let harness: ReturnType<typeof makeTraceHarness>;
+
+ beforeEach(async () => {
+ root = await makeTempRoot();
+ harness = makeTraceHarness(root);
+ service = harness.service;
+ });
+ afterEach(async () => {
+ harness.close();
+ await fs.rm(root, { recursive: true, force: true });
+ });
+
+ it("tail mid-shard: newest N units, before cursor round-trips to the previous window, beginning ends the chain", async () => {
+ await writeTraceFile(root, P, A, "2026-07-20", S, 1, [
+ sessionMeta(metaPayload()),
+ ...turn(0, 1, 1000),
+ ...turn(1, 2, 2000),
+ ...turn(2, 3, 3000),
+ ...turn(3, 4, 4000),
+ ]);
+
+ const tail = await service.readMessagesPage(P, A, S, { kind: "tail", limit: 2 });
+ expect(userTexts(tail.messages)).toEqual(["q3", "q4"]);
+ expect(tail.messages.some((m) => m.type === "session_meta")).toBe(false);
+ expect(tail.before).toBeDefined();
+ expect(tail.prior.turns).toBe(2);
+ // The cursor names the window's first unit: shard 1, ordinal of q3 (meta + 2×5 turns).
+ expect(decodeCursor(tail.before!)).toEqual({ fileIndex: 1, ordinal: 11 });
+
+ const mid = await service.readMessagesPage(P, A, S, {
+ kind: "before",
+ cursor: decodeCursor(tail.before!)!,
+ limit: 1,
+ });
+ expect(userTexts(mid.messages)).toEqual(["q2"]);
+ expect(mid.prior.turns).toBe(1);
+ expect(mid.before).toBeDefined();
+
+ // The oldest window absorbs the preamble (session_meta) and carries no cursor.
+ const first = await service.readMessagesPage(P, A, S, {
+ kind: "before",
+ cursor: decodeCursor(mid.before!)!,
+ limit: 5,
+ });
+ expect(userTexts(first.messages)).toEqual(["q1"]);
+ expect(first.messages[0]!.type).toBe("session_meta");
+ expect(first.before).toBeUndefined();
+ expect(first.prior).toEqual({
+ turns: 0,
+ subagentTokens: 0,
+ elapsedMs: 0,
+ sessionTokens: 0,
+ contextTokens: 0,
+ });
+
+ // Windows tile the transcript exactly: concatenated they equal the full read.
+ const full = await service.readMessages(P, A, S);
+ expect([...first.messages, ...mid.messages, ...tail.messages]).toEqual(full);
+ });
+
+ it("windows span shard boundaries; a mid-Task rotation stays glued to its Task's window", async () => {
+ // Shard 1: turn 1, then turn 2 begins and rotates mid-Task (auto compaction with
+ // carry-over): the continuation lives in shard 2 with no new user prompt.
+ await writeTraceFile(root, P, A, "2026-07-20", S, 1, [
+ sessionMeta(metaPayload()),
+ ...turn(0, 1, 1000),
+ at("2026-07-20T10:01:00.000Z", userText("q2")),
+ at("2026-07-20T10:01:01.000Z", requestBegin()),
+ at("2026-07-20T10:01:02.000Z", requestEnd("completed")),
+ at("2026-07-20T10:01:02.100Z", tokenUsage(counts(2000), counts(900))),
+ at(
+ "2026-07-20T10:01:03.000Z",
+ compactionBegin({ reason: "context", mode: "summarize", context: 900, turns: 2 }),
+ ),
+ at("2026-07-20T10:01:04.000Z", requestBegin()),
+ at("2026-07-20T10:01:05.000Z", assistantText("[summary]s[/summary]")),
+ at("2026-07-20T10:01:06.000Z", requestEnd("completed")),
+ at(
+ "2026-07-20T10:01:07.000Z",
+ compactionEnd({ reason: "context", mode: "summarize", status: "completed" }),
+ ),
+ ]);
+ await writeTraceFile(root, P, A, "2026-07-20", S, 2, [
+ sessionMeta(metaPayload()),
+ at("2026-07-20T10:01:08.000Z", userText("[context_summary]\ns\n[/context_summary]")),
+ at("2026-07-20T10:01:09.000Z", requestBegin()),
+ at("2026-07-20T10:01:10.000Z", assistantText("a2")),
+ at("2026-07-20T10:01:11.000Z", requestEnd("completed")),
+ at("2026-07-20T10:01:11.500Z", tokenUsage(counts(2500), counts(300))),
+ ...turn(2, 3, 3000),
+ ]);
+
+ // Tail of 2 units = turn 2 (which spans BOTH shards, compaction included) + turn 3.
+ const tail = await service.readMessagesPage(P, A, S, { kind: "tail", limit: 2 });
+ expect(userTexts(tail.messages)[0]).toBe("q2");
+ expect(userTexts(tail.messages)).toContain("q3");
+ expect(
+ tail.messages.some((m) => (m.payload as { type?: string }).type === "compaction_begin"),
+ ).toBe(true);
+ // The rotated shard's rewritten session_meta and summary injection ride along inside the window.
+ expect(tail.messages.filter((m) => m.type === "session_meta")).toHaveLength(1);
+ expect(decodeCursor(tail.before!)).toEqual({ fileIndex: 1, ordinal: 6 });
+ expect(tail.prior.turns).toBe(1);
+
+ const older = await service.readMessagesPage(P, A, S, {
+ kind: "before",
+ cursor: decodeCursor(tail.before!)!,
+ limit: 10,
+ });
+ expect(userTexts(older.messages)).toEqual(["q1"]);
+ expect(older.before).toBeUndefined();
+ const full = await service.readMessages(P, A, S);
+ expect([...older.messages, ...tail.messages]).toEqual(full);
+ });
+
+ it("cuts are pairing-safe: a tool_call and its output never split, steering images stay with their chip", async () => {
+ await writeTraceFile(root, P, A, "2026-07-20", S, 1, [
+ sessionMeta(metaPayload()),
+ ...turn(0, 1, 1000),
+ // Turn 2: tool call whose output lands after request_end, steering + image mid-run.
+ at("2026-07-20T10:01:00.000Z", userText("q2")),
+ at("2026-07-20T10:01:01.000Z", requestBegin()),
+ at("2026-07-20T10:01:02.000Z", toolCall({ name: "exec", arguments: "{}", toolCallId: "t1" })),
+ at("2026-07-20T10:01:03.000Z", requestEnd("completed")),
+ at("2026-07-20T10:01:04.000Z", toolCallOutput({ output: "out", toolCallId: "t1" })),
+ at("2026-07-20T10:01:05.000Z", userText("[user_steering]\nfaster\n[/user_steering]")),
+ at("2026-07-20T10:01:05.100Z", imageUrlMessage("data:image/png;base64,AAAA")),
+ at("2026-07-20T10:01:06.000Z", requestBegin()),
+ at("2026-07-20T10:01:07.000Z", assistantText("a2")),
+ at("2026-07-20T10:01:08.000Z", requestEnd("completed")),
+ at("2026-07-20T10:01:08.500Z", tokenUsage(counts(2000), counts(200))),
+ ]);
+
+ // limit 1 must take the WHOLE second turn: the cut lands at q2, never at the
+ // steering text, its image, or between t1's call and output.
+ const tail = await service.readMessagesPage(P, A, S, { kind: "tail", limit: 1 });
+ expect(userTexts(tail.messages)[0]).toBe("q2");
+ const kinds = tail.messages.map((m) => (m.payload as { type?: string }).type);
+ expect(kinds).toContain("tool_call");
+ expect(kinds).toContain("tool_call_output");
+ expect(kinds).toContain("image_url");
+ // Steering opened no new unit: the previous window holds exactly turn 1.
+ const older = await service.readMessagesPage(P, A, S, {
+ kind: "before",
+ cursor: decodeCursor(tail.before!)!,
+ limit: 10,
+ });
+ expect(userTexts(older.messages)).toEqual(["q1"]);
+ });
+
+ it("a text+images send is one unit and one outline turn; banner and goal-round prompts cut but never count", async () => {
+ await writeTraceFile(root, P, A, "2026-07-20", S, 1, [
+ sessionMeta(metaPayload()),
+ // Send 1: text + two images (one entry, one unit).
+ at("2026-07-20T10:00:00.000Z", userText("look")),
+ at("2026-07-20T10:00:00.100Z", imageUrlMessage("data:image/png;base64,AAAA")),
+ at("2026-07-20T10:00:00.200Z", imageUrlMessage("data:image/png;base64,BBBB")),
+ at("2026-07-20T10:00:01.000Z", requestBegin()),
+ at("2026-07-20T10:00:02.000Z", assistantText("a1")),
+ at("2026-07-20T10:00:03.000Z", requestEnd("completed")),
+ at("2026-07-20T10:00:03.500Z", tokenUsage(counts(1000), counts(100))),
+ // A handoff banner send: machine-only, no outline entry (buildOutline returns null body).
+ at(
+ "2026-07-20T10:01:00.000Z",
+ userText(buildHandoffMessage({ agentId: "worker", workspace: "/tmp/w" })),
+ ),
+ at("2026-07-20T10:01:01.000Z", requestBegin()),
+ at("2026-07-20T10:01:02.000Z", assistantText("a2")),
+ at("2026-07-20T10:01:03.000Z", requestEnd("completed")),
+ at("2026-07-20T10:01:03.500Z", tokenUsage(counts(2000), counts(200))),
+ // A goal round-2 re-send: starts a Task but opens no outline entry.
+ at("2026-07-20T10:02:00.000Z", userText("[goal]\nround: 2\nbudget: unlimited\n[/goal]\ngo")),
+ at("2026-07-20T10:02:01.000Z", requestBegin()),
+ at("2026-07-20T10:02:02.000Z", assistantText("a3")),
+ at("2026-07-20T10:02:03.000Z", requestEnd("completed")),
+ at("2026-07-20T10:02:03.500Z", tokenUsage(counts(3000), counts(300))),
+ ...turn(3, 4, 4000),
+ ]);
+
+ // Four units in total (each send cuts), but only ONE outline entry precedes q4:
+ // the text+images send counts once, the banner and the goal round count zero —
+ // exactly buildOutline's rule, so q4 renders as global turn 2 with offset 1.
+ const tail = await service.readMessagesPage(P, A, S, { kind: "tail", limit: 1 });
+ expect(userTexts(tail.messages)).toEqual(["q4"]);
+ expect(tail.prior.turns).toBe(1);
+
+ // Walk one more window back: the goal-round unit alone; still 1 entry before it.
+ const goalWin = await service.readMessagesPage(P, A, S, {
+ kind: "before",
+ cursor: decodeCursor(tail.before!)!,
+ limit: 1,
+ });
+ expect(userTexts(goalWin.messages)[0]).toContain("[goal]");
+ expect(goalWin.prior.turns).toBe(1);
+
+ const bannerWin = await service.readMessagesPage(P, A, S, {
+ kind: "before",
+ cursor: decodeCursor(goalWin.before!)!,
+ limit: 1,
+ });
+ expect(bannerWin.prior.turns).toBe(1); // only the image send precedes the banner
+ const firstWin = await service.readMessagesPage(P, A, S, {
+ kind: "before",
+ cursor: decodeCursor(bannerWin.before!)!,
+ limit: 1,
+ });
+ expect(firstWin.prior.turns).toBe(0);
+ expect(firstWin.before).toBeUndefined();
+ // The text and its two images stayed one unit.
+ expect(userTexts(firstWin.messages)).toEqual(["look"]);
+ expect(
+ firstWin.messages.filter((m) => (m.payload as { type?: string }).type === "image_url"),
+ ).toHaveLength(2);
+ });
+
+ it("prior stats: finished-Task elapsed, session/context token readings", async () => {
+ await writeTraceFile(root, P, A, "2026-07-20", S, 1, [
+ sessionMeta(metaPayload()),
+ ...turn(0, 1, 1000), // request_begin 10:00:01 → request_end 10:00:03 = 2s... elapsed = lastReqEnd - firstMsg(q1 at 10:00:00) = 3s
+ ...turn(1, 2, 2000),
+ ...turn(2, 3, 3000),
+ ]);
+ const tail = await service.readMessagesPage(P, A, S, { kind: "tail", limit: 1 });
+ // Web semantics: a turn's elapsed = last request_end − its first message = 3s each.
+ expect(tail.prior.elapsedMs).toBe(2 * 3000);
+ expect(tail.prior.sessionTokens).toBe(2000); // last session.total before the window
+ expect(tail.prior.contextTokens).toBe(102); // last request.total before the window (turn(…, 2) writes 100+2)
+ expect(tail.prior.subagentTokens).toBe(0);
+ });
+
+ it("subagent pointers expand only inside the window; earlier children feed prior.subagentTokens without appearing", async () => {
+ const child2 = "session-2026-07-20-10-02-00-eeff0003";
+ await writeTraceFile(root, P, A, "2026-07-20", S, 1, [
+ sessionMeta(metaPayload()),
+ // Turn 1 spawns CHILD.
+ at("2026-07-20T10:00:00.000Z", userText("q1")),
+ at("2026-07-20T10:00:01.000Z", requestBegin()),
+ at(
+ "2026-07-20T10:00:02.000Z",
+ toolCall({ name: "run_subagent", arguments: "{}", toolCallId: "c1" }),
+ ),
+ at("2026-07-20T10:00:03.000Z", subagentEvent(CHILD)),
+ at("2026-07-20T10:00:04.000Z", requestEnd("completed")),
+ at("2026-07-20T10:00:05.000Z", toolCallOutput({ output: "done", toolCallId: "c1" })),
+ at("2026-07-20T10:00:06.000Z", tokenUsage(counts(1000), counts(100))),
+ // Turn 2 spawns child2.
+ at("2026-07-20T10:01:00.000Z", userText("q2")),
+ at("2026-07-20T10:01:01.000Z", requestBegin()),
+ at(
+ "2026-07-20T10:01:02.000Z",
+ toolCall({ name: "run_subagent", arguments: "{}", toolCallId: "c2" }),
+ ),
+ at("2026-07-20T10:01:03.000Z", subagentEvent(child2)),
+ at("2026-07-20T10:01:04.000Z", requestEnd("completed")),
+ at("2026-07-20T10:01:05.000Z", toolCallOutput({ output: "done", toolCallId: "c2" })),
+ at("2026-07-20T10:01:06.000Z", tokenUsage(counts(2000), counts(120))),
+ ]);
+ await writeTraceFile(root, P, A, "2026-07-20", CHILD, 1, [
+ sessionMeta(metaPayload({ session_id: CHILD })),
+ at("2026-07-20T10:00:03.500Z", assistantText("child says")),
+ at("2026-07-20T10:00:03.800Z", tokenUsage(counts(400), counts(400))),
+ ]);
+ await writeTraceFile(root, P, A, "2026-07-20", child2, 1, [
+ sessionMeta(metaPayload({ session_id: child2 })),
+ at("2026-07-20T10:01:03.500Z", assistantText("child2 says")),
+ at("2026-07-20T10:01:03.800Z", tokenUsage(counts(70), counts(70))),
+ ]);
+
+ const tail = await service.readMessagesPage(P, A, S, { kind: "tail", limit: 1 });
+ // The window (turn 2) expands child2 in place, origin-tagged, pointer replaced.
+ const origins = tail.messages.filter((m) => m.origin !== undefined);
+ expect(origins.length).toBeGreaterThan(0);
+ for (const m of origins) expect(m.origin).toEqual([child2]);
+ expect(tail.messages.some((m) => (m.payload as { type?: string }).type === "subagent")).toBe(
+ false,
+ );
+ // CHILD (turn 1) is NOT in the window — its usage rides prior.subagentTokens instead.
+ expect(tail.messages.some((m) => textOf(m) === "child says")).toBe(false);
+ expect(tail.prior.subagentTokens).toBe(400);
+
+ // The older window then expands CHILD with the exact shape the full path produces.
+ const older = await service.readMessagesPage(P, A, S, {
+ kind: "before",
+ cursor: decodeCursor(tail.before!)!,
+ limit: 10,
+ });
+ const full = await service.readMessages(P, A, S);
+ expect([...older.messages, ...tail.messages]).toEqual(full);
+ });
+
+ it("shard-read discipline: after priming, old-window requests never read the newest shard and tail requests never read old shards", async () => {
+ await writeTraceFile(root, P, A, "2026-07-20", S, 1, [
+ sessionMeta(metaPayload()),
+ ...turn(0, 1, 1000),
+ ...turn(1, 2, 2000),
+ ]);
+ await writeTraceFile(root, P, A, "2026-07-21", S, 2, [
+ sessionMeta(metaPayload()),
+ ...turn(2, 3, 3000),
+ ]);
+ await writeTraceFile(root, P, A, "2026-07-21", S, 3, [
+ sessionMeta(metaPayload()),
+ ...turn(3, 4, 4000),
+ ...turn(4, 5, 5000),
+ ]);
+
+ // Priming: the first windowed read backfills the per-shard prefix cache (reads old shards once).
+ const primed = await service.readMessagesPage(P, A, S, { kind: "tail", limit: 1 });
+ expect(userTexts(primed.messages)).toEqual(["q5"]);
+
+ // A tail request now touches ONLY the newest shard.
+ harness.shardReads.length = 0;
+ await service.readMessagesPage(P, A, S, { kind: "tail", limit: 1 });
+ expect(harness.shardReads).toHaveLength(1);
+ expect(harness.shardReads[0]).toContain(`${S}_003.jsonl`);
+
+ // An old-window request touches ONLY its own shard — never the newest one.
+ harness.shardReads.length = 0;
+ const older = await service.readMessagesPage(P, A, S, {
+ kind: "before",
+ cursor: { fileIndex: 2, ordinal: 1 },
+ limit: 1,
+ });
+ expect(userTexts(older.messages)).toEqual(["q2"]);
+ expect(harness.shardReads.every((p) => !p.includes(`${S}_003.jsonl`))).toBe(true);
+ expect(harness.shardReads.some((p) => p.includes(`${S}_001.jsonl`))).toBe(true);
+ });
+
+ it("cursor edge cases: unknown shard yields an empty end-of-history page; empty sessions page cleanly", async () => {
+ expect(await service.readMessagesPage(P, A, S, { kind: "tail", limit: 5 })).toEqual({
+ messages: [],
+ prior: { turns: 0, subagentTokens: 0, elapsedMs: 0, sessionTokens: 0, contextTokens: 0 },
+ });
+ await writeTraceFile(root, P, A, "2026-07-20", S, 1, [
+ sessionMeta(metaPayload()),
+ ...turn(0, 1, 1000),
+ ]);
+ const gone = await service.readMessagesPage(P, A, S, {
+ kind: "before",
+ cursor: { fileIndex: 9, ordinal: 4 },
+ limit: 5,
+ });
+ expect(gone.messages).toEqual([]);
+ expect(gone.before).toBeUndefined();
+ // Round-trip of the cursor encoding itself.
+ expect(decodeCursor(encodeCursor({ fileIndex: 12, ordinal: 345 }))).toEqual({
+ fileIndex: 12,
+ ordinal: 345,
+ });
+ expect(decodeCursor("12:")).toBeNull();
+ expect(decodeCursor("a:b")).toBeNull();
+ });
+
+ it("tail covering the whole transcript returns everything with no cursor and equals the full read", async () => {
+ await writeTraceFile(root, P, A, "2026-07-20", S, 1, [
+ sessionMeta(metaPayload()),
+ ...turn(0, 1, 1000),
+ ...turn(1, 2, 2000),
+ ]);
+ const tail = await service.readMessagesPage(P, A, S, { kind: "tail", limit: 50 });
+ expect(tail.before).toBeUndefined();
+ expect(tail.prior.turns).toBe(0);
+ expect(tail.messages).toEqual(await service.readMessages(P, A, S));
+ });
+});
diff --git a/packages/web/src/api/endpoints.ts b/packages/web/src/api/endpoints.ts
index fc6ebcef..19fdb271 100644
--- a/packages/web/src/api/endpoints.ts
+++ b/packages/web/src/api/endpoints.ts
@@ -306,17 +306,32 @@ export const patchSession = (sessionId: string, body: SessionPatchRequest) =>
export const deleteSession = (sessionId: string) =>
apiFetch<void>(`/api/sessions/${encodeURIComponent(sessionId)}`, { method: "DELETE" });
+/** Windowed history request: the newest N units (tail), or the N units before a cursor. */
+export type MessagesPageQuery =
+ { kind: "tail"; limit: number } | { kind: "before"; cursor: string; limit: number };
+
/**
* History rebuild. Carries the server's clock at read time (see ApiFetchMeta.serverNowMs)
* alongside the messages: a Task still running has no Trace entry for the event currently in
* flight, so its elapsed can only be measured by differencing this against the Task's first
* message timestamp — both server-side values, so no client clock offset enters the result
* (see pushMessages).
+ *
+ * With `page`, requests a WINDOW instead of the full transcript (tail-first loading /
+ * scroll-up backfill — see stream-controller): the response then carries
+ * `MessagesResponse.page`. Omitted = the legacy full read (the resync fallback path).
*/
-export const getMessages = (sessionId: string) =>
- apiFetchWithMeta<MessagesResponse>(
- `/api/sessions/${encodeURIComponent(sessionId)}/messages`,
+export const getMessages = (sessionId: string, page?: MessagesPageQuery) => {
+ const qs =
+ page === undefined
+ ? ""
+ : page.kind === "tail"
+ ? `?tailLimit=${page.limit}`
+ : `?before=${encodeURIComponent(page.cursor)}&limit=${page.limit}`;
+ return apiFetchWithMeta<MessagesResponse>(
+ `/api/sessions/${encodeURIComponent(sessionId)}/messages${qs}`,
).then(({ data, serverNowMs }) => ({ ...data, serverNowMs }));
+};
// Task execution, approval, abort, compaction ------------------------------------------------------
diff --git a/packages/web/src/features/chat/chat-page.tsx b/packages/web/src/features/chat/chat-page.tsx
index 19e09897..f8fd042a 100644
--- a/packages/web/src/features/chat/chat-page.tsx
+++ b/packages/web/src/features/chat/chat-page.tsx
@@ -289,16 +289,43 @@ export function ChatPage() {
discard: discardSessionDraft,
} = useSessionDraft(selected?.sessionId ?? null);
+ // The rendered transcript: backfilled older windows (frozen items, negative ids) ahead
+ // of the live tail model's items. Version keys the memo — a prepend bumps it.
+ const allItems = useMemo(
+ () =>
+ stream.prefixItems.length > 0
+ ? [...stream.prefixItems, ...stream.model.items]
+ : stream.model.items,
+ // eslint-disable-next-line react-hooks/exhaustive-deps
+ [stream.version, routeSessionId],
+ );
// Derivations over the stream items (the model mutates in place, so `version` — its own
// repaint signal — keys the memos; the session id covers a switch racing a same-valued
- // version): the composer's ↑/↓ recall list and the left outline's entries.
+ // version): the composer's ↑/↓ recall list and the left outline's entries. Both read the
+ // LOADED transcript (prefix included), so backfilling extends recall and the index alike.
const inputHistory = useMemo(
- () => buildInputHistory(stream.model.items),
+ () => buildInputHistory(allItems),
// eslint-disable-next-line react-hooks/exhaustive-deps
[stream.version, routeSessionId],
);
const outline = useMemo(
- () => buildOutline(stream.model.items),
+ () => buildOutline(allItems),
+ // eslint-disable-next-line react-hooks/exhaustive-deps
+ [stream.version, routeSessionId],
+ );
+ // The subagents panel's model view: the live model, with backfilled windows' items and
+ // nested subagent models merged in — a chip clicked on a backfilled turn must still
+ // resolve its historical Task slice and child conversation. Scalar fields snapshot per
+ // version, which is exactly as fresh as everything else the panel renders.
+ const panelModel = useMemo<StreamModel>(
+ () =>
+ stream.prefixItems.length > 0 || stream.prefixSubagents.size > 0
+ ? {
+ ...stream.model,
+ items: [...allItems],
+ subagents: new Map([...stream.prefixSubagents, ...stream.model.subagents]),
+ }
+ : stream.model,
// eslint-disable-next-line react-hooks/exhaustive-deps
[stream.version, routeSessionId],
);
@@ -347,6 +374,10 @@ export function ChatPage() {
// dot still signal), and never re-triggers an already-open panel (that would yank a pinned
// historical graph back to the latest Task); the tracker consumes the attempt regardless.
const panelTaskScopeRef = useRef(createPanelTaskScope());
+ // Deliberately the LIVE model's items only (never the backfilled prefix): the tracker
+ // reads an INCREASE as "the user started a new Task", and a scroll-up backfill growing
+ // the count would spuriously re-arm the auto-open mid-conversation. The latest Task
+ // always lives in the live tail window, so live-only loses nothing.
const taskCount = taskStartCount(stream.model.items);
const liveSpawn = stream.taskState !== "idle" && latestTaskHasSubagent(stream.model);
useEffect(() => {
@@ -1087,6 +1118,7 @@ export function ChatPage() {
{!railFit.shown && (
<OutlineMenuButton
entries={outline}
+ turnOffset={stream.outlineOffset}
scrollRef={streamScrollRef}
running={stream.taskState !== "idle"}
/>
@@ -1240,16 +1272,27 @@ export function ChatPage() {
</div>
) : (
<MessageStream
- items={stream.model.items}
+ items={allItems}
version={stream.version}
ctx={ctx}
scrollElRef={streamScrollRef}
+ // Scroll-up backfill of older history windows (tail-first
+ // loading): near-top scrolling prepends the previous window,
+ // scroll position anchored (see MessageStream).
+ older={{
+ hasMore: stream.older.hasMore,
+ loading: stream.older.loading,
+ error: stream.older.error,
+ prependedCount: stream.prefixItems.length,
+ onLoad: stream.loadOlder,
+ }}
// Tick-rail minimap over the stream's left gutter (zero layout
// width; hides itself when the gutter is too narrow or the
// pointer can't hover).
outline={
<ConversationOutline
entries={outline}
+ turnOffset={stream.outlineOffset}
version={stream.version}
scrollRef={streamScrollRef}
running={stream.taskState !== "idle"}
@@ -1289,7 +1332,9 @@ export function ChatPage() {
<SubagentsPanel
session={selected}
panel={subagentsPanel}
- model={stream.model}
+ // The merged view (backfilled windows included): a chip on an older turn keeps
+ // its historical graph and child conversation reachable after pagination.
+ model={panelModel}
version={stream.version}
taskRunning={stream.taskState !== "idle"}
ctx={ctx}
diff --git a/packages/web/src/features/chat/conversation-outline.tsx b/packages/web/src/features/chat/conversation-outline.tsx
index aafebf0f..11d903a1 100644
--- a/packages/web/src/features/chat/conversation-outline.tsx
+++ b/packages/web/src/features/chat/conversation-outline.tsx
@@ -41,7 +41,8 @@ import { Dropdown } from "../../components/ui/dropdown";
import { GlyphIcon } from "../../components/ui/glyph-icon";
import type { OutlineEntry } from "./outline-model";
import {
- OUTLINE_MIN_TURNS,
+ globalTurnNumber,
+ outlineVisible,
previewText,
railTickPitch,
railWindowHalf,
@@ -202,12 +203,20 @@ function answerPreview(
export function ConversationOutline({
entries,
+ turnOffset = 0,
version,
scrollRef,
running,
fit,
}: {
entries: OutlineEntry[];
+ /**
+ * Turns that exist BEFORE the loaded history window (windowed loading): added to every
+ * tick's global turn number, counted toward the visibility gate, and >0 keeps the
+ * "more above" edge dots on — numbering never lies about unloaded turns, and the rail
+ * signals that scrolling up will reveal them.
+ */
+ turnOffset?: number;
/** Stream repaint signal: re-runs the scrollspy as content grows or the stream remounts. */
version: number;
/** MessageStream's scroll container (null while the stream isn't mounted, e.g. the empty greeting). */
@@ -227,7 +236,7 @@ export function ConversationOutline({
// cheap, and keying on version also re-binds after the stream remounts on a session switch.
useEffect(() => {
const el = scrollRef.current;
- if (!fit.shown || !el || entries.length < OUTLINE_MIN_TURNS) return;
+ if (!fit.shown || !el || !outlineVisible(turnOffset, entries.length)) return;
const ids = new Set(entries.map((entry) => entry.anchorId));
let raf: number | null = null;
const compute = () => {
@@ -246,9 +255,11 @@ export function ConversationOutline({
};
// `entries` is rebuilt per version; length + version cover it.
// eslint-disable-next-line react-hooks/exhaustive-deps
- }, [fit.shown, scrollRef, entries.length, version]);
+ }, [fit.shown, scrollRef, entries.length, turnOffset, version]);
- if (!fit.shown || entries.length < OUTLINE_MIN_TURNS) return null;
+ // The gate counts the WHOLE conversation (loaded + unloaded turns): a long session
+ // whose tail window happens to hold few entries still deserves its index.
+ if (!fit.shown || !outlineVisible(turnOffset, entries.length)) return null;
/** Tick center Y relative to the rail overlay (the preview card anchors to it, clamped in render). */
const tickTop = (e: MouseEvent<HTMLElement> | FocusEvent<HTMLElement>) => {
@@ -291,7 +302,9 @@ export function ConversationOutline({
inside the rail by construction, and this guarantees a mismeasure still can't
push ticks (which take pointer events) out over the toolbar or composer. */}
<div className="max-h-full overflow-hidden">
- {start > 0 && <RailOverflowMark edge="above" />}
+ {/* "More above" also covers turns not yet LOADED (turnOffset > 0): the dots tell
+ the same story either way — earlier turns exist beyond the rendered ticks. */}
+ {(start > 0 || turnOffset > 0) && <RailOverflowMark edge="above" />}
{visible.map((entry, i) => {
const active = entry.anchorId === activeId;
return (
@@ -300,10 +313,10 @@ export function ConversationOutline({
type="button"
data-outline-tick={entry.anchorId}
aria-current={active || undefined}
- // Global turn number (start + i): the window changes which ticks render,
- // never how a turn is numbered.
+ // Global turn number (turnOffset + start + i): neither the sliding window
+ // nor a partially-loaded history changes how a turn is numbered.
aria-label={S.chat.outlineTickLabel(
- start + i + 1,
+ globalTurnNumber(turnOffset, start + i),
entry.question || S.chat.outlineNoText,
)}
style={{ height: pitch }}
@@ -373,17 +386,20 @@ export function ConversationOutline({
*/
export function OutlineMenuButton({
entries,
+ turnOffset = 0,
scrollRef,
running,
}: {
entries: OutlineEntry[];
+ /** Turns before the loaded window (windowed loading): gates visibility on the WHOLE conversation; the list itself shows loaded turns only. */
+ turnOffset?: number;
scrollRef: RefObject<HTMLDivElement | null>;
running: boolean;
}) {
const [open, setOpen] = useState(false);
const [activeId, setActiveId] = useState<number | null>(null);
// Same gate as the rail: with this few turns neither shape earns its place.
- if (entries.length < OUTLINE_MIN_TURNS) return null;
+ if (!outlineVisible(turnOffset, entries.length)) return null;
const setOpenComputing = (next: boolean) => {
if (next && scrollRef.current) {
diff --git a/packages/web/src/features/chat/message-stream.tsx b/packages/web/src/features/chat/message-stream.tsx
index 8b2019b6..7effe7d3 100644
--- a/packages/web/src/features/chat/message-stream.tsx
+++ b/packages/web/src/features/chat/message-stream.tsx
@@ -155,12 +155,29 @@ export function MessageItems({ items, ctx }: { items: ChatItem[]; ctx: StreamRen
return <>{nodes}</>;
}
+/** Scroll-up backfill wiring (windowed history): state + trigger for the top-of-stream affordance. */
+export interface OlderHistoryControls {
+ /** Older windows exist beyond the loaded history (scrolling near the top triggers onLoad). */
+ hasMore: boolean;
+ /** A backfill request is in flight (spinner row). */
+ loading: boolean;
+ /** The last backfill failed (retry row); null = fine. */
+ error: string | null;
+ /** Number of windows already prepended: the prepend signal for scroll anchoring, and >0 gates the beginning-of-history marker (a session that fit one window shows no extra chrome). */
+ prependedCount: number;
+ onLoad: () => void;
+}
+
+/** Distance from the top (px) at which scrolling starts fetching the previous history window. */
+const OLDER_TRIGGER_PX = 300;
+
export function MessageStream({
items,
version,
ctx,
scrollElRef,
outline,
+ older,
}: {
items: ChatItem[];
/** View-model version number (a repaint signal for in-place updates that also drives auto-scroll). */
@@ -174,6 +191,8 @@ export function MessageStream({
* and anchor its absolute positioning to this wrapper, which only this component owns.
*/
outline?: ReactNode;
+ /** Scroll-up backfill of older history windows; omitted = the whole transcript is loaded (no top affordance). */
+ older?: OlderHistoryControls;
}) {
const scrollRef = useRef<HTMLDivElement>(null);
// An upward-swipe intent immediately exits auto-follow; scrolling back near the bottom resumes it — see stream-follow.ts (#75) for the exact rule.
@@ -220,6 +239,19 @@ export function MessageStream({
);
};
+ /** Held refs for prepend scroll anchoring (see the layout effect below). */
+ const olderRef = useRef(older);
+ olderRef.current = older;
+ const lastPrependedRef = useRef(older?.prependedCount ?? 0);
+ const lastHeightRef = useRef(0);
+
+ /** Near the top of loaded history: fetch the previous window (loading/error states gate re-triggering; the retry row is click-driven). */
+ const maybeLoadOlder = (el: HTMLDivElement) => {
+ const o = olderRef.current;
+ if (!o || !o.hasMore || o.loading || o.error !== null) return;
+ if (el.scrollTop < OLDER_TRIGGER_PX) o.onLoad();
+ };
+
const onScroll = () => {
const el = scrollRef.current;
if (!el) return;
@@ -234,6 +266,7 @@ export function MessageStream({
scrollHeight: el.scrollHeight,
clientHeight: el.clientHeight,
});
+ maybeLoadOlder(el);
syncJump();
};
@@ -242,11 +275,24 @@ export function MessageStream({
// during the animated return — the glide owns the scroll position until it arrives.
useLayoutEffect(() => {
const el = scrollRef.current;
+ // Prepend scroll anchoring: when older windows land ABOVE the viewport, keep the
+ // message the user was reading exactly where it was by offsetting scrollTop by the
+ // content growth (same pre-paint timing as the stick snap, so nothing flashes).
+ // Keyed on the prepend count — ordinary streaming growth at the bottom must not
+ // shift the view. lastHeightRef is refreshed every commit, so at the prepend commit
+ // it still holds the pre-prepend height. Skipped while sticking (the snap below
+ // owns the position; a prepend while stuck at the bottom cannot move the tail).
+ const prepended = older?.prependedCount ?? 0;
+ if (el && prepended > lastPrependedRef.current && !follow.stick && !returningRef.current) {
+ el.scrollTop += el.scrollHeight - lastHeightRef.current;
+ }
+ lastPrependedRef.current = prepended;
+ if (el) lastHeightRef.current = el.scrollHeight;
if (el && follow.stick && !returningRef.current) el.scrollTop = el.scrollHeight;
syncJump();
// syncJump is recreated per render; the effect intentionally keys on stream growth only.
// eslint-disable-next-line react-hooks/exhaustive-deps
- }, [version, follow]);
+ }, [version, follow, older?.prependedCount]);
/** Back-to-bottom: glide down to the live bottom (reduced motion gets an instant jump); follow re-engages on arrival. */
const jumpToLatest = () => {
@@ -316,6 +362,32 @@ export function MessageStream({
className="anim-fade h-full overflow-y-auto px-4 py-4 md:px-6"
>
<div className="mx-auto max-w-3xl">
+ {/* Top-of-history affordance: spinner while the previous window loads, a click-to-retry
+ row after a failure, and — once at least one window was backfilled — a quiet
+ beginning-of-conversation marker when there is nothing older. Idle-with-more shows
+ nothing: scrolling near the top triggers the fetch by itself. */}
+ {older && items.length > 0 && (
+ <div className="flex justify-center pb-2">
+ {older.loading ? (
+ <span className="flex items-center gap-2 py-1 text-xs text-gray-400 dark:text-gray-500">
+ <span className="inline-block h-3 w-3 animate-spin rounded-full border-2 border-gray-400 border-t-transparent" />
+ {S.chat.loadingEarlier}
+ </span>
+ ) : older.error !== null ? (
+ <button
+ type="button"
+ onClick={older.onLoad}
+ className="py-1 text-xs text-red-600 transition-colors duration-150 hover:text-red-700 dark:text-red-400 dark:hover:text-red-300"
+ >
+ {S.chat.loadEarlierRetry}
+ </button>
+ ) : !older.hasMore && older.prependedCount > 0 ? (
+ <span className="py-1 text-xs text-gray-400 dark:text-gray-500">
+ {S.chat.historyBeginning}
+ </span>
+ ) : null}
+ </div>
+ )}
{items.length === 0 ? (
<EmptyState title={S.chat.emptyStream} />
) : (
diff --git a/packages/web/src/features/chat/outline-model.ts b/packages/web/src/features/chat/outline-model.ts
index 08e25128..4fdfd14b 100644
--- a/packages/web/src/features/chat/outline-model.ts
+++ b/packages/web/src/features/chat/outline-model.ts
@@ -36,6 +36,24 @@ const ANSWER_CAP = 500;
*/
export const OUTLINE_MIN_TURNS = 5;
+/**
+ * With windowed history loading, entries built from the loaded items are only the tail of
+ * the conversation: `turnOffset` (MessagesPageInfo.earlierTurns — the server counts with
+ * the same entry rule buildOutline applies; the two must stay in step) is the number of
+ * turns that exist before them. These two helpers are the ONLY places that combine the
+ * offset with loaded-entry indices, so numbering can never drift between the shapes.
+ */
+
+/** Global 1-based turn number of loaded entry `index` (its position in the loaded entries array). */
+export function globalTurnNumber(turnOffset: number, index: number): number {
+ return turnOffset + index + 1;
+}
+
+/** Whether the outline earns its place: the gate counts the WHOLE conversation — unloaded earlier turns included — never just the loaded window. */
+export function outlineVisible(turnOffset: number, loadedCount: number): boolean {
+ return turnOffset + loadedCount >= OUTLINE_MIN_TURNS;
+}
+
/** Rail window half-widths: at most this many ticks render before/after the active one. */
export const OUTLINE_WINDOW_BEFORE = 20;
export const OUTLINE_WINDOW_AFTER = 20;
diff --git a/packages/web/src/features/chat/use-session-stream.ts b/packages/web/src/features/chat/use-session-stream.ts
index 7ba5932a..3f0e9a63 100644
--- a/packages/web/src/features/chat/use-session-stream.ts
+++ b/packages/web/src/features/chat/use-session-stream.ts
@@ -24,19 +24,37 @@ import type {
import { getGoal, getMe, getMessages } from "../../api/endpoints";
import { openSessionStream } from "../../api/sse";
import { createStreamController } from "../../lib/omni/stream-controller";
-import type { PendingApproval, StreamController } from "../../lib/omni/stream-controller";
+import type {
+ OlderHistoryState,
+ PendingApproval,
+ StreamController,
+} from "../../lib/omni/stream-controller";
import { createStreamModel } from "../../lib/omni/stream-model";
-import type { StreamModel } from "../../lib/omni/stream-model";
+import type { ChatItem, StreamModel } from "../../lib/omni/stream-model";
import type { GoalBannerState } from "./goal-use";
-export type { PendingApproval } from "../../lib/omni/stream-controller";
+export type { OlderHistoryState, PendingApproval } from "../../lib/omni/stream-controller";
/** Minimum spacing between version commits: below one frame at 8fps, invisible as staleness, but ~8× fewer full re-parses of the growing message during a fast large-code stream. */
const BUMP_MIN_INTERVAL_MS = 120;
export interface SessionStreamState {
- /** View model (updated in place; version bump triggers re-render). */
+ /** View model (updated in place; version bump triggers re-render): the LIVE tail window. */
model: StreamModel;
+ /**
+ * Backfilled older-window items, oldest first — the transcript renders
+ * `[...prefixItems, ...model.items]`. Empty until the user scrolls up past the tail
+ * window (see loadOlder); ids are negative and unique, so keys/anchors stay clean.
+ */
+ prefixItems: readonly ChatItem[];
+ /** Nested subagent models owned by backfilled windows (the subagents panel merges them with model.subagents). */
+ prefixSubagents: ReadonlyMap<string, StreamModel>;
+ /** Outline entries existing before the oldest loaded window (global turn-numbering offset). */
+ outlineOffset: number;
+ /** Scroll-up backfill state (top affordance: spinner / retry / beginning-of-history). */
+ older: OlderHistoryState;
+ /** Prepend the previous history window (triggered near the top of the loaded transcript). */
+ loadOlder: () => void;
version: number;
/** True until history finishes loading. */
loading: boolean;
@@ -79,6 +97,9 @@ export interface SessionStreamState {
}
const EMPTY_PENDING: ReadonlyMap<string, PendingApproval> = new Map();
+const EMPTY_PREFIX: readonly ChatItem[] = [];
+const EMPTY_SUBAGENTS: ReadonlyMap<string, StreamModel> = new Map();
+const IDLE_OLDER: OlderHistoryState = { hasMore: false, loading: false, error: null };
export function useSessionStream(
sessionId: string | null,
@@ -208,8 +229,9 @@ export function useSessionStream(
const controller = createStreamController({
// The whole response rides through: `live` (in-progress stream tail) lets the
- // controller seed the currently streaming message after a reload (see stream-controller).
- loadMessages: () => getMessages(sessionId),
+ // controller seed the currently streaming message after a reload, and `page` (the
+ // windowed-history envelope) drives tail-first loading (see stream-controller).
+ loadMessages: (page) => getMessages(sessionId, page),
onTaskState: setTaskState,
onQueuedFollowUps: setQueuedFollowUps,
onPendingSteering: setPendingSteering,
@@ -269,6 +291,10 @@ export function useSessionStream(
void controllerRef.current?.retry();
}, []);
+ const loadOlder = useCallback(() => {
+ void controllerRef.current?.loadOlder();
+ }, []);
+
const dismissModelAuthDead = useCallback(() => {
const m = controllerRef.current?.model;
if (m && m.lastAuthFailureMs !== null) {
@@ -282,6 +308,11 @@ export function useSessionStream(
return {
model: controllerRef.current?.model ?? placeholderRef.current,
+ prefixItems: controllerRef.current?.prefixItems ?? EMPTY_PREFIX,
+ prefixSubagents: controllerRef.current?.prefixSubagents ?? EMPTY_SUBAGENTS,
+ outlineOffset: controllerRef.current?.outlineOffset ?? 0,
+ older: controllerRef.current?.older ?? IDLE_OLDER,
+ loadOlder,
version,
loading,
taskState,
diff --git a/packages/web/src/lib/omni/stream-controller.ts b/packages/web/src/lib/omni/stream-controller.ts
index f725e9f7..a220010d 100644
--- a/packages/web/src/lib/omni/stream-controller.ts
+++ b/packages/web/src/lib/omni/stream-controller.ts
@@ -34,6 +34,7 @@ import type { OmniMessage, ToolCallPayload } from "@prismshadow/penguin-core/omn
import type {
GoalServerEvent,
MessagesLiveTail,
+ MessagesPageInfo,
PendingSteeringInfo,
ServerEvent,
SessionStatus,
@@ -51,7 +52,8 @@ import {
pushMessages,
registerLocalDecision,
} from "./stream-model";
-import type { StreamModel } from "./stream-model";
+import type { ChatItem, StreamModel } from "./stream-model";
+import { seedPriorStats } from "./task-stats";
/** A single pending approval (keyed by approvalKey(origin, toolCallId)). */
export interface PendingApproval {
@@ -73,17 +75,45 @@ function parseEventId(id: string): { epoch: string; seq: number } | null {
return { epoch: id.slice(0, sep), seq };
}
+/** A windowed history request (mirrors the server's tailLimit / before params). */
+export type MessagesPageQuery =
+ { kind: "tail"; limit: number } | { kind: "before"; cursor: string; limit: number };
+
+/**
+ * Initial (tail) window size, in message-bearing units — one unit = one Task, opened by
+ * a user prompt (the server's cut rule; see MessagesPageInfo). 200 covers the vast
+ * majority of real sessions in a single request, so ordinary conversations still load
+ * whole exactly as before — only the pathological long tail (months-long sessions,
+ * agentic marathons) starts windowed, which is the point: their full-transcript reads
+ * were the unbounded memory/disk cost this pagination removes.
+ */
+export const TAIL_UNITS = 200;
+
+/** Scroll-up backfill window size: smaller than the tail so each prepend stays snappy. */
+export const OLDER_UNITS = 100;
+
+/**
+ * Item-id space reserved per prepended window. The live model numbers its items upward
+ * from 1; each prepended window numbers upward from its own NEGATIVE base, so ids stay
+ * unique across the concatenated view (React keys, outline anchors) without ever
+ * renumbering already-mounted items. A window holds at most a few thousand items —
+ * far under the span.
+ */
+const PREPEND_ID_SPAN = 1_000_000;
+
export interface StreamControllerDeps {
/**
* Fetch history messages (GET /api/sessions/:id/messages), including the live tail while
* running. `serverNowMs` is the server's clock at read time (the response's `Date` header);
* omitted/null just costs a running Task's header the time its in-flight event has taken so
- * far, which falls back to the Trace's own span (see pushMessages).
+ * far, which falls back to the Trace's own span (see pushMessages). `page` requests a
+ * WINDOW (the response then carries `page`); omitted = the legacy full transcript.
*/
- loadMessages: () => Promise<{
+ loadMessages: (page?: MessagesPageQuery) => Promise<{
messages: OmniMessage[];
live?: MessagesLiveTail;
serverNowMs?: number | null;
+ page?: MessagesPageInfo;
}>;
/** Authoritative running state from the stream (covers both the subscription snapshot and transition events). */
onTaskState: (state: SessionStatus) => void;
@@ -108,14 +138,37 @@ export interface StreamControllerDeps {
now?: () => number;
}
+/** Scroll-up backfill state (drives the stream's top affordance). */
+export interface OlderHistoryState {
+ /** Older windows exist beyond the loaded prefix. */
+ hasMore: boolean;
+ /** A backfill request is in flight. */
+ loading: boolean;
+ /** The last backfill failed (the affordance offers a retry); null = fine. */
+ error: string | null;
+}
+
export interface StreamController {
- /** The current view model (a resync rebuild swaps in a new object). */
+ /** The current view model (a resync rebuild swaps in a new object): the LIVE tail window. */
readonly model: StreamModel;
+ /**
+ * Items of the backfilled older windows, oldest first — render them immediately BEFORE
+ * `model.items`. Frozen once built (their Tasks are complete); item ids are negative
+ * and unique across windows, so the concatenated list keys/anchors cleanly.
+ */
+ readonly prefixItems: readonly ChatItem[];
+ /** Nested subagent models of the backfilled windows (merged view for the subagents panel; disjoint from model.subagents — a child session lives in exactly one window). */
+ readonly prefixSubagents: ReadonlyMap<string, StreamModel>;
+ /** Outline entries that exist before the OLDEST loaded window: the outline's global numbering offset. */
+ readonly outlineOffset: number;
+ readonly older: OlderHistoryState;
readonly pendingApprovals: ReadonlyMap<string, PendingApproval>;
- /** Load history for the first time (called once after connect-first). */
+ /** Load history for the first time (called once after connect-first): fetches the TAIL window. */
load: () => Promise<void>;
/** Retry entry point after a history load failure (keeps the buffer, refetches history). */
retry: () => Promise<void>;
+ /** Prepend the previous window (scroll-up backfill); no-op while loading, failed, at the beginning, or before the initial load settled. */
+ loadOlder: () => Promise<void>;
/** SSE OmniMessage entry point (`eventId`: the SSE event id, used for live-tail cursor alignment). */
handleOmni: (msg: OmniMessage, eventId?: string | null) => void;
/** SSE server-event entry point (`eventId`: same as handleOmni). */
@@ -146,6 +199,49 @@ export function createStreamController(deps: StreamControllerDeps): StreamContro
/** Whether the most recent load failed (retry only takes effect after a failure, to avoid mistakenly replaying history). */
let failed = false;
+ // —— Windowed-history state (tail-first load + scroll-up backfill) ——
+ /** Items of backfilled older windows, oldest first (frozen; rendered before model.items). */
+ let prefixItems: ChatItem[] = [];
+ /** Nested subagent models owned by backfilled windows. */
+ let prefixSubagents = new Map<string, StreamModel>();
+ /** How many windows have been prepended (derives each one's negative item-id base). */
+ let prependCount = 0;
+ /** Cursor for the NEXT older window (= the oldest loaded window's start); null = beginning reached or full transcript loaded. */
+ let nextBefore: string | null = null;
+ /**
+ * The LIVE tail window's start cursor, as returned by the last tail fetch — the resync
+ * continuity anchor: a refetched tail whose start cursor equals this provably abuts the
+ * retained prefix. Null = the tail reaches the beginning (or the transcript was loaded
+ * whole), in which case there is no prefix to splice against.
+ */
+ let tailStartCursor: string | null = null;
+ const older: OlderHistoryState = { hasMore: false, loading: false, error: null };
+ /** Outline entries before the OLDEST loaded window (the outline's numbering offset). */
+ let outlineOffset = 0;
+
+ /** Reset all windowed-history bookkeeping to "everything loaded from the beginning". */
+ const resetPaging = (): void => {
+ prefixItems = [];
+ prefixSubagents = new Map();
+ prependCount = 0;
+ nextBefore = null;
+ tailStartCursor = null;
+ older.hasMore = false;
+ older.loading = false;
+ older.error = null;
+ outlineOffset = 0;
+ };
+
+ /** Adopt a TAIL page's pagination envelope as the fresh baseline (initial load / prefix-dropping rebuild). */
+ const adoptTailPage = (page: MessagesPageInfo | undefined): void => {
+ resetPaging();
+ if (page === undefined) return; // full transcript: nothing older exists by definition
+ nextBefore = page.before ?? null;
+ tailStartCursor = page.before ?? null;
+ older.hasMore = page.before !== undefined;
+ outlineOffset = page.earlierTurns;
+ };
+
const clearPending = (): void => {
if (pending.size === 0) return;
pending.clear();
@@ -222,6 +318,32 @@ export function createStreamController(deps: StreamControllerDeps): StreamContro
}
};
+ /**
+ * resync_required decision tree — which refetch rebuilds the model. Resync means the
+ * SSE buffer was evicted and the transcript state is suspect, so every branch below
+ * chooses correctness over cleverness (ANY doubt falls back to the full read):
+ *
+ * 1. No backfilled prefix → refetch the TAIL window. Identical in shape to the
+ * initial load: the window is a disk-true suffix, the buffered events replay
+ * with overlap dedup, and the live attachment weaves in under the existing
+ * channel-epoch guard (weaveLiveTail skips seeding when the cursor's epoch
+ * doesn't match the events seen on this connection).
+ * 2. Prefix retained → refetch the TAIL window and splice ONLY when continuity is
+ * provable: the refetched window's start cursor must EQUAL the recorded start
+ * of the current tail window (cursors are (shard, ordinal) positions on
+ * immutable storage, so equality proves the new tail abuts the prefix exactly —
+ * no gap, no overlap). Equality holds precisely when no new unit started since
+ * the last tail fetch, the common mid-Task resync.
+ * 3. Prefix retained but the refetched tail reaches the very beginning (no cursor)
+ * → the tail alone provably covers everything: drop the prefix and use it.
+ * 4. Anything else — the start cursor moved (new units arrived), the response
+ * carried no page envelope, or the tail fetch itself failed mid-decision —
+ * is doubt: fall back to the legacy FULL refetch (one complete transcript, no
+ * prefix, offsets zeroed). Slow but beyond suspicion.
+ *
+ * The decision runs inside load() (it needs the response); this entry only picks the
+ * request shape.
+ */
const rebuild = async (): Promise<void> => {
epoch += 1;
phase = "buffering";
@@ -238,7 +360,10 @@ export function createStreamController(deps: StreamControllerDeps): StreamContro
// the input for a skeleton, losing scroll position, expanded tool cards, and composer
// focus/draft.) Deltas arriving during the refetch are buffered and replayed on swap; the brief
// no-new-text pause is invisible next to a full teardown.
- await load(epoch, createStreamModel(localDecisions));
+ await load(epoch, createStreamModel(localDecisions), {
+ page: { kind: "tail", limit: TAIL_UNITS },
+ splice: prefixItems.length > 0,
+ });
};
/**
@@ -274,15 +399,45 @@ export function createStreamController(deps: StreamControllerDeps): StreamContro
return [...pre, ...seeds, ...post];
};
- const load = async (currentEpoch: number, freshModel?: StreamModel): Promise<void> => {
+ const load = async (
+ currentEpoch: number,
+ freshModel?: StreamModel,
+ opts: { page?: MessagesPageQuery; splice?: boolean } = {},
+ ): Promise<void> => {
try {
- const { messages, live, serverNowMs } = await deps.loadMessages();
+ let res = await deps.loadMessages(opts.page);
if (disposed || currentEpoch !== epoch) return;
+ if (opts.splice === true) {
+ // The resync decision tree's prefix-retained branches (see rebuild): splice only
+ // on exact cursor continuity; a beginning-reaching tail supersedes the prefix;
+ // everything else falls back to the full read within this same epoch (events
+ // keep buffering meanwhile).
+ const start = res.page?.before ?? null;
+ if (res.page !== undefined && start !== null && start === tailStartCursor) {
+ // Continuity proven: keep prefix and paging state exactly as they are.
+ } else if (res.page !== undefined && start === null) {
+ adoptTailPage(res.page); // tail covers everything: prefix dropped, provably complete
+ } else {
+ res = await deps.loadMessages();
+ if (disposed || currentEpoch !== epoch) return;
+ adoptTailPage(undefined); // full transcript: no prefix, no cursors
+ }
+ } else if (opts.page !== undefined) {
+ // Fresh tail baseline (initial load / retry): any previously-loaded prefix is
+ // superseded by the new window chain.
+ adoptTailPage(res.page);
+ } else {
+ adoptTailPage(undefined);
+ }
+ const { messages, live, serverNowMs } = res;
// Rebuild path: make the freshly-built model visible only now, atomically — the old model
// stayed on screen throughout the refetch above (see rebuild). Initial load / retry pass no
// freshModel and keep operating on the current model.
if (freshModel) model = freshModel;
const target = model;
+ // Windowed loads seed the stats accrued before the window, so header chips and
+ // per-turn cumulative rows equal a full load (see seedPriorStats).
+ if (res.page !== undefined) seedPriorStats(target.stats, res.page.prior);
pushMessages(target, messages, now(), serverNowMs ?? null);
const dedup = buildDedupIndex(messages, 100);
// Replay the buffer (events that arrived while fetching history), with dedup; while a
@@ -322,16 +477,79 @@ export function createStreamController(deps: StreamControllerDeps): StreamContro
}
};
+ /**
+ * Scroll-up backfill: fetch the window before the oldest loaded one and prepend it.
+ * The window's messages build a FRESH model (its own negative id base, priors seeded,
+ * finalizeHistory closing its last Task — complete by construction, since a newer
+ * window follows), whose items freeze into the prefix. Guarded to the live phase: a
+ * rebuild in flight owns the loading pipeline, and its epoch bump discards any
+ * backfill that raced it.
+ */
+ const loadOlder = async (): Promise<void> => {
+ if (disposed || phase !== "live" || failed) return;
+ if (older.loading || !older.hasMore || nextBefore === null) return;
+ const currentEpoch = epoch;
+ older.loading = true;
+ older.error = null;
+ deps.onModelChange();
+ try {
+ const res = await deps.loadMessages({
+ kind: "before",
+ cursor: nextBefore,
+ limit: OLDER_UNITS,
+ });
+ if (disposed || currentEpoch !== epoch) return;
+ // A before-request against a server without windowing support would return the
+ // full transcript with no envelope; prepending that would duplicate history.
+ if (res.page === undefined) throw new Error("windowed history not supported");
+ prependCount += 1;
+ const m = createStreamModel(localDecisions);
+ m.nextItemId = -prependCount * PREPEND_ID_SPAN;
+ seedPriorStats(m.stats, res.page.prior);
+ pushMessages(m, res.messages, now(), null);
+ finalizeHistory(m);
+ prefixItems = [...m.items, ...prefixItems];
+ // Child sessions live in exactly one window (a spawn is contained in its Task),
+ // so the merge is disjoint; newer windows' entries win defensively on a clash.
+ const mergedSubagents = new Map(m.subagents);
+ for (const [sid, sub] of prefixSubagents) mergedSubagents.set(sid, sub);
+ prefixSubagents = mergedSubagents;
+ nextBefore = res.page.before ?? null;
+ older.hasMore = res.page.before !== undefined;
+ outlineOffset = res.page.earlierTurns;
+ } catch (e) {
+ if (disposed || currentEpoch !== epoch) return;
+ older.error = e instanceof Error ? e.message : String(e);
+ } finally {
+ if (!disposed && currentEpoch === epoch) {
+ older.loading = false;
+ deps.onModelChange();
+ }
+ }
+ };
+
return {
get model() {
return model;
},
+ get prefixItems(): readonly ChatItem[] {
+ return prefixItems;
+ },
+ get prefixSubagents(): ReadonlyMap<string, StreamModel> {
+ return prefixSubagents;
+ },
+ get outlineOffset() {
+ return outlineOffset;
+ },
+ get older(): OlderHistoryState {
+ return older;
+ },
get pendingApprovals(): ReadonlyMap<string, PendingApproval> {
return pending;
},
load: () => {
epoch += 1;
- return load(epoch);
+ return load(epoch, undefined, { page: { kind: "tail", limit: TAIL_UNITS } });
},
retry: async () => {
if (disposed || !failed) return;
@@ -341,11 +559,15 @@ export function createStreamController(deps: StreamControllerDeps): StreamContro
// history straight onto it would duplicate the entire conversation (pushMessages appends with
// no id-dedup). load() swaps the fresh model in only once the refetch succeeds, then replays
// the still-accumulating buffer into it; localDecisions carry over via the shared set.
+ // The refetch is a fresh TAIL baseline: any retained prefix is superseded on success.
deps.onError(null);
deps.onLoading(true);
epoch += 1;
- await load(epoch, createStreamModel(localDecisions));
+ await load(epoch, createStreamModel(localDecisions), {
+ page: { kind: "tail", limit: TAIL_UNITS },
+ });
},
+ loadOlder,
handleOmni: (msg, eventId = null) => {
if (disposed) return;
if (eventId !== null) lastEventId = eventId;
diff --git a/packages/web/src/lib/omni/task-stats.ts b/packages/web/src/lib/omni/task-stats.ts
index 8a5ecbcf..96c7c128 100644
--- a/packages/web/src/lib/omni/task-stats.ts
+++ b/packages/web/src/lib/omni/task-stats.ts
@@ -139,6 +139,33 @@ export function createTaskStatsTracker(): TaskStatsTracker {
};
}
+/**
+ * Seed the tracker with the cumulative stats accrued BEFORE a partial history window
+ * (MessagesPageInfo.prior from a windowed GET /messages): finished-Task elapsed,
+ * subagent token totals, and the last session/context token readings. Applied before
+ * the window's messages replay, so header chips and per-turn cumulative rows land on
+ * the same figures a full-transcript load computes. sessionTotal/contextNow are only
+ * "last seen" fallbacks — any token_usage inside the window overwrites them; the
+ * elapsed/subagent/delta baselines genuinely accumulate on top.
+ */
+export function seedPriorStats(
+ t: TaskStatsTracker,
+ prior: {
+ subagentTokens: number;
+ elapsedMs: number;
+ sessionTokens: number;
+ contextTokens: number;
+ },
+): void {
+ t.subagentTotal = prior.subagentTokens;
+ t.sessionElapsedMs = prior.elapsedMs;
+ t.sessionTotal = prior.sessionTokens;
+ t.contextNow = prior.contextTokens;
+ // The first in-window stats row's context delta measures against the pre-window
+ // occupancy, not against zero.
+ t.contextAtLastStats = prior.contextTokens;
+}
+
/** This Task's bucketed accumulation (shared by main + subagent sessions; for real-time cost calc). */
function addBuckets(t: TaskStatsTracker, p: TokenUsagePayload): void {
t.taskCacheRead += p.request.cache_read;
diff --git a/packages/web/src/lib/strings-en.ts b/packages/web/src/lib/strings-en.ts
index 1975b552..7d806f92 100644
--- a/packages/web/src/lib/strings-en.ts
+++ b/packages/web/src/lib/strings-en.ts
@@ -758,6 +758,12 @@ Scenarios:
statusCompacting: "Compacting",
pendingApprovals: (n: number) => `${n} pending approval${n > 1 ? "s" : ""}`,
jumpToLatest: "Jump to latest",
+ /** Top-of-stream affordance while the previous history window is being fetched (scroll-up backfill). */
+ loadingEarlier: "Loading earlier messages…",
+ /** Top-of-stream affordance after a backfill failure: click to retry fetching the previous window. */
+ loadEarlierRetry: "Failed to load earlier messages — click to retry",
+ /** Top-of-stream marker once the loaded history reaches the very beginning (shown only after a backfill happened). */
+ historyBeginning: "Beginning of conversation",
/** Conversation minimap (tick rail over the stream's left gutter): rail aria-label. */
outlineTitle: "Outline",
/** Tick accessible name: turn number + the question (or the no-text placeholder). */
diff --git a/packages/web/src/lib/strings.ts b/packages/web/src/lib/strings.ts
index 806a0a49..3f288d3b 100644
--- a/packages/web/src/lib/strings.ts
+++ b/packages/web/src/lib/strings.ts
@@ -736,6 +736,12 @@ Benchmark:
statusCompacting: "压缩中",
pendingApprovals: (n: number) => `${n} 个待审批`,
jumpToLatest: "回到最新消息",
+ /** Top-of-stream affordance while the previous history window is being fetched (scroll-up backfill). */
+ loadingEarlier: "正在加载更早的对话…",
+ /** Top-of-stream affordance after a backfill failure: click to retry fetching the previous window. */
+ loadEarlierRetry: "更早的对话加载失败,点击重试",
+ /** Top-of-stream marker once the loaded history reaches the very beginning (shown only after a backfill happened). */
+ historyBeginning: "已是对话开头",
/** Conversation minimap (tick rail over the stream's left gutter): rail aria-label. */
outlineTitle: "对话索引",
/** Tick accessible name: turn number + the question (or the no-text placeholder). */
diff --git a/packages/web/test/outline-model.test.ts b/packages/web/test/outline-model.test.ts
index 0cab3cdd..29363601 100644
--- a/packages/web/test/outline-model.test.ts
+++ b/packages/web/test/outline-model.test.ts
@@ -8,11 +8,14 @@ import type { ChatItem } from "../src/lib/omni/stream-model";
import { handoffMessage } from "../src/features/chat/agent-handoff";
import { buildScheduledMessage } from "@prismshadow/penguin-core/markers";
import {
+ OUTLINE_MIN_TURNS,
OUTLINE_WINDOW_AFTER,
OUTLINE_WINDOW_BEFORE,
TICK_PITCH_MAX,
TICK_PITCH_MIN,
buildOutline,
+ globalTurnNumber,
+ outlineVisible,
previewText,
railTickPitch,
railWindowHalf,
@@ -162,6 +165,35 @@ describe("rail fit (pitch and height-adaptive window half-width)", () => {
});
});
+describe("windowed-history offset (globalTurnNumber / outlineVisible)", () => {
+ it("numbers loaded entries globally: offset (unloaded earlier turns) + loaded index + 1", () => {
+ // A conversation of 10 turns loaded from turn 8 on (server earlierTurns = 7): the
+ // three loaded entries must read 第 8/9/10 轮 — the window never renumbers.
+ const items: ChatItem[] = [
+ user("q8"),
+ assistant("a8"),
+ stats(),
+ user("q9"),
+ assistant("a9"),
+ stats(),
+ user("q10"),
+ ];
+ const entries = buildOutline(items);
+ expect(entries.map((_, i) => globalTurnNumber(7, i))).toEqual([8, 9, 10]);
+ // Without an offset the numbering degenerates to the classic 1-based index.
+ expect(globalTurnNumber(0, 0)).toBe(1);
+ });
+
+ it("the visibility gate counts the WHOLE conversation, not the loaded window", () => {
+ // Two loaded entries alone would hide the outline; 7 earlier turns make it a long
+ // conversation that deserves its index (with the earlier-turns hint shown).
+ expect(outlineVisible(0, 2)).toBe(false);
+ expect(outlineVisible(7, 2)).toBe(true);
+ expect(outlineVisible(0, OUTLINE_MIN_TURNS)).toBe(true);
+ expect(outlineVisible(OUTLINE_MIN_TURNS, 0)).toBe(true);
+ });
+});
+
describe("previewText", () => {
it("flattens markdown to one plain line", () => {
const md =
diff --git a/packages/web/test/stream-controller.test.ts b/packages/web/test/stream-controller.test.ts
index ab8933c2..4013e2fb 100644
--- a/packages/web/test/stream-controller.test.ts
+++ b/packages/web/test/stream-controller.test.ts
@@ -19,12 +19,13 @@ import {
import type { OmniMessage, TokenCounts } from "@prismshadow/penguin-core/omnimessage";
import type {
MessagesLiveTail,
+ MessagesPageInfo,
PendingSteeringInfo,
ServerEvent,
SessionStatus,
} from "@prismshadow/penguin-server/api";
-import { createStreamController } from "../src/lib/omni/stream-controller";
-import type { StreamController } from "../src/lib/omni/stream-controller";
+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, TaskStatsItem, ToolCallItem } from "../src/lib/omni/stream-model";
@@ -47,10 +48,13 @@ interface Harness {
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;
}
@@ -61,6 +65,7 @@ function createHarness(): Harness {
messages: OmniMessage[];
live?: MessagesLiveTail;
serverNowMs?: number | null;
+ page?: MessagesPageInfo;
}) => void;
reject: (e: unknown) => void;
}> = [];
@@ -68,15 +73,18 @@ function createHarness(): Harness {
const pendingSteering: PendingSteeringInfo[][] = [];
const errors: Array<string | null> = [];
const loadings: boolean[] = [];
+ const pageArgs: Array<MessagesPageQuery | undefined> = [];
let calls = 0;
const controller = createStreamController({
- loadMessages: () =>
+ 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),
@@ -94,16 +102,27 @@ function createHarness(): Harness {
errors,
loadings,
loadCalls: () => calls,
- resolveLoad: (messages, live, serverNowMs) =>
+ 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, 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"),
@@ -452,6 +471,198 @@ describe("live-tail seeding (reload mid-stream)", () => {
});
});
+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("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, 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);
+ 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("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("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();