@threadplane/ag-ui 0.0.55 → 0.0.57

package/fesm2022/threadplane-ag-ui.mjs

@@ -1,6 +1,6 @@
 import { signal, computed, InjectionToken, inject } from '@angular/core';
 import { Subject, Observable } from 'rxjs';
-import { toAgentError, isAbortError } from '@threadplane/chat';
+import { completeDelivery, staticDelivery, streamingDelivery, toAgentError, selectPendingClientToolCalls, isAbortError } from '@threadplane/chat';
 import { HttpAgent, AbstractAgent, EventType } from '@ag-ui/client';
 
 // SPDX-License-Identifier: MIT
@@ -263,12 +263,19 @@ function normalizeCitation(entry, fallbackIndex) {
         }
         return undefined;
     };
+    const publishedAt = e['publishedAt'];
+    const normalizedPublishedAt = typeof publishedAt === 'string' || typeof publishedAt === 'number' || publishedAt instanceof Date
+        ? publishedAt
+        : undefined;
     return {
         id: str('id') ?? str('refId') ?? `c${fallbackIndex}`,
         index: typeof e['index'] === 'number' ? e['index'] : fallbackIndex,
         title: firstStr('title', 'name'),
         url: firstStr('url', 'href', 'source'),
         snippet: firstStr('snippet', 'content', 'excerpt'),
+        sourceType: str('sourceType'),
+        iconUrl: str('iconUrl'),
+        publishedAt: normalizedPublishedAt,
         extra: typeof e['extra'] === 'object' && e['extra'] !== null
             ? e['extra']
             : undefined,
@@ -280,6 +287,16 @@ function normalizeCitation(entry, fallbackIndex) {
 // Discriminator strings (e.g. 'RUN_STARTED') match EventType enum members
 // verbatim; the switch cases below use the string literals directly so this
 // file has no runtime dependency on the EventType enum import.
+/** Finalize one run without touching messages owned by another generation. */
+function finalizeDeliveryRun(store, run, outcome) {
+    if (run.outcome !== undefined)
+        return false;
+    run.outcome = outcome;
+    store.messages.update(messages => messages.map(message => message.delivery.generation === run.generation
+        ? { ...message, delivery: completeDelivery(run.generation, outcome) }
+        : message));
+    return true;
+}
 /**
  * Per-message reasoning timing. Populated by REASONING_MESSAGE_START /
  * REASONING_MESSAGE_END handlers. The map lives on the module — same
@@ -306,6 +323,9 @@ function resolveReasoningDurationMs(messageId) {
 function reduceEvent(event, store) {
     switch (event.type) {
         case 'RUN_STARTED': {
+            const run = store.deliveryRun;
+            if (!run || run.outcome !== undefined || !bindRunId(event, run))
+                return;
             store.status.set('running');
             store.isLoading.set(true);
             store.error.set(undefined);
@@ -315,11 +335,17 @@ function reduceEvent(event, store) {
             return;
         }
         case 'RUN_FINISHED': {
+            const run = currentRunForEvent(event, store);
+            if (!run || !finalizeDeliveryRun(store, run, 'success'))
+                return;
             store.status.set('idle');
             store.isLoading.set(false);
             return;
         }
         case 'RUN_ERROR': {
+            const run = currentRunForEvent(event, store);
+            if (!run || !finalizeDeliveryRun(store, run, 'error'))
+                return;
             store.status.set('error');
             store.isLoading.set(false);
             const runErrorMsg = event.message;
@@ -328,28 +354,37 @@ function reduceEvent(event, store) {
         }
         case 'TEXT_MESSAGE_START': {
             const id = messageIdFrom(event);
+            const delivery = ownAssistantMessage(store, id);
+            if (!delivery)
+                return;
             store.messages.update((prev) => prev.some((m) => m.id === id)
-                ? prev.map((m) => m.id === id ? { ...m, content: m.content ?? '' } : m)
-                : [...prev, { id, role: 'assistant', content: '' }]);
+                ? prev.map((m) => m.id === id ? { ...m, content: m.content ?? '', delivery } : m)
+                : [...prev, { id, role: 'assistant', content: '', delivery }]);
             return;
         }
         case 'REASONING_MESSAGE_START': {
             const id = messageIdFrom(event);
+            const delivery = ownAssistantMessage(store, id);
+            if (!delivery)
+                return;
             reasoningTimingMap.set(id, { startedAt: Date.now() });
             // Initialize an assistant slot with empty reasoning if it doesn't already exist.
             store.messages.update((prev) => prev.some((m) => m.id === id)
                 ? prev.map((m) => m.id === id
-                    ? { ...m, reasoning: m.reasoning ?? '' }
+                    ? { ...m, reasoning: m.reasoning ?? '', delivery }
                     : m)
-                : [...prev, { id, role: 'assistant', content: '', reasoning: '' }]);
+                : [...prev, { id, role: 'assistant', content: '', reasoning: '', delivery }]);
             return;
         }
         case 'REASONING_MESSAGE_CONTENT':
         case 'REASONING_MESSAGE_CHUNK': {
             const id = messageIdFrom(event);
+            const delivery = ownAssistantMessage(store, id);
+            if (!delivery)
+                return;
             const delta = event.delta ?? '';
             store.messages.update((prev) => prev.map((m) => m.id === id
-                ? { ...m, reasoning: (m.reasoning ?? '') + delta }
+                ? { ...m, reasoning: (m.reasoning ?? '') + delta, delivery }
                 : m));
             return;
         }
@@ -368,8 +403,11 @@ function reduceEvent(event, store) {
         }
         case 'TEXT_MESSAGE_CONTENT': {
             const id = messageIdFrom(event);
+            const delivery = ownAssistantMessage(store, id);
+            if (!delivery)
+                return;
             const delta = event.delta ?? '';
-            store.messages.update((prev) => prev.map((m) => m.id === id ? { ...m, content: m.content + delta } : m));
+            store.messages.update((prev) => prev.map((m) => m.id === id ? { ...m, content: m.content + delta, delivery } : m));
             return;
         }
         case 'TEXT_MESSAGE_END': {
@@ -390,14 +428,17 @@ function reduceEvent(event, store) {
             // tool-call-only turn emits no TEXT_MESSAGE_START), create a slot.
             const parentId = e.parentMessageId;
             if (parentId) {
+                const delivery = ownAssistantMessage(store, parentId);
+                if (!delivery)
+                    return;
                 store.messages.update((prev) => {
                     const existing = prev.find((m) => m.id === parentId);
                     if (existing) {
                         return prev.map((m) => m.id === parentId
-                            ? { ...m, toolCallIds: [...(m.toolCallIds ?? []), e.toolCallId] }
+                            ? { ...m, toolCallIds: [...(m.toolCallIds ?? []), e.toolCallId], delivery }
                             : m);
                     }
-                    return [...prev, { id: parentId, role: 'assistant', content: '', toolCallIds: [e.toolCallId] }];
+                    return [...prev, { id: parentId, role: 'assistant', content: '', toolCallIds: [e.toolCallId], delivery }];
                 });
             }
             return;
@@ -456,6 +497,13 @@ function reduceEvent(event, store) {
         case 'MESSAGES_SNAPSHOT': {
             const e = event;
             const raw = e.messages ?? [];
+            const run = store.deliveryRun?.outcome === undefined ? store.deliveryRun : null;
+            const canonicalAssistantId = resolveCanonicalAssistantId(raw, run);
+            const activeCanonicalAssistantId = canonicalAssistantId
+                && ownAssistantMessage(store, canonicalAssistantId)
+                ? canonicalAssistantId
+                : undefined;
+            const previousById = new Map(store.messages().map(message => [message.id, message]));
             // AG-UI AssistantMessage carries `toolCalls` (ToolCall objects) on the
             // snapshot wire. Bridge them to `toolCallIds` so that the chat lib's
             // per-message tool-call resolution (resolveMessageToolCalls) can scope
@@ -463,23 +511,71 @@ function reduceEvent(event, store) {
             // so the data is visible to <chat-tool-views>.
             const snapshotToolCalls = [];
             const messages = raw.map((m) => {
+                const previous = previousById.get(m.id);
+                const completedMessage = m.id !== activeCanonicalAssistantId
+                    && previous?.delivery.phase === 'complete'
+                    && (!run
+                        || run.ownedMessageIds.has(m.id)
+                        || run.snapshotReplacementIds.has(m.id))
+                    ? previous
+                    : undefined;
+                let delivery = previous?.delivery ?? staticDelivery(m.id);
+                let snapshotMessage;
                 if (m.role !== 'assistant' || !m.toolCalls || m.toolCalls.length === 0) {
-                    return m;
+                    snapshotMessage = m;
+                }
+                else {
+                    const ids = [];
+                    for (const tc of m.toolCalls) {
+                        ids.push(tc.id);
+                        snapshotToolCalls.push({
+                            id: tc.id,
+                            name: tc.function.name,
+                            args: safeParseArgs(tc.function.arguments),
+                            status: 'complete',
+                        });
+                    }
+                    const { toolCalls: _dropped, ...rest } = m;
+                    snapshotMessage = { ...rest, toolCallIds: ids };
+                }
+                if (completedMessage) {
+                    const snapshotChanged = completedMessage.content !== snapshotMessage.content
+                        || !sameStringArray(completedMessage.toolCallIds, snapshotMessage.toolCallIds);
+                    if (!snapshotChanged)
+                        return completedMessage;
+                    run?.snapshotReplacementIds.add(m.id);
+                    return {
+                        ...completedMessage,
+                        ...snapshotMessage,
+                        delivery: completeDelivery(store.allocateDeliveryGeneration(`snapshot:${m.id}`), 'success'),
+                    };
                 }
-                const ids = [];
-                for (const tc of m.toolCalls) {
-                    ids.push(tc.id);
-                    snapshotToolCalls.push({
-                        id: tc.id,
-                        name: tc.function.name,
-                        args: safeParseArgs(tc.function.arguments),
-                        status: 'complete',
-                    });
+                if (run && (run.ownedMessageIds.has(m.id) || m.id === canonicalAssistantId)) {
+                    delivery = delivery.generation === run.generation && delivery.phase === 'complete'
+                        ? delivery
+                        : streamingDelivery(run.generation);
+                    run.ownedMessageIds.add(m.id);
+                    if (m.id === activeCanonicalAssistantId)
+                        run.currentAssistantMessageId = m.id;
                 }
-                const { toolCalls: _dropped, ...rest } = m;
-                return { ...rest, toolCallIds: ids };
+                return { ...snapshotMessage, delivery };
             });
-            store.messages.set(messages);
+            const currentAssistant = run?.currentAssistantMessageId
+                ? previousById.get(run.currentAssistantMessageId)
+                : undefined;
+            if (run
+                && currentAssistant?.delivery.generation === run.generation
+                && currentAssistant.delivery.phase === 'streaming'
+                && !messages.some(message => message.id === currentAssistant.id)) {
+                messages.push(currentAssistant);
+            }
+            // Re-apply per-message citations from the already-received STATE. A
+            // MESSAGES_SNAPSHOT replaces the streamed messages wholesale — and the
+            // final snapshot message id (str(AIMessage.id), e.g. "resp-…") differs
+            // from the streaming chunk id the earlier STATE_SNAPSHOT bridged against,
+            // so without re-bridging here the citations (keyed by the final id) would
+            // be dropped on the message swap.
+            store.messages.set(bridgeCitationsState({ state: store.state() }, messages));
             if (snapshotToolCalls.length > 0) {
                 store.toolCalls.update((prev) => {
                     // Merge: keep existing entries (they may carry richer state from
@@ -498,7 +594,14 @@ function reduceEvent(event, store) {
             // (e.g. ChatApprovalCardComponent) receive a plain object, not a string.
             const parsedValue = typeof e.value === 'string' ? safeParseJson(e.value) : e.value;
             if (e.name === 'on_interrupt') {
+                const run = currentRunForEvent(event, store);
+                if (store.deliveryRun && !run)
+                    return;
                 store.interrupt.set({ id: randomId$1(), value: parsedValue, resumable: true });
+                if (run && finalizeDeliveryRun(store, run, 'paused')) {
+                    store.status.set('idle');
+                    store.isLoading.set(false);
+                }
                 return;
             }
             // Surface every other custom event on the customEvents signal so the
@@ -517,13 +620,17 @@ function reduceEvent(event, store) {
             const e = event;
             const map = new Map(store.activities());
             const existing = map.get(e.messageId);
-            if (existing && existing.activityType === e.activityType && !e.replace) {
-                existing.content.update((c) => ({ ...c, ...e.content }));
+            if (existing && existing.activityType === e.activityType) {
+                if (e.replace)
+                    existing.content.set(e.content ?? {});
+                else
+                    existing.content.update((c) => ({ ...c, ...e.content }));
             }
             else {
                 map.set(e.messageId, {
                     messageId: e.messageId,
                     activityType: e.activityType,
+                    generation: store.allocateDeliveryGeneration(`activity:${e.messageId}`),
                     content: signal(e.content ?? {}),
                 });
             }
@@ -559,6 +666,68 @@ function reduceEvent(event, store) {
 function randomId$1() {
     return Math.random().toString(36).slice(2);
 }
+function eventRunId(event) {
+    const runId = event.runId;
+    return typeof runId === 'string' ? runId : undefined;
+}
+function bindRunId(event, run) {
+    const runId = eventRunId(event);
+    if (!runId)
+        return true;
+    if (run.protocolRunId && run.protocolRunId !== runId)
+        return false;
+    run.protocolRunId = runId;
+    return true;
+}
+function currentRunForEvent(event, store) {
+    const run = store.deliveryRun;
+    if (!run || !bindRunId(event, run))
+        return null;
+    return run;
+}
+function ownAssistantMessage(store, id) {
+    const run = store.deliveryRun;
+    if (!run || run.outcome !== undefined)
+        return undefined;
+    const currentId = run.currentAssistantMessageId;
+    if (currentId && currentId !== id) {
+        if (run.ownedMessageIds.has(id))
+            return undefined;
+        store.messages.update(messages => messages.map(message => message.id === currentId
+            && message.delivery.generation === run.generation
+            && message.delivery.phase === 'streaming'
+            ? { ...message, delivery: completeDelivery(run.generation, 'success') }
+            : message));
+    }
+    run.ownedMessageIds.add(id);
+    run.currentAssistantMessageId = id;
+    return streamingDelivery(run.generation);
+}
+function sameStringArray(left, right) {
+    if (left === right)
+        return true;
+    if (!left || !right || left.length !== right.length)
+        return false;
+    return left.every((value, index) => value === right[index]);
+}
+function resolveCanonicalAssistantId(messages, run) {
+    if (!run)
+        return undefined;
+    if (run.currentAssistantMessageId
+        && messages.some(message => message.id === run.currentAssistantMessageId)) {
+        return run.currentAssistantMessageId;
+    }
+    for (let index = messages.length - 1; index >= 0; index -= 1) {
+        const message = messages[index];
+        if (message.role === 'assistant' && !run.baselineMessageIds.has(message.id)) {
+            return message.id;
+        }
+    }
+    return run.eligibleBaselineAssistantId
+        && messages.some(message => message.role === 'assistant' && message.id === run.eligibleBaselineAssistantId)
+        ? run.eligibleBaselineAssistantId
+        : undefined;
+}
 function messageIdFrom(event) {
     return event.messageId ?? 'unknown';
 }
@@ -618,21 +787,59 @@ function safeStringify(v) {
  *    have no backend result, and haven't been resolved client-side yet — but ONLY
  *    when the run is not in progress (isLoading===false). The backend ends the run
  *    without emitting TOOL_CALL_RESULT for client tools, so result stays undefined.
- *  - resolve(id, result): marks the call as resolved, writes the outcome onto
+ *  - settle(id, result): marks the call as resolved, writes the outcome onto
  *    the local ToolCall in the store (so the transcript freezes: the mounted
  *    ask component re-renders with its emitted value as props and can branch to
- *    a frozen state), adds a ToolMessage via source.addMessage, then re-runs
- *    the agent with the catalog tools attached.
+ *    a frozen state), and adds a ToolMessage via source.addMessage without
+ *    starting a run.
+ *  - flush(): no-op. settle() already made the result durable by adding it to
+ *    the source's message list, so there is nothing left to write.
+ *  - resolve(id, result): settles the result, then requests a continuation
+ *    through the adapter-owned run gateway. Any ToolMessages previously
+ *    settled into the source are flushed by that single run.
  *
  * Call catalogAsAgUiTools() to get the current catalog as AG-UI Tool[] for
- * threading into runAgent().
+ * attaching to each adapter-owned run.
  */
-function createClientToolsCapability(source, store) {
+function createClientToolsCapability(source, store, continueRun) {
     const catalog = signal([], ...(ngDevMode ? [{ debugName: "catalog" }] : []));
     const resolvedIds = signal(new Set(), ...(ngDevMode ? [{ debugName: "resolvedIds" }] : []));
     function catalogAsAgUiTools() {
         return catalog().map(toAgUiTool);
     }
+    function settleResult(id, result) {
+        // Mark as resolved first so pending() drops it immediately.
+        resolvedIds.update((s) => new Set(s).add(id));
+        // Write the outcome onto the LOCAL ToolCall in the store. The client tool
+        // DID produce a result client-side, so this is semantically correct — and
+        // it freezes the transcript card: toToolViewSpec spreads `{...args,
+        // ...result, status}` into the mounted ask component, so the component
+        // re-renders with its own emitted value as props and can branch to a
+        // resolved/frozen state. The backend ToolMessage never reaches this local
+        // ToolCall, so without this write the card stays interactive forever.
+        const ok = result.ok;
+        const value = result.value;
+        const error = result.error;
+        store.toolCalls.update((calls) => calls.map((tc) => tc.id === id
+            ? {
+                ...tc,
+                result: ok ? value : { error },
+                ...(ok ? {} : { error, status: 'error' }),
+            }
+            : tc));
+        // Cast rather than rely on discriminant narrowing: consumer apps that
+        // compile this source with `strictNullChecks: false` don't narrow the
+        // ClientToolResult union in a ternary.
+        const content = ok
+            ? safeStringify(value)
+            : `Error: ${error}`;
+        source.addMessage({
+            id: `tool-${id}`,
+            role: 'tool',
+            toolCallId: id,
+            content,
+        });
+    }
     const clientTools = {
         setCatalog(specs) {
             catalog.set([...specs]);
@@ -640,45 +847,25 @@ function createClientToolsCapability(source, store) {
         pending: computed(() => {
             // Client tools are only actionable after the run ends (backend signals it
             // by ending the run WITHOUT emitting TOOL_CALL_RESULT for client tools).
-            if (store.isLoading())
-                return [];
-            const names = new Set(catalog().map((s) => s.name));
-            const done = resolvedIds();
-            return store.toolCalls().filter((tc) => names.has(tc.name) && tc.result === undefined && !done.has(tc.id));
+            return selectPendingClientToolCalls({
+                isLoading: store.isLoading(),
+                toolCalls: store.toolCalls(),
+                catalogNames: new Set(catalog().map((s) => s.name)),
+                resolvedIds: resolvedIds(),
+            });
         }),
+        settle(id, result) {
+            settleResult(id, result);
+        },
+        // AG-UI's settle() already calls source.addMessage(), which places the
+        // ToolMessage in the outgoing message list. Nothing further is needed to
+        // make it durable — the next run carries it.
+        flush() {
+            /* no-op: settle() is already durable */
+        },
         resolve(id, result) {
-            // Mark as resolved first so pending() drops it immediately.
-            resolvedIds.update((s) => new Set(s).add(id));
-            // Write the outcome onto the LOCAL ToolCall in the store. The client tool
-            // DID produce a result client-side, so this is semantically correct — and
-            // it freezes the transcript card: toToolViewSpec spreads `{...args,
-            // ...result, status}` into the mounted ask component, so the component
-            // re-renders with its own emitted value as props and can branch to a
-            // resolved/frozen state. The backend ToolMessage never reaches this local
-            // ToolCall, so without this write the card stays interactive forever.
-            const ok = result.ok;
-            const value = result.value;
-            const error = result.error;
-            store.toolCalls.update((calls) => calls.map((tc) => tc.id === id
-                ? {
-                    ...tc,
-                    result: ok ? value : { error },
-                    ...(ok ? {} : { error, status: 'error' }),
-                }
-                : tc));
-            // Cast rather than rely on discriminant narrowing: consumer apps that
-            // compile this source with `strictNullChecks: false` don't narrow the
-            // ClientToolResult union in a ternary.
-            const content = ok
-                ? safeStringify(value)
-                : `Error: ${error}`;
-            source.addMessage({
-                id: `tool-${id}`,
-                role: 'tool',
-                toolCallId: id,
-                content,
-            });
-            void source.runAgent({ tools: catalogAsAgUiTools() });
+            settleResult(id, result);
+            void continueRun();
         },
         catalogAsAgUiTools,
     };
@@ -721,8 +908,18 @@ function agentRuntimeTelemetryErrorClass(error) {
  * of toAgent() should treat the returned object's lifecycle as tied to the
  * agent instance they constructed. The subscriber registered via
  * source.subscribe() will fire for the lifetime of source.
+ *
+ * @example
+ * ```ts
+ * import { HttpAgent } from '@ag-ui/client';
+ * import { toAgent } from '@threadplane/ag-ui';
+ *
+ * const agent = toAgent(new HttpAgent({ url: '/api/agent' }));
+ * ```
  */
 function toAgent(source, options = {}) {
+    let generationSequence = 0;
+    const allocateDeliveryGeneration = (scope) => `${scope}-${++generationSequence}-${Math.random().toString(36).slice(2, 10)}`;
     const store = {
         messages: signal([]),
         status: signal('idle'),
@@ -734,55 +931,39 @@ function toAgent(source, options = {}) {
         events$: new Subject(),
         customEvents: signal([]),
         activities: signal(new Map()),
+        deliveryRun: null,
+        allocateDeliveryGeneration,
     };
     const telemetryProperties = { transport: 'ag-ui', surface: 'to_agent' };
     let activeRun = null;
-    // Set by stop(); lets run-failure handlers distinguish a user-initiated
-    // abort (graceful cancel) from a genuine stream failure.
-    let abortRequested = false;
-    // Set to true the first time settleIfAborted() handles an abort error for the
-    // current run. The AG-UI client can surface the same abort via both the event
-    // stream (RUN_ERROR event) AND onRunFailed — abortSettled lets the second
-    // delivery see through as a no-op rather than re-writing store state or
-    // triggering a real error path. Both flags are reset together at the top of
-    // submit() so the next run starts clean.
-    let abortSettled = false;
+    const runsByProtocolId = new Map();
     // Tracks the last AgentSubmitInput so retry() can re-run it without
     // duplicating the user message. Set at the top of submit()'s message path.
     let lastInput;
-    /** Settles the store as idle for stop()-induced failures; returns true if handled. */
-    function settleIfAborted(error) {
-        // If we already settled this abort (duplicate delivery — e.g. RUN_ERROR
-        // event THEN onRunFailed), defensively re-apply the idle settle so any
-        // state written between the two deliveries (e.g. RUN_STARTED from a new
-        // run that started before flags were reset) is corrected. Telemetry is
-        // not re-emitted — the guard returns true to suppress further processing.
-        if (abortSettled && isAbortError(error)) {
-            store.status.set('idle');
-            store.isLoading.set(false);
-            return true;
-        }
-        if (!abortRequested || !isAbortError(error))
-            return false;
-        abortRequested = false;
-        abortSettled = true;
-        store.status.set('idle');
-        store.isLoading.set(false);
-        // Not a failure: leave store.error null and close out telemetry as a
-        // normal finish so the aborted run doesn't count as errored.
-        const run = activeRun;
-        if (run) {
-            finishRunTelemetry(run);
-            // Mark errored so any subsequent finishRunTelemetry/failRunTelemetry
-            // call on the same run object (e.g. from submit's try block resolving
-            // after the abort) is a no-op — telemetry fires at most once per run.
-            run.errored = true;
+    function resolveCallbackRun(protocolRunId) {
+        if (!protocolRunId)
+            return activeRun;
+        const known = runsByProtocolId.get(protocolRunId);
+        if (known)
+            return known;
+        if (!activeRun || activeRun.protocolRunId)
+            return null;
+        activeRun.protocolRunId = protocolRunId;
+        runsByProtocolId.set(protocolRunId, activeRun);
+        while (runsByProtocolId.size > 16) {
+            const oldestId = runsByProtocolId.keys().next().value;
+            if (!oldestId)
+                break;
+            if (runsByProtocolId.get(oldestId) === activeRun) {
+                const current = runsByProtocolId.get(oldestId);
+                runsByProtocolId.delete(oldestId);
+                runsByProtocolId.set(oldestId, current);
+                continue;
+            }
+            runsByProtocolId.delete(oldestId);
         }
-        return true;
+        return activeRun;
     }
-    // Build the client-tools capability. catalogAsAgUiTools() is used below to
-    // thread the catalog into every runAgent() call.
-    const clientToolsCap = createClientToolsCapability(source, store);
     /** Forward a neutral-contract state patch onto the AG-UI run input.
      *  Mirrors the canonical demo's `input.state` mechanism: the patch is
      *  merged into the source agent's client state (carried on
@@ -795,9 +976,27 @@ function toAgent(source, options = {}) {
         store.state.update((prev) => ({ ...prev, ...patch }));
     };
     captureAgentRuntimeTelemetry(options.telemetry, 'tplane:runtime_instance_created', telemetryProperties);
-    function startRunTelemetry(requestType) {
-        const run = { startedAt: Date.now(), errored: false };
+    function beginRun(requestType, allowBaselineTail = false) {
+        if (activeRun && activeRun.outcome === undefined) {
+            const supersededRun = activeRun;
+            finalizeDeliveryRun(store, supersededRun, 'interrupted');
+            const interruption = new Error('Run superseded by a newer request');
+            interruption.name = 'InterruptedError';
+            failRunTelemetry(interruption, supersededRun);
+        }
+        const run = {
+            generation: allocateDeliveryGeneration('run'),
+            baselineMessageIds: new Set(store.messages().map(message => message.id)),
+            ownedMessageIds: new Set(),
+            snapshotReplacementIds: new Set(),
+            eligibleBaselineAssistantId: allowBaselineTail
+                ? getTailAssistantMessageId(store.messages())
+                : undefined,
+            startedAt: Date.now(),
+            telemetrySettled: false,
+        };
         activeRun = run;
+        store.deliveryRun = run;
         captureAgentRuntimeTelemetry(options.telemetry, 'tplane:runtime_request_created', {
             ...telemetryProperties,
             requestType,
@@ -806,76 +1005,115 @@ function toAgent(source, options = {}) {
         return run;
     }
     function finishRunTelemetry(run) {
-        if (run.errored)
+        if (run.telemetrySettled)
             return;
+        run.telemetrySettled = true;
         captureAgentRuntimeTelemetry(options.telemetry, 'tplane:stream_ended', {
             ...telemetryProperties,
             durationMs: Date.now() - run.startedAt,
         });
-        if (activeRun === run)
-            activeRun = null;
     }
     function failRunTelemetry(error, run = activeRun) {
-        if (!run || run.errored)
+        if (!run || run.telemetrySettled)
             return;
-        run.errored = true;
+        run.telemetrySettled = true;
         captureAgentRuntimeTelemetry(options.telemetry, 'tplane:stream_errored', {
             ...telemetryProperties,
             durationMs: Date.now() - run.startedAt,
             errorClass: agentRuntimeTelemetryErrorClass(error),
         });
-        if (activeRun === run)
-            activeRun = null;
     }
-    /**
-     * Fires the current message list against the source agent (no append).
-     * Both submit() and retry() share this path; submit() appends the user
-     * message first, retry() skips the append and calls this directly.
-     */
-    async function runCurrentMessages() {
-        const run = startRunTelemetry('submit');
+    function failRun(run, error) {
+        if (run.outcome !== undefined)
+            return;
+        finalizeDeliveryRun(store, run, 'error');
+        if (activeRun === run) {
+            store.status.set('error');
+            store.isLoading.set(false);
+            store.error.set(toAgentError(error));
+        }
+        failRunTelemetry(error, run);
+    }
+    function settleTransportClose(run) {
+        if (run.outcome === undefined) {
+            finalizeDeliveryRun(store, run, run.ownedMessageIds.size > 0 ? 'interrupted' : 'success');
+            if (activeRun === run) {
+                store.status.set('idle');
+                store.isLoading.set(false);
+                store.error.set(undefined);
+            }
+        }
+        finishRunTelemetry(run);
+    }
+    async function executeRun(requestType, parameters, allowBaselineTail = false) {
+        const run = beginRun(requestType, allowBaselineTail);
         const tools = clientToolsCap.catalogAsAgUiTools();
+        const runParameters = parameters === undefined && tools.length === 0
+            ? undefined
+            : { ...parameters, ...(tools.length > 0 ? { tools } : {}) };
         try {
-            await source.runAgent(tools.length > 0 ? { tools } : undefined);
-            finishRunTelemetry(run);
+            await source.runAgent(runParameters);
+            settleTransportClose(run);
         }
         catch (err) {
-            if (!settleIfAborted(err)) {
-                store.status.set('error');
-                store.isLoading.set(false);
-                store.error.set(toAgentError(err));
-                failRunTelemetry(err, run);
-            }
+            if (run.outcome === 'aborted' && isAbortError(err))
+                return;
+            failRun(run, err);
         }
     }
+    const clientToolsCap = createClientToolsCapability(source, store, () => executeRun('client-tool-continuation', undefined, true));
     // Tap all events from the source agent via the AgentSubscriber API.
     // This subscription lives for the lifetime of `source`.
     source.subscribe({
-        onEvent({ event }) {
-            // The AG-UI client surfaces a user-initiated abort both as a
-            // RUN_ERROR event (here) and via onRunFailed; guard the event path too
-            // so the reducer never marks a deliberate stop as an error.
-            if (event.type === 'RUN_ERROR') {
-                const message = event.message ?? '';
-                if (settleIfAborted(new Error(message)))
-                    return;
+        onRunInitialized({ input }) {
+            resolveCallbackRun(input.runId);
+        },
+        onEvent({ event, input }) {
+            const callbackRunId = input?.runId ?? event.runId;
+            const run = resolveCallbackRun(callbackRunId);
+            if (!run) {
+                if (!callbackRunId)
+                    reduceEvent(event, store);
+                return;
+            }
+            if (run !== activeRun) {
+                if (event.type === 'RUN_FINISHED')
+                    finalizeDeliveryRun(store, run, 'success');
+                else if (event.type === 'RUN_ERROR')
+                    finalizeDeliveryRun(store, run, 'error');
+                return;
             }
+            if (event.type === 'RUN_ERROR' && run.outcome === 'aborted')
+                return;
             reduceEvent(event, store);
+            if (run && event.type === 'RUN_FINISHED' && run.outcome === 'success') {
+                finishRunTelemetry(run);
+            }
+            else if (run && event.type === 'RUN_ERROR' && run.outcome === 'error') {
+                failRunTelemetry(event.message ?? event, run);
+            }
         },
-        onRunFailed({ error }) {
-            if (settleIfAborted(error))
+        onRunFailed({ error, input }) {
+            const run = resolveCallbackRun(input?.runId);
+            if (run) {
+                if (run.outcome === 'aborted' && isAbortError(error))
+                    return;
+                failRun(run, error);
+                return;
+            }
+            if (input?.runId)
                 return;
             store.status.set('error');
             store.isLoading.set(false);
             store.error.set(toAgentError(error));
-            failRunTelemetry(error);
         },
     });
     // Stable Subagent wrappers per messageId so chat-subagents (tracks by
     // toolCallId) doesn't churn as activity content streams.
     const subagentWrappers = new Map();
     function subagentFor(id, entry) {
-        let w = subagentWrappers.get(id);
+        const cached = subagentWrappers.get(id);
+        let w = cached?.generation === entry.generation ? cached.wrapper : undefined;
         if (!w) {
             w = {
                 toolCallId: entry.content()['toolCallId'] ?? id,
@@ -883,17 +1121,27 @@ function toAgent(source, options = {}) {
                 status: computed(() => entry.content()['status'] ?? 'running'),
                 messages: computed(() => {
                     const c = entry.content();
+                    const status = c['status'] ?? 'running';
+                    const assistantDelivery = status === 'error'
+                        ? completeDelivery(entry.generation, 'error')
+                        : status === 'complete'
+                            ? completeDelivery(entry.generation, 'success')
+                            : streamingDelivery(entry.generation);
                     const raw = c['messages'];
                     if (Array.isArray(raw)) {
-                        return raw.map((m, i) => ({
-                            id: m['id'] ?? `${id}-${i}`,
-                            role: 'assistant',
-                            content: typeof m['content'] === 'string' ? m['content'] : m['content'] ?? '',
-                            ...(Array.isArray(m['toolCallIds']) ? { toolCallIds: m['toolCallIds'] } : {}),
-                            ...(typeof m['reasoning'] === 'string' ? { reasoning: m['reasoning'] } : {}),
-                        }));
+                        return raw.map((m, i) => {
+                            const messageId = m['id'] ?? `${id}-${i}`;
+                            return {
+                                id: messageId,
+                                role: 'assistant',
+                                content: typeof m['content'] === 'string' ? m['content'] : m['content'] ?? '',
+                                delivery: m['role'] === 'assistant' ? assistantDelivery : staticDelivery(messageId),
+                                ...(Array.isArray(m['toolCallIds']) ? { toolCallIds: m['toolCallIds'] } : {}),
+                                ...(typeof m['reasoning'] === 'string' ? { reasoning: m['reasoning'] } : {}),
+                            };
+                        });
                     }
-                    return [{ id, role: 'assistant', content: String(c['text'] ?? '') }];
+                    return [{ id, role: 'assistant', content: String(c['text'] ?? ''), delivery: assistantDelivery }];
                 }),
                 toolCalls: computed(() => {
                     const raw = entry.content()['toolCalls'];
@@ -901,7 +1149,7 @@ function toAgent(source, options = {}) {
                 }),
                 state: computed(() => entry.content()['state'] ?? {}),
             };
-            subagentWrappers.set(id, w);
+            subagentWrappers.set(id, { generation: entry.generation, wrapper: w });
         }
         return w;
     }
@@ -932,33 +1180,13 @@ function toAgent(source, options = {}) {
         }),
         clientTools: clientToolsCap,
         submit: async (input, _opts) => {
-            // Reset both abort flags so a new submit starts clean and genuine
-            // failures after a previous stop are never swallowed.
-            abortRequested = false;
-            abortSettled = false;
             if (input.resume !== undefined) {
                 // Resume path: clear the pending interrupt and replay the run with the
                 // resume payload forwarded to the LangGraph backend via AG-UI's
                 // forwardedProps.command.resume mechanism.
                 applyStatePatch(input.state);
                 store.interrupt.set(undefined);
-                const run = startRunTelemetry('resume');
-                const tools = clientToolsCap.catalogAsAgUiTools();
-                try {
-                    await source.runAgent({
-                        forwardedProps: { command: { resume: input.resume } },
-                        ...(tools.length > 0 ? { tools } : {}),
-                    });
-                    finishRunTelemetry(run);
-                }
-                catch (err) {
-                    if (!settleIfAborted(err)) {
-                        store.status.set('error');
-                        store.isLoading.set(false);
-                        store.error.set(toAgentError(err));
-                        failRunTelemetry(err, run);
-                    }
-                }
+                await executeRun('resume', { forwardedProps: { command: { resume: input.resume } } }, true);
                 return;
             }
             applyStatePatch(input.state);
@@ -973,7 +1201,7 @@ function toAgent(source, options = {}) {
             // Record the input so retry() can re-run it without re-appending the
             // user message (the message is already in the list by this point).
             lastInput = input;
-            await runCurrentMessages();
+            await executeRun('submit');
         },
         retry: async () => {
             if (store.isLoading())
@@ -984,22 +1212,23 @@ function toAgent(source, options = {}) {
             // Re-run the same message list against the source without appending a
             // duplicate user message — the message is already in store.messages and
             // source's internal list from the original submit().
-            await runCurrentMessages();
+            await executeRun('retry', undefined, true);
         },
         stop: async () => {
-            abortRequested = true;
+            const run = activeRun;
+            if (run && run.outcome === undefined) {
+                finalizeDeliveryRun(store, run, 'aborted');
+                store.status.set('idle');
+                store.isLoading.set(false);
+                store.error.set(undefined);
+                finishRunTelemetry(run);
+            }
             source.abortRun();
         },
         regenerate: async (assistantMessageIndex) => {
             if (store.isLoading()) {
                 throw new Error('Cannot regenerate while agent is loading another response');
             }
-            // Reset abort flags so a regenerate starts clean, exactly like submit().
-            // Without this, flags left over from a prior stop() would cause the
-            // duplicate-delivery guard in settleIfAborted() to silently swallow the
-            // abort error without settling, wedging the store in streaming/running.
-            abortRequested = false;
-            abortSettled = false;
             const msgs = store.messages();
             const target = msgs[assistantMessageIndex];
             if (!target || target.role !== 'assistant') {
@@ -1025,20 +1254,7 @@ function toAgent(source, options = {}) {
             // agent's internal message list without appending — the trailing user
             // message in `trimmed` becomes the active prompt for the next run.
             source.setMessages(trimmed);
-            const run = startRunTelemetry('regenerate');
-            const regenTools = clientToolsCap.catalogAsAgUiTools();
-            try {
-                await source.runAgent(regenTools.length > 0 ? { tools: regenTools } : undefined);
-                finishRunTelemetry(run);
-            }
-            catch (err) {
-                if (!settleIfAborted(err)) {
-                    store.status.set('error');
-                    store.isLoading.set(false);
-                    store.error.set(toAgentError(err));
-                    failRunTelemetry(err, run);
-                }
-            }
+            await executeRun('regenerate');
         },
     };
 }
@@ -1048,11 +1264,16 @@ function buildUserMessage(input) {
     const content = typeof input.message === 'string'
         ? input.message
         : input.message.map((b) => b.type === 'text' ? b.text : JSON.stringify(b)).join('');
-    return { id: randomId(), role: 'user', content };
+    const id = randomId();
+    return { id, role: 'user', content, delivery: staticDelivery(id) };
 }
 function randomId() {
     return Math.random().toString(36).slice(2);
 }
+function getTailAssistantMessageId(messages) {
+    const tail = messages[messages.length - 1];
+    return tail?.role === 'assistant' ? tail.id : undefined;
+}
 
 // SPDX-License-Identifier: MIT
 /**
@@ -1111,6 +1332,8 @@ class FakeAgent extends AbstractAgent {
     reasoningTokens;
     /** Milliseconds between successive token emissions. */
     delayMs;
+    /** Optional deterministic event branches for tests that need exact streams. */
+    script;
     constructor(opts = {}) {
         super();
         this.tokens = opts.tokens ?? [
@@ -1119,11 +1342,14 @@ class FakeAgent extends AbstractAgent {
         ];
         this.reasoningTokens = opts.reasoningTokens ?? [];
         this.delayMs = opts.delayMs ?? 60;
+        this.script = opts.script ?? [];
     }
     run(input) {
+        const scripted = this.scriptedSequence(input);
+        if (scripted)
+            return this.emitSequence(scripted, 30);
         const tokens = this.tokens;
         const reasoningTokens = this.reasoningTokens;
-        const delayMs = this.delayMs;
         const messageId = `fake-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
         const sequence = [
             { type: EventType.RUN_STARTED, threadId: input.threadId, runId: input.runId },
@@ -1141,6 +1367,22 @@ class FakeAgent extends AbstractAgent {
         }
         sequence.push({ type: EventType.TEXT_MESSAGE_END, messageId });
         sequence.push({ type: EventType.RUN_FINISHED, threadId: input.threadId, runId: input.runId });
+        return this.emitSequence(sequence, 30);
+    }
+    scriptedSequence(input) {
+        if (this.script.length === 0)
+            return undefined;
+        const branch = this.script.find((candidate) => matchesBranch(candidate.when, input));
+        if (!branch)
+            return undefined;
+        return [
+            { type: EventType.RUN_STARTED, threadId: input.threadId, runId: input.runId },
+            ...branch.events,
+            { type: EventType.RUN_FINISHED, threadId: input.threadId, runId: input.runId },
+        ];
+    }
+    emitSequence(sequence, initialDelayMs) {
+        const delayMs = this.delayMs;
         return new Observable((observer) => {
             let cancelled = false;
             let timer;
@@ -1157,7 +1399,7 @@ class FakeAgent extends AbstractAgent {
                 // Steady cadence except a tiny initial delay before RUN_STARTED.
                 timer = setTimeout(emitNext, delayMs);
             };
-            timer = setTimeout(emitNext, 30);
+            timer = setTimeout(emitNext, initialDelayMs);
             return () => {
                 cancelled = true;
                 if (timer !== undefined)
@@ -1166,6 +1408,26 @@ class FakeAgent extends AbstractAgent {
         });
     }
 }
+function matchesBranch(when, input) {
+    if (when === 'initial')
+        return !hasToolMessages(input);
+    return hasToolMessageFor(input, when.toolMessageFor);
+}
+function hasToolMessages(input) {
+    return (input.messages ?? []).some((message) => isToolMessage(message));
+}
+function hasToolMessageFor(input, toolCallId) {
+    return (input.messages ?? []).some((message) => {
+        if (!isToolMessage(message))
+            return false;
+        const record = message;
+        return record['toolCallId'] === toolCallId || record['tool_call_id'] === toolCallId;
+    });
+}
+function isToolMessage(message) {
+    const record = message;
+    return record['role'] === 'tool' || record['type'] === 'tool';
+}
 
 /**
  * Registers an in-process FakeAgent under AGENT.
@@ -1176,7 +1438,7 @@ class FakeAgent extends AbstractAgent {
  * @example
  * ```ts
  * TestBed.configureTestingModule({
- *   providers: [provideFakeAgent({ responses: ['Hello from the fake agent'] })],
+ *   providers: [provideFakeAgent({ tokens: ['Hello from the fake agent'] })],
  * });
  * ```
  */