@langchain/langgraph-sdk 1.9.19 → 1.9.21

package/dist/stream/index.d.ts

@@ -18,8 +18,9 @@ import { toolCallsProjection } from "./projections/tool-calls.js";
 import { valuesProjection } from "./projections/values.js";
 import { extensionProjection } from "./projections/extension.js";
 import { ChannelProjectionOptions, channelProjection } from "./projections/channel.js";
+import { ChannelEffectOptions, acquireChannelEffect } from "./projections/channel-effect.js";
 import { MediaProjectionOptions, audioProjection, filesProjection, imagesProjection, videoProjection } from "./projections/media.js";
 import { AssembledToMessageInput, ExtendedMessageRole, assembledMessageToBaseMessage, assembledToBaseMessage } from "./assembled-to-message.js";
 import { NAMESPACE_SEPARATOR } from "./constants.js";
 import { Channel, Event } from "@langchain/protocol";
-export { type AcquiredProjection, type AgentServerAdapter, type AgentServerOptions, type AgentTypeConfigLike, type AnyMediaHandle, type AssembledToMessageInput, type AssembledToolCall, type AssembledToolCallFromTool, type AudioMedia, type Channel, type ChannelProjectionOptions, ChannelRegistry, type CompiledSubAgentLike, type CustomAdapterOptions, type DeepAgentTypeConfigLike, type DefaultSubagentStates, type DefaultToolCall, type Event, type ExtendedMessageRole, type ExtractAgentConfig, type ExtractDeepAgentConfig, type ExtractSubAgentMiddleware, type FileMedia, type ImageMedia, type InferAgentToolCalls, type InferBag, type InferDeepAgentSubagents, type InferNodeNames, type InferStateType, type InferSubagentByName, type InferSubagentNames, type InferSubagentState, type InferSubagentStates, type InferToolCalls, type InferToolOutput, type IsAgentLike, type IsDeepAgentLike, MediaAssembler, type MediaAssemblerCallbacks, type MediaAssemblerOptions, MediaAssemblyError, type MediaAssemblyErrorKind, type MediaBase, type MediaBlockType, type MediaProjectionOptions, type MessageMetadata, type MessageMetadataMap, NAMESPACE_SEPARATOR, type ProjectionRuntime, type ProjectionSpec, ROOT_PUMP_CHANNELS, type RootEventBus, type RootSnapshot, type RunCompletedInfo, type RunExecutionInfo, type RunExecutionReason, type StoreListener, StreamController, type StreamControllerOptions, type StreamRespondAllOptions, type StreamRespondOptions, type StreamStopOptions, StreamStore, type StreamSubmitOptions, type SubAgentLike, SubagentDiscovery, type SubagentDiscoverySnapshot, type SubagentMap, type SubagentStateMap, type SubagentToolCall, type SubgraphByNodeMap, SubgraphDiscovery, type SubgraphDiscoverySnapshot, type SubgraphMap, type SubmissionQueueEntry, type SubmissionQueueSnapshot, type Target, type ToolCallFromTool, type ToolCallStatus, type TransportAdapter, type UseStreamCommonOptions, type UseStreamOptions, type VideoMedia, type WidenUpdateMessages, assembledMessageToBaseMessage, assembledToBaseMessage, audioProjection, channelProjection, extensionProjection, filesProjection, imagesProjection, messagesProjection, parseToolOutput, parseToolPayload, toolCallsProjection, valuesProjection, videoProjection };
+export { type AcquiredProjection, type AgentServerAdapter, type AgentServerOptions, type AgentTypeConfigLike, type AnyMediaHandle, type AssembledToMessageInput, type AssembledToolCall, type AssembledToolCallFromTool, type AudioMedia, type Channel, type ChannelEffectOptions, type ChannelProjectionOptions, ChannelRegistry, type CompiledSubAgentLike, type CustomAdapterOptions, type DeepAgentTypeConfigLike, type DefaultSubagentStates, type DefaultToolCall, type Event, type ExtendedMessageRole, type ExtractAgentConfig, type ExtractDeepAgentConfig, type ExtractSubAgentMiddleware, type FileMedia, type ImageMedia, type InferAgentToolCalls, type InferBag, type InferDeepAgentSubagents, type InferNodeNames, type InferStateType, type InferSubagentByName, type InferSubagentNames, type InferSubagentState, type InferSubagentStates, type InferToolCalls, type InferToolOutput, type IsAgentLike, type IsDeepAgentLike, MediaAssembler, type MediaAssemblerCallbacks, type MediaAssemblerOptions, MediaAssemblyError, type MediaAssemblyErrorKind, type MediaBase, type MediaBlockType, type MediaProjectionOptions, type MessageMetadata, type MessageMetadataMap, NAMESPACE_SEPARATOR, type ProjectionRuntime, type ProjectionSpec, ROOT_PUMP_CHANNELS, type RootEventBus, type RootSnapshot, type RunCompletedInfo, type RunExecutionInfo, type RunExecutionReason, type StoreListener, StreamController, type StreamControllerOptions, type StreamRespondAllOptions, type StreamRespondOptions, type StreamStopOptions, StreamStore, type StreamSubmitOptions, type SubAgentLike, SubagentDiscovery, type SubagentDiscoverySnapshot, type SubagentMap, type SubagentStateMap, type SubagentToolCall, type SubgraphByNodeMap, SubgraphDiscovery, type SubgraphDiscoverySnapshot, type SubgraphMap, type SubmissionQueueEntry, type SubmissionQueueSnapshot, type Target, type ToolCallFromTool, type ToolCallStatus, type TransportAdapter, type UseStreamCommonOptions, type UseStreamOptions, type VideoMedia, type WidenUpdateMessages, acquireChannelEffect, assembledMessageToBaseMessage, assembledToBaseMessage, audioProjection, channelProjection, extensionProjection, filesProjection, imagesProjection, messagesProjection, parseToolOutput, parseToolPayload, toolCallsProjection, valuesProjection, videoProjection };

package/dist/stream/index.js

@@ -13,6 +13,7 @@ import { toolCallsProjection } from "./projections/tool-calls.js";
 import { valuesProjection } from "./projections/values.js";
 import { extensionProjection } from "./projections/extension.js";
 import { channelProjection } from "./projections/channel.js";
+import { acquireChannelEffect } from "./projections/channel-effect.js";
 import { audioProjection, filesProjection, imagesProjection, videoProjection } from "./projections/media.js";
 import "./projections/index.js";
-export { ChannelRegistry, MediaAssembler, MediaAssemblyError, NAMESPACE_SEPARATOR, ROOT_PUMP_CHANNELS, StreamController, StreamStore, SubagentDiscovery, SubgraphDiscovery, assembledMessageToBaseMessage, assembledToBaseMessage, audioProjection, channelProjection, extensionProjection, filesProjection, imagesProjection, messagesProjection, parseToolOutput, parseToolPayload, toolCallsProjection, valuesProjection, videoProjection };
+export { ChannelRegistry, MediaAssembler, MediaAssemblyError, NAMESPACE_SEPARATOR, ROOT_PUMP_CHANNELS, StreamController, StreamStore, SubagentDiscovery, SubgraphDiscovery, acquireChannelEffect, assembledMessageToBaseMessage, assembledToBaseMessage, audioProjection, channelProjection, extensionProjection, filesProjection, imagesProjection, messagesProjection, parseToolOutput, parseToolPayload, toolCallsProjection, valuesProjection, videoProjection };

package/dist/stream/projections/channel-effect.cjs

@@ -0,0 +1,52 @@
+const require_channel = require("./channel.cjs");
+//#region src/stream/projections/channel-effect.ts
+/**
+* Acquire a side-effect subscription over one or more channels.
+*
+* @param registry - The stream's {@link ChannelRegistry}.
+* @param channels - Channels to observe (e.g. `["lifecycle", "tools"]`).
+* @param namespace - Resolved namespace (`[]` for the root).
+* @param options - Callbacks plus projection (`bufferSize`/`replay`)
+*   options.
+* @returns A `dispose()` function that detaches the listener and
+*   releases the ref-counted projection. Idempotent.
+*/
+function acquireChannelEffect(registry, channels, namespace, options) {
+	const { onEvent, onError, ...projectionOptions } = options;
+	const acquired = registry.acquire(require_channel.channelProjection(channels, namespace, {
+		replay: projectionOptions.replay ?? false,
+		bufferSize: projectionOptions.bufferSize
+	}));
+	const { store } = acquired;
+	const initial = store.getSnapshot();
+	let lastDelivered = initial.length > 0 ? initial[initial.length - 1] : void 0;
+	const deliver = () => {
+		const snapshot = store.getSnapshot();
+		let start = 0;
+		if (lastDelivered !== void 0) {
+			const index = snapshot.lastIndexOf(lastDelivered);
+			start = index === -1 ? 0 : index + 1;
+		}
+		for (let i = start; i < snapshot.length; i += 1) {
+			const event = snapshot[i];
+			try {
+				onEvent(event);
+			} catch (error) {
+				if (onError) onError(error);
+			}
+		}
+		if (snapshot.length > 0) lastDelivered = snapshot[snapshot.length - 1];
+	};
+	const unsubscribe = store.subscribe(deliver);
+	let released = false;
+	return () => {
+		if (released) return;
+		released = true;
+		unsubscribe();
+		acquired.release();
+	};
+}
+//#endregion
+exports.acquireChannelEffect = acquireChannelEffect;
+
+//# sourceMappingURL=channel-effect.cjs.map

package/dist/stream/projections/channel-effect.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"channel-effect.cjs","names":["channelProjection"],"sources":["../../../src/stream/projections/channel-effect.ts"],"sourcesContent":["/**\n * Side-effect counterpart to {@link channelProjection}.\n *\n * Where `channelProjection` retains a bounded *buffer* of raw events\n * for rendering, this helper delivers each event to a callback exactly\n * once — the idiomatic shape for analytics, logging, and other side\n * effects that should not live in render. Framework bindings wrap it as\n * `useChannelEffect` (React/Svelte/Vue) / `injectChannelEffect`\n * (Angular).\n *\n * # Why this is built on the registry\n *\n * It acquires the very same ref-counted {@link channelProjection} entry\n * that the selector hooks use, so:\n *\n *  - N consumers of the same `channels`/`namespace`/options share a\n *    single server subscription (the registry dedupes by `spec.key`).\n *  - The subscription survives thread swaps for free (the registry\n *    rebinds every live entry on `controller.hydrate(...)`).\n *\n * Each consumer then diffs the shared store independently, so multiple\n * `useChannelEffect` callers with *different* callbacks each receive\n * their own delivery.\n *\n * # Delivery semantics\n *\n *  - Only events that arrive while the effect is attached are\n *    delivered. Events already buffered when the effect attaches (e.g.\n *    a sibling `useChannel` populated the buffer first) are skipped —\n *    analytics must not double-count history on a late mount.\n *  - `channelProjection` appends exactly one event per store\n *    notification, so the cursor below tracks the last delivered event\n *    by identity and forwards everything after it. On a thread rebind\n *    the store resets to `[]`; the old cursor is no longer found, so\n *    the next batch of events for the new thread is delivered from the\n *    start.\n *  - `replay` is forwarded to the projection. It defaults to `false`\n *    here (live-only) — the opposite of `useChannel`'s buffer default —\n *    because firing analytics for replayed history is rarely what a\n *    side-effect consumer wants.\n */\nimport type { Channel, Event } from \"@langchain/protocol\";\nimport type { ChannelRegistry } from \"../channel-registry.js\";\nimport { channelProjection, type ChannelProjectionOptions } from \"./channel.js\";\n\n/**\n * Options for {@link acquireChannelEffect}. Extends\n * {@link ChannelProjectionOptions} (`bufferSize`, `replay`) with the\n * per-event callback and an optional error sink.\n */\nexport interface ChannelEffectOptions extends ChannelProjectionOptions {\n  /** Invoked once for every event observed while attached. */\n  onEvent: (event: Event) => void;\n  /**\n   * Invoked when {@link onEvent} throws. When omitted, a throwing\n   * `onEvent` is swallowed so one bad delivery cannot wedge the shared\n   * store's notification loop or other consumers.\n   */\n  onError?: (error: unknown) => void;\n}\n\n/**\n * Acquire a side-effect subscription over one or more channels.\n *\n * @param registry - The stream's {@link ChannelRegistry}.\n * @param channels - Channels to observe (e.g. `[\"lifecycle\", \"tools\"]`).\n * @param namespace - Resolved namespace (`[]` for the root).\n * @param options - Callbacks plus projection (`bufferSize`/`replay`)\n *   options.\n * @returns A `dispose()` function that detaches the listener and\n *   releases the ref-counted projection. Idempotent.\n */\nexport function acquireChannelEffect(\n  registry: ChannelRegistry,\n  channels: readonly Channel[],\n  namespace: readonly string[],\n  options: ChannelEffectOptions\n): () => void {\n  const { onEvent, onError, ...projectionOptions } = options;\n  const acquired = registry.acquire<Event[]>(\n    channelProjection(channels, namespace, {\n      // Live-only by default for side effects; callers opt into replay\n      // explicitly when they want to re-process history.\n      replay: projectionOptions.replay ?? false,\n      bufferSize: projectionOptions.bufferSize,\n    })\n  );\n  const { store } = acquired;\n\n  // Cursor: the last event already delivered to `onEvent`. Seeded with\n  // the current tail so events buffered before this consumer attached\n  // are skipped (no double-counting on a late mount).\n  const initial = store.getSnapshot();\n  let lastDelivered: Event | undefined =\n    initial.length > 0 ? initial[initial.length - 1] : undefined;\n\n  const deliver = (): void => {\n    const snapshot = store.getSnapshot();\n    let start = 0;\n    if (lastDelivered !== undefined) {\n      const index = snapshot.lastIndexOf(lastDelivered);\n      // `index === -1` means the cursor fell out of the buffer (thread\n      // rebind reset the store, or the bounded buffer evicted it).\n      // Deliver from the start of the current snapshot.\n      start = index === -1 ? 0 : index + 1;\n    }\n    for (let i = start; i < snapshot.length; i += 1) {\n      const event = snapshot[i] as Event;\n      try {\n        onEvent(event);\n      } catch (error) {\n        if (onError) onError(error);\n      }\n    }\n    if (snapshot.length > 0) {\n      lastDelivered = snapshot[snapshot.length - 1];\n    }\n  };\n\n  const unsubscribe = store.subscribe(deliver);\n\n  let released = false;\n  return () => {\n    if (released) return;\n    released = true;\n    unsubscribe();\n    acquired.release();\n  };\n}\n"],"mappings":";;;;;;;;;;;;;AAwEA,SAAgB,qBACd,UACA,UACA,WACA,SACY;CACZ,MAAM,EAAE,SAAS,SAAS,GAAG,sBAAsB;CACnD,MAAM,WAAW,SAAS,QACxBA,gBAAAA,kBAAkB,UAAU,WAAW;EAGrC,QAAQ,kBAAkB,UAAU;EACpC,YAAY,kBAAkB;EAC/B,CAAC,CACH;CACD,MAAM,EAAE,UAAU;CAKlB,MAAM,UAAU,MAAM,aAAa;CACnC,IAAI,gBACF,QAAQ,SAAS,IAAI,QAAQ,QAAQ,SAAS,KAAK,KAAA;CAErD,MAAM,gBAAsB;EAC1B,MAAM,WAAW,MAAM,aAAa;EACpC,IAAI,QAAQ;AACZ,MAAI,kBAAkB,KAAA,GAAW;GAC/B,MAAM,QAAQ,SAAS,YAAY,cAAc;AAIjD,WAAQ,UAAU,KAAK,IAAI,QAAQ;;AAErC,OAAK,IAAI,IAAI,OAAO,IAAI,SAAS,QAAQ,KAAK,GAAG;GAC/C,MAAM,QAAQ,SAAS;AACvB,OAAI;AACF,YAAQ,MAAM;YACP,OAAO;AACd,QAAI,QAAS,SAAQ,MAAM;;;AAG/B,MAAI,SAAS,SAAS,EACpB,iBAAgB,SAAS,SAAS,SAAS;;CAI/C,MAAM,cAAc,MAAM,UAAU,QAAQ;CAE5C,IAAI,WAAW;AACf,cAAa;AACX,MAAI,SAAU;AACd,aAAW;AACX,eAAa;AACb,WAAS,SAAS"}

package/dist/stream/projections/channel-effect.d.cts

@@ -0,0 +1,35 @@
+import { ChannelRegistry } from "../channel-registry.cjs";
+import { ChannelProjectionOptions } from "./channel.cjs";
+import { Channel, Event } from "@langchain/protocol";
+
+//#region src/stream/projections/channel-effect.d.ts
+/**
+ * Options for {@link acquireChannelEffect}. Extends
+ * {@link ChannelProjectionOptions} (`bufferSize`, `replay`) with the
+ * per-event callback and an optional error sink.
+ */
+interface ChannelEffectOptions extends ChannelProjectionOptions {
+  /** Invoked once for every event observed while attached. */
+  onEvent: (event: Event) => void;
+  /**
+   * Invoked when {@link onEvent} throws. When omitted, a throwing
+   * `onEvent` is swallowed so one bad delivery cannot wedge the shared
+   * store's notification loop or other consumers.
+   */
+  onError?: (error: unknown) => void;
+}
+/**
+ * Acquire a side-effect subscription over one or more channels.
+ *
+ * @param registry - The stream's {@link ChannelRegistry}.
+ * @param channels - Channels to observe (e.g. `["lifecycle", "tools"]`).
+ * @param namespace - Resolved namespace (`[]` for the root).
+ * @param options - Callbacks plus projection (`bufferSize`/`replay`)
+ *   options.
+ * @returns A `dispose()` function that detaches the listener and
+ *   releases the ref-counted projection. Idempotent.
+ */
+declare function acquireChannelEffect(registry: ChannelRegistry, channels: readonly Channel[], namespace: readonly string[], options: ChannelEffectOptions): () => void;
+//#endregion
+export { ChannelEffectOptions, acquireChannelEffect };
+//# sourceMappingURL=channel-effect.d.cts.map

package/dist/stream/projections/channel-effect.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"channel-effect.d.cts","names":[],"sources":["../../../src/stream/projections/channel-effect.ts"],"mappings":";;;;;;;;;;UAkDiB,oBAAA,SAA6B,wBAAA;;EAE5C,OAAA,GAAU,KAAA,EAAO,KAAA;;;;;;EAMjB,OAAA,IAAW,KAAA;AAAA;;;;;;;;;;;;iBAcG,oBAAA,CACd,QAAA,EAAU,eAAA,EACV,QAAA,WAAmB,OAAA,IACnB,SAAA,qBACA,OAAA,EAAS,oBAAA"}

package/dist/stream/projections/channel-effect.d.ts

@@ -0,0 +1,35 @@
+import { ChannelRegistry } from "../channel-registry.js";
+import { ChannelProjectionOptions } from "./channel.js";
+import { Channel, Event } from "@langchain/protocol";
+
+//#region src/stream/projections/channel-effect.d.ts
+/**
+ * Options for {@link acquireChannelEffect}. Extends
+ * {@link ChannelProjectionOptions} (`bufferSize`, `replay`) with the
+ * per-event callback and an optional error sink.
+ */
+interface ChannelEffectOptions extends ChannelProjectionOptions {
+  /** Invoked once for every event observed while attached. */
+  onEvent: (event: Event) => void;
+  /**
+   * Invoked when {@link onEvent} throws. When omitted, a throwing
+   * `onEvent` is swallowed so one bad delivery cannot wedge the shared
+   * store's notification loop or other consumers.
+   */
+  onError?: (error: unknown) => void;
+}
+/**
+ * Acquire a side-effect subscription over one or more channels.
+ *
+ * @param registry - The stream's {@link ChannelRegistry}.
+ * @param channels - Channels to observe (e.g. `["lifecycle", "tools"]`).
+ * @param namespace - Resolved namespace (`[]` for the root).
+ * @param options - Callbacks plus projection (`bufferSize`/`replay`)
+ *   options.
+ * @returns A `dispose()` function that detaches the listener and
+ *   releases the ref-counted projection. Idempotent.
+ */
+declare function acquireChannelEffect(registry: ChannelRegistry, channels: readonly Channel[], namespace: readonly string[], options: ChannelEffectOptions): () => void;
+//#endregion
+export { ChannelEffectOptions, acquireChannelEffect };
+//# sourceMappingURL=channel-effect.d.ts.map

package/dist/stream/projections/channel-effect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"channel-effect.d.ts","names":[],"sources":["../../../src/stream/projections/channel-effect.ts"],"mappings":";;;;;;;;;;UAkDiB,oBAAA,SAA6B,wBAAA;;EAE5C,OAAA,GAAU,KAAA,EAAO,KAAA;;;;;;EAMjB,OAAA,IAAW,KAAA;AAAA;;;;;;;;;;;;iBAcG,oBAAA,CACd,QAAA,EAAU,eAAA,EACV,QAAA,WAAmB,OAAA,IACnB,SAAA,qBACA,OAAA,EAAS,oBAAA"}

package/dist/stream/projections/channel-effect.js

@@ -0,0 +1,52 @@
+import { channelProjection } from "./channel.js";
+//#region src/stream/projections/channel-effect.ts
+/**
+* Acquire a side-effect subscription over one or more channels.
+*
+* @param registry - The stream's {@link ChannelRegistry}.
+* @param channels - Channels to observe (e.g. `["lifecycle", "tools"]`).
+* @param namespace - Resolved namespace (`[]` for the root).
+* @param options - Callbacks plus projection (`bufferSize`/`replay`)
+*   options.
+* @returns A `dispose()` function that detaches the listener and
+*   releases the ref-counted projection. Idempotent.
+*/
+function acquireChannelEffect(registry, channels, namespace, options) {
+	const { onEvent, onError, ...projectionOptions } = options;
+	const acquired = registry.acquire(channelProjection(channels, namespace, {
+		replay: projectionOptions.replay ?? false,
+		bufferSize: projectionOptions.bufferSize
+	}));
+	const { store } = acquired;
+	const initial = store.getSnapshot();
+	let lastDelivered = initial.length > 0 ? initial[initial.length - 1] : void 0;
+	const deliver = () => {
+		const snapshot = store.getSnapshot();
+		let start = 0;
+		if (lastDelivered !== void 0) {
+			const index = snapshot.lastIndexOf(lastDelivered);
+			start = index === -1 ? 0 : index + 1;
+		}
+		for (let i = start; i < snapshot.length; i += 1) {
+			const event = snapshot[i];
+			try {
+				onEvent(event);
+			} catch (error) {
+				if (onError) onError(error);
+			}
+		}
+		if (snapshot.length > 0) lastDelivered = snapshot[snapshot.length - 1];
+	};
+	const unsubscribe = store.subscribe(deliver);
+	let released = false;
+	return () => {
+		if (released) return;
+		released = true;
+		unsubscribe();
+		acquired.release();
+	};
+}
+//#endregion
+export { acquireChannelEffect };
+
+//# sourceMappingURL=channel-effect.js.map

package/dist/stream/projections/channel-effect.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"channel-effect.js","names":[],"sources":["../../../src/stream/projections/channel-effect.ts"],"sourcesContent":["/**\n * Side-effect counterpart to {@link channelProjection}.\n *\n * Where `channelProjection` retains a bounded *buffer* of raw events\n * for rendering, this helper delivers each event to a callback exactly\n * once — the idiomatic shape for analytics, logging, and other side\n * effects that should not live in render. Framework bindings wrap it as\n * `useChannelEffect` (React/Svelte/Vue) / `injectChannelEffect`\n * (Angular).\n *\n * # Why this is built on the registry\n *\n * It acquires the very same ref-counted {@link channelProjection} entry\n * that the selector hooks use, so:\n *\n *  - N consumers of the same `channels`/`namespace`/options share a\n *    single server subscription (the registry dedupes by `spec.key`).\n *  - The subscription survives thread swaps for free (the registry\n *    rebinds every live entry on `controller.hydrate(...)`).\n *\n * Each consumer then diffs the shared store independently, so multiple\n * `useChannelEffect` callers with *different* callbacks each receive\n * their own delivery.\n *\n * # Delivery semantics\n *\n *  - Only events that arrive while the effect is attached are\n *    delivered. Events already buffered when the effect attaches (e.g.\n *    a sibling `useChannel` populated the buffer first) are skipped —\n *    analytics must not double-count history on a late mount.\n *  - `channelProjection` appends exactly one event per store\n *    notification, so the cursor below tracks the last delivered event\n *    by identity and forwards everything after it. On a thread rebind\n *    the store resets to `[]`; the old cursor is no longer found, so\n *    the next batch of events for the new thread is delivered from the\n *    start.\n *  - `replay` is forwarded to the projection. It defaults to `false`\n *    here (live-only) — the opposite of `useChannel`'s buffer default —\n *    because firing analytics for replayed history is rarely what a\n *    side-effect consumer wants.\n */\nimport type { Channel, Event } from \"@langchain/protocol\";\nimport type { ChannelRegistry } from \"../channel-registry.js\";\nimport { channelProjection, type ChannelProjectionOptions } from \"./channel.js\";\n\n/**\n * Options for {@link acquireChannelEffect}. Extends\n * {@link ChannelProjectionOptions} (`bufferSize`, `replay`) with the\n * per-event callback and an optional error sink.\n */\nexport interface ChannelEffectOptions extends ChannelProjectionOptions {\n  /** Invoked once for every event observed while attached. */\n  onEvent: (event: Event) => void;\n  /**\n   * Invoked when {@link onEvent} throws. When omitted, a throwing\n   * `onEvent` is swallowed so one bad delivery cannot wedge the shared\n   * store's notification loop or other consumers.\n   */\n  onError?: (error: unknown) => void;\n}\n\n/**\n * Acquire a side-effect subscription over one or more channels.\n *\n * @param registry - The stream's {@link ChannelRegistry}.\n * @param channels - Channels to observe (e.g. `[\"lifecycle\", \"tools\"]`).\n * @param namespace - Resolved namespace (`[]` for the root).\n * @param options - Callbacks plus projection (`bufferSize`/`replay`)\n *   options.\n * @returns A `dispose()` function that detaches the listener and\n *   releases the ref-counted projection. Idempotent.\n */\nexport function acquireChannelEffect(\n  registry: ChannelRegistry,\n  channels: readonly Channel[],\n  namespace: readonly string[],\n  options: ChannelEffectOptions\n): () => void {\n  const { onEvent, onError, ...projectionOptions } = options;\n  const acquired = registry.acquire<Event[]>(\n    channelProjection(channels, namespace, {\n      // Live-only by default for side effects; callers opt into replay\n      // explicitly when they want to re-process history.\n      replay: projectionOptions.replay ?? false,\n      bufferSize: projectionOptions.bufferSize,\n    })\n  );\n  const { store } = acquired;\n\n  // Cursor: the last event already delivered to `onEvent`. Seeded with\n  // the current tail so events buffered before this consumer attached\n  // are skipped (no double-counting on a late mount).\n  const initial = store.getSnapshot();\n  let lastDelivered: Event | undefined =\n    initial.length > 0 ? initial[initial.length - 1] : undefined;\n\n  const deliver = (): void => {\n    const snapshot = store.getSnapshot();\n    let start = 0;\n    if (lastDelivered !== undefined) {\n      const index = snapshot.lastIndexOf(lastDelivered);\n      // `index === -1` means the cursor fell out of the buffer (thread\n      // rebind reset the store, or the bounded buffer evicted it).\n      // Deliver from the start of the current snapshot.\n      start = index === -1 ? 0 : index + 1;\n    }\n    for (let i = start; i < snapshot.length; i += 1) {\n      const event = snapshot[i] as Event;\n      try {\n        onEvent(event);\n      } catch (error) {\n        if (onError) onError(error);\n      }\n    }\n    if (snapshot.length > 0) {\n      lastDelivered = snapshot[snapshot.length - 1];\n    }\n  };\n\n  const unsubscribe = store.subscribe(deliver);\n\n  let released = false;\n  return () => {\n    if (released) return;\n    released = true;\n    unsubscribe();\n    acquired.release();\n  };\n}\n"],"mappings":";;;;;;;;;;;;;AAwEA,SAAgB,qBACd,UACA,UACA,WACA,SACY;CACZ,MAAM,EAAE,SAAS,SAAS,GAAG,sBAAsB;CACnD,MAAM,WAAW,SAAS,QACxB,kBAAkB,UAAU,WAAW;EAGrC,QAAQ,kBAAkB,UAAU;EACpC,YAAY,kBAAkB;EAC/B,CAAC,CACH;CACD,MAAM,EAAE,UAAU;CAKlB,MAAM,UAAU,MAAM,aAAa;CACnC,IAAI,gBACF,QAAQ,SAAS,IAAI,QAAQ,QAAQ,SAAS,KAAK,KAAA;CAErD,MAAM,gBAAsB;EAC1B,MAAM,WAAW,MAAM,aAAa;EACpC,IAAI,QAAQ;AACZ,MAAI,kBAAkB,KAAA,GAAW;GAC/B,MAAM,QAAQ,SAAS,YAAY,cAAc;AAIjD,WAAQ,UAAU,KAAK,IAAI,QAAQ;;AAErC,OAAK,IAAI,IAAI,OAAO,IAAI,SAAS,QAAQ,KAAK,GAAG;GAC/C,MAAM,QAAQ,SAAS;AACvB,OAAI;AACF,YAAQ,MAAM;YACP,OAAO;AACd,QAAI,QAAS,SAAQ,MAAM;;;AAG/B,MAAI,SAAS,SAAS,EACpB,iBAAgB,SAAS,SAAS,SAAS;;CAI/C,MAAM,cAAc,MAAM,UAAU,QAAQ;CAE5C,IAAI,WAAW;AACf,cAAa;AACX,MAAI,SAAU;AACd,aAAW;AACX,eAAa;AACb,WAAS,SAAS"}

package/dist/stream/projections/index.cjs

@@ -3,4 +3,5 @@ require("./tool-calls.cjs");
 require("./values.cjs");
 require("./extension.cjs");
 require("./channel.cjs");
+require("./channel-effect.cjs");
 require("./media.cjs");

package/dist/stream/projections/index.d.ts

@@ -3,4 +3,5 @@ import { toolCallsProjection } from "./tool-calls.js";
 import { valuesProjection } from "./values.js";
 import { extensionProjection } from "./extension.js";
 import { ChannelProjectionOptions, channelProjection } from "./channel.js";
+import { ChannelEffectOptions, acquireChannelEffect } from "./channel-effect.js";
 import { MediaProjectionOptions, audioProjection, filesProjection, imagesProjection, videoProjection } from "./media.js";

package/dist/stream/projections/index.js

@@ -3,5 +3,6 @@ import "./tool-calls.js";
 import "./values.js";
 import "./extension.js";
 import "./channel.js";
+import "./channel-effect.js";
 import "./media.js";
 export {};

package/dist/stream/root-message-projection.cjs

@@ -80,6 +80,37 @@ var RootMessageProjection = class {
 	*/
 	#maxStep = void 0;
 	/**
+	* Message ids seeded as complete-and-final from an idle thread's
+	* `getState()` snapshot. An idle thread defers its root SSE pump, and
+	* the first `submit()` brings it up — at which point the transport
+	* replays the finished run from `seq=0`. Unlike the `values` channel
+	* (guarded by {@link #maxStep}), `messages`-channel deltas carry no
+	* step, so that replay would otherwise rebuild each already-complete
+	* message from an empty `message-start` and re-stream the whole turn
+	* token-by-token, clobbering the seeded tail (a visible "messages
+	* replay" on the first submit). Deltas for a sealed id are dropped in
+	* {@link handleMessage}. The seal is lifted once a checkpoint advances
+	* strictly past {@link #sealStep} (see {@link applyValues}) or on
+	* thread rebind ({@link reset}). New ids from the next run are never
+	* sealed, so they stream normally.
+	*/
+	#sealedMessageIds = /* @__PURE__ */ new Set();
+	/**
+	* High-water {@link #maxStep} captured when {@link sealMessageIds} ran,
+	* i.e. the seed checkpoint's step (or `undefined` when `getState()`
+	* carried no `metadata.step`). It is the boundary between the replayed
+	* idle history (steps `<= #sealStep`, emitted by the deferred pump's
+	* `seq=0` replay) and the new run (steps `> #sealStep`); only a
+	* checkpoint strictly past it lifts the seal. Without this boundary the
+	* replayed old-run checkpoints — which themselves carry increasing
+	* steps — would advance {@link #maxStep} and lift the seal mid-replay,
+	* reopening the clobber. When the seed step is unknown the boundary
+	* stays `undefined` and the seal holds until {@link reset}; the
+	* `values` channel (which ignores the seal) still reconciles any
+	* genuine change to a sealed id, only its streamed deltas are dropped.
+	*/
+	#sealStep = void 0;
+	/**
 	* @param params.messagesKey - Key inside `values` that holds the
 	*   message array.
 	* @param params.store       - Root snapshot store to mutate.
@@ -102,6 +133,28 @@ var RootMessageProjection = class {
 		this.#pendingValues = null;
 		this.#flushScheduled = false;
 		this.#maxStep = void 0;
+		this.#sealedMessageIds.clear();
+		this.#sealStep = void 0;
+	}
+	/**
+	* Seal message ids so the streamed `messages` channel cannot downgrade
+	* them to partial re-streams. Called by {@link StreamController.hydrate}
+	* after seeding an idle thread, whose deferred pump replays the finished
+	* run from `seq=0` on the first submit.
+	*
+	* Captures the current {@link #maxStep} as the lift boundary
+	* ({@link #sealStep}). The seal is applied immediately after the seed's
+	* `getState()` snapshot is reconciled, so `#maxStep` here is the seed
+	* step (or `undefined` when `getState()` carried no `metadata.step`).
+	* The seal is lifted once a checkpoint advances strictly past that
+	* boundary (see {@link applyValues}) or on thread rebind
+	* ({@link reset}).
+	*
+	* @param ids - Complete message ids from the idle `getState()` seed.
+	*/
+	sealMessageIds(ids) {
+		for (const id of ids) this.#sealedMessageIds.add(id);
+		if (this.#sealStep == null) this.#sealStep = this.#maxStep;
 	}
 	/**
 	* Record a `namespace → tool_call_id` mapping captured from a root
@@ -151,6 +204,7 @@ var RootMessageProjection = class {
 		if (update == null) return;
 		const id = update.message.id;
 		if (id == null) return;
+		if (this.#sealedMessageIds.has(id)) return;
 		const captured = this.#roles.get(id) ?? { role: "ai" };
 		const base = require_assembled_to_message.assembledMessageToBaseMessage(update.message, captured.role, { toolCallId: captured.toolCallId });
 		const baselineMessages = this.#pendingMessages ?? this.#store.getSnapshot().messages;
@@ -195,6 +249,7 @@ var RootMessageProjection = class {
 		const step = opts?.step;
 		const addOnly = step != null && this.#maxStep != null && step < this.#maxStep;
 		if (step != null && (this.#maxStep == null || step > this.#maxStep)) this.#maxStep = step;
+		if (this.#sealedMessageIds.size > 0 && step != null && this.#sealStep != null && step > this.#sealStep) this.#sealedMessageIds.clear();
 		if (nextMessages.length === 0) {
 			if (stateValuesShallowEqual(baselineValues, nextValues, this.#messagesKey)) return;
 			this.#pendingValues = syncMessagesIntoValues(nextValues, this.#messagesKey, baselineMessages);

package/dist/stream/root-message-projection.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"root-message-projection.cjs","names":["#messagesKey","#store","MessageAssembler","#roles","#indexById","#toolCallIdByNamespace","#assembler","#valuesMessageIds","#pendingMessages","#pendingValues","#flushScheduled","#maxStep","namespaceKey","assembledMessageToBaseMessage","messagesEqual","#scheduleFlush","reconcileMessagesFromValues","shouldPreferValuesMessageForToolCalls","buildMessageIndex","#flushPending"],"sources":["../../src/stream/root-message-projection.ts"],"sourcesContent":["/**\n * Root-namespace message projection.\n *\n * # What this module is\n *\n * The {@link RootMessageProjection} is the piece of the\n * {@link StreamController} that owns \"what messages does the root\n * namespace currently contain?\". It assembles streamed message deltas\n * via {@link MessageAssembler}, reconciles them against authoritative\n * `values.messages` snapshots from the server, and writes the merged\n * list back into the controller's root snapshot store.\n *\n * # Two streams of truth\n *\n * Root messages arrive on two channels and need to merge cleanly:\n *\n *   - **`messages` channel.** Token-level deltas that build messages\n *     incrementally. The {@link MessageAssembler} keeps partial\n *     messages by id and emits an updated `BaseMessage` per delta.\n *   - **`values` channel.** Periodic full-state snapshots that include\n *     the authoritative messages array. Used for ordering, removals,\n *     and forks (where the streamed messages may pre-date the new\n *     timeline).\n *\n * The reconciliation rules (delegated to\n * {@link reconcileMessagesFromValues}) preserve in-flight streamed\n * content while letting values dictate ordering and removals.\n *\n * # Tool-message namespace correlation\n *\n * Tool messages arrive on `messages-start` events with `role: \"tool\"`\n * but the start event doesn't always include a `tool_call_id`. We\n * recover it via three fallbacks:\n *\n *   1. The start event itself, when the server includes it.\n *   2. The legacy `<id>-tool-<call_id>` message id format.\n *   3. The most recent `tool-started` event recorded under the same\n *      namespace via {@link recordToolCallNamespace}.\n *\n * Without this correlation, tool messages render with empty\n * `tool_call_id` and downstream UIs can't pair them with the\n * originating tool call.\n *\n * # Store-write batching\n *\n * Every {@link handleMessage} / {@link applyValues} call updates the\n * in-projection bookkeeping (assembler state, id index, role cache)\n * synchronously, then stages the new `messages` / `values` into a\n * pending buffer and schedules a `setTimeout(0)` flush. A single\n * coalesced `store.setState` runs at the next macrotask boundary.\n *\n * The motivation is the long-replay freeze: a thread with hundreds\n * of messages replays through the `messages` channel on refresh or\n * mid-run join. Those events drain through the controller's\n * `for await` pump as a long microtask chain. Per-event\n * `store.setState` notifies `useSyncExternalStore` per event, and\n * after enough notifications React's `nestedUpdateCount` guard trips\n * with \"Maximum update depth exceeded\", permanently freezing the UI\n * on the first few messages. Coalescing to one notification per\n * macrotask lets React's scheduler commit between flushes.\n *\n * # Lifecycle\n *\n *   - `handleMessage(event)`              — apply a `messages` event delta.\n *   - `applyValues(values, msgs)`         — merge a `values` snapshot.\n *   - `recordToolCallNamespace(ns, id)`   — capture `namespace → tool_call_id`\n *     so subsequent tool message starts can recover the id.\n *   - `reset()`                           — clear all state on thread rebind.\n */\nimport type {\n  MessagesEvent,\n  MessageRole,\n  MessageStartData,\n} from \"@langchain/protocol\";\nimport type { BaseMessage } from \"@langchain/core/messages\";\nimport { MessageAssembler } from \"../client/stream/messages.js\";\nimport {\n  assembledMessageToBaseMessage,\n  type ExtendedMessageRole,\n} from \"./assembled-to-message.js\";\nimport type { StreamStore } from \"./store.js\";\nimport type { RootSnapshot } from \"./types.js\";\nimport { namespaceKey } from \"./namespace.js\";\nimport {\n  buildMessageIndex,\n  messagesEqual,\n  reconcileMessagesFromValues,\n  shouldPreferValuesMessageForToolCalls,\n} from \"./message-reconciliation.js\";\n\n/**\n * Root-namespace message projection. Owns the merge between the\n * `messages` (streamed deltas) and `values` (authoritative\n * snapshots) channels for the root namespace.\n *\n * @typeParam StateType     - Root state shape; the messages array is read\n *   from `values[messagesKey]`.\n * @typeParam InterruptType - Shape of root protocol interrupts (forwarded\n *   into `RootSnapshot` updates).\n */\nexport class RootMessageProjection<\n  StateType extends object,\n  InterruptType = unknown,\n> {\n  /**\n   * Key inside `values` that holds the message array. Defaults to\n   * `\"messages\"` in the controller; configurable for state graphs\n   * that surface messages under a different slot.\n   */\n  readonly #messagesKey: string;\n\n  /** Root snapshot store written to on every merge. */\n  readonly #store: StreamStore<RootSnapshot<StateType, InterruptType>>;\n\n  /**\n   * Stateful chunk assembler for in-flight messages. Reset (via a\n   * fresh instance) on every {@link reset} so a new thread starts\n   * with no half-built messages from the previous one.\n   */\n  #assembler = new MessageAssembler();\n\n  /**\n   * `messageId → role/toolCallId` captured from `message-start` events.\n   * The assembler's intermediate output drops these fields, so we cache\n   * them at start-time and reapply when projecting to a `BaseMessage`.\n   */\n  readonly #roles = new Map<\n    string,\n    { role: ExtendedMessageRole; toolCallId?: string }\n  >();\n\n  /**\n   * `messageId → position in #store.messages` for fast in-place\n   * updates as deltas arrive. Rebuilt on every full reconciliation\n   * driven by a `values` event.\n   */\n  readonly #indexById = new Map<string, number>();\n\n  /**\n   * Ids observed in the most recent `values.messages` snapshot.\n   * Reconciliation uses this to detect server-side removals: a\n   * previously-seen id missing from the next snapshot means it was\n   * removed by the server (and should drop from the projection).\n   */\n  #valuesMessageIds = new Set<string>();\n\n  /**\n   * `namespaceKey → tool_call_id` captured from root `tool-started`\n   * events. Used as a fallback when a tool-role `message-start` is\n   * missing its `tool_call_id` field.\n   */\n  readonly #toolCallIdByNamespace = new Map<string, string>();\n\n  /**\n   * Coalescing buffer for store writes. {@link handleMessage} and\n   * {@link applyValues} stage their computed `messages` / `values`\n   * here instead of calling `store.setState` per event. A single\n   * `setTimeout(0)` flush commits them in one `setState`, so a\n   * burst of SSE events draining as a microtask chain becomes one\n   * store notification at the next macrotask boundary.\n   *\n   * `null` means \"no staged write\" — once a flush settles, the\n   * slots are cleared so the next call starts from the latest\n   * committed store snapshot.\n   */\n  #pendingMessages: BaseMessage[] | null = null;\n  #pendingValues: StateType | null = null;\n  #flushScheduled = false;\n\n  /**\n   * Highest checkpoint `step` whose `values` snapshot has been applied.\n   * Seeded by {@link StreamController.hydrate} from `getState()` and\n   * advanced by live `values` events. A snapshot arriving with a lower\n   * step is an older checkpoint replayed by the content pump on\n   * reconnect; it is reconciled in add-only mode so it cannot remove\n   * the seeded message tail (the final assistant turn). `undefined`\n   * until the first step-bearing snapshot, where the legacy\n   * remove-on-absence behavior is preserved.\n   */\n  #maxStep: number | undefined = undefined;\n\n  /**\n   * @param params.messagesKey - Key inside `values` that holds the\n   *   message array.\n   * @param params.store       - Root snapshot store to mutate.\n   */\n  constructor(params: {\n    messagesKey: string;\n    store: StreamStore<RootSnapshot<StateType, InterruptType>>;\n  }) {\n    this.#messagesKey = params.messagesKey;\n    this.#store = params.store;\n  }\n\n  /**\n   * Drop all per-thread state. Called by the controller on thread\n   * rebind / dispose so a swap doesn't surface stale messages.\n   */\n  reset(): void {\n    this.#assembler = new MessageAssembler();\n    this.#roles.clear();\n    this.#indexById.clear();\n    this.#valuesMessageIds = new Set();\n    this.#toolCallIdByNamespace.clear();\n    // Drop any unflushed pending writes — they were computed against\n    // the previous thread's baseline and committing them after a\n    // rebind would bleed stale messages into the new thread.\n    this.#pendingMessages = null;\n    this.#pendingValues = null;\n    this.#flushScheduled = false;\n    this.#maxStep = undefined;\n  }\n\n  /**\n   * Record a `namespace → tool_call_id` mapping captured from a root\n   * `tool-started` event.\n   *\n   * The companion tool-role `message-start` event may not carry a\n   * `tool_call_id`, so we fall back to the most recent value recorded\n   * here for the same namespace.\n   *\n   * @param namespace  - Event namespace from the `tool-started` event.\n   * @param toolCallId - Tool call id from the same event.\n   */\n  recordToolCallNamespace(\n    namespace: readonly string[],\n    toolCallId: string\n  ): void {\n    this.#toolCallIdByNamespace.set(namespaceKey(namespace), toolCallId);\n  }\n\n  /**\n   * Apply a `messages` channel event to the projection.\n   *\n   * Captures role/tool metadata on `message-start`, feeds the chunk\n   * to the assembler, projects the assembled output to a\n   * {@link BaseMessage}, and either appends or in-place updates the\n   * pending messages buffer based on whether the id was seen before.\n   *\n   * @param event - The `messages` channel event to consume.\n   */\n  handleMessage(event: MessagesEvent): void {\n    const data = event.params.data;\n    if (data.event === \"message-start\") {\n      const startData = data as MessageStartData;\n      const role = (startData.role ?? \"ai\") as MessageRole;\n      const extendedRole =\n        (startData as { role?: ExtendedMessageRole }).role ?? role;\n      let toolCallId = (startData as { tool_call_id?: string }).tool_call_id;\n      // Tool messages need a tool_call_id to render. Fall back through:\n      //   1. legacy `<id>-tool-<call_id>` message id format\n      //   2. namespace-recorded tool_call_id (from #recordToolCallNamespace)\n      if (extendedRole === \"tool\" && toolCallId == null) {\n        const messageId = startData.id;\n        if (messageId != null) {\n          const match = /-tool-(.+)$/.exec(messageId);\n          if (match != null) toolCallId = match[1];\n        }\n        if (toolCallId == null) {\n          toolCallId = this.#toolCallIdByNamespace.get(\n            namespaceKey(event.params.namespace)\n          );\n        }\n      }\n      if (startData.id != null) {\n        this.#roles.set(startData.id, {\n          role: extendedRole,\n          toolCallId,\n        });\n      }\n    }\n\n    const update = this.#assembler.consume(event);\n    if (update == null) return;\n    const id = update.message.id;\n    if (id == null) return;\n    const captured = this.#roles.get(id) ?? { role: \"ai\" as const };\n    const base = assembledMessageToBaseMessage(update.message, captured.role, {\n      toolCallId: captured.toolCallId,\n    });\n\n    // Compute against the pending baseline if we have one (so an\n    // earlier handleMessage in the same tick is the input to this\n    // one), else against the latest committed store snapshot.\n    // `#indexById` is the synchronous source of truth for \"where is\n    // each id in the current messages list\" — every code path below\n    // keeps it in sync before returning.\n    const baselineMessages =\n      this.#pendingMessages ?? this.#store.getSnapshot().messages;\n    const existingIdx = this.#indexById.get(id);\n    let messages: BaseMessage[];\n    if (existingIdx == null) {\n      this.#indexById.set(id, baselineMessages.length);\n      messages = [...baselineMessages, base];\n    } else if (messagesEqual(baselineMessages[existingIdx], base)) {\n      // Identical re-emission — skip the store write to keep\n      // snapshot identity stable.\n      return;\n    } else {\n      messages = baselineMessages.slice();\n      messages[existingIdx] = base;\n    }\n\n    // Mirror the new messages list into `values[messagesKey]` so\n    // direct `values` reads (used by some hooks and by the eventual\n    // `values` reconciliation) stay in sync.\n    const baselineValues =\n      this.#pendingValues ?? this.#store.getSnapshot().values;\n    const values = syncMessagesIntoValues(\n      baselineValues,\n      this.#messagesKey,\n      messages\n    );\n    this.#pendingMessages = messages;\n    if (values !== baselineValues) this.#pendingValues = values;\n    this.#scheduleFlush();\n  }\n\n  /**\n   * Reconcile a full `values` snapshot into the projection.\n   *\n   * Delegates the merge to {@link reconcileMessagesFromValues}:\n   * values stays authoritative for ordering and removals, while\n   * streamed in-flight messages keep their content until the server\n   * echoes them back. Empty messages just refresh the values blob.\n   *\n   * Rebuilds {@link #indexById} after the merge so subsequent delta\n   * applications target the new positions.\n   *\n   * @param nextValues   - Full values snapshot from the `values` event.\n   * @param nextMessages - The messages array extracted from\n   *   `values[messagesKey]` and coerced to `BaseMessage` instances.\n   * @param opts.step    - Checkpoint superstep for this snapshot, when\n   *   known. A snapshot whose step is below the highest applied step is\n   *   treated as a stale reconnect replay and reconciled add-only.\n   */\n  applyValues(\n    nextValues: StateType,\n    nextMessages: BaseMessage[],\n    opts?: { step?: number }\n  ): void {\n    const baselineSnapshot = this.#store.getSnapshot();\n    const baselineMessages = this.#pendingMessages ?? baselineSnapshot.messages;\n    const baselineValues = this.#pendingValues ?? baselineSnapshot.values;\n\n    const step = opts?.step;\n    // Stale only when we have both a prior high-water step and a lower\n    // incoming step. A missing step preserves the legacy semantics.\n    const addOnly =\n      step != null && this.#maxStep != null && step < this.#maxStep;\n    if (step != null && (this.#maxStep == null || step > this.#maxStep)) {\n      this.#maxStep = step;\n    }\n\n    if (nextMessages.length === 0) {\n      if (\n        stateValuesShallowEqual(baselineValues, nextValues, this.#messagesKey)\n      ) {\n        return;\n      }\n      // Mirror the current `messages` list back into the values slot\n      // so the staged snapshot stays consistent with the (separately\n      // tracked) messages array.\n      this.#pendingValues = syncMessagesIntoValues(\n        nextValues,\n        this.#messagesKey,\n        baselineMessages\n      );\n      this.#scheduleFlush();\n      return;\n    }\n\n    const reconciliation = reconcileMessagesFromValues({\n      valueMessages: nextMessages,\n      currentMessages: baselineMessages,\n      currentIndexById: this.#indexById,\n      previousValueMessageIds: this.#valuesMessageIds,\n      preferValuesMessage: shouldPreferValuesMessageForToolCalls,\n      addOnly,\n    });\n    // A stale replay snapshot must not shrink the authoritative id set:\n    // keep the (larger) seeded set so a genuinely-newer removal is still\n    // detected once the timeline advances past the seed.\n    if (!addOnly) this.#valuesMessageIds = reconciliation.valueMessageIds;\n    const messages = reconciliation.messages as BaseMessage[];\n    const values = {\n      ...(nextValues as Record<string, unknown>),\n      [this.#messagesKey]: messages,\n    } as StateType;\n    if (\n      messages === baselineMessages &&\n      stateValuesShallowEqual(baselineValues, values, this.#messagesKey)\n    ) {\n      return;\n    }\n\n    // Reconciliation may reorder, drop, or substitute messages, so\n    // rebuild the id → index map to match the new array.\n    this.#indexById.clear();\n    for (const [id, idx] of buildMessageIndex(messages)) {\n      this.#indexById.set(id, idx);\n    }\n    this.#pendingMessages = messages;\n    this.#pendingValues = values;\n    this.#scheduleFlush();\n  }\n\n  /**\n   * Append messages applied optimistically by a local `submit()`,\n   * keyed by id so the eventual server echo reconciles cleanly.\n   *\n   * Unlike {@link applyValues}, the supplied messages are *not* treated\n   * as an authoritative ordered snapshot: they are appended to the end\n   * of the current projection (or replaced in place when the id already\n   * exists), preserving prior history ordering. When the server later\n   * emits a `values` snapshot containing the same ids,\n   * {@link applyValues} → {@link reconcileMessagesFromValues} takes over\n   * (server ordering wins, the echoed message replaces the optimistic\n   * one).\n   *\n   * Non-message input keys are shallow-merged into `values` via\n   * `extraValues`; they are dropped/overwritten automatically by the\n   * first server `values` event (which rebuilds `values` from the\n   * server snapshot), or rolled back via {@link restoreValueKeys} when\n   * the run fails before any echo.\n   *\n   * @param messages    - Optimistic messages (already coerced to\n   *   `BaseMessage` instances, each carrying a stable id).\n   * @param extraValues - Non-message input keys to shallow-merge into\n   *   `values`.\n   */\n  appendOptimistic(\n    messages: BaseMessage[],\n    extraValues?: Record<string, unknown>\n  ): void {\n    let working = this.#pendingMessages ?? this.#store.getSnapshot().messages;\n    let mutated = false;\n    for (const message of messages) {\n      const id = message.id;\n      if (id == null) continue;\n      const existingIdx = this.#indexById.get(id);\n      if (existingIdx == null) {\n        if (!mutated) {\n          working = working.slice();\n          mutated = true;\n        }\n        this.#indexById.set(id, working.length);\n        working.push(message);\n      } else if (!messagesEqual(working[existingIdx], message)) {\n        if (!mutated) {\n          working = working.slice();\n          mutated = true;\n        }\n        working[existingIdx] = message;\n      }\n    }\n\n    const baselineValues =\n      this.#pendingValues ?? this.#store.getSnapshot().values;\n    let values = baselineValues;\n    if (extraValues != null && Object.keys(extraValues).length > 0) {\n      values = { ...(baselineValues as object), ...extraValues } as StateType;\n    }\n    values = syncMessagesIntoValues(values, this.#messagesKey, working);\n    if (!mutated && values === baselineValues) return;\n    this.#pendingMessages = working;\n    if (values !== baselineValues) this.#pendingValues = values;\n    this.#scheduleFlush();\n  }\n\n  /**\n   * Drop optimistic messages by id without disturbing the rest of the\n   * projection. Used by {@link StreamController.hydrate} to remove\n   * never-persisted optimistic messages (`pending` / `failed`) so a\n   * reload converges to server truth.\n   *\n   * @param ids - Message ids to remove.\n   */\n  dropOptimisticMessages(ids: ReadonlySet<string>): void {\n    if (ids.size === 0) return;\n    const baselineMessages =\n      this.#pendingMessages ?? this.#store.getSnapshot().messages;\n    const next = baselineMessages.filter((m) => m.id == null || !ids.has(m.id));\n    if (next.length === baselineMessages.length) return;\n    this.#indexById.clear();\n    for (const [id, idx] of buildMessageIndex(next)) {\n      this.#indexById.set(id, idx);\n    }\n    const baselineValues =\n      this.#pendingValues ?? this.#store.getSnapshot().values;\n    this.#pendingMessages = next;\n    this.#pendingValues = syncMessagesIntoValues(\n      baselineValues,\n      this.#messagesKey,\n      next\n    );\n    this.#scheduleFlush();\n  }\n\n  /**\n   * Restore (or delete) `values` keys that were optimistically merged\n   * by {@link appendOptimistic} but never echoed by the server — i.e.\n   * roll back non-message optimistic state when the run fails before\n   * any `values` event lands. Messages are left untouched (kept on\n   * failure per the optimistic contract).\n   *\n   * @param restore - Per-key pre-submit snapshot: when `hadKey` is\n   *   false the key is deleted, otherwise it is reset to `prevValue`.\n   */\n  restoreValueKeys(\n    restore: ReadonlyArray<{\n      key: string;\n      hadKey: boolean;\n      prevValue: unknown;\n    }>\n  ): void {\n    if (restore.length === 0) return;\n    const baselineValues =\n      this.#pendingValues ?? this.#store.getSnapshot().values;\n    const next = { ...(baselineValues as Record<string, unknown>) };\n    let changed = false;\n    for (const { key, hadKey, prevValue } of restore) {\n      if (key === this.#messagesKey) continue;\n      if (hadKey) {\n        if (!Object.is(next[key], prevValue)) {\n          next[key] = prevValue;\n          changed = true;\n        }\n      } else if (Object.prototype.hasOwnProperty.call(next, key)) {\n        delete next[key];\n        changed = true;\n      }\n    }\n    if (!changed) return;\n    this.#pendingValues = next as StateType;\n    this.#scheduleFlush();\n  }\n\n  /**\n   * Schedule a coalesced flush on the next macrotask. Idempotent\n   * within a tick — multiple `handleMessage` / `applyValues` calls\n   * before the flush fires collapse into one store write.\n   *\n   * `setTimeout(0)` is a macrotask: it runs after the current\n   * microtask chain drains, so a burst of SSE events processed by\n   * the controller's `for await` pump becomes one `store.setState`\n   * (and therefore one `useSyncExternalStore` notification).\n   */\n  #scheduleFlush = (): void => {\n    if (this.#flushScheduled) return;\n    this.#flushScheduled = true;\n    setTimeout(this.#flushPending, 0);\n  };\n\n  /**\n   * Drain `#pendingMessages` / `#pendingValues` to the store in a\n   * single `setState` call.\n   */\n  #flushPending = (): void => {\n    this.#flushScheduled = false;\n    const messages = this.#pendingMessages;\n    const values = this.#pendingValues;\n    this.#pendingMessages = null;\n    this.#pendingValues = null;\n    if (messages == null && values == null) return;\n    this.#store.setState((s) => {\n      // Other rootStore mutators (controller-driven `isLoading`,\n      // `interrupts`, `toolCalls`, etc.) do not touch `s.messages`\n      // / `s.values`, so a last-write-wins commit on those two\n      // fields is safe.\n      if (messages == null) {\n        return values == null ? s : { ...s, values };\n      }\n      if (values == null) return { ...s, messages };\n      return { ...s, messages, values };\n    });\n  };\n}\n\n/**\n * Mirror a freshly-updated message list into `values[messagesKey]`.\n *\n * Returns the same `values` reference when the list is already\n * equal-by-content so the caller can keep the existing snapshot\n * identity (and avoid spurious `setSnapshot` notifications).\n */\nfunction syncMessagesIntoValues<StateType extends object>(\n  values: StateType,\n  messagesKey: string,\n  messages: BaseMessage[]\n): StateType {\n  const record = values as Record<string, unknown>;\n  const current = record[messagesKey];\n  if (Array.isArray(current) && messagesEqualList(current, messages)) {\n    return values;\n  }\n  return {\n    ...record,\n    [messagesKey]: messages,\n  } as StateType;\n}\n\n/**\n * True when two `BaseMessage` arrays carry the same per-message\n * content (using {@link messagesEqual}).\n */\nfunction messagesEqualList(\n  previous: readonly BaseMessage[],\n  next: readonly BaseMessage[]\n): boolean {\n  if (previous === next) return true;\n  if (previous.length !== next.length) return false;\n  for (let i = 0; i < previous.length; i += 1) {\n    if (!messagesEqual(previous[i], next[i])) return false;\n  }\n  return true;\n}\n\n/**\n * Shallow-equal for `values` objects, *ignoring* the messages slot.\n *\n * The messages array is compared separately by the caller (via\n * {@link messagesEqualList}) because both arrays contain class\n * instances whose JSON representation is not stable across reads.\n */\nfunction stateValuesShallowEqual(\n  previous: object,\n  next: object,\n  messagesKey: string\n): boolean {\n  if (previous === next) return true;\n  const previousRecord = previous as Record<string, unknown>;\n  const nextRecord = next as Record<string, unknown>;\n  const previousKeys = Object.keys(previousRecord);\n  const nextKeys = Object.keys(nextRecord);\n  if (previousKeys.length !== nextKeys.length) return false;\n  for (const key of previousKeys) {\n    if (!Object.prototype.hasOwnProperty.call(nextRecord, key)) return false;\n    const previousValue = previousRecord[key];\n    const nextValue = nextRecord[key];\n    if (\n      key === messagesKey &&\n      Array.isArray(previousValue) &&\n      Array.isArray(nextValue)\n    ) {\n      continue;\n    }\n    if (!Object.is(previousValue, nextValue)) return false;\n  }\n  return true;\n}\n"],"mappings":"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"}
+{"version":3,"file":"root-message-projection.cjs","names":["#messagesKey","#store","MessageAssembler","#roles","#indexById","#toolCallIdByNamespace","#sealedMessageIds","#assembler","#valuesMessageIds","#pendingMessages","#pendingValues","#flushScheduled","#maxStep","#sealStep","namespaceKey","assembledMessageToBaseMessage","messagesEqual","#scheduleFlush","reconcileMessagesFromValues","shouldPreferValuesMessageForToolCalls","buildMessageIndex","#flushPending"],"sources":["../../src/stream/root-message-projection.ts"],"sourcesContent":["/**\n * Root-namespace message projection.\n *\n * # What this module is\n *\n * The {@link RootMessageProjection} is the piece of the\n * {@link StreamController} that owns \"what messages does the root\n * namespace currently contain?\". It assembles streamed message deltas\n * via {@link MessageAssembler}, reconciles them against authoritative\n * `values.messages` snapshots from the server, and writes the merged\n * list back into the controller's root snapshot store.\n *\n * # Two streams of truth\n *\n * Root messages arrive on two channels and need to merge cleanly:\n *\n *   - **`messages` channel.** Token-level deltas that build messages\n *     incrementally. The {@link MessageAssembler} keeps partial\n *     messages by id and emits an updated `BaseMessage` per delta.\n *   - **`values` channel.** Periodic full-state snapshots that include\n *     the authoritative messages array. Used for ordering, removals,\n *     and forks (where the streamed messages may pre-date the new\n *     timeline).\n *\n * The reconciliation rules (delegated to\n * {@link reconcileMessagesFromValues}) preserve in-flight streamed\n * content while letting values dictate ordering and removals.\n *\n * # Tool-message namespace correlation\n *\n * Tool messages arrive on `messages-start` events with `role: \"tool\"`\n * but the start event doesn't always include a `tool_call_id`. We\n * recover it via three fallbacks:\n *\n *   1. The start event itself, when the server includes it.\n *   2. The legacy `<id>-tool-<call_id>` message id format.\n *   3. The most recent `tool-started` event recorded under the same\n *      namespace via {@link recordToolCallNamespace}.\n *\n * Without this correlation, tool messages render with empty\n * `tool_call_id` and downstream UIs can't pair them with the\n * originating tool call.\n *\n * # Store-write batching\n *\n * Every {@link handleMessage} / {@link applyValues} call updates the\n * in-projection bookkeeping (assembler state, id index, role cache)\n * synchronously, then stages the new `messages` / `values` into a\n * pending buffer and schedules a `setTimeout(0)` flush. A single\n * coalesced `store.setState` runs at the next macrotask boundary.\n *\n * The motivation is the long-replay freeze: a thread with hundreds\n * of messages replays through the `messages` channel on refresh or\n * mid-run join. Those events drain through the controller's\n * `for await` pump as a long microtask chain. Per-event\n * `store.setState` notifies `useSyncExternalStore` per event, and\n * after enough notifications React's `nestedUpdateCount` guard trips\n * with \"Maximum update depth exceeded\", permanently freezing the UI\n * on the first few messages. Coalescing to one notification per\n * macrotask lets React's scheduler commit between flushes.\n *\n * # Lifecycle\n *\n *   - `handleMessage(event)`              — apply a `messages` event delta.\n *   - `applyValues(values, msgs)`         — merge a `values` snapshot.\n *   - `recordToolCallNamespace(ns, id)`   — capture `namespace → tool_call_id`\n *     so subsequent tool message starts can recover the id.\n *   - `reset()`                           — clear all state on thread rebind.\n */\nimport type {\n  MessagesEvent,\n  MessageRole,\n  MessageStartData,\n} from \"@langchain/protocol\";\nimport type { BaseMessage } from \"@langchain/core/messages\";\nimport { MessageAssembler } from \"../client/stream/messages.js\";\nimport {\n  assembledMessageToBaseMessage,\n  type ExtendedMessageRole,\n} from \"./assembled-to-message.js\";\nimport type { StreamStore } from \"./store.js\";\nimport type { RootSnapshot } from \"./types.js\";\nimport { namespaceKey } from \"./namespace.js\";\nimport {\n  buildMessageIndex,\n  messagesEqual,\n  reconcileMessagesFromValues,\n  shouldPreferValuesMessageForToolCalls,\n} from \"./message-reconciliation.js\";\n\n/**\n * Root-namespace message projection. Owns the merge between the\n * `messages` (streamed deltas) and `values` (authoritative\n * snapshots) channels for the root namespace.\n *\n * @typeParam StateType     - Root state shape; the messages array is read\n *   from `values[messagesKey]`.\n * @typeParam InterruptType - Shape of root protocol interrupts (forwarded\n *   into `RootSnapshot` updates).\n */\nexport class RootMessageProjection<\n  StateType extends object,\n  InterruptType = unknown,\n> {\n  /**\n   * Key inside `values` that holds the message array. Defaults to\n   * `\"messages\"` in the controller; configurable for state graphs\n   * that surface messages under a different slot.\n   */\n  readonly #messagesKey: string;\n\n  /** Root snapshot store written to on every merge. */\n  readonly #store: StreamStore<RootSnapshot<StateType, InterruptType>>;\n\n  /**\n   * Stateful chunk assembler for in-flight messages. Reset (via a\n   * fresh instance) on every {@link reset} so a new thread starts\n   * with no half-built messages from the previous one.\n   */\n  #assembler = new MessageAssembler();\n\n  /**\n   * `messageId → role/toolCallId` captured from `message-start` events.\n   * The assembler's intermediate output drops these fields, so we cache\n   * them at start-time and reapply when projecting to a `BaseMessage`.\n   */\n  readonly #roles = new Map<\n    string,\n    { role: ExtendedMessageRole; toolCallId?: string }\n  >();\n\n  /**\n   * `messageId → position in #store.messages` for fast in-place\n   * updates as deltas arrive. Rebuilt on every full reconciliation\n   * driven by a `values` event.\n   */\n  readonly #indexById = new Map<string, number>();\n\n  /**\n   * Ids observed in the most recent `values.messages` snapshot.\n   * Reconciliation uses this to detect server-side removals: a\n   * previously-seen id missing from the next snapshot means it was\n   * removed by the server (and should drop from the projection).\n   */\n  #valuesMessageIds = new Set<string>();\n\n  /**\n   * `namespaceKey → tool_call_id` captured from root `tool-started`\n   * events. Used as a fallback when a tool-role `message-start` is\n   * missing its `tool_call_id` field.\n   */\n  readonly #toolCallIdByNamespace = new Map<string, string>();\n\n  /**\n   * Coalescing buffer for store writes. {@link handleMessage} and\n   * {@link applyValues} stage their computed `messages` / `values`\n   * here instead of calling `store.setState` per event. A single\n   * `setTimeout(0)` flush commits them in one `setState`, so a\n   * burst of SSE events draining as a microtask chain becomes one\n   * store notification at the next macrotask boundary.\n   *\n   * `null` means \"no staged write\" — once a flush settles, the\n   * slots are cleared so the next call starts from the latest\n   * committed store snapshot.\n   */\n  #pendingMessages: BaseMessage[] | null = null;\n  #pendingValues: StateType | null = null;\n  #flushScheduled = false;\n\n  /**\n   * Highest checkpoint `step` whose `values` snapshot has been applied.\n   * Seeded by {@link StreamController.hydrate} from `getState()` and\n   * advanced by live `values` events. A snapshot arriving with a lower\n   * step is an older checkpoint replayed by the content pump on\n   * reconnect; it is reconciled in add-only mode so it cannot remove\n   * the seeded message tail (the final assistant turn). `undefined`\n   * until the first step-bearing snapshot, where the legacy\n   * remove-on-absence behavior is preserved.\n   */\n  #maxStep: number | undefined = undefined;\n\n  /**\n   * Message ids seeded as complete-and-final from an idle thread's\n   * `getState()` snapshot. An idle thread defers its root SSE pump, and\n   * the first `submit()` brings it up — at which point the transport\n   * replays the finished run from `seq=0`. Unlike the `values` channel\n   * (guarded by {@link #maxStep}), `messages`-channel deltas carry no\n   * step, so that replay would otherwise rebuild each already-complete\n   * message from an empty `message-start` and re-stream the whole turn\n   * token-by-token, clobbering the seeded tail (a visible \"messages\n   * replay\" on the first submit). Deltas for a sealed id are dropped in\n   * {@link handleMessage}. The seal is lifted once a checkpoint advances\n   * strictly past {@link #sealStep} (see {@link applyValues}) or on\n   * thread rebind ({@link reset}). New ids from the next run are never\n   * sealed, so they stream normally.\n   */\n  readonly #sealedMessageIds = new Set<string>();\n\n  /**\n   * High-water {@link #maxStep} captured when {@link sealMessageIds} ran,\n   * i.e. the seed checkpoint's step (or `undefined` when `getState()`\n   * carried no `metadata.step`). It is the boundary between the replayed\n   * idle history (steps `<= #sealStep`, emitted by the deferred pump's\n   * `seq=0` replay) and the new run (steps `> #sealStep`); only a\n   * checkpoint strictly past it lifts the seal. Without this boundary the\n   * replayed old-run checkpoints — which themselves carry increasing\n   * steps — would advance {@link #maxStep} and lift the seal mid-replay,\n   * reopening the clobber. When the seed step is unknown the boundary\n   * stays `undefined` and the seal holds until {@link reset}; the\n   * `values` channel (which ignores the seal) still reconciles any\n   * genuine change to a sealed id, only its streamed deltas are dropped.\n   */\n  #sealStep: number | undefined = undefined;\n\n  /**\n   * @param params.messagesKey - Key inside `values` that holds the\n   *   message array.\n   * @param params.store       - Root snapshot store to mutate.\n   */\n  constructor(params: {\n    messagesKey: string;\n    store: StreamStore<RootSnapshot<StateType, InterruptType>>;\n  }) {\n    this.#messagesKey = params.messagesKey;\n    this.#store = params.store;\n  }\n\n  /**\n   * Drop all per-thread state. Called by the controller on thread\n   * rebind / dispose so a swap doesn't surface stale messages.\n   */\n  reset(): void {\n    this.#assembler = new MessageAssembler();\n    this.#roles.clear();\n    this.#indexById.clear();\n    this.#valuesMessageIds = new Set();\n    this.#toolCallIdByNamespace.clear();\n    // Drop any unflushed pending writes — they were computed against\n    // the previous thread's baseline and committing them after a\n    // rebind would bleed stale messages into the new thread.\n    this.#pendingMessages = null;\n    this.#pendingValues = null;\n    this.#flushScheduled = false;\n    this.#maxStep = undefined;\n    this.#sealedMessageIds.clear();\n    this.#sealStep = undefined;\n  }\n\n  /**\n   * Seal message ids so the streamed `messages` channel cannot downgrade\n   * them to partial re-streams. Called by {@link StreamController.hydrate}\n   * after seeding an idle thread, whose deferred pump replays the finished\n   * run from `seq=0` on the first submit.\n   *\n   * Captures the current {@link #maxStep} as the lift boundary\n   * ({@link #sealStep}). The seal is applied immediately after the seed's\n   * `getState()` snapshot is reconciled, so `#maxStep` here is the seed\n   * step (or `undefined` when `getState()` carried no `metadata.step`).\n   * The seal is lifted once a checkpoint advances strictly past that\n   * boundary (see {@link applyValues}) or on thread rebind\n   * ({@link reset}).\n   *\n   * @param ids - Complete message ids from the idle `getState()` seed.\n   */\n  sealMessageIds(ids: Iterable<string>): void {\n    for (const id of ids) this.#sealedMessageIds.add(id);\n    if (this.#sealStep == null) this.#sealStep = this.#maxStep;\n  }\n\n  /**\n   * Record a `namespace → tool_call_id` mapping captured from a root\n   * `tool-started` event.\n   *\n   * The companion tool-role `message-start` event may not carry a\n   * `tool_call_id`, so we fall back to the most recent value recorded\n   * here for the same namespace.\n   *\n   * @param namespace  - Event namespace from the `tool-started` event.\n   * @param toolCallId - Tool call id from the same event.\n   */\n  recordToolCallNamespace(\n    namespace: readonly string[],\n    toolCallId: string\n  ): void {\n    this.#toolCallIdByNamespace.set(namespaceKey(namespace), toolCallId);\n  }\n\n  /**\n   * Apply a `messages` channel event to the projection.\n   *\n   * Captures role/tool metadata on `message-start`, feeds the chunk\n   * to the assembler, projects the assembled output to a\n   * {@link BaseMessage}, and either appends or in-place updates the\n   * pending messages buffer based on whether the id was seen before.\n   *\n   * @param event - The `messages` channel event to consume.\n   */\n  handleMessage(event: MessagesEvent): void {\n    const data = event.params.data;\n    if (data.event === \"message-start\") {\n      const startData = data as MessageStartData;\n      const role = (startData.role ?? \"ai\") as MessageRole;\n      const extendedRole =\n        (startData as { role?: ExtendedMessageRole }).role ?? role;\n      let toolCallId = (startData as { tool_call_id?: string }).tool_call_id;\n      // Tool messages need a tool_call_id to render. Fall back through:\n      //   1. legacy `<id>-tool-<call_id>` message id format\n      //   2. namespace-recorded tool_call_id (from #recordToolCallNamespace)\n      if (extendedRole === \"tool\" && toolCallId == null) {\n        const messageId = startData.id;\n        if (messageId != null) {\n          const match = /-tool-(.+)$/.exec(messageId);\n          if (match != null) toolCallId = match[1];\n        }\n        if (toolCallId == null) {\n          toolCallId = this.#toolCallIdByNamespace.get(\n            namespaceKey(event.params.namespace)\n          );\n        }\n      }\n      if (startData.id != null) {\n        this.#roles.set(startData.id, {\n          role: extendedRole,\n          toolCallId,\n        });\n      }\n    }\n\n    const update = this.#assembler.consume(event);\n    if (update == null) return;\n    const id = update.message.id;\n    if (id == null) return;\n    // A sealed id belongs to a message seeded complete from an idle\n    // thread's `getState()`; the deferred pump's `seq=0` replay would\n    // otherwise rebuild it from an empty start and re-stream the whole\n    // turn. Drop the replayed delta — the authoritative seed already\n    // holds the final content (see {@link #sealedMessageIds}).\n    if (this.#sealedMessageIds.has(id)) return;\n    const captured = this.#roles.get(id) ?? { role: \"ai\" as const };\n    const base = assembledMessageToBaseMessage(update.message, captured.role, {\n      toolCallId: captured.toolCallId,\n    });\n\n    // Compute against the pending baseline if we have one (so an\n    // earlier handleMessage in the same tick is the input to this\n    // one), else against the latest committed store snapshot.\n    // `#indexById` is the synchronous source of truth for \"where is\n    // each id in the current messages list\" — every code path below\n    // keeps it in sync before returning.\n    const baselineMessages =\n      this.#pendingMessages ?? this.#store.getSnapshot().messages;\n    const existingIdx = this.#indexById.get(id);\n    let messages: BaseMessage[];\n    if (existingIdx == null) {\n      this.#indexById.set(id, baselineMessages.length);\n      messages = [...baselineMessages, base];\n    } else if (messagesEqual(baselineMessages[existingIdx], base)) {\n      // Identical re-emission — skip the store write to keep\n      // snapshot identity stable.\n      return;\n    } else {\n      messages = baselineMessages.slice();\n      messages[existingIdx] = base;\n    }\n\n    // Mirror the new messages list into `values[messagesKey]` so\n    // direct `values` reads (used by some hooks and by the eventual\n    // `values` reconciliation) stay in sync.\n    const baselineValues =\n      this.#pendingValues ?? this.#store.getSnapshot().values;\n    const values = syncMessagesIntoValues(\n      baselineValues,\n      this.#messagesKey,\n      messages\n    );\n    this.#pendingMessages = messages;\n    if (values !== baselineValues) this.#pendingValues = values;\n    this.#scheduleFlush();\n  }\n\n  /**\n   * Reconcile a full `values` snapshot into the projection.\n   *\n   * Delegates the merge to {@link reconcileMessagesFromValues}:\n   * values stays authoritative for ordering and removals, while\n   * streamed in-flight messages keep their content until the server\n   * echoes them back. Empty messages just refresh the values blob.\n   *\n   * Rebuilds {@link #indexById} after the merge so subsequent delta\n   * applications target the new positions.\n   *\n   * @param nextValues   - Full values snapshot from the `values` event.\n   * @param nextMessages - The messages array extracted from\n   *   `values[messagesKey]` and coerced to `BaseMessage` instances.\n   * @param opts.step    - Checkpoint superstep for this snapshot, when\n   *   known. A snapshot whose step is below the highest applied step is\n   *   treated as a stale reconnect replay and reconciled add-only.\n   */\n  applyValues(\n    nextValues: StateType,\n    nextMessages: BaseMessage[],\n    opts?: { step?: number }\n  ): void {\n    const baselineSnapshot = this.#store.getSnapshot();\n    const baselineMessages = this.#pendingMessages ?? baselineSnapshot.messages;\n    const baselineValues = this.#pendingValues ?? baselineSnapshot.values;\n\n    const step = opts?.step;\n    // Stale only when we have both a prior high-water step and a lower\n    // incoming step. A missing step preserves the legacy semantics.\n    const addOnly =\n      step != null && this.#maxStep != null && step < this.#maxStep;\n    if (step != null && (this.#maxStep == null || step > this.#maxStep)) {\n      this.#maxStep = step;\n    }\n    // Lift the replay seal only when a checkpoint advances strictly past\n    // the step captured when the ids were sealed (the seed step). That\n    // boundary separates the replayed idle history (steps <= #sealStep,\n    // emitted by the deferred pump's seq=0 replay) from the new run\n    // (steps > #sealStep), so crossing it means seeded ids may now take\n    // genuine streamed updates. Replayed old-run checkpoints advance\n    // #maxStep but never reach past #sealStep, so they can't lift it. A\n    // `null` boundary (the seed step was unknown) keeps the seal until\n    // reset() — we can't tell replay from live, and the values channel\n    // still reconciles a sealed id even while its streamed deltas drop.\n    if (\n      this.#sealedMessageIds.size > 0 &&\n      step != null &&\n      this.#sealStep != null &&\n      step > this.#sealStep\n    ) {\n      this.#sealedMessageIds.clear();\n    }\n\n    if (nextMessages.length === 0) {\n      if (\n        stateValuesShallowEqual(baselineValues, nextValues, this.#messagesKey)\n      ) {\n        return;\n      }\n      // Mirror the current `messages` list back into the values slot\n      // so the staged snapshot stays consistent with the (separately\n      // tracked) messages array.\n      this.#pendingValues = syncMessagesIntoValues(\n        nextValues,\n        this.#messagesKey,\n        baselineMessages\n      );\n      this.#scheduleFlush();\n      return;\n    }\n\n    const reconciliation = reconcileMessagesFromValues({\n      valueMessages: nextMessages,\n      currentMessages: baselineMessages,\n      currentIndexById: this.#indexById,\n      previousValueMessageIds: this.#valuesMessageIds,\n      preferValuesMessage: shouldPreferValuesMessageForToolCalls,\n      addOnly,\n    });\n    // A stale replay snapshot must not shrink the authoritative id set:\n    // keep the (larger) seeded set so a genuinely-newer removal is still\n    // detected once the timeline advances past the seed.\n    if (!addOnly) this.#valuesMessageIds = reconciliation.valueMessageIds;\n    const messages = reconciliation.messages as BaseMessage[];\n    const values = {\n      ...(nextValues as Record<string, unknown>),\n      [this.#messagesKey]: messages,\n    } as StateType;\n    if (\n      messages === baselineMessages &&\n      stateValuesShallowEqual(baselineValues, values, this.#messagesKey)\n    ) {\n      return;\n    }\n\n    // Reconciliation may reorder, drop, or substitute messages, so\n    // rebuild the id → index map to match the new array.\n    this.#indexById.clear();\n    for (const [id, idx] of buildMessageIndex(messages)) {\n      this.#indexById.set(id, idx);\n    }\n    this.#pendingMessages = messages;\n    this.#pendingValues = values;\n    this.#scheduleFlush();\n  }\n\n  /**\n   * Append messages applied optimistically by a local `submit()`,\n   * keyed by id so the eventual server echo reconciles cleanly.\n   *\n   * Unlike {@link applyValues}, the supplied messages are *not* treated\n   * as an authoritative ordered snapshot: they are appended to the end\n   * of the current projection (or replaced in place when the id already\n   * exists), preserving prior history ordering. When the server later\n   * emits a `values` snapshot containing the same ids,\n   * {@link applyValues} → {@link reconcileMessagesFromValues} takes over\n   * (server ordering wins, the echoed message replaces the optimistic\n   * one).\n   *\n   * Non-message input keys are shallow-merged into `values` via\n   * `extraValues`; they are dropped/overwritten automatically by the\n   * first server `values` event (which rebuilds `values` from the\n   * server snapshot), or rolled back via {@link restoreValueKeys} when\n   * the run fails before any echo.\n   *\n   * @param messages    - Optimistic messages (already coerced to\n   *   `BaseMessage` instances, each carrying a stable id).\n   * @param extraValues - Non-message input keys to shallow-merge into\n   *   `values`.\n   */\n  appendOptimistic(\n    messages: BaseMessage[],\n    extraValues?: Record<string, unknown>\n  ): void {\n    let working = this.#pendingMessages ?? this.#store.getSnapshot().messages;\n    let mutated = false;\n    for (const message of messages) {\n      const id = message.id;\n      if (id == null) continue;\n      const existingIdx = this.#indexById.get(id);\n      if (existingIdx == null) {\n        if (!mutated) {\n          working = working.slice();\n          mutated = true;\n        }\n        this.#indexById.set(id, working.length);\n        working.push(message);\n      } else if (!messagesEqual(working[existingIdx], message)) {\n        if (!mutated) {\n          working = working.slice();\n          mutated = true;\n        }\n        working[existingIdx] = message;\n      }\n    }\n\n    const baselineValues =\n      this.#pendingValues ?? this.#store.getSnapshot().values;\n    let values = baselineValues;\n    if (extraValues != null && Object.keys(extraValues).length > 0) {\n      values = { ...(baselineValues as object), ...extraValues } as StateType;\n    }\n    values = syncMessagesIntoValues(values, this.#messagesKey, working);\n    if (!mutated && values === baselineValues) return;\n    this.#pendingMessages = working;\n    if (values !== baselineValues) this.#pendingValues = values;\n    this.#scheduleFlush();\n  }\n\n  /**\n   * Drop optimistic messages by id without disturbing the rest of the\n   * projection. Used by {@link StreamController.hydrate} to remove\n   * never-persisted optimistic messages (`pending` / `failed`) so a\n   * reload converges to server truth.\n   *\n   * @param ids - Message ids to remove.\n   */\n  dropOptimisticMessages(ids: ReadonlySet<string>): void {\n    if (ids.size === 0) return;\n    const baselineMessages =\n      this.#pendingMessages ?? this.#store.getSnapshot().messages;\n    const next = baselineMessages.filter((m) => m.id == null || !ids.has(m.id));\n    if (next.length === baselineMessages.length) return;\n    this.#indexById.clear();\n    for (const [id, idx] of buildMessageIndex(next)) {\n      this.#indexById.set(id, idx);\n    }\n    const baselineValues =\n      this.#pendingValues ?? this.#store.getSnapshot().values;\n    this.#pendingMessages = next;\n    this.#pendingValues = syncMessagesIntoValues(\n      baselineValues,\n      this.#messagesKey,\n      next\n    );\n    this.#scheduleFlush();\n  }\n\n  /**\n   * Restore (or delete) `values` keys that were optimistically merged\n   * by {@link appendOptimistic} but never echoed by the server — i.e.\n   * roll back non-message optimistic state when the run fails before\n   * any `values` event lands. Messages are left untouched (kept on\n   * failure per the optimistic contract).\n   *\n   * @param restore - Per-key pre-submit snapshot: when `hadKey` is\n   *   false the key is deleted, otherwise it is reset to `prevValue`.\n   */\n  restoreValueKeys(\n    restore: ReadonlyArray<{\n      key: string;\n      hadKey: boolean;\n      prevValue: unknown;\n    }>\n  ): void {\n    if (restore.length === 0) return;\n    const baselineValues =\n      this.#pendingValues ?? this.#store.getSnapshot().values;\n    const next = { ...(baselineValues as Record<string, unknown>) };\n    let changed = false;\n    for (const { key, hadKey, prevValue } of restore) {\n      if (key === this.#messagesKey) continue;\n      if (hadKey) {\n        if (!Object.is(next[key], prevValue)) {\n          next[key] = prevValue;\n          changed = true;\n        }\n      } else if (Object.prototype.hasOwnProperty.call(next, key)) {\n        delete next[key];\n        changed = true;\n      }\n    }\n    if (!changed) return;\n    this.#pendingValues = next as StateType;\n    this.#scheduleFlush();\n  }\n\n  /**\n   * Schedule a coalesced flush on the next macrotask. Idempotent\n   * within a tick — multiple `handleMessage` / `applyValues` calls\n   * before the flush fires collapse into one store write.\n   *\n   * `setTimeout(0)` is a macrotask: it runs after the current\n   * microtask chain drains, so a burst of SSE events processed by\n   * the controller's `for await` pump becomes one `store.setState`\n   * (and therefore one `useSyncExternalStore` notification).\n   */\n  #scheduleFlush = (): void => {\n    if (this.#flushScheduled) return;\n    this.#flushScheduled = true;\n    setTimeout(this.#flushPending, 0);\n  };\n\n  /**\n   * Drain `#pendingMessages` / `#pendingValues` to the store in a\n   * single `setState` call.\n   */\n  #flushPending = (): void => {\n    this.#flushScheduled = false;\n    const messages = this.#pendingMessages;\n    const values = this.#pendingValues;\n    this.#pendingMessages = null;\n    this.#pendingValues = null;\n    if (messages == null && values == null) return;\n    this.#store.setState((s) => {\n      // Other rootStore mutators (controller-driven `isLoading`,\n      // `interrupts`, `toolCalls`, etc.) do not touch `s.messages`\n      // / `s.values`, so a last-write-wins commit on those two\n      // fields is safe.\n      if (messages == null) {\n        return values == null ? s : { ...s, values };\n      }\n      if (values == null) return { ...s, messages };\n      return { ...s, messages, values };\n    });\n  };\n}\n\n/**\n * Mirror a freshly-updated message list into `values[messagesKey]`.\n *\n * Returns the same `values` reference when the list is already\n * equal-by-content so the caller can keep the existing snapshot\n * identity (and avoid spurious `setSnapshot` notifications).\n */\nfunction syncMessagesIntoValues<StateType extends object>(\n  values: StateType,\n  messagesKey: string,\n  messages: BaseMessage[]\n): StateType {\n  const record = values as Record<string, unknown>;\n  const current = record[messagesKey];\n  if (Array.isArray(current) && messagesEqualList(current, messages)) {\n    return values;\n  }\n  return {\n    ...record,\n    [messagesKey]: messages,\n  } as StateType;\n}\n\n/**\n * True when two `BaseMessage` arrays carry the same per-message\n * content (using {@link messagesEqual}).\n */\nfunction messagesEqualList(\n  previous: readonly BaseMessage[],\n  next: readonly BaseMessage[]\n): boolean {\n  if (previous === next) return true;\n  if (previous.length !== next.length) return false;\n  for (let i = 0; i < previous.length; i += 1) {\n    if (!messagesEqual(previous[i], next[i])) return false;\n  }\n  return true;\n}\n\n/**\n * Shallow-equal for `values` objects, *ignoring* the messages slot.\n *\n * The messages array is compared separately by the caller (via\n * {@link messagesEqualList}) because both arrays contain class\n * instances whose JSON representation is not stable across reads.\n */\nfunction stateValuesShallowEqual(\n  previous: object,\n  next: object,\n  messagesKey: string\n): boolean {\n  if (previous === next) return true;\n  const previousRecord = previous as Record<string, unknown>;\n  const nextRecord = next as Record<string, unknown>;\n  const previousKeys = Object.keys(previousRecord);\n  const nextKeys = Object.keys(nextRecord);\n  if (previousKeys.length !== nextKeys.length) return false;\n  for (const key of previousKeys) {\n    if (!Object.prototype.hasOwnProperty.call(nextRecord, key)) return false;\n    const previousValue = previousRecord[key];\n    const nextValue = nextRecord[key];\n    if (\n      key === messagesKey &&\n      Array.isArray(previousValue) &&\n      Array.isArray(nextValue)\n    ) {\n      continue;\n    }\n    if (!Object.is(previousValue, nextValue)) return false;\n  }\n  return true;\n}\n"],"mappings":";;;;;;;;;;;;;;;AAoGA,IAAa,wBAAb,MAGE;;;;;;CAMA;;CAGA;;;;;;CAOA,aAAa,IAAIE,iBAAAA,kBAAkB;;;;;;CAOnC,yBAAkB,IAAI,KAGnB;;;;;;CAOH,6BAAsB,IAAI,KAAqB;;;;;;;CAQ/C,oCAAoB,IAAI,KAAa;;;;;;CAOrC,yCAAkC,IAAI,KAAqB;;;;;;;;;;;;;CAc3D,mBAAyC;CACzC,iBAAmC;CACnC,kBAAkB;;;;;;;;;;;CAYlB,WAA+B,KAAA;;;;;;;;;;;;;;;;CAiB/B,oCAA6B,IAAI,KAAa;;;;;;;;;;;;;;;CAgB9C,YAAgC,KAAA;;;;;;CAOhC,YAAY,QAGT;AACD,QAAA,cAAoB,OAAO;AAC3B,QAAA,QAAc,OAAO;;;;;;CAOvB,QAAc;AACZ,QAAA,YAAkB,IAAIA,iBAAAA,kBAAkB;AACxC,QAAA,MAAY,OAAO;AACnB,QAAA,UAAgB,OAAO;AACvB,QAAA,mCAAyB,IAAI,KAAK;AAClC,QAAA,sBAA4B,OAAO;AAInC,QAAA,kBAAwB;AACxB,QAAA,gBAAsB;AACtB,QAAA,iBAAuB;AACvB,QAAA,UAAgB,KAAA;AAChB,QAAA,iBAAuB,OAAO;AAC9B,QAAA,WAAiB,KAAA;;;;;;;;;;;;;;;;;;CAmBnB,eAAe,KAA6B;AAC1C,OAAK,MAAM,MAAM,IAAK,OAAA,iBAAuB,IAAI,GAAG;AACpD,MAAI,MAAA,YAAkB,KAAM,OAAA,WAAiB,MAAA;;;;;;;;;;;;;CAc/C,wBACE,WACA,YACM;AACN,QAAA,sBAA4B,IAAIY,kBAAAA,aAAa,UAAU,EAAE,WAAW;;;;;;;;;;;;CAatE,cAAc,OAA4B;EACxC,MAAM,OAAO,MAAM,OAAO;AAC1B,MAAI,KAAK,UAAU,iBAAiB;GAClC,MAAM,YAAY;GAClB,MAAM,OAAQ,UAAU,QAAQ;GAChC,MAAM,eACH,UAA6C,QAAQ;GACxD,IAAI,aAAc,UAAwC;AAI1D,OAAI,iBAAiB,UAAU,cAAc,MAAM;IACjD,MAAM,YAAY,UAAU;AAC5B,QAAI,aAAa,MAAM;KACrB,MAAM,QAAQ,cAAc,KAAK,UAAU;AAC3C,SAAI,SAAS,KAAM,cAAa,MAAM;;AAExC,QAAI,cAAc,KAChB,cAAa,MAAA,sBAA4B,IACvCA,kBAAAA,aAAa,MAAM,OAAO,UAAU,CACrC;;AAGL,OAAI,UAAU,MAAM,KAClB,OAAA,MAAY,IAAI,UAAU,IAAI;IAC5B,MAAM;IACN;IACD,CAAC;;EAIN,MAAM,SAAS,MAAA,UAAgB,QAAQ,MAAM;AAC7C,MAAI,UAAU,KAAM;EACpB,MAAM,KAAK,OAAO,QAAQ;AAC1B,MAAI,MAAM,KAAM;AAMhB,MAAI,MAAA,iBAAuB,IAAI,GAAG,CAAE;EACpC,MAAM,WAAW,MAAA,MAAY,IAAI,GAAG,IAAI,EAAE,MAAM,MAAe;EAC/D,MAAM,OAAOC,6BAAAA,8BAA8B,OAAO,SAAS,SAAS,MAAM,EACxE,YAAY,SAAS,YACtB,CAAC;EAQF,MAAM,mBACJ,MAAA,mBAAyB,MAAA,MAAY,aAAa,CAAC;EACrD,MAAM,cAAc,MAAA,UAAgB,IAAI,GAAG;EAC3C,IAAI;AACJ,MAAI,eAAe,MAAM;AACvB,SAAA,UAAgB,IAAI,IAAI,iBAAiB,OAAO;AAChD,cAAW,CAAC,GAAG,kBAAkB,KAAK;aAC7BC,+BAAAA,cAAc,iBAAiB,cAAc,KAAK,CAG3D;OACK;AACL,cAAW,iBAAiB,OAAO;AACnC,YAAS,eAAe;;EAM1B,MAAM,iBACJ,MAAA,iBAAuB,MAAA,MAAY,aAAa,CAAC;EACnD,MAAM,SAAS,uBACb,gBACA,MAAA,aACA,SACD;AACD,QAAA,kBAAwB;AACxB,MAAI,WAAW,eAAgB,OAAA,gBAAsB;AACrD,QAAA,eAAqB;;;;;;;;;;;;;;;;;;;;CAqBvB,YACE,YACA,cACA,MACM;EACN,MAAM,mBAAmB,MAAA,MAAY,aAAa;EAClD,MAAM,mBAAmB,MAAA,mBAAyB,iBAAiB;EACnE,MAAM,iBAAiB,MAAA,iBAAuB,iBAAiB;EAE/D,MAAM,OAAO,MAAM;EAGnB,MAAM,UACJ,QAAQ,QAAQ,MAAA,WAAiB,QAAQ,OAAO,MAAA;AAClD,MAAI,QAAQ,SAAS,MAAA,WAAiB,QAAQ,OAAO,MAAA,SACnD,OAAA,UAAgB;AAYlB,MACE,MAAA,iBAAuB,OAAO,KAC9B,QAAQ,QACR,MAAA,YAAkB,QAClB,OAAO,MAAA,SAEP,OAAA,iBAAuB,OAAO;AAGhC,MAAI,aAAa,WAAW,GAAG;AAC7B,OACE,wBAAwB,gBAAgB,YAAY,MAAA,YAAkB,CAEtE;AAKF,SAAA,gBAAsB,uBACpB,YACA,MAAA,aACA,iBACD;AACD,SAAA,eAAqB;AACrB;;EAGF,MAAM,iBAAiBE,+BAAAA,4BAA4B;GACjD,eAAe;GACf,iBAAiB;GACjB,kBAAkB,MAAA;GAClB,yBAAyB,MAAA;GACzB,qBAAqBC,+BAAAA;GACrB;GACD,CAAC;AAIF,MAAI,CAAC,QAAS,OAAA,mBAAyB,eAAe;EACtD,MAAM,WAAW,eAAe;EAChC,MAAM,SAAS;GACb,GAAI;IACH,MAAA,cAAoB;GACtB;AACD,MACE,aAAa,oBACb,wBAAwB,gBAAgB,QAAQ,MAAA,YAAkB,CAElE;AAKF,QAAA,UAAgB,OAAO;AACvB,OAAK,MAAM,CAAC,IAAI,QAAQC,+BAAAA,kBAAkB,SAAS,CACjD,OAAA,UAAgB,IAAI,IAAI,IAAI;AAE9B,QAAA,kBAAwB;AACxB,QAAA,gBAAsB;AACtB,QAAA,eAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;CA2BvB,iBACE,UACA,aACM;EACN,IAAI,UAAU,MAAA,mBAAyB,MAAA,MAAY,aAAa,CAAC;EACjE,IAAI,UAAU;AACd,OAAK,MAAM,WAAW,UAAU;GAC9B,MAAM,KAAK,QAAQ;AACnB,OAAI,MAAM,KAAM;GAChB,MAAM,cAAc,MAAA,UAAgB,IAAI,GAAG;AAC3C,OAAI,eAAe,MAAM;AACvB,QAAI,CAAC,SAAS;AACZ,eAAU,QAAQ,OAAO;AACzB,eAAU;;AAEZ,UAAA,UAAgB,IAAI,IAAI,QAAQ,OAAO;AACvC,YAAQ,KAAK,QAAQ;cACZ,CAACJ,+BAAAA,cAAc,QAAQ,cAAc,QAAQ,EAAE;AACxD,QAAI,CAAC,SAAS;AACZ,eAAU,QAAQ,OAAO;AACzB,eAAU;;AAEZ,YAAQ,eAAe;;;EAI3B,MAAM,iBACJ,MAAA,iBAAuB,MAAA,MAAY,aAAa,CAAC;EACnD,IAAI,SAAS;AACb,MAAI,eAAe,QAAQ,OAAO,KAAK,YAAY,CAAC,SAAS,EAC3D,UAAS;GAAE,GAAI;GAA2B,GAAG;GAAa;AAE5D,WAAS,uBAAuB,QAAQ,MAAA,aAAmB,QAAQ;AACnE,MAAI,CAAC,WAAW,WAAW,eAAgB;AAC3C,QAAA,kBAAwB;AACxB,MAAI,WAAW,eAAgB,OAAA,gBAAsB;AACrD,QAAA,eAAqB;;;;;;;;;;CAWvB,uBAAuB,KAAgC;AACrD,MAAI,IAAI,SAAS,EAAG;EACpB,MAAM,mBACJ,MAAA,mBAAyB,MAAA,MAAY,aAAa,CAAC;EACrD,MAAM,OAAO,iBAAiB,QAAQ,MAAM,EAAE,MAAM,QAAQ,CAAC,IAAI,IAAI,EAAE,GAAG,CAAC;AAC3E,MAAI,KAAK,WAAW,iBAAiB,OAAQ;AAC7C,QAAA,UAAgB,OAAO;AACvB,OAAK,MAAM,CAAC,IAAI,QAAQI,+BAAAA,kBAAkB,KAAK,CAC7C,OAAA,UAAgB,IAAI,IAAI,IAAI;EAE9B,MAAM,iBACJ,MAAA,iBAAuB,MAAA,MAAY,aAAa,CAAC;AACnD,QAAA,kBAAwB;AACxB,QAAA,gBAAsB,uBACpB,gBACA,MAAA,aACA,KACD;AACD,QAAA,eAAqB;;;;;;;;;;;;CAavB,iBACE,SAKM;AACN,MAAI,QAAQ,WAAW,EAAG;EAG1B,MAAM,OAAO,EAAE,GADb,MAAA,iBAAuB,MAAA,MAAY,aAAa,CAAC,QACY;EAC/D,IAAI,UAAU;AACd,OAAK,MAAM,EAAE,KAAK,QAAQ,eAAe,SAAS;AAChD,OAAI,QAAQ,MAAA,YAAmB;AAC/B,OAAI;QACE,CAAC,OAAO,GAAG,KAAK,MAAM,UAAU,EAAE;AACpC,UAAK,OAAO;AACZ,eAAU;;cAEH,OAAO,UAAU,eAAe,KAAK,MAAM,IAAI,EAAE;AAC1D,WAAO,KAAK;AACZ,cAAU;;;AAGd,MAAI,CAAC,QAAS;AACd,QAAA,gBAAsB;AACtB,QAAA,eAAqB;;;;;;;;;;;;CAavB,uBAA6B;AAC3B,MAAI,MAAA,eAAsB;AAC1B,QAAA,iBAAuB;AACvB,aAAW,MAAA,cAAoB,EAAE;;;;;;CAOnC,sBAA4B;AAC1B,QAAA,iBAAuB;EACvB,MAAM,WAAW,MAAA;EACjB,MAAM,SAAS,MAAA;AACf,QAAA,kBAAwB;AACxB,QAAA,gBAAsB;AACtB,MAAI,YAAY,QAAQ,UAAU,KAAM;AACxC,QAAA,MAAY,UAAU,MAAM;AAK1B,OAAI,YAAY,KACd,QAAO,UAAU,OAAO,IAAI;IAAE,GAAG;IAAG;IAAQ;AAE9C,OAAI,UAAU,KAAM,QAAO;IAAE,GAAG;IAAG;IAAU;AAC7C,UAAO;IAAE,GAAG;IAAG;IAAU;IAAQ;IACjC;;;;;;;;;;AAWN,SAAS,uBACP,QACA,aACA,UACW;CACX,MAAM,SAAS;CACf,MAAM,UAAU,OAAO;AACvB,KAAI,MAAM,QAAQ,QAAQ,IAAI,kBAAkB,SAAS,SAAS,CAChE,QAAO;AAET,QAAO;EACL,GAAG;GACF,cAAc;EAChB;;;;;;AAOH,SAAS,kBACP,UACA,MACS;AACT,KAAI,aAAa,KAAM,QAAO;AAC9B,KAAI,SAAS,WAAW,KAAK,OAAQ,QAAO;AAC5C,MAAK,IAAI,IAAI,GAAG,IAAI,SAAS,QAAQ,KAAK,EACxC,KAAI,CAACJ,+BAAAA,cAAc,SAAS,IAAI,KAAK,GAAG,CAAE,QAAO;AAEnD,QAAO;;;;;;;;;AAUT,SAAS,wBACP,UACA,MACA,aACS;AACT,KAAI,aAAa,KAAM,QAAO;CAC9B,MAAM,iBAAiB;CACvB,MAAM,aAAa;CACnB,MAAM,eAAe,OAAO,KAAK,eAAe;CAChD,MAAM,WAAW,OAAO,KAAK,WAAW;AACxC,KAAI,aAAa,WAAW,SAAS,OAAQ,QAAO;AACpD,MAAK,MAAM,OAAO,cAAc;AAC9B,MAAI,CAAC,OAAO,UAAU,eAAe,KAAK,YAAY,IAAI,CAAE,QAAO;EACnE,MAAM,gBAAgB,eAAe;EACrC,MAAM,YAAY,WAAW;AAC7B,MACE,QAAQ,eACR,MAAM,QAAQ,cAAc,IAC5B,MAAM,QAAQ,UAAU,CAExB;AAEF,MAAI,CAAC,OAAO,GAAG,eAAe,UAAU,CAAE,QAAO;;AAEnD,QAAO"}

package/dist/stream/root-message-projection.js

@@ -80,6 +80,37 @@ var RootMessageProjection = class {
 	*/
 	#maxStep = void 0;
 	/**
+	* Message ids seeded as complete-and-final from an idle thread's
+	* `getState()` snapshot. An idle thread defers its root SSE pump, and
+	* the first `submit()` brings it up — at which point the transport
+	* replays the finished run from `seq=0`. Unlike the `values` channel
+	* (guarded by {@link #maxStep}), `messages`-channel deltas carry no
+	* step, so that replay would otherwise rebuild each already-complete
+	* message from an empty `message-start` and re-stream the whole turn
+	* token-by-token, clobbering the seeded tail (a visible "messages
+	* replay" on the first submit). Deltas for a sealed id are dropped in
+	* {@link handleMessage}. The seal is lifted once a checkpoint advances
+	* strictly past {@link #sealStep} (see {@link applyValues}) or on
+	* thread rebind ({@link reset}). New ids from the next run are never
+	* sealed, so they stream normally.
+	*/
+	#sealedMessageIds = /* @__PURE__ */ new Set();
+	/**
+	* High-water {@link #maxStep} captured when {@link sealMessageIds} ran,
+	* i.e. the seed checkpoint's step (or `undefined` when `getState()`
+	* carried no `metadata.step`). It is the boundary between the replayed
+	* idle history (steps `<= #sealStep`, emitted by the deferred pump's
+	* `seq=0` replay) and the new run (steps `> #sealStep`); only a
+	* checkpoint strictly past it lifts the seal. Without this boundary the
+	* replayed old-run checkpoints — which themselves carry increasing
+	* steps — would advance {@link #maxStep} and lift the seal mid-replay,
+	* reopening the clobber. When the seed step is unknown the boundary
+	* stays `undefined` and the seal holds until {@link reset}; the
+	* `values` channel (which ignores the seal) still reconciles any
+	* genuine change to a sealed id, only its streamed deltas are dropped.
+	*/
+	#sealStep = void 0;
+	/**
 	* @param params.messagesKey - Key inside `values` that holds the
 	*   message array.
 	* @param params.store       - Root snapshot store to mutate.
@@ -102,6 +133,28 @@ var RootMessageProjection = class {
 		this.#pendingValues = null;
 		this.#flushScheduled = false;
 		this.#maxStep = void 0;
+		this.#sealedMessageIds.clear();
+		this.#sealStep = void 0;
+	}
+	/**
+	* Seal message ids so the streamed `messages` channel cannot downgrade
+	* them to partial re-streams. Called by {@link StreamController.hydrate}
+	* after seeding an idle thread, whose deferred pump replays the finished
+	* run from `seq=0` on the first submit.
+	*
+	* Captures the current {@link #maxStep} as the lift boundary
+	* ({@link #sealStep}). The seal is applied immediately after the seed's
+	* `getState()` snapshot is reconciled, so `#maxStep` here is the seed
+	* step (or `undefined` when `getState()` carried no `metadata.step`).
+	* The seal is lifted once a checkpoint advances strictly past that
+	* boundary (see {@link applyValues}) or on thread rebind
+	* ({@link reset}).
+	*
+	* @param ids - Complete message ids from the idle `getState()` seed.
+	*/
+	sealMessageIds(ids) {
+		for (const id of ids) this.#sealedMessageIds.add(id);
+		if (this.#sealStep == null) this.#sealStep = this.#maxStep;
 	}
 	/**
 	* Record a `namespace → tool_call_id` mapping captured from a root
@@ -151,6 +204,7 @@ var RootMessageProjection = class {
 		if (update == null) return;
 		const id = update.message.id;
 		if (id == null) return;
+		if (this.#sealedMessageIds.has(id)) return;
 		const captured = this.#roles.get(id) ?? { role: "ai" };
 		const base = assembledMessageToBaseMessage(update.message, captured.role, { toolCallId: captured.toolCallId });
 		const baselineMessages = this.#pendingMessages ?? this.#store.getSnapshot().messages;
@@ -195,6 +249,7 @@ var RootMessageProjection = class {
 		const step = opts?.step;
 		const addOnly = step != null && this.#maxStep != null && step < this.#maxStep;
 		if (step != null && (this.#maxStep == null || step > this.#maxStep)) this.#maxStep = step;
+		if (this.#sealedMessageIds.size > 0 && step != null && this.#sealStep != null && step > this.#sealStep) this.#sealedMessageIds.clear();
 		if (nextMessages.length === 0) {
 			if (stateValuesShallowEqual(baselineValues, nextValues, this.#messagesKey)) return;
 			this.#pendingValues = syncMessagesIntoValues(nextValues, this.#messagesKey, baselineMessages);