diff --git a/docs/timeline-sync.md b/docs/timeline-sync.md index 4fa2567210..d7a77afc5a 100644 --- a/docs/timeline-sync.md +++ b/docs/timeline-sync.md @@ -67,7 +67,9 @@ Opening or resuming an agent fetches the latest available turns with a soft targ projected items. Backward pages and prompt-jump windows also include whole turns, including 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 +item pages with continuation cursors so the rest remains reachable. A tail page starts at the first row of +the source span it reaches, so when one item's updates span more than the limit, no smaller page +exists and the request fails with an error. Local history mounting uses turn boundaries so revealing older rows does not change the collapse state of a turn already displayed. diff --git a/packages/client/src/index.ts b/packages/client/src/index.ts index 1a056de459..7a51a4abe0 100644 --- a/packages/client/src/index.ts +++ b/packages/client/src/index.ts @@ -308,7 +308,8 @@ export interface PaseoAgentTimelineRefetchOptions { projection?: FetchAgentTimelineProjection; /** * Extends a `tail` or `before` page back to the start of the oldest turn it touches, so - * `{ direction: "tail", limit: 1, wholeTurns: true }` returns the latest turn. + * `{ direction: "tail", limit: 1, wholeTurns: true }` returns the latest turn. When the complete + * turns do not fit the message limit, the host returns an item page that can start mid-turn. */ wholeTurns?: boolean; requestId?: string; diff --git a/packages/plugin/src/server/lifecycle.ts b/packages/plugin/src/server/lifecycle.ts index cedc2e3019..2485d6c170 100644 --- a/packages/plugin/src/server/lifecycle.ts +++ b/packages/plugin/src/server/lifecycle.ts @@ -109,7 +109,8 @@ export interface PluginHookEvents { * The payload carries no history. Read the turn with * `paseo.agents.ref(agent.id).timeline.refetch({ direction: "tail", limit: 1, wholeTurns: true })` * and keep the entries whose `turnId` equals this `turnId`. The result is empty when a newer turn - * started before the read, or when `turnId` is `null`. + * started before the read, or when `turnId` is `null`. A turn larger than the message limit + * arrives as an item page that can start mid-turn; page `before` its `startCursor` for the rest. */ outcome: PluginTurnOutcome; }; 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 8265411ac0..40deada848 100644 --- a/packages/server/src/server/agent/agent-timeline-store.test.ts +++ b/packages/server/src/server/agent/agent-timeline-store.test.ts @@ -92,6 +92,44 @@ describe("whole-turn byte budget", () => { /timeline item exceeds the response size limit/i, ); }); + + it("stops when one tool call spans the page and a smaller limit cannot shrink it", () => { + const store = new InMemoryAgentTimelineStore(); + store.initialize("agent", { epoch: "current" }); + const tool = (status: "running" | "completed") => + ({ + type: "tool_call", + callId: "background", + name: "shell", + status, + error: null, + detail: { type: "shell", command: "sleep 600" }, + }) as AgentTimelineItem; + store.append("agent", tool("running"), { turnId: "one-turn" }); + for (let index = 1; index <= 8; index++) { + store.append( + "agent", + { type: "assistant_message", messageId: `item-${index}`, text: "€".repeat(180) }, + { turnId: "one-turn" }, + ); + } + store.append("agent", tool("completed"), { turnId: "one-turn" }); + + let selects = 0; + expect(() => + selectTimelineResponseWithinFrameBudget({ + wholeTurns: true, + limit: 40, + maxBytes: 1300, + select: ({ wholeTurns, limit }) => { + selects++; + const { rows, ...page } = store.fetch("agent", { direction: "tail", wholeTurns, limit }); + return { type: "fetch_agent_timeline_response", payload: { ...page, entries: rows } }; + }, + }), + ).toThrow(/one item spans more than the response size limit/i); + expect(selects).toBe(3); + }); }); describe("InMemoryAgentTimelineStore", () => { diff --git a/packages/server/src/server/daemon-e2e/oversized-whole-turn.e2e.test.ts b/packages/server/src/server/daemon-e2e/oversized-whole-turn.e2e.test.ts index 4a5a55bf41..a6623b9afb 100644 --- a/packages/server/src/server/daemon-e2e/oversized-whole-turn.e2e.test.ts +++ b/packages/server/src/server/daemon-e2e/oversized-whole-turn.e2e.test.ts @@ -62,3 +62,46 @@ test("reading a turn larger than the message limit returns pages that reach its rmSync(cwd, { recursive: true, force: true }); } }, 180_000); + +// A tail page starts at the first row of the source span it lands in. One tool call that starts +// before the oversized turn and completes after it spans every row, so no smaller page exists. +// The daemon answers with an error instead of letting the request time out. +test("reading a turn that one tool call spans past the message limit fails with a reply", async () => { + const ctx = await createDaemonTestContext(); + const cwd = mkdtempSync(path.join(tmpdir(), "oversized-spanned-turn-")); + try { + const agent = await ctx.client.createAgent({ provider: "codex", cwd }); + const background = (status: "running" | "completed") => ({ + type: "tool_call" as const, + callId: "background", + name: "Bash", + status, + error: null, + detail: { type: "shell" as const, command: "sleep 600" }, + }); + await ctx.daemon.daemon.agentManager.appendTimelineItem(agent.id, background("running")); + for (let index = 0; index < 420; index += 1) { + await ctx.daemon.daemon.agentManager.appendTimelineItem(agent.id, { + type: "assistant_message", + messageId: `reply-${index}`, + text: `reply-${index} ${"x".repeat(250 * 1024)}`, + }); + } + await ctx.daemon.daemon.agentManager.appendTimelineItem(agent.id, background("completed")); + + await expect( + ctx.client.fetchAgentTimeline(agent.id, { + direction: "tail", + limit: 40, + wholeTurns: true, + timeout: 20_000, + }), + ).rejects.toThrow(/one item spans more than the response size limit/i); + + const small = await ctx.client.fetchAgentTimeline(agent.id, { direction: "before", limit: 1 }); + expect(small.entries).toHaveLength(1); + } finally { + await ctx.cleanup(); + rmSync(cwd, { recursive: true, force: true }); + } +}, 180_000); diff --git a/packages/server/src/server/session/timeline-frame-budget.ts b/packages/server/src/server/session/timeline-frame-budget.ts index 80de1c203a..4bf486a869 100644 --- a/packages/server/src/server/session/timeline-frame-budget.ts +++ b/packages/server/src/server/session/timeline-frame-budget.ts @@ -37,15 +37,24 @@ export function selectTimelineResponseWithinFrameBudget= previousCount) { + throw new Error( + "One item spans more than the response size limit, so the timeline page cannot shrink.", + ); + } + if (count <= 1) { throw new Error("A timeline item exceeds the response size limit."); } - limit = Math.floor(currentLimit / 2); + previousCount = count; + limit = Math.floor(Math.min(limit ?? count, count) / 2); } } diff --git a/public-docs/plugins/hooks.md b/public-docs/plugins/hooks.md index ec498f5918..df8e2cd6da 100644 --- a/public-docs/plugins/hooks.md +++ b/public-docs/plugins/hooks.md @@ -538,7 +538,7 @@ server.addHook("agent.turn.before", async ({ agent, turnId }) => { ## agent.turn.after -A live turn completes, fails, or is canceled. Receives `{ agent, turnId, outcome }`. `outcome.kind` is `completed`, `failed`, or `canceled`. The payload carries no history. Read the turn from the agent's timeline: `refetch({ direction: "tail", limit: 1, wholeTurns: true })` returns the latest turn whole, as below. Keep the entries whose `turnId` equals `event.turnId`, because a turn that starts before your read, such as a follow-up another plugin sent, replaces this one as the latest. The filtered list is empty in that case, and when `event.turnId` is `null`. Plugins built against an older SDK that read `event.timeline` get an empty array. +A live turn completes, fails, or is canceled. Receives `{ agent, turnId, outcome }`. `outcome.kind` is `completed`, `failed`, or `canceled`. The payload carries no history. Read the turn from the agent's timeline: `refetch({ direction: "tail", limit: 1, wholeTurns: true })` returns the latest turn whole, as below, unless the turn is larger than the message limit ([timeline handle](/docs/sdk/reference#timeline-handle)). Keep the entries whose `turnId` equals `event.turnId`, because a turn that starts before your read, such as a follow-up another plugin sent, replaces this one as the latest. The filtered list is empty in that case, and when `event.turnId` is `null`. Plugins built against an older SDK that read `event.timeline` get an empty array. ### Send a follow-up when a turn ends diff --git a/public-docs/plugins/hooks.zh-CN.md b/public-docs/plugins/hooks.zh-CN.md index 5bdb94a61b..dcba1b3c34 100644 --- a/public-docs/plugins/hooks.zh-CN.md +++ b/public-docs/plugins/hooks.zh-CN.md @@ -527,7 +527,7 @@ server.addHook("agent.turn.before", async ({ agent, turnId }) => { ## agent.turn.after {#agentturnafter} -实时轮次完成、失败或取消后触发,收到 `{ agent, turnId, outcome }`。`outcome.kind` 为 `completed`、`failed` 或 `canceled`。载荷不含历史。请从 Agent 的时间线读取本轮:`refetch({ direction: "tail", limit: 1, wholeTurns: true })` 会完整返回最近一轮,见下面的示例。只保留 `turnId` 等于 `event.turnId` 的条目:如果在读取前已有新一轮开始(例如另一个插件发送的后续消息),最近一轮就不再是本轮。此时过滤后的列表为空;`event.turnId` 为 `null` 时也为空。基于旧版 SDK 构建、仍读取 `event.timeline` 的插件只会拿到空数组。 +实时轮次完成、失败或取消后触发,收到 `{ agent, turnId, outcome }`。`outcome.kind` 为 `completed`、`failed` 或 `canceled`。载荷不含历史。请从 Agent 的时间线读取本轮:`refetch({ direction: "tail", limit: 1, wholeTurns: true })` 会完整返回最近一轮,见下面的示例;超过消息上限的轮次除外(见[时间线句柄](/docs/sdk/reference#timeline-handle))。只保留 `turnId` 等于 `event.turnId` 的条目:如果在读取前已有新一轮开始(例如另一个插件发送的后续消息),最近一轮就不再是本轮。此时过滤后的列表为空;`event.turnId` 为 `null` 时也为空。基于旧版 SDK 构建、仍读取 `event.timeline` 的插件只会拿到空数组。 ### 在轮次结束时发送后续消息 {#send-a-follow-up-when-a-turn-ends} diff --git a/public-docs/sdk/reference.md b/public-docs/sdk/reference.md index 4db6277f85..3d5b44062b 100644 --- a/public-docs/sdk/reference.md +++ b/public-docs/sdk/reference.md @@ -118,7 +118,7 @@ workspace the call creates is background too. With a `parent` and no value, the ### Timeline handle -`agent.timeline.refetch(options?)` fetches a page. Options are `direction`, `cursor`, `limit`, `projection`, `wholeTurns`, and `requestId`. `wholeTurns: true` extends a `tail` or `before` page back to the start of the oldest turn it reaches, so `{ direction: "tail", limit: 1, wholeTurns: true }` returns the latest turn. It requires `features.wholeTurnTimeline`; older hosts ignore it and return a page of `limit` items. +`agent.timeline.refetch(options?)` fetches a page. Options are `direction`, `cursor`, `limit`, `projection`, `wholeTurns`, and `requestId`. `wholeTurns: true` extends a `tail` or `before` page back to the start of the oldest turn it reaches, so `{ direction: "tail", limit: 1, wholeTurns: true }` returns the latest turn. If the complete turns of a page do not fit the 100 MiB message limit, the host returns a page of items with cursors instead, and that page can start partway through a turn. Use `startCursor` with `direction: "before"` to read the rest. It requires `features.wholeTurnTimeline`; older hosts ignore it and return a page of `limit` items. `agent.timeline.subscribe(handler)` establishes network demand for this agent and restores it after reconnect. Its unsubscribe function releases that demand; await `unsubscribe.ready` for initial daemon acknowledgement before starting work. Delivery is live-only. Reconnect emits a local `subscription_restored` event; request missed history explicitly with `refetch()`. A live replacement invalidates the previous epoch. See the callback shapes, paging and failure behavior in [timeline events](./events.md#follow-timeline-events). diff --git a/public-docs/sdk/reference.zh-CN.md b/public-docs/sdk/reference.zh-CN.md index 87166ff76f..aa925d5d56 100644 --- a/public-docs/sdk/reference.zh-CN.md +++ b/public-docs/sdk/reference.zh-CN.md @@ -114,7 +114,7 @@ nav: API 参考 ### 时间线句柄 {#timeline-handle} -`agent.timeline.refetch(options?)` 获取一页时间线。选项有 `direction`、`cursor`、`limit`、`projection`、`wholeTurns` 和 `requestId`。`wholeTurns: true` 会把 `tail` 或 `before` 页向前扩展到它所触及的最早一轮的开头,因此 `{ direction: "tail", limit: 1, wholeTurns: true }` 返回最近一轮。它需要 `features.wholeTurnTimeline`;旧版主机会忽略它,返回 `limit` 条记录。 +`agent.timeline.refetch(options?)` 获取一页时间线。选项有 `direction`、`cursor`、`limit`、`projection`、`wholeTurns` 和 `requestId`。`wholeTurns: true` 会把 `tail` 或 `before` 页向前扩展到它所触及的最早一轮的开头,因此 `{ direction: "tail", limit: 1, wholeTurns: true }` 返回最近一轮。如果一页的完整轮次超过 100 MiB 消息上限,主机会改为返回带游标的条目页,这一页可能从某一轮的中间开始。用 `startCursor` 和 `direction: "before"` 读取其余部分。它需要 `features.wholeTurnTimeline`;旧版主机会忽略它,返回 `limit` 条记录。 `agent.timeline.subscribe(handler)` 为该 Agent 建立网络订阅需求,并在重连后恢复它。它返回的取消订阅函数会释放这项需求;开始工作之前,请 await `unsubscribe.ready` 以等待 daemon 的初始确认。投递只包含实时内容。重连时会发出一个本地的 `subscription_restored` 事件;错过的历史请用 `refetch()` 显式请求。实时的替换会使之前的 epoch 失效。回调的形状、分页和失败行为见[时间线事件](./events.md#follow-timeline-events)。