fix(timeline): stop the frame-budget fallback when a page cannot shrink

A tail page starts at the first row of the source span it lands in. When
one tool call starts before an oversized turn and completes after it, its
span covers every row, so a smaller limit returns the same page. The
fallback halved the limit down to 1 and then reported that a single item
was too large. It now stops at the first reselect that does not shrink and
says that one item spans more than the limit.

Document in the SDK reference, the plugin hook docs, and the zh-CN copies
that a whole-turn page over the message limit arrives as an item page that
can start partway through a turn.

Co-authored-by: AnalyticETH <hello@analytic.lol>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
paseo-bot[bot]
2026-11-19 02:44:10 +00:00
co-authored by AnalyticETH Claude Opus 5.5
parent b93afb9156
commit d016bf0b44
10 changed files with 104 additions and 10 deletions
+3 -1
View File
@@ -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.
+2 -1
View File
@@ -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;
+2 -1
View File
@@ -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;
};
@@ -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", () => {
@@ -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);
@@ -37,15 +37,24 @@ export function selectTimelineResponseWithinFrameBudget<T extends TimelineRespon
// Preserve whole-turn pages that fit and the existing explicit full-read contract.
if (wholeTurns !== true || limit === 0 || fitsFrameBudget(requested, maxBytes)) return requested;
let previousCount = Infinity;
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) {
const count = page.payload.entries.length;
// A tail page must start at the first row of the source span it lands in.
// When one item's updates span the page, a smaller limit returns the same rows.
if (count >= 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);
}
}
+1 -1
View File
@@ -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
+1 -1
View File
@@ -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}
+1 -1
View File
@@ -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).
+1 -1
View File
@@ -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)。