From 73af0870d79c8525418b76d7204337cb81bd9e69 Mon Sep 17 00:00:00 2001 From: Mohamed Boudra Date: Wed, 18 Nov 2026 15:07:34 +0100 Subject: [PATCH] fix(timeline): keep idle text streams and item updates together Adjacent idle text shares a display turn across coalescer windows. Resolve tool and plugin updates inside timeline ingestion, after checking retirement and before publishing the committed association. --- .../agent-manager-stream-coalescing.test.ts | 39 ++++++++++- .../server/src/server/agent/agent-manager.ts | 69 +++++++++++-------- .../src/server/agent/agent-sdk-types.ts | 2 - .../server/agent/agent-stream-coalescer.ts | 19 ++--- .../src/server/agent/plugin-provider.ts | 11 +-- .../src/server/agent/timeline-projection.ts | 3 +- .../agent/timeline/internal/agent-timeline.ts | 16 ++--- 7 files changed, 92 insertions(+), 67 deletions(-) diff --git a/packages/server/src/server/agent/agent-manager-stream-coalescing.test.ts b/packages/server/src/server/agent/agent-manager-stream-coalescing.test.ts index dee00add07..1870e0ed0f 100644 --- a/packages/server/src/server/agent/agent-manager-stream-coalescing.test.ts +++ b/packages/server/src/server/agent/agent-manager-stream-coalescing.test.ts @@ -563,6 +563,41 @@ describe("root live turn membership", () => { } }); + test("keeps adjacent idle text chunks together across coalescer windows", async () => { + vi.useFakeTimers(); + const harness = createHarness(); + try { + const { agentId, session } = await createManagedSession(harness); + session.pushEvent(assistant("one ")); + session.pushEvent(assistant("two ")); + await waitForSessionEventQueue(); + await vi.advanceTimersByTimeAsync(COALESCE_WINDOW_MS); + session.pushEvent(assistant("three")); + session.pushEvent( + timelineEvent({ type: "notification", level: "info", message: "Independent notice" }), + ); + session.pushEvent(assistant("another reply")); + await waitForSessionEventQueue(); + await harness.manager.flush(); + + const rows = (await harness.manager.fetchTimeline(agentId, { wholeTurns: true, limit: 0 })) + .rows; + expect(getTimelineItems(rows)).toEqual([ + { type: "assistant_message", text: "one two three" }, + { type: "notification", level: "info", message: "Independent notice" }, + { type: "assistant_message", text: "another reply" }, + ]); + expect(rows.map((row) => row.turnId)).toEqual([ + expect.any(String), + expect.any(String), + expect.any(String), + ]); + expect(new Set(rows.map((row) => row.turnId)).size).toBe(3); + } finally { + harness.cleanup(); + } + }); + test("a late tool update keeps the turn where the tool started", async () => { const harness = createHarness(); try { @@ -571,7 +606,7 @@ describe("root live turn membership", () => { session.pushEvent(timelineEvent(toolCall())); session.pushEvent(terminalEvent("turn_completed", "first")); session.pushEvent({ type: "turn_started", provider: "codex", turnId: "second" }); - session.pushEvent(timelineEvent(toolCall({ status: "completed" }))); + session.pushEvent(timelineEvent(toolCall({ status: "completed" }), "codex", "second")); session.pushEvent(assistant("Second reply")); session.pushEvent(terminalEvent("turn_completed", "second")); await vi.waitFor(() => { @@ -759,7 +794,6 @@ describe("target coalesced behavior", () => { const harness = createHarness(); try { const { agentId, session } = await createManagedSession(harness); - session.pushEvent({ type: "turn_started", provider: "codex", turnId: "streaming-turn" }); for (let i = 0; i < 100; i++) { session.pushEvent(reasoning("r")); @@ -1175,7 +1209,6 @@ describe("target coalesced behavior", () => { const harness = createHarness(); try { const { agentId, session } = await createManagedSession(harness); - session.pushEvent({ type: "turn_started", provider: "codex", turnId: "streaming-turn" }); session.pushEvent(assistant("")); session.pushEvent(assistant(" ")); diff --git a/packages/server/src/server/agent/agent-manager.ts b/packages/server/src/server/agent/agent-manager.ts index 0479826704..782b2c2986 100644 --- a/packages/server/src/server/agent/agent-manager.ts +++ b/packages/server/src/server/agent/agent-manager.ts @@ -923,7 +923,10 @@ export class AgentManager { >(); private readonly collectingRuntimes = new Set(); private readonly lifecycleMutationTails = new Map>(); - private readonly sourceItemTurnIds = new WeakMap(); + private readonly idleTextTurns = new WeakMap< + ActiveManagedAgent, + { turnId: string; messageId?: string } + >(); private readonly agentStreamCoalescer: AgentStreamCoalescer; private mcpBaseUrl: string | null; private readonly mcpAuthToken: string | null; @@ -974,7 +977,7 @@ export class AgentManager { onFlush: ({ agentId, item, provider, turnId }) => { this.trackTimelineWrite( agentId, - this.recordAndDispatchTimelineItem(agentId, item, provider, turnId, { + this.recordAndDispatchTimelineItem(agentId, item, provider, turnId ?? randomUUID(), { notifyWaiters: true, }), ); @@ -3240,9 +3243,7 @@ export class AgentManager { item = limitAgentTimelineItemContent(item); this.touchUpdatedAt(agent); const turnId = this.liveTurnId(agent); - const result = await this.recordAndDispatchTimelineItem(agentId, item, agent.provider, turnId, { - inheritItemTurn: item.type === "tool_call", - }); + const result = await this.recordAndDispatchTimelineItem(agentId, item, agent.provider, turnId); if (result.kind === "dropped") { throw new Error("Timeline item belongs to a rewound turn"); } @@ -3596,6 +3597,7 @@ export class AgentManager { } private openActiveTurn(agent: ActiveManagedAgent, turnId: string, startedAt: Date): void { + this.idleTextTurns.delete(agent); agent.activeTurnId = turnId; agent.activeTurnStartedAt = startedAt; } @@ -5496,42 +5498,30 @@ export class AgentManager { agent: ActiveManagedAgent, event: Extract, ): Promise { - const sourceItem = event.item; - // Capture the open turn at admission, before an identity lookup can yield. - const fallbackTurnId = this.liveTurnId(agent, event.turnId); - const originalTurnId = - event.turnId === undefined && sourceItem.type === "tool_call" - ? (this.agentStreamCoalescer.pendingToolTurnId(agent.id, sourceItem.callId) ?? - (await this.timeline.itemTurnId({ agentId: agent.id }, sourceItem))) - : undefined; - const { sourceItem: identity, ...timelineEvent } = event; - const turnId = - (identity ? this.sourceItemTurnIds.get(identity) : undefined) ?? - originalTurnId ?? - fallbackTurnId; - if (identity) this.sourceItemTurnIds.set(identity, turnId); - const liveEvent = { ...timelineEvent, turnId }; + const turnId = this.assignLiveTurn(agent, event.turnId, event.item); + const liveEvent = { ...event, turnId }; this.touchUpdatedAt(agent); if (this.agentStreamCoalescer.handle(agent.id, liveEvent)) { - this.traceCoalescerBuffered(agent, liveEvent, turnId); + this.traceCoalescerBuffered(agent, event, turnId ?? undefined); return false; } this.agentStreamCoalescer.flushFor(agent.id); await this.timeline.settled({ agentId: agent.id }); + const resolvedTurnId = turnId ?? randomUUID(); let notifyWaiters = false; for (const item of projectAgentMessages(event.item)) { if ( item.type === "user_message" && item.clientMessageId && - (await this.reconcileSubmittedPromptEcho(agent, item, turnId)) + (await this.reconcileSubmittedPromptEcho(agent, item, resolvedTurnId)) ) continue; const result = await this.recordAndDispatchTimelineItem( agent.id, item, event.provider, - turnId, + resolvedTurnId, ); if (result.kind === "dropped") continue; if (item.type === "user_message") { @@ -5741,7 +5731,31 @@ export class AgentManager { } private liveTurnId(agent: ActiveManagedAgent, turnId?: string): string { - return turnId ?? agent.activeForegroundTurnId ?? agent.activeTurnId ?? randomUUID(); + return this.assignLiveTurn(agent, turnId) ?? randomUUID(); + } + + private assignLiveTurn( + agent: ActiveManagedAgent, + turnId?: string, + item?: AgentTimelineItem, + ): string | null { + const openTurnId = turnId ?? agent.activeForegroundTurnId ?? agent.activeTurnId; + if (openTurnId || (item?.type !== "assistant_message" && item?.type !== "reasoning")) { + this.idleTextTurns.delete(agent); + // Anonymous tool snapshots coalesce by call ID before ingest assigns their turn. + return openTurnId ?? (item?.type === "tool_call" ? null : randomUUID()); + } + + const previous = this.idleTextTurns.get(agent); + const messageId = item.type === "assistant_message" ? item.messageId : undefined; + const sameMessage = + previous && (!messageId || !previous.messageId || messageId === previous.messageId); + const textTurn = { + turnId: sameMessage ? previous.turnId : randomUUID(), + messageId: messageId ?? previous?.messageId, + }; + this.idleTextTurns.set(agent, textTurn); + return textTurn.turnId; } private async recordAndDispatchTimelineItem( @@ -5752,7 +5766,6 @@ export class AgentManager { options?: { providerMessageId?: string; notifyWaiters?: boolean; - inheritItemTurn?: boolean; onRecorded?: () => void; }, ): Promise { @@ -5770,11 +5783,11 @@ export class AgentManager { ...(options?.providerMessageId ? { providerMessageId: options.providerMessageId } : {}), }, { - inheritItemTurn: item.type === "plugin" || options?.inheritItemTurn, publish: (commit) => { options?.onRecorded?.(); - this.publishTimelineEvent(agentId, { ...event, turnId: commit.row.turnId }, commit); - if (options?.notifyWaiters) this.notifyForegroundTurnWaiters(agentId, event); + const committedEvent = { ...event, turnId: commit.row.turnId }; + this.publishTimelineEvent(agentId, committedEvent, commit); + if (options?.notifyWaiters) this.notifyForegroundTurnWaiters(agentId, committedEvent); if ( item.type === "tool_call" && item.status === "completed" && diff --git a/packages/server/src/server/agent/agent-sdk-types.ts b/packages/server/src/server/agent/agent-sdk-types.ts index 456879529e..5ca947591f 100644 --- a/packages/server/src/server/agent/agent-sdk-types.ts +++ b/packages/server/src/server/agent/agent-sdk-types.ts @@ -450,8 +450,6 @@ export type AgentStreamEvent = type: "timeline"; item: AgentTimelineItem; provider: AgentProvider; - /** The same reference for deltas of one provider item. Used only during live admission. */ - sourceItem?: object; turnId?: string; timestamp?: string; } diff --git a/packages/server/src/server/agent/agent-stream-coalescer.ts b/packages/server/src/server/agent/agent-stream-coalescer.ts index 158d1c2af4..d11b25704a 100644 --- a/packages/server/src/server/agent/agent-stream-coalescer.ts +++ b/packages/server/src/server/agent/agent-stream-coalescer.ts @@ -7,8 +7,8 @@ type CoalescableTextKind = "assistant_message" | "reasoning"; type CoalescableTimelineKind = CoalescableTextKind | "tool_call"; type CoalescableTextItem = Extract; type CoalescableTimelineItem = Extract; -export type LiveTimelineEvent = Extract & { - turnId: string; +export type LiveTimelineEvent = Omit, "turnId"> & { + turnId: string | null; }; type CoalescerEvent = Exclude | LiveTimelineEvent; type CoalescableTimelineEvent = LiveTimelineEvent & { @@ -24,7 +24,7 @@ export interface AgentStreamCoalescerFlush { agentId: string; item: CoalescableTimelineItem; provider: AgentProvider; - turnId: string; + turnId: string | null; } export interface AgentStreamCoalescerOptions { @@ -39,14 +39,14 @@ interface PendingTextEntry { item: CoalescableTextItem; text: string; provider: AgentProvider; - turnId: string; + turnId: string | null; } interface PendingToolCallEntry { kind: "tool_call"; item: Extract; provider: AgentProvider; - turnId: string; + turnId: string | null; } type PendingAgentStreamEntry = PendingTextEntry | PendingToolCallEntry; @@ -55,7 +55,6 @@ interface PendingAgentStreamBuffer { agentId: string; entries: PendingAgentStreamEntry[]; toolCallEntryIndexes: Map; - latestToolTurns: Map; timer: ReturnType | null; flushing: boolean; lastFlushAt: number | null; @@ -139,11 +138,6 @@ export class AgentStreamCoalescer { return true; } - pendingToolTurnId(agentId: string, callId: string): string | undefined { - const buffer = this.buffers.get(agentId); - return buffer?.latestToolTurns.get(callId); - } - flushFor(agentId: string): void { this.flushBuffer(agentId); } @@ -173,7 +167,6 @@ export class AgentStreamCoalescer { agentId, entries: [], toolCallEntryIndexes: new Map(), - latestToolTurns: new Map(), timer: null, flushing: false, lastFlushAt: null, @@ -194,7 +187,6 @@ export class AgentStreamCoalescer { return; } - buffer.latestToolTurns.set(event.item.callId, event.turnId); const key = JSON.stringify([event.item.callId, event.turnId]); const existingIndex = buffer.toolCallEntryIndexes.get(key); const existing = existingIndex !== undefined ? buffer.entries[existingIndex] : undefined; @@ -256,7 +248,6 @@ export class AgentStreamCoalescer { const entries = buffer.entries; buffer.entries = []; buffer.toolCallEntryIndexes.clear(); - buffer.latestToolTurns.clear(); buffer.flushing = true; buffer.lastFlushAt = this.now(); diff --git a/packages/server/src/server/agent/plugin-provider.ts b/packages/server/src/server/agent/plugin-provider.ts index 867da3d849..29e1369ad4 100644 --- a/packages/server/src/server/agent/plugin-provider.ts +++ b/packages/server/src/server/agent/plugin-provider.ts @@ -1180,7 +1180,6 @@ class PluginAgentClient implements AgentClient { interface TimelineTextSnapshot { type: "assistant_message" | "reasoning" | "user_message"; text: string; - identity: object; } function isTextSnapshotItem( @@ -1606,10 +1605,6 @@ class PluginAgentSession implements AgentSession { type: "timeline", provider: this.provider, item, - sourceItem: - item.type === "assistant_message" || item.type === "reasoning" - ? this.timelineSnapshots.get(event.item.id)?.identity - : undefined, turnId: this.currentTurnId ?? undefined, timestamp: event.timestamp, }, @@ -2024,11 +2019,7 @@ function mapTimelineItem( ): AgentTimelineItem | null { const previous = snapshots.get(item.id); if (isTextSnapshotItem(item)) { - snapshots.set(item.id, { - type: item.type, - text: item.text, - identity: previous?.type === item.type ? previous.identity : {}, - }); + snapshots.set(item.id, { type: item.type, text: item.text }); } const { id, revertToken: _revertToken, ...withoutIdentity } = item; rememberRevertToken(item, revertTokens); diff --git a/packages/server/src/server/agent/timeline-projection.ts b/packages/server/src/server/agent/timeline-projection.ts index aebe56465a..0ac220fb7b 100644 --- a/packages/server/src/server/agent/timeline-projection.ts +++ b/packages/server/src/server/agent/timeline-projection.ts @@ -427,7 +427,8 @@ export class TimelineProjection { itemTurnId(item: AgentTimelineItem): string | undefined { const identity = timelineItemIdentity(item); const index = identity === null ? undefined : this.identities.get(identity); - return index === undefined ? undefined : this.rows[index].turnId; + const row = index === undefined ? undefined : this.rows[index]; + return row?.item.type === item.type ? row.turnId : undefined; } getRows(): ProjectedTimelineRow[] { diff --git a/packages/server/src/server/agent/timeline/internal/agent-timeline.ts b/packages/server/src/server/agent/timeline/internal/agent-timeline.ts index 4197c9b9b8..e6e73c2950 100644 --- a/packages/server/src/server/agent/timeline/internal/agent-timeline.ts +++ b/packages/server/src/server/agent/timeline/internal/agent-timeline.ts @@ -126,8 +126,6 @@ export type TimelineReconcileResult = | { kind: "rewind_open" }; export interface TimelineIngestOptions { - /** A direct write using an open or standalone turn as fallback for an existing item. */ - inheritItemTurn?: boolean; /** * Runs right after the commit, before any later operation on the agent's timeline starts, so * publications leave in commit order. Not called when the commit fails or is a duplicate. @@ -277,10 +275,6 @@ export class AgentTimeline { }); } - itemTurnId(scope: TimelineScope, item: AgentTimelineItem): Promise { - return this.run(scope, () => this.backend.itemTurnId(scope, item)); - } - ingest( scope: TimelineScope, entry: TimelineEntry, @@ -300,12 +294,16 @@ export class AgentTimeline { }; } } - // Upserts resolve the original turn under the same lock as the write. - if (options?.inheritItemTurn) { + if (await this.backend.isRetired(scope, entry)) return { kind: "dropped" }; + // A root live upsert updates the item where it first appeared. + if ( + scope.subagentId === undefined && + entry.turnId !== undefined && + (entry.item.type === "tool_call" || entry.item.type === "plugin") + ) { const originalTurnId = await this.backend.itemTurnId(scope, entry.item); if (originalTurnId) entry = { ...entry, turnId: originalTurnId }; } - if (await this.backend.isRetired(scope, entry)) return { kind: "dropped" }; const [commit] = await this.commit(scope, [entry]); const failure = publishCommitted(options?.publish, commit); return failure