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.
This commit is contained in:
Mohamed Boudra
2026-11-18 15:07:34 +01:00
parent bd1a8925df
commit 73af0870d7
7 changed files with 92 additions and 67 deletions
@@ -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(" "));
@@ -923,7 +923,10 @@ export class AgentManager {
>();
private readonly collectingRuntimes = new Set<string>();
private readonly lifecycleMutationTails = new Map<string, Promise<void>>();
private readonly sourceItemTurnIds = new WeakMap<object, string>();
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<AgentStreamEvent, { type: "timeline" }>,
): Promise<boolean> {
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<TimelineIngestResult> {
@@ -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" &&
@@ -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;
}
@@ -7,8 +7,8 @@ type CoalescableTextKind = "assistant_message" | "reasoning";
type CoalescableTimelineKind = CoalescableTextKind | "tool_call";
type CoalescableTextItem = Extract<AgentTimelineItem, { type: CoalescableTextKind }>;
type CoalescableTimelineItem = Extract<AgentTimelineItem, { type: CoalescableTimelineKind }>;
export type LiveTimelineEvent = Extract<AgentStreamEvent, { type: "timeline" }> & {
turnId: string;
export type LiveTimelineEvent = Omit<Extract<AgentStreamEvent, { type: "timeline" }>, "turnId"> & {
turnId: string | null;
};
type CoalescerEvent = Exclude<AgentStreamEvent, { type: "timeline" }> | 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<AgentTimelineItem, { type: "tool_call" }>;
provider: AgentProvider;
turnId: string;
turnId: string | null;
}
type PendingAgentStreamEntry = PendingTextEntry | PendingToolCallEntry;
@@ -55,7 +55,6 @@ interface PendingAgentStreamBuffer {
agentId: string;
entries: PendingAgentStreamEntry[];
toolCallEntryIndexes: Map<string, number>;
latestToolTurns: Map<string, string>;
timer: ReturnType<typeof setTimeout> | 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();
@@ -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);
@@ -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[] {
@@ -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<string | undefined> {
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