@threadplane/langgraph 0.0.57 → 0.0.59

package/fesm2022/threadplane-langgraph.mjs

@@ -278,6 +278,7 @@ class SubagentTracker {
             this.subagents.set(id, {
                 id,
                 generation: existing?.generation ?? createSubagentGeneration(),
+                kind: 'tool',
                 status: existing?.status ?? 'pending',
                 toolCall: {
                     id,
@@ -328,14 +329,14 @@ class SubagentTracker {
             return toolCallId;
         };
         for (const [toolCallId, subagent] of this.subagents) {
-            if (mapped.has(toolCallId))
+            if (subagent.kind !== 'tool' || mapped.has(toolCallId))
                 continue;
             if (subagent.toolCall.args['description'] === description) {
                 return establish(toolCallId);
             }
         }
         for (const [toolCallId, subagent] of this.subagents) {
-            if (mapped.has(toolCallId))
+            if (subagent.kind !== 'tool' || mapped.has(toolCallId))
                 continue;
             const subagentDescription = subagent.toolCall.args['description'];
             if (typeof subagentDescription !== 'string' || !subagentDescription)
@@ -344,7 +345,11 @@ class SubagentTracker {
                 return establish(toolCallId);
             }
         }
+        // Last-resort fallback — tool children only. A subgraph child is keyed by
+        // its own namespace and must never absorb an unrelated child's events.
         for (const [toolCallId, subagent] of this.subagents) {
+            if (subagent.kind !== 'tool')
+                continue;
             if (!mapped.has(toolCallId) && (subagent.status === 'pending' || subagent.status === 'running')) {
                 return establish(toolCallId);
             }
@@ -372,6 +377,46 @@ class SubagentTracker {
         });
         this.onSubagentChange?.();
     }
+    /**
+     * Register a plain-subgraph child stream on its first namespaced event.
+     *
+     * Unlike tool children — announced ahead of time by the parent's tool call —
+     * a compiled child added as a plain node has no announcement: its existence
+     * is learned from the first event carrying its namespace. It starts
+     * 'running' because by the time we see an event, it is.
+     */
+    ensureSubgraphStream(key, name) {
+        if (this.subagents.has(key))
+            return;
+        this.subagents.set(key, {
+            id: key,
+            generation: createSubagentGeneration(),
+            kind: 'subgraph',
+            status: 'running',
+            toolCall: { id: key, name, args: {} },
+            values: {},
+            messages: [],
+        });
+        this.onSubagentChange?.();
+    }
+    /**
+     * Settle still-running subgraph children when the run reaches a terminal
+     * outcome. Tool children settle through their tool result
+     * (`processToolMessage`); subgraph children have no result message, so the
+     * run's own settle is their completion signal. Paused/interrupted runs must
+     * NOT call this — a child can resume with the thread.
+     */
+    settleRunningSubgraphs(outcome) {
+        let changed = false;
+        for (const [key, subagent] of this.subagents) {
+            if (subagent.kind !== 'subgraph' || subagent.status !== 'running')
+                continue;
+            this.subagents.set(key, { ...subagent, status: outcome });
+            changed = true;
+        }
+        if (changed)
+            this.onSubagentChange?.();
+    }
     updateSubagentValues(namespaceId, values) {
         const toolCallId = this.resolveToolCallId(namespaceId);
         const subagent = this.subagents.get(toolCallId);
@@ -437,12 +482,40 @@ class SubagentTracker {
         return this.namespaceToToolCallId.get(namespaceId) ?? namespaceId;
     }
 }
-function isSubagentNamespace(namespace) {
+/**
+ * True when a stream event belongs to a child graph rather than the parent —
+ * i.e. it carries any namespace at all. This is the single classification
+ * question; which child owns the event is a separate (attribution) question.
+ *
+ * Kept consistent with the terminal-evidence guard, which has always refused
+ * ANY namespaced event as proof the parent run finished.
+ */
+function isChildNamespace(namespace) {
     if (!namespace)
         return false;
     if (typeof namespace === 'string')
-        return namespace.includes('tools:');
-    return namespace.some(segment => segment.startsWith('tools:'));
+        return namespace.length > 0;
+    return namespace.length > 0;
+}
+/**
+ * Derive a child stream's identity from an event namespace.
+ *
+ * `tools:<id>` segments identify a tool-dispatched child by its tool-call id.
+ * Any other segment (e.g. `research:<uuid>` from a compiled graph added with
+ * `add_node`) identifies a plain subgraph child: the full segment is the key
+ * (unique per invocation) and the part before the first ':' is the node name.
+ */
+function childStreamRefFromNamespace(namespace) {
+    for (const segment of namespace) {
+        if (segment.startsWith('tools:')) {
+            return { key: segment.slice(6), name: '', kind: 'tool' };
+        }
+    }
+    const first = namespace[0];
+    if (!first)
+        return undefined;
+    const colon = first.indexOf(':');
+    return { key: first, name: colon > 0 ? first.slice(0, colon) : first, kind: 'subgraph' };
 }
 function extractToolCallIdFromNamespace(namespace) {
     if (!namespace)
@@ -649,6 +722,13 @@ function createStreamManagerBridge({ options, subjects, threadId$, destroy$ }) {
                 continue;
             finalizeMessage(attempt, id, outcome);
         }
+        // Subgraph children have no tool result to settle them; the run's own
+        // terminal outcome is their completion signal. Paused/interrupted runs
+        // are excluded — a child can resume with the thread.
+        if (outcome === 'success' || outcome === 'error' || outcome === 'aborted') {
+            subagentManager.settleRunningSubgraphs(outcome === 'success' ? 'complete' : 'error');
+            publishSubagents();
+        }
     }
     function finishOutcome(attempt) {
         return attempt.terminalOutcome
@@ -750,6 +830,8 @@ function createStreamManagerBridge({ options, subjects, threadId$, destroy$ }) {
         if (resetState) {
             invalidateQueueDrain();
             abortController?.abort();
+            lastPayload = null;
+            lastOptions = undefined;
         }
         currentThreadId = id;
         if (resetState) {
@@ -1011,7 +1093,7 @@ function createStreamManagerBridge({ options, subjects, threadId$, destroy$ }) {
         subjects.toolProgress$.next([]);
         toolProgressMap.clear();
         canonicalMessageIds.clear();
-        lastPayload = payload;
+        lastPayload = payload ?? null;
         lastOptions = opts;
         // Tracks whether at least one stream event has been processed this run.
         // Used to distinguish a mid-stream network interruption (kind:'interrupted')
@@ -1044,10 +1126,10 @@ function createStreamManagerBridge({ options, subjects, threadId$, destroy$ }) {
                 processEvent(event);
             }
             if (!isCurrentExecution(controller, attempt))
-                return;
+                return finishOutcome(attempt);
             const outcome = await finalizeClosedAttempt(controller, attempt);
             if (outcome === null)
-                return;
+                return finishOutcome(attempt);
             if (!controller.signal.aborted) {
                 if (outcome !== 'error') {
                     subjects.status$.next(ResourceStatus.Resolved);
@@ -1058,12 +1140,13 @@ function createStreamManagerBridge({ options, subjects, threadId$, destroy$ }) {
                     durationMs: Date.now() - startedAt,
                 });
             }
+            return outcome;
         }
         catch (err) {
             if (!isCurrentExecution(controller, attempt))
-                return;
+                return finishOutcome(attempt);
             if (attempt.terminalOutcome)
-                return;
+                return attempt.terminalOutcome;
             if (isAbortError(err) && userAbortedControllers.has(controller)) {
                 finalizeAttempt(attempt, 'aborted');
                 // User explicitly called stop() — treat as graceful idle, not an error.
@@ -1095,6 +1178,7 @@ function createStreamManagerBridge({ options, subjects, threadId$, destroy$ }) {
                     errorClass: agentRuntimeTelemetryErrorClass(err),
                 });
             }
+            return finishOutcome(attempt);
         }
         finally {
             if (abortController === controller)
@@ -1114,17 +1198,23 @@ function createStreamManagerBridge({ options, subjects, threadId$, destroy$ }) {
             const normalized = options.toMessage
                 ? msgs.map(options.toMessage)
                 : msgs;
-            if (isSubagentNamespace(namespace)) {
-                const namespaceId = namespace ? extractToolCallIdFromNamespace(namespace) : undefined;
-                if (namespaceId) {
+            // Any namespaced message event is child content. It feeds the child's
+            // stream and never merges into the parent transcript — the parent
+            // transcript is what the parent graph says. Shared-state children still
+            // surface at settle through the authoritative top-level `values` sync.
+            if (isChildNamespace(namespace)) {
+                const child = namespace ? childStreamRefFromNamespace(namespace) : undefined;
+                if (child) {
+                    if (child.kind === 'subgraph') {
+                        subagentManager.ensureSubgraphStream(child.key, child.name);
+                    }
                     for (const msg of normalized) {
-                        subagentManager.addMessageToSubagent(namespaceId, msg);
+                        subagentManager.addMessageToSubagent(child.key, msg);
                     }
                     publishSubagents();
                 }
-                if (options.filterSubagentMessages) {
-                    return;
-                }
+                storeMessageMetadata(normalized, event);
+                return;
             }
             // Partial and message-tuple events are incremental. Merge them by id
             // so optimistic human messages and earlier tool messages are preserved.
@@ -1139,7 +1229,7 @@ function createStreamManagerBridge({ options, subjects, threadId$, destroy$ }) {
                 const merged = mergeMessages(subjects.messages$.value, normalized, reasoningTimingMap, mode, canonicalMessageIds, affectedMessageIds, activeAttempt?.currentAssistantMessageId !== undefined
                     && activeAttempt.currentStepHasTerminalEvidence !== true);
                 subjects.messages$.next(merged);
-                if (!isSubagentNamespace(namespace)) {
+                {
                     trackAssistantMessages(merged.filter(message => {
                         const id = message['id'];
                         return typeof id === 'string' && affectedMessageIds.has(id);
@@ -1162,7 +1252,7 @@ function createStreamManagerBridge({ options, subjects, threadId$, destroy$ }) {
                 const affectedMessageIds = new Set();
                 const preserved = preserveIds(subjects.messages$.value, normalized, affectedMessageIds);
                 subjects.messages$.next(preserved);
-                if (!isSubagentNamespace(namespace)) {
+                {
                     trackAssistantMessages(preserved.filter(message => {
                         const id = message['id'];
                         return typeof id === 'string' && affectedMessageIds.has(id);
@@ -1181,8 +1271,11 @@ function createStreamManagerBridge({ options, subjects, threadId$, destroy$ }) {
         switch (baseType) {
             case 'values': {
                 const vals = extractEventData(event);
-                if (isSubagentNamespace(namespace) && isRecord$1(vals)) {
-                    updateSubagentValues(namespace, vals);
+                if (isChildNamespace(namespace)) {
+                    // A child's state must not clobber the parent's `values$` — route it
+                    // to the child stream and stop.
+                    if (isRecord$1(vals))
+                        updateSubagentValues(namespace, vals);
                     break;
                 }
                 if ((namespace?.length ?? 0) === 0) {
@@ -1248,7 +1341,9 @@ function createStreamManagerBridge({ options, subjects, threadId$, destroy$ }) {
             }
             case 'updates': {
                 const upd = extractEventData(event);
-                if (isSubagentNamespace(namespace)) {
+                if (isChildNamespace(namespace)) {
+                    // A child's updates must not spread-merge into the parent's
+                    // `values$` — they only mark the child stream running.
                     markSubagentRunning(namespace);
                     break;
                 }
@@ -1311,24 +1406,34 @@ function createStreamManagerBridge({ options, subjects, threadId$, destroy$ }) {
         publishSubagents();
     }
     function updateSubagentValues(namespace, values) {
-        const namespaceId = namespace ? extractToolCallIdFromNamespace(namespace) : undefined;
-        if (!namespaceId)
+        const child = namespace ? childStreamRefFromNamespace(namespace) : undefined;
+        if (!child)
             return;
-        const messages = values['messages'];
-        if (Array.isArray(messages) && messages.length > 0) {
-            const first = messages[0];
-            if (isRecord$1(first) && (first['type'] === 'human' || first['type'] === 'user') && typeof first['content'] === 'string') {
-                subagentManager.matchSubgraphToSubagent(namespaceId, first['content']);
+        if (child.kind === 'tool') {
+            // Attribution ladder applies to tool children only: their namespace id
+            // may need mapping onto a registered tool call.
+            const messages = values['messages'];
+            if (Array.isArray(messages) && messages.length > 0) {
+                const first = messages[0];
+                if (isRecord$1(first) && (first['type'] === 'human' || first['type'] === 'user') && typeof first['content'] === 'string') {
+                    subagentManager.matchSubgraphToSubagent(child.key, first['content']);
+                }
             }
         }
-        subagentManager.updateSubagentValues(namespaceId, values);
+        else {
+            subagentManager.ensureSubgraphStream(child.key, child.name);
+        }
+        subagentManager.updateSubagentValues(child.key, values);
         publishSubagents();
     }
     function markSubagentRunning(namespace) {
-        const namespaceId = namespace ? extractToolCallIdFromNamespace(namespace) : undefined;
-        if (!namespaceId)
+        const child = namespace ? childStreamRefFromNamespace(namespace) : undefined;
+        if (!child)
             return;
-        subagentManager.markRunningFromNamespace(namespaceId, namespace);
+        if (child.kind === 'subgraph') {
+            subagentManager.ensureSubgraphStream(child.key, child.name);
+        }
+        subagentManager.markRunningFromNamespace(child.key, namespace);
         publishSubagents();
     }
     function publishSubagents() {
@@ -1407,9 +1512,9 @@ function createStreamManagerBridge({ options, subjects, threadId$, destroy$ }) {
         submit: async (payload, opts) => {
             if (opts?.multitaskStrategy === 'enqueue' && subjects.status$.value === ResourceStatus.Loading) {
                 await enqueueRun(payload, opts);
-                return;
+                return 'success';
             }
-            await runStream(payload, opts);
+            return runStream(payload, opts);
         },
         stop: async () => {
             invalidateQueueDrain();
@@ -1499,9 +1604,9 @@ function createStreamManagerBridge({ options, subjects, threadId$, destroy$ }) {
             }
         },
         resubmitLast: async () => {
-            if (lastPayload !== null) {
-                await runStream(lastPayload, lastOptions, 'resubmit');
-            }
+            if (lastPayload === null)
+                return 'not-started';
+            return runStream(lastPayload, lastOptions, 'resubmit');
         },
         getReasoningDurationMs: (id) => {
             const entry = reasoningTimingMap.get(id);
@@ -2126,9 +2231,13 @@ function toSubagentRefs(subagents) {
     subagents.forEach((subagent, key) => {
         refs.set(key, {
             toolCallId: subagent.id,
+            // Tool children are named by their `subagent_type` arg; subgraph
+            // children by their node name (stored as the synthetic toolCall name).
             name: typeof subagent.toolCall.args['subagent_type'] === 'string'
                 ? subagent.toolCall.args['subagent_type']
-                : undefined,
+                : subagent.kind === 'subgraph'
+                    ? subagent.toolCall.name
+                    : undefined,
             status: signal(subagent.status),
             values: signal(subagent.values),
             messages: signal(subagent.messages),
@@ -2364,6 +2473,24 @@ function mergeClientTools(payload, catalog) {
         return payload;
     return { ...payload, client_tools: catalog };
 }
+/**
+ * Merge A2UI client capabilities into a run payload under the
+ * `a2ui_client_capabilities` state key. Same payload semantics as
+ * {@link mergeClientTools}: null/undefined payloads (command resumes,
+ * regenerates) and non-record payloads pass through untouched, and the
+ * original object is never mutated. Because LangGraph thread state
+ * persists across runs, the capabilities stamped by any run remain
+ * readable by later runs on the same thread.
+ */
+function mergeA2uiClientCapabilities(payload, capabilities) {
+    if (!capabilities)
+        return payload;
+    if (payload === null || payload === undefined)
+        return payload;
+    if (typeof payload !== 'object' || Array.isArray(payload))
+        return payload;
+    return { ...payload, a2ui_client_capabilities: capabilities };
+}
 /**
  * Prepend staged tool messages to a run payload's message list.
  *
@@ -2396,22 +2523,25 @@ function mergeStagedToolMessages(payload, staged) {
  *    The backend ends the run without emitting a ToolMessage result for
  *    client tools, so `result` stays undefined on those entries.
  *  - settle(id, result): marks the call as resolved, writes the local result,
- *    and buffers a ToolMessage without issuing a run.
- *  - flush(): makes the whole buffer durable in ONE persistFn call without
+ *    and stages a ToolMessage with a deterministic ID without issuing a run.
+ *  - flush(): snapshots the whole staged group into ONE persistFn call without
  *    starting a run — the settlement path for tool groups that never continue.
- *    The batch leaves the buffer at snapshot time and is re-staged only if the
- *    write fails, so a failure (or an absent persistFn) still degrades to the
- *    next flush or to the drainToolMessages() fallback in the submit wrapper,
- *    while a concurrent resolve()/drain can never re-send an in-flight batch.
- *  - clearStagedToolMessages(): discards the buffer on a thread switch.
+ *    Successful persistence acknowledges the captured entries; failed writes
+ *    retain them. When persistFn is absent, a non-empty flush rejects without
+ *    changing the staged results. Flushes are chained so entries settled after
+ *    one snapshot receive their own write. Concurrent persistence,
+ *    continuation, and ordinary submits may safely carry the same stable IDs.
+ *  - clearStagedToolMessages(): discards staged results on a thread switch and
+ *    advances the generation so late acknowledgments cannot affect new state.
  *  - resolve(id, result): settles the result, then issues a NEW run on the SAME
- *    thread by calling submitFn with the full buffered ToolMessage group:
+ *    thread by calling submitFn with a non-destructive ToolMessage snapshot:
  *      input: {
  *        messages: [{ type: 'tool', role: 'tool', tool_call_id: id, content }],
  *        client_tools: catalog(),
  *      }
- *    The `add_messages` reducer on the Python side appends the ToolMessage
- *    to thread state. Including `client_tools` ensures the model sees the
+ *    The snapshot remains staged unless that continuation reports success.
+ *    LangGraph's `add_messages` reducer reuses each stable message ID on safe
+ *    overlap or replay. Including `client_tools` ensures the model sees the
  *    full tool catalog on the continuation run.
  *
  * Catalog shipping: the catalog is NOT injected by this factory's
@@ -2426,8 +2556,8 @@ function createClientToolsCapability(submitFn, store, persistFn, currentThreadId
     const resolvedIds = signal(new Set(), ...(ngDevMode ? [{ debugName: "resolvedIds" }] : []));
     const toolMessageBuffer = [];
     let flushInFlight;
-    // Bumped whenever the buffer is discarded, so an in-flight flush can tell
-    // whether its batch still belongs to the current thread.
+    // Bumped whenever a thread reset discards staged state. Every snapshot keeps
+    // its generation, making acknowledgments from the prior thread no-ops.
     let bufferGeneration = 0;
     // Tool calls belonging to threads we have left. A handler still running when
     // the user switches threads settles AFTER the switch, by which point both the
@@ -2482,62 +2612,76 @@ function createClientToolsCapability(submitFn, store, persistFn, currentThreadId
         // shape used in buildSubmitUpdate (agent.fn.ts line 732).
         toolMessageBuffer.push({
             threadId: currentThreadIdFn?.() ?? null,
-            message: { type: 'tool', role: 'tool', tool_call_id: id, content },
+            message: {
+                id: `client-tool-result-${id}`,
+                type: 'tool',
+                role: 'tool',
+                tool_call_id: id,
+                content,
+            },
         });
     }
     /**
-     * Remove every staged entry, returning only those still valid for the thread
-     * a write would land on right now. An entry is stale when it was stamped with
-     * a different thread — dropped rather than misdelivered.
+     * Returns a non-destructive snapshot of entries still valid for the thread a
+     * write would land on right now. Captured entries remain staged, so
+     * overlapping operations may carry the same deterministic message IDs.
+     * Acknowledgment removes only the exact captured entries while the snapshot
+     * generation is current. An entry stamped for another thread is dropped
+     * rather than misdelivered.
      *
      * A null on either side means "thread not tracked yet" (no threadId option
      * and no run has reported one); those are kept, since there is no evidence of
      * a switch and dropping them would lose results on untracked transports.
      */
-    function takeStagedForCurrentThread() {
+    function snapshotToolMessages() {
         const current = currentThreadIdFn?.() ?? null;
-        const taken = toolMessageBuffer.splice(0, toolMessageBuffer.length);
-        return taken.filter((entry) => {
+        for (let index = toolMessageBuffer.length - 1; index >= 0; index -= 1) {
+            const entry = toolMessageBuffer[index];
             const stale = entry.threadId !== null && current !== null && entry.threadId !== current;
             if (stale) {
                 console.warn(`Discarding a client tool result staged for thread ${entry.threadId}; ` +
                     `the active thread is now ${current}.`);
+                toolMessageBuffer.splice(index, 1);
             }
-            return !stale;
-        });
+        }
+        const generation = bufferGeneration;
+        const entries = [...toolMessageBuffer];
+        const messages = entries.map(({ message }) => ({ ...message }));
+        let acknowledged = false;
+        return {
+            generation,
+            messages,
+            acknowledge() {
+                if (acknowledged || generation !== bufferGeneration)
+                    return;
+                acknowledged = true;
+                for (const entry of entries) {
+                    const index = toolMessageBuffer.indexOf(entry);
+                    if (index !== -1)
+                        toolMessageBuffer.splice(index, 1);
+                }
+            },
+        };
     }
     /**
-     * Persist one batch. Takes ownership of the buffer at snapshot time:
-     * resolve() and drainToolMessages() clear the buffer unconditionally and know
-     * nothing about an in-flight write, so anything left staged across the await
-     * could be re-sent (a duplicate ToolMessage for one tool_call_id) or removed
-     * by the wrong index (dropping a result that was never persisted).
+     * Persist one snapshot. Only that snapshot is acknowledged after persistence
+     * succeeds; failure leaves its exact entries staged for retry or submit.
      */
     function runFlush() {
-        if (!persistFn)
-            return Promise.resolve();
-        const staged = takeStagedForCurrentThread();
-        if (staged.length === 0)
+        const batch = snapshotToolMessages();
+        if (batch.messages.length === 0)
             return Promise.resolve();
-        const generation = bufferGeneration;
-        const batch = staged.map((entry) => entry.message);
-        const inFlight = persistFn(batch)
-            .catch((err) => {
-            // Re-stage at the FRONT so ordering is preserved for the next drain —
-            // unless the buffer was cleared meanwhile (thread switch), in which
-            // case these results belong to a thread we have left.
-            if (generation === bufferGeneration) {
-                toolMessageBuffer.unshift(...staged);
-            }
-            console.warn(`Client tool flush failed; ${batch.length} result(s) remain staged for the next run.`, err);
+        if (!persistFn) {
+            return Promise.reject(new Error('Cannot flush staged client tool results. ' +
+                'Custom LangGraph transports using terminal client tools must implement updateState().'));
+        }
+        return persistFn(batch.messages)
+            .then(() => {
+            batch.acknowledge();
         })
-            .finally(() => {
-            // Only clear if no later flush has already claimed the slot.
-            if (flushInFlight === inFlight)
-                flushInFlight = undefined;
+            .catch((err) => {
+            console.warn(`Client tool flush failed; ${batch.messages.length} result(s) remain staged for the next run.`, err);
         });
-        flushInFlight = inFlight;
-        return inFlight;
     }
     const capability = {
         catalog,
@@ -2548,9 +2692,8 @@ function createClientToolsCapability(submitFn, store, persistFn, currentThreadId
         settle(id, result) {
             settleResult(id, result);
         },
-        /** Remove and return every buffered tool message valid for this thread. */
-        drainToolMessages() {
-            return takeStagedForCurrentThread().map((entry) => entry.message);
+        snapshotToolMessages() {
+            return snapshotToolMessages();
         },
         /**
          * Discard everything staged. Called when the active thread changes: a
@@ -2564,36 +2707,43 @@ function createClientToolsCapability(submitFn, store, persistFn, currentThreadId
             for (const toolCall of store.toolCalls())
                 retiredToolCallIds.add(toolCall.id);
             toolMessageBuffer.length = 0;
-            // Invalidate any in-flight flush so its failure path cannot re-stage the
-            // old thread's messages into the new thread's buffer.
+            // Invalidate every outstanding snapshot acknowledgment from the old thread.
             bufferGeneration += 1;
         },
         flush() {
-            if (!persistFn)
-                return Promise.resolve();
-            if (flushInFlight) {
-                // Chain rather than short-circuit. The caller's batch may have been
-                // staged AFTER the in-flight write took its snapshot, so returning that
-                // promise would resolve without ever persisting it — which is exactly
-                // what happens when an abort fires one flush per settled call. The
-                // chain terminates because runFlush() returns immediately once the
-                // buffer is empty.
-                const chained = flushInFlight.then(() => runFlush());
-                flushInFlight = chained;
-                return chained;
-            }
-            return runFlush();
+            // Only this method owns the queue tail. Results settled after an active
+            // snapshot need their own write, and every caller must remain behind all
+            // callers already queued. The chain terminates when a fresh snapshot is
+            // empty.
+            const queued = flushInFlight
+                ? flushInFlight.then(() => runFlush(), () => runFlush())
+                : runFlush();
+            flushInFlight = queued;
+            const clearTail = () => {
+                if (flushInFlight === queued)
+                    flushInFlight = undefined;
+            };
+            // Both handlers return normally, so this bookkeeping branch cannot
+            // create an unhandled rejection when the caller observes `queued`.
+            void queued.then(clearTail, clearTail);
+            return queued;
         },
         resolve(id, result) {
             settleResult(id, result);
-            // Issue a new run on the same thread. LangGraph's add_messages reducer
-            // appends the ToolMessages to the thread state. `client_tools` is
-            // included so the model sees the full tool catalog on the continuation.
+            // Issue a new run with a non-destructive snapshot. The exact batch is
+            // acknowledged only when that continuation succeeds; failures retain it
+            // for retry. Stable IDs make overlap with flush or submit safe under
+            // LangGraph's add_messages reducer. `client_tools` keeps the full catalog
+            // visible to the continuation.
+            const batch = snapshotToolMessages();
             const toolPayload = {
-                messages: takeStagedForCurrentThread().map((entry) => entry.message),
+                messages: batch.messages,
                 client_tools: catalog(),
             };
-            void submitFn(toolPayload);
+            void submitFn(toolPayload, undefined, batch).then((outcome) => {
+                if (outcome === 'success')
+                    batch.acknowledge();
+            });
         },
     };
     return capability;
@@ -2709,6 +2859,7 @@ function agent(options) {
     // seam lives here. A holder keeps the binding itself a `const` while its
     // member is filled in later.
     const clientToolStaging = {};
+    let retryableToolMessageBatch;
     function resetDerivedThreadState() {
         status$.next(ResourceStatus.Idle);
         error$.next(undefined);
@@ -2920,10 +3071,14 @@ function agent(options) {
     // updateState() silently no-ops when the transport has no updateState, so
     // only supply a persist function when the effective transport supports it —
     // an omitted transport means the bridge builds a FetchStreamTransport, which
-    // does. When persistFn is undefined, flush() keeps the buffer and the submit
-    // wrapper below drains it into the next run instead.
+    // does. When persistFn is undefined, a non-empty flush() rejects while the
+    // results stay staged; an ordinary non-null submit remains their in-memory
+    // fallback path.
     const canPersistToolMessages = !transport || typeof transport.updateState === 'function';
-    const clientToolsCap = createClientToolsCapability((payload, opts) => manager.submit(payload, opts), {
+    const clientToolsCap = createClientToolsCapability((payload, opts, batch) => {
+        retryableToolMessageBatch = batch;
+        return manager.submit(payload, opts);
+    }, {
         toolCalls: toolCallsNeutral,
         isLoading,
         applyClientResult: (id, patch) => clientResultOverrides.update((m) => new Map(m).set(id, patch)),
@@ -2942,7 +3097,16 @@ function agent(options) {
     // Stamps each staged result with the thread it was settled on, so a write
     // can never land on a thread the user has since moved to.
     () => manager.currentThreadId);
-    clientToolStaging.clear = () => clientToolsCap.clearStagedToolMessages();
+    clientToolStaging.clear = () => {
+        retryableToolMessageBatch = undefined;
+        clientToolsCap.clearStagedToolMessages();
+    };
+    async function resubmitWithToolRecovery() {
+        const batch = retryableToolMessageBatch;
+        const outcome = await manager.resubmitLast();
+        if (outcome === 'success')
+            batch?.acknowledge();
+    }
     return {
         // ── Runtime-neutral surface (AgentWithHistory) ────────────────────────
         messages: messagesNeutral,
@@ -2956,7 +3120,7 @@ function agent(options) {
         events$,
         history: historyNeutral,
         messageCheckpoints: messageCheckpointsSig,
-        submit: (input, opts) => {
+        submit: async (input, opts) => {
             // Lifecycle: first submit with no existing threadId → thread create.
             if (lcThreadCreatedAt() === null && lastThreadId == null) {
                 lcThreadCreatedAt.set(Date.now());
@@ -2970,25 +3134,33 @@ function agent(options) {
             // backend middleware can merge them into the model's tool list. Null
             // payloads (regenerate re-runs, command resumes) are left unchanged.
             //
-            // Drain any results settled but not yet made durable (flush unavailable
-            // or a prior flush failed) so they ride along with this run. A null
-            // payload cannot carry them, so leave the buffer alone in that case
-            // rather than silently discarding the staged results.
-            const staged = request.payload === null || request.payload === undefined
-                ? []
-                : clientToolsCap.drainToolMessages();
+            // Snapshot results settled but not yet durable (flush unavailable or a
+            // prior flush failed) so they ride along without being forgotten. The
+            // exact snapshot is acknowledged only when this operation succeeds;
+            // overlaps may safely carry the same deterministic message IDs. A null
+            // payload cannot carry results, so it leaves staging unchanged.
+            const batch = request.payload === null || request.payload === undefined
+                ? undefined
+                : clientToolsCap.snapshotToolMessages();
+            const staged = batch?.messages ?? [];
             const withStaged = staged.length > 0
                 ? mergeStagedToolMessages(request.payload, staged)
                 : request.payload;
-            const payload = mergeClientTools(withStaged, clientToolsCap.catalog());
-            return manager.submit(payload, request.options);
+            const payload = mergeA2uiClientCapabilities(mergeClientTools(withStaged, clientToolsCap.catalog()), options.a2uiClientCapabilities);
+            const createsQueuedRun = request.options?.multitaskStrategy === 'enqueue' && isLoading();
+            if (!createsQueuedRun) {
+                retryableToolMessageBatch = batch;
+            }
+            const outcome = await manager.submit(payload, request.options);
+            if (outcome === 'success')
+                batch?.acknowledge();
         },
         stop: () => manager.stop(),
         retry: async () => {
             if (isLoading())
                 return; // no-op while a run is in flight
             error$.next(undefined); // clear the error before re-running
-            await manager.resubmitLast();
+            await resubmitWithToolRecovery();
         },
         clientTools: clientToolsCap,
         regenerate: async (assistantMessageIndex) => {
@@ -3045,6 +3217,7 @@ function agent(options) {
             // at `__start__`, this resumes at the entry node and produces a fresh
             // assistant message — the trailing user message becomes the active
             // prompt without being re-appended.
+            retryableToolMessageBatch = undefined;
             await manager.submit(null, undefined);
         },
         // ── Raw LangGraph signals ─────────────────────────────────────────────
@@ -3056,7 +3229,9 @@ function agent(options) {
         // ── Other LangGraph-specific fields ──────────────────────────────────
         value: value,
         hasValue: hasValueSig,
-        reload: () => manager.resubmitLast(),
+        reload: () => {
+            void resubmitWithToolRecovery();
+        },
         toolProgress: toolProgSig,
         queue: queueSig,
         activeSubagents,
@@ -3354,7 +3529,6 @@ function agentFactory() {
         ...(config.transport !== undefined ? { transport: config.transport } : {}),
         ...(config.clientOptions !== undefined ? { clientOptions: config.clientOptions } : {}),
         ...(config.telemetry !== undefined ? { telemetry: config.telemetry } : {}),
-        ...(config.filterSubagentMessages !== undefined ? { filterSubagentMessages: config.filterSubagentMessages } : {}),
         ...(config.subagentToolNames !== undefined ? { subagentToolNames: config.subagentToolNames } : {}),
         ...(config.transcriptNodeNames !== undefined ? { transcriptNodeNames: config.transcriptNodeNames } : {}),
     });