diff --git a/docs/timeline-sync.md b/docs/timeline-sync.md index b0643b72e5..4fa2567210 100644 --- a/docs/timeline-sync.md +++ b/docs/timeline-sync.md @@ -65,9 +65,11 @@ Initialization timeouts guard lack of catch-up progress, not the full multi-page Opening or resuming an agent fetches the latest available turns with a soft target of 40 projected items. Backward pages and prompt-jump windows also include whole turns, including -all currently available rows of an active run. There is no per-turn cap: a large run can -exceed the target. Local history mounting uses the same boundaries so revealing older rows -does not change the collapse state of a turn already displayed. +all currently available rows of an active run. A large run can exceed the target. For a paged +request whose complete-turn reply cannot fit the wire message limit, the daemon falls back to +item pages with continuation cursors so the rest remains reachable. Local history mounting uses +turn boundaries so revealing older rows does not change the collapse state of a turn already +displayed. `wholeTurns` is a preference negotiated once at the client fetch boundary. Hosts advertising `features.wholeTurnTimeline` receive it; other hosts receive the existing item-based request. diff --git a/packages/server/src/server/agent/agent-timeline-store.test.ts b/packages/server/src/server/agent/agent-timeline-store.test.ts index 9ec4df4d55..8265411ac0 100644 --- a/packages/server/src/server/agent/agent-timeline-store.test.ts +++ b/packages/server/src/server/agent/agent-timeline-store.test.ts @@ -5,6 +5,94 @@ import { describe, expect, it } from "vitest"; import { selectReferenceProjectedTimelinePage } from "./test-utils/timeline-page-reference.js"; import type { AgentTimelineItem } from "./agent-sdk-types.js"; import { InMemoryAgentTimelineStore } from "./agent-timeline-store.js"; +import { selectTimelineResponseWithinFrameBudget } from "../session/timeline-frame-budget.js"; + +describe("whole-turn byte budget", () => { + function fixture() { + const store = new InMemoryAgentTimelineStore(); + store.initialize("agent", { epoch: "current" }); + for (let index = 1; index <= 8; index++) { + store.append( + "agent", + { type: "assistant_message", messageId: `item-${index}`, text: "\u20ac".repeat(180) }, + { turnId: "one-turn" }, + ); + } + return store; + } + + function request( + store: ReturnType, + options: { + maxBytes: number; + limit: number; + direction?: "before" | "after"; + cursor?: { epoch: string; seq: number }; + }, + ) { + return selectTimelineResponseWithinFrameBudget({ + wholeTurns: true, + limit: options.limit, + maxBytes: options.maxBytes, + select: ({ wholeTurns, limit }) => { + const { rows, ...page } = store.fetch("agent", { + direction: options.direction ?? "tail", + cursor: options.cursor, + wholeTurns, + limit, + }); + return { type: "fetch_agent_timeline_response", payload: { ...page, entries: rows } }; + }, + }).payload; + } + + it("keeps complete turns whenever they fit, and leaves explicit full reads unchanged", () => { + const store = fixture(); + expect(request(store, { maxBytes: 10000, limit: 2 }).entries.map((row) => row.seq)).toEqual([ + 1, 2, 3, 4, 5, 6, 7, 8, + ]); + expect(request(store, { maxBytes: 500, limit: 0 }).entries).toHaveLength(8); + }); + + it("splits an oversized turn into adjacent older pages without losing any entries", () => { + const store = fixture(); + let page = request(store, { maxBytes: 1300, limit: 2 }); + expect(page).toMatchObject({ startSeq: 8, endSeq: 8, hasOlder: true }); + const seen = page.entries.map((row) => row.seq); + for (let index = 7; index >= 1; index--) { + page = request(store, { + maxBytes: 1300, + limit: 2, + direction: "before", + cursor: { epoch: page.epoch, seq: page.startSeq! }, + }); + expect(page).toMatchObject({ startSeq: index, endSeq: index, hasOlder: index > 1 }); + seen.unshift(...page.entries.map((row) => row.seq)); + } + expect(seen).toEqual([1, 2, 3, 4, 5, 6, 7, 8]); + }); + + it("keeps the forward cursor on the oldest unsent part of an oversized turn", () => { + const store = fixture(); + let seq = 1; + for (let expected = 2; expected <= 8; expected++) { + const page = request(store, { + maxBytes: 1300, + limit: 2, + direction: "after", + cursor: { epoch: "current", seq }, + }); + expect(page).toMatchObject({ startSeq: expected, endSeq: expected, hasNewer: expected < 8 }); + seq = page.endSeq!; + } + }); + + it("reports when even a single row cannot fit", () => { + expect(() => request(fixture(), { maxBytes: 100, limit: 2 })).toThrow( + /timeline item exceeds the response size limit/i, + ); + }); +}); describe("InMemoryAgentTimelineStore", () => { it("resets stale forward cursors to complete available turns", () => { diff --git a/packages/server/src/server/session.ts b/packages/server/src/server/session.ts index 2bdad76ba3..9295262588 100644 --- a/packages/server/src/server/session.ts +++ b/packages/server/src/server/session.ts @@ -213,6 +213,7 @@ import { type SpeechModelsSessionOptions, } from "./session/speech/speech-models-session.js"; import { WorkspaceFilesSession } from "./session/files/workspace-files-session.js"; +import { selectTimelineResponseWithinFrameBudget } from "./session/timeline-frame-budget.js"; import { AgentConfigSession } from "./session/agent-config/agent-config-session.js"; import { ProjectConfigSession } from "./session/project-config/project-config-session.js"; import { DaemonSession, type DaemonRuntimeConfig } from "./session/daemon/daemon-session.js"; @@ -8458,76 +8459,58 @@ export class Session { }); const agentPayload = await this.buildAgentPayload(snapshot); - const fetchedControlTimeline = this.agentManager.fetchTimeline(msg.agentId, { - direction, - cursor, + const supportsReasoningMerge = source + ? this.supportsForSource(CLIENT_CAPS.reasoningMergeEnum, source) + : this.supports(CLIENT_CAPS.reasoningMergeEnum); + const response = selectTimelineResponseWithinFrameBudget({ limit: msg.limit, wholeTurns: msg.wholeTurns, - }); - const selectedTimeline = { - timeline: fetchedControlTimeline, - entries: fetchedControlTimeline.rows, - startSeq: fetchedControlTimeline.startSeq, - endSeq: fetchedControlTimeline.endSeq, - hasOlder: fetchedControlTimeline.hasOlder, - hasNewer: fetchedControlTimeline.hasNewer, - }; - const startCursor = - selectedTimeline.startSeq !== null - ? { epoch: selectedTimeline.timeline.epoch, seq: selectedTimeline.startSeq } - : null; - const endCursor = - selectedTimeline.endSeq !== null - ? { epoch: selectedTimeline.timeline.epoch, seq: selectedTimeline.endSeq } - : null; - const entries = selectedTimeline.entries.filter((entry) => - this.supportsTimelineItem(entry.item, source), - ); - - this.emitForSource( - { - type: "fetch_agent_timeline_response", - payload: { - requestId: msg.requestId, - agentId: msg.agentId, - agent: agentPayload, + select: ({ limit, wholeTurns }) => { + const timeline = this.agentManager.fetchTimeline(msg.agentId, { direction, - projection, - epoch: selectedTimeline.timeline.epoch, - reset: fetchedControlTimeline.reset, - staleCursor: fetchedControlTimeline.staleCursor, - gap: fetchedControlTimeline.gap, - window: selectedTimeline.timeline.window, - startCursor, - endCursor, - hasOlder: selectedTimeline.hasOlder, - hasNewer: selectedTimeline.hasNewer, - ...(msg.mergeWindow === true ? { mergeWindow: true } : {}), - entries: entries.map((entry) => { - const payloadEntry = { - provider: snapshot.provider, - item: entry.item, - timestamp: entry.timestamp, - seqStart: entry.seqStart, - seqEnd: entry.seqEnd, - sourceSeqRanges: entry.sourceSeqRanges, - turnId: undefined as string | undefined, - collapsed: ( - source - ? this.supportsForSource(CLIENT_CAPS.reasoningMergeEnum, source) - : this.supports(CLIENT_CAPS.reasoningMergeEnum) - ) - ? entry.collapsed - : entry.collapsed.filter((value) => value !== "reasoning_merge"), - }; - payloadEntry.turnId = entry.turnId; - return payloadEntry; - }), - error: null, - }, + cursor, + limit, + wholeTurns, + }); + const { epoch, startSeq, endSeq } = timeline; + return { + type: "fetch_agent_timeline_response" as const, + payload: { + requestId: msg.requestId, + agentId: msg.agentId, + agent: agentPayload, + direction, + projection, + epoch, + reset: timeline.reset, + staleCursor: timeline.staleCursor, + gap: timeline.gap, + window: timeline.window, + startCursor: startSeq === null ? null : { epoch, seq: startSeq }, + endCursor: endSeq === null ? null : { epoch, seq: endSeq }, + hasOlder: timeline.hasOlder, + hasNewer: timeline.hasNewer, + ...(msg.mergeWindow === true ? { mergeWindow: true } : {}), + entries: timeline.rows + .filter((entry) => this.supportsTimelineItem(entry.item, source)) + .map((entry) => ({ + provider: snapshot.provider, + item: entry.item, + timestamp: entry.timestamp, + seqStart: entry.seqStart, + seqEnd: entry.seqEnd, + sourceSeqRanges: entry.sourceSeqRanges, + turnId: entry.turnId, + collapsed: supportsReasoningMerge + ? entry.collapsed + : entry.collapsed.filter((value) => value !== "reasoning_merge"), + })), + error: null, + }, + }; }, - source, - ); + }); + this.emitForSource(response, source); } catch (error) { this.sessionLogger.error( { err: error, agentId: msg.agentId }, diff --git a/packages/server/src/server/session/timeline-frame-budget.ts b/packages/server/src/server/session/timeline-frame-budget.ts new file mode 100644 index 0000000000..80de1c203a --- /dev/null +++ b/packages/server/src/server/session/timeline-frame-budget.ts @@ -0,0 +1,51 @@ +import { MAX_WEBSOCKET_MESSAGE_BYTES } from "@getpaseo/protocol/websocket-message-limit"; + +// Routed replies add their own envelope around the session frame. +const TIMELINE_FRAME_BUDGET_BYTES = MAX_WEBSOCKET_MESSAGE_BYTES - 64 * 1024; + +interface TimelineRequest { + wholeTurns?: boolean; + limit?: number; +} + +interface TimelineResponse { + payload: { entries: readonly unknown[] }; +} + +function fitsFrameBudget(response: TimelineResponse, maxBytes: number): boolean { + const { entries, ...payload } = response.payload; + // Count bytes without constructing an oversized JSON string for the whole turn. + let bytes = Buffer.byteLength( + JSON.stringify({ + type: "session", + message: { ...response, payload: { ...payload, entries: [] } }, + }), + ); + for (const entry of entries) { + bytes += Buffer.byteLength(JSON.stringify(entry)) + 1; + if (bytes > maxBytes) return false; + } + return bytes <= maxBytes; +} + +export function selectTimelineResponseWithinFrameBudget( + options: TimelineRequest & { select: (request: TimelineRequest) => T; maxBytes?: number }, +): T { + const { select, wholeTurns, maxBytes = TIMELINE_FRAME_BUDGET_BYTES } = options; + let { limit } = options; + const requested = select({ wholeTurns, limit }); + // Preserve whole-turn pages that fit and the existing explicit full-read contract. + if (wholeTurns !== true || limit === 0 || fitsFrameBudget(requested, maxBytes)) return requested; + + for (;;) { + // Reselect using the original direction and cursor; slicing the old response + // would keep the wrong fences and hide the skipped entries from scrollback. + const page = select({ wholeTurns: false, limit }); + if (fitsFrameBudget(page, maxBytes)) return page; + const currentLimit = limit ?? page.payload.entries.length; + if (currentLimit <= 1) { + throw new Error("A timeline item exceeds the response size limit."); + } + limit = Math.floor(currentLimit / 2); + } +}