@langchain/langgraph 1.2.9 → 1.3.0

package/dist/stream/convert.js

@@ -0,0 +1,206 @@
+//#region src/stream/convert.ts
+/**
+* The set of stream modes requested by
+* `streamEvents(..., { version: "v3" })` — every mode the protocol maps
+* to a channel.
+*
+* The verbose `"debug"` mode is intentionally excluded: it was a thin
+* re-wrap of `checkpoints` + `tasks` carrying no new information.
+*
+* The `"checkpoints"` mode is likewise excluded from the stream-mode
+* request because the protocol's `checkpoints` channel carries only a
+* lightweight envelope (`id`, `parent_id`, `step`, `source`) derived from
+* {@link StreamChunkMeta.checkpoint} on the adjacent `values` chunk — not
+* the full-state shape that Pregel's `checkpoints` stream mode produces.
+* `convertToProtocolEvent` emits a companion `checkpoints` protocol event
+* next to each `values` event when meta is present, so clients can build
+* branching/time-travel UIs without a full-state `checkpoints` subscription.
+*/
+const STREAM_EVENTS_V3_MODES = [
+	"values",
+	"updates",
+	"messages",
+	"tools",
+	"custom",
+	"tasks"
+];
+function unwrapMessagesPayload(payload) {
+	if (!Array.isArray(payload) || payload.length !== 2) return { data: payload };
+	const [data, metadata] = payload;
+	if (metadata == null || typeof metadata !== "object") return { data: payload };
+	const record = metadata;
+	const node = typeof record.langgraph_node === "string" ? record.langgraph_node : void 0;
+	const runId = typeof record.run_id === "string" ? record.run_id : void 0;
+	return {
+		data: runId != null && data != null && typeof data === "object" ? {
+			...data,
+			run_id: runId
+		} : data,
+		node
+	};
+}
+function convertToProtocolEvent({ namespace: ns, mode, payload, seq, meta }) {
+	const timestamp = Date.now();
+	const base = { type: "event" };
+	switch (mode) {
+		case "messages": {
+			const { data, node } = unwrapMessagesPayload(payload);
+			return [{
+				...base,
+				seq,
+				method: "messages",
+				params: {
+					namespace: ns,
+					timestamp,
+					...node ? { node } : {},
+					data
+				}
+			}];
+		}
+		case "tools": return [{
+			...base,
+			seq,
+			method: "tools",
+			params: {
+				namespace: ns,
+				timestamp,
+				data: convertToolsPayload(payload)
+			}
+		}];
+		case "values": {
+			const events = [];
+			if (meta?.checkpoint != null) events.push({
+				...base,
+				seq,
+				method: "checkpoints",
+				params: {
+					namespace: ns,
+					timestamp,
+					data: meta.checkpoint
+				}
+			});
+			events.push({
+				...base,
+				seq: meta?.checkpoint != null ? seq + 1 : seq,
+				method: "values",
+				params: {
+					namespace: ns,
+					timestamp,
+					data: payload
+				}
+			});
+			return events;
+		}
+		case "updates": {
+			const data = convertUpdatesPayload(payload);
+			return [{
+				...base,
+				seq,
+				method: "updates",
+				params: {
+					namespace: ns,
+					timestamp,
+					...typeof data.node === "string" ? { node: data.node } : {},
+					data
+				}
+			}];
+		}
+		case "custom": {
+			const data = typeof payload === "object" && payload !== null && !Array.isArray(payload) && "name" in payload ? payload : { payload };
+			return [{
+				...base,
+				seq,
+				method: "custom",
+				params: {
+					namespace: ns,
+					timestamp,
+					data
+				}
+			}];
+		}
+		case "tasks": return [{
+			...base,
+			seq,
+			method: "tasks",
+			params: {
+				namespace: ns,
+				timestamp,
+				data: payload
+			}
+		}];
+		default: return [];
+	}
+}
+/**
+* Normalises a raw tools-mode payload into a typed {@link ToolsEventData}
+* discriminated union, mapping internal lifecycle events (`on_tool_start`,
+* `on_tool_end`, etc.) to their protocol counterparts.
+*
+* @param payload - The raw payload from a `"tools"` stream chunk.
+* @returns A {@link ToolsEventData} object with the appropriate `event`
+*   discriminant and associated fields.
+*/
+function convertToolsPayload(payload) {
+	if (typeof payload !== "object" || payload === null) return {
+		event: "tool-error",
+		tool_call_id: "",
+		message: "Unexpected tools payload shape"
+	};
+	const p = payload;
+	const tool_call_id = String(p.toolCallId ?? "");
+	switch (p.event) {
+		case "on_tool_start": return {
+			event: "tool-started",
+			tool_call_id,
+			tool_name: String(p.name ?? "unknown"),
+			input: p.input
+		};
+		case "on_tool_event": return {
+			event: "tool-output-delta",
+			tool_call_id,
+			delta: typeof p.data === "string" ? p.data : JSON.stringify(p.data ?? "")
+		};
+		case "on_tool_end": return {
+			event: "tool-finished",
+			tool_call_id,
+			output: p.output
+		};
+		case "on_tool_error": {
+			const err = p.error;
+			return {
+				event: "tool-error",
+				tool_call_id,
+				message: typeof err === "object" && err !== null && "message" in err && typeof err.message === "string" ? err.message : String(err ?? "unknown error")
+			};
+		}
+		default: return {
+			event: "tool-error",
+			tool_call_id: "",
+			message: `Unknown tool event: ${String(p.event)}`
+		};
+	}
+}
+/**
+* Extracts the first `{node: delta}` entry from an updates-mode payload and
+* reshapes it into an {@link UpdatesEventData} with explicit `node` and
+* `values` fields.  Non-object payloads are coerced to `{ values: {} }`.
+*
+* @param payload - The raw payload from an `"updates"` stream chunk,
+*   expected to be a `Record<string, unknown>` keyed by node name.
+* @returns An {@link UpdatesEventData} containing the extracted node name
+*   and its associated delta values.
+*/
+function convertUpdatesPayload(payload) {
+	if (typeof payload !== "object" || payload === null) return { values: {} };
+	const entries = Object.entries(payload);
+	if (entries.length === 0) return { values: {} };
+	const [node, values] = entries[0];
+	return {
+		node,
+		values: typeof values === "object" && values !== null ? values : { value: values }
+	};
+}
+//#endregion
+export { STREAM_EVENTS_V3_MODES, convertToProtocolEvent };
+
+//# sourceMappingURL=convert.js.map

package/dist/stream/convert.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"convert.js","names":[],"sources":["../../src/stream/convert.ts"],"sourcesContent":["/**\n * Protocol event conversion — maps raw `[ns, mode, payload, meta?]` stream\n * chunks from graph.stream() to CDDL-aligned ProtocolEvents.\n */\n\nimport type { StreamMode } from \"../pregel/types.js\";\nimport type { StreamChunkMeta } from \"../pregel/stream.js\";\nimport type {\n  Namespace,\n  ProtocolEvent,\n  ToolsEventData,\n  UpdatesEventData,\n} from \"./types.js\";\n\n/**\n * The set of stream modes requested by\n * `streamEvents(..., { version: \"v3\" })` — every mode the protocol maps\n * to a channel.\n *\n * The verbose `\"debug\"` mode is intentionally excluded: it was a thin\n * re-wrap of `checkpoints` + `tasks` carrying no new information.\n *\n * The `\"checkpoints\"` mode is likewise excluded from the stream-mode\n * request because the protocol's `checkpoints` channel carries only a\n * lightweight envelope (`id`, `parent_id`, `step`, `source`) derived from\n * {@link StreamChunkMeta.checkpoint} on the adjacent `values` chunk — not\n * the full-state shape that Pregel's `checkpoints` stream mode produces.\n * `convertToProtocolEvent` emits a companion `checkpoints` protocol event\n * next to each `values` event when meta is present, so clients can build\n * branching/time-travel UIs without a full-state `checkpoints` subscription.\n */\nexport const STREAM_EVENTS_V3_MODES: StreamMode[] = [\n  \"values\",\n  \"updates\",\n  \"messages\",\n  \"tools\",\n  \"custom\",\n  \"tasks\",\n];\n\n/**\n * Converts a raw `[ns, mode, payload, meta?]` stream chunk emitted by\n * `graph.stream()` into one or more CDDL-aligned {@link ProtocolEvent}s.\n *\n * Most modes produce a single event. `values` chunks carrying\n * {@link StreamChunkMeta.checkpoint} additionally produce a companion\n * `checkpoints` event immediately after the `values` event, so clients\n * that subscribe only to `checkpoints` can build a branching timeline\n * without also paying for full-state `values` payloads, and clients that\n * subscribe to both can correlate the pair by `(namespace, step)` or by\n * adjacent `seq` numbers.\n *\n * Returns an empty array for stream modes that have no protocol mapping.\n *\n * @param options - Conversion inputs for a single raw stream chunk.\n * @param options.namespace - Hierarchical namespace path identifying the\n *   source in the agent tree.\n * @param options.mode - The stream mode that produced this chunk (e.g.\n *   `\"messages\"`, `\"tools\"`).\n * @param options.payload - The raw payload emitted by the stream for this\n *   mode.\n * @param options.seq - Monotonically increasing sequence number assigned to\n *   the first returned event; the companion `checkpoints` event (when\n *   emitted) uses `seq + 1`.\n * @param options.meta - Optional chunk-level metadata (e.g. the checkpoint\n *   envelope paired with a `values` chunk).\n * @returns An ordered list of {@link ProtocolEvent}s ready for downstream\n *   reducers. Callers advance their `seq` counter by `result.length`.\n */\nexport interface ConvertToProtocolEventOptions {\n  namespace: Namespace;\n  mode: StreamMode;\n  payload: unknown;\n  seq: number;\n  meta?: StreamChunkMeta;\n}\n\nfunction unwrapMessagesPayload(payload: unknown) {\n  if (!Array.isArray(payload) || payload.length !== 2) {\n    return { data: payload };\n  }\n\n  const [data, metadata] = payload;\n  if (metadata == null || typeof metadata !== \"object\") {\n    return { data: payload };\n  }\n\n  const record = metadata as Record<string, unknown>;\n  const node =\n    typeof record.langgraph_node === \"string\"\n      ? record.langgraph_node\n      : undefined;\n  const runId = typeof record.run_id === \"string\" ? record.run_id : undefined;\n  const dataWithRunId =\n    runId != null && data != null && typeof data === \"object\"\n      ? { ...(data as Record<string, unknown>), run_id: runId }\n      : data;\n\n  return { data: dataWithRunId, node };\n}\n\nexport function convertToProtocolEvent({\n  namespace: ns,\n  mode,\n  payload,\n  seq,\n  meta,\n}: ConvertToProtocolEventOptions): ProtocolEvent[] {\n  const timestamp = Date.now();\n  const base = { type: \"event\" as const };\n\n  switch (mode) {\n    case \"messages\": {\n      const { data, node } = unwrapMessagesPayload(payload);\n      return [\n        {\n          ...base,\n          seq,\n          method: \"messages\",\n          params: { namespace: ns, timestamp, ...(node ? { node } : {}), data },\n        },\n      ];\n    }\n\n    case \"tools\":\n      return [\n        {\n          ...base,\n          seq,\n          method: \"tools\",\n          params: {\n            namespace: ns,\n            timestamp,\n            data: convertToolsPayload(payload),\n          },\n        },\n      ];\n\n    case \"values\": {\n      // Emit the `checkpoints` event immediately BEFORE its companion\n      // `values` event so clients subscribed to both channels have the\n      // envelope buffered by the time the values payload arrives. This\n      // lets the SDK attach `parentCheckpointId` to messages extracted\n      // from the values snapshot without waiting for a second pass.\n      const events: ProtocolEvent[] = [];\n      if (meta?.checkpoint != null) {\n        events.push({\n          ...base,\n          seq,\n          method: \"checkpoints\",\n          params: { namespace: ns, timestamp, data: meta.checkpoint },\n        });\n      }\n      events.push({\n        ...base,\n        seq: meta?.checkpoint != null ? seq + 1 : seq,\n        method: \"values\",\n        params: { namespace: ns, timestamp, data: payload },\n      });\n      return events;\n    }\n\n    case \"updates\": {\n      const data = convertUpdatesPayload(payload);\n      return [\n        {\n          ...base,\n          seq,\n          method: \"updates\",\n          params: {\n            namespace: ns,\n            timestamp,\n            // Surface the completed node at the top level of `params` so\n            // transformers (notably `LifecycleTransformer`) can attribute\n            // a finished task to its child namespace without re-parsing\n            // the payload.  The same value is retained inside `data` for\n            // downstream consumers that inspect the event body.\n            ...(typeof data.node === \"string\" ? { node: data.node } : {}),\n            data,\n          },\n        },\n      ];\n    }\n\n    case \"custom\": {\n      const data =\n        typeof payload === \"object\" &&\n        payload !== null &&\n        !Array.isArray(payload) &&\n        \"name\" in payload\n          ? payload\n          : { payload };\n      return [\n        {\n          ...base,\n          seq,\n          method: \"custom\",\n          params: { namespace: ns, timestamp, data },\n        },\n      ];\n    }\n\n    case \"tasks\":\n      return [\n        {\n          ...base,\n          seq,\n          method: \"tasks\",\n          params: { namespace: ns, timestamp, data: payload },\n        },\n      ];\n\n    default:\n      return [];\n  }\n}\n\n/**\n * Normalises a raw tools-mode payload into a typed {@link ToolsEventData}\n * discriminated union, mapping internal lifecycle events (`on_tool_start`,\n * `on_tool_end`, etc.) to their protocol counterparts.\n *\n * @param payload - The raw payload from a `\"tools\"` stream chunk.\n * @returns A {@link ToolsEventData} object with the appropriate `event`\n *   discriminant and associated fields.\n */\nfunction convertToolsPayload(payload: unknown): ToolsEventData {\n  if (typeof payload !== \"object\" || payload === null) {\n    return {\n      event: \"tool-error\",\n      tool_call_id: \"\",\n      message: \"Unexpected tools payload shape\",\n    };\n  }\n\n  const p = payload as Record<string, unknown>;\n  const tool_call_id = String(p.toolCallId ?? \"\");\n\n  switch (p.event) {\n    case \"on_tool_start\":\n      return {\n        event: \"tool-started\",\n        tool_call_id,\n        tool_name: String(p.name ?? \"unknown\"),\n        input: p.input,\n      };\n\n    case \"on_tool_event\": {\n      const delta =\n        typeof p.data === \"string\" ? p.data : JSON.stringify(p.data ?? \"\");\n      return {\n        event: \"tool-output-delta\",\n        tool_call_id,\n        delta,\n      };\n    }\n\n    case \"on_tool_end\":\n      return {\n        event: \"tool-finished\",\n        tool_call_id,\n        output: p.output,\n      };\n\n    case \"on_tool_error\": {\n      const err = p.error;\n      const errMessage =\n        typeof err === \"object\" &&\n        err !== null &&\n        \"message\" in err &&\n        typeof (err as { message: unknown }).message === \"string\"\n          ? (err as { message: string }).message\n          : String(err ?? \"unknown error\");\n      return {\n        event: \"tool-error\",\n        tool_call_id,\n        message: errMessage,\n      };\n    }\n\n    default:\n      return {\n        event: \"tool-error\",\n        tool_call_id: \"\",\n        message: `Unknown tool event: ${String(p.event)}`,\n      };\n  }\n}\n\n/**\n * Extracts the first `{node: delta}` entry from an updates-mode payload and\n * reshapes it into an {@link UpdatesEventData} with explicit `node` and\n * `values` fields.  Non-object payloads are coerced to `{ values: {} }`.\n *\n * @param payload - The raw payload from an `\"updates\"` stream chunk,\n *   expected to be a `Record<string, unknown>` keyed by node name.\n * @returns An {@link UpdatesEventData} containing the extracted node name\n *   and its associated delta values.\n */\nfunction convertUpdatesPayload(payload: unknown): UpdatesEventData {\n  if (typeof payload !== \"object\" || payload === null) {\n    return { values: {} };\n  }\n\n  const entries = Object.entries(payload as Record<string, unknown>);\n  if (entries.length === 0) {\n    return { values: {} };\n  }\n\n  const [node, values] = entries[0];\n  return {\n    node,\n    values: (typeof values === \"object\" && values !== null\n      ? values\n      : { value: values }) as Record<string, unknown>,\n  };\n}\n"],"mappings":"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"}

package/dist/stream/index.cjs

@@ -0,0 +1,11 @@
+require("./stream-channel.cjs");
+require("./convert.cjs");
+require("./mux.cjs");
+require("./transformers/lifecycle.cjs");
+require("./transformers/messages.cjs");
+require("./transformers/subgraphs.cjs");
+require("./transformers/values.cjs");
+require("./transformers/index.cjs");
+require("./types.cjs");
+require("./run-stream.cjs");
+require("@langchain/core/language_models/stream");

package/dist/stream/index.d.cts

@@ -0,0 +1,12 @@
+import { AgentStatus, ChatModelStream as ChatModelStream$1, InferExtensions, InterruptPayload, LifecycleCause, LifecycleData, MessagesEventData, Namespace, NativeStreamTransformer, ProtocolEvent, StreamEmitter, StreamTransformer, ToolCallStatus, ToolCallStream, ToolsEventData, UpdatesEventData, UsageInfo, isNativeTransformer } from "./types.cjs";
+import { StreamChannel } from "./stream-channel.cjs";
+import { ConvertToProtocolEventOptions, STREAM_EVENTS_V3_MODES, convertToProtocolEvent } from "./convert.cjs";
+import { REJECT_VALUES, RESOLVE_VALUES, StreamHandle, StreamMux, SubgraphDiscovery } from "./mux.cjs";
+import { LifecycleEntry, LifecycleTransformerOptions } from "./transformers/types.cjs";
+import { LifecycleProjection, createLifecycleTransformer, filterLifecycleEntries } from "./transformers/lifecycle.cjs";
+import { createMessagesTransformer } from "./transformers/messages.cjs";
+import { SubgraphDiscoveryProjection, SubgraphDiscoveryTransformerOptions, createSubgraphDiscoveryTransformer, filterSubgraphHandles } from "./transformers/subgraphs.cjs";
+import { createValuesTransformer } from "./transformers/values.cjs";
+import { CreateGraphRunStreamOptions, GraphRunStream, SET_LIFECYCLE_ITERABLE, SET_MESSAGES_ITERABLE, SET_VALUES_LOG, SubgraphRunStream, createGraphRunStream } from "./run-stream.cjs";
+import { ChatModelStream as ChatModelStreamImpl } from "@langchain/core/language_models/stream";
+export { ChatModelStreamImpl };

package/dist/stream/index.d.ts

@@ -0,0 +1,12 @@
+import { AgentStatus, ChatModelStream as ChatModelStream$1, InferExtensions, InterruptPayload, LifecycleCause, LifecycleData, MessagesEventData, Namespace, NativeStreamTransformer, ProtocolEvent, StreamEmitter, StreamTransformer, ToolCallStatus, ToolCallStream, ToolsEventData, UpdatesEventData, UsageInfo, isNativeTransformer } from "./types.js";
+import { StreamChannel } from "./stream-channel.js";
+import { ConvertToProtocolEventOptions, STREAM_EVENTS_V3_MODES, convertToProtocolEvent } from "./convert.js";
+import { REJECT_VALUES, RESOLVE_VALUES, StreamHandle, StreamMux, SubgraphDiscovery } from "./mux.js";
+import { LifecycleEntry, LifecycleTransformerOptions } from "./transformers/types.js";
+import { LifecycleProjection, createLifecycleTransformer, filterLifecycleEntries } from "./transformers/lifecycle.js";
+import { createMessagesTransformer } from "./transformers/messages.js";
+import { SubgraphDiscoveryProjection, SubgraphDiscoveryTransformerOptions, createSubgraphDiscoveryTransformer, filterSubgraphHandles } from "./transformers/subgraphs.js";
+import { createValuesTransformer } from "./transformers/values.js";
+import { CreateGraphRunStreamOptions, GraphRunStream, SET_LIFECYCLE_ITERABLE, SET_MESSAGES_ITERABLE, SET_VALUES_LOG, SubgraphRunStream, createGraphRunStream } from "./run-stream.js";
+import { ChatModelStream as ChatModelStreamImpl } from "@langchain/core/language_models/stream";
+export { ChatModelStreamImpl };

package/dist/stream/index.js

@@ -0,0 +1,12 @@
+import "./stream-channel.js";
+import "./convert.js";
+import "./mux.js";
+import "./transformers/lifecycle.js";
+import "./transformers/messages.js";
+import "./transformers/subgraphs.js";
+import "./transformers/values.js";
+import "./transformers/index.js";
+import "./types.js";
+import "./run-stream.js";
+import { ChatModelStream as ChatModelStreamImpl } from "@langchain/core/language_models/stream";
+export { ChatModelStreamImpl };

package/dist/stream/mux.cjs

@@ -0,0 +1,350 @@
+const require_constants = require("../constants.cjs");
+const require_stream_channel = require("./stream-channel.cjs");
+const require_convert = require("./convert.cjs");
+//#region src/stream/mux.ts
+/**
+* Structural `PromiseLike<T>` predicate — true for thenables including
+* native promises, user-constructed `{ then }` objects, and helper
+* wrappers. Used by {@link StreamMux.wireChannels} to detect final-value
+* projections distinctly from streaming `StreamChannel` values.
+*/
+function isPromiseLike(value) {
+	return value != null && (typeof value === "object" || typeof value === "function") && typeof value.then === "function";
+}
+/**
+* Symbol key used by {@link StreamMux} to resolve the values promise on a
+* stream handle. Using a symbol keeps this off the public autocomplete surface.
+*/
+const RESOLVE_VALUES = Symbol("resolveValues");
+/**
+* Symbol key used by {@link StreamMux} to reject the values promise on a
+* stream handle. Using a symbol keeps this off the public autocomplete surface.
+*/
+const REJECT_VALUES = Symbol("rejectValues");
+/**
+* Central event dispatcher that routes {@link ProtocolEvent}s through a
+* pipeline of {@link StreamTransformer}s, manages namespace discovery for
+* subgraph streams, and exposes async iteration over filtered event
+* sequences.
+*
+* One `StreamMux` instance exists per top-level
+* `streamEvents(..., { version: "v3" })` invocation.
+*/
+var StreamMux = class {
+	/** @internal All protocol events in arrival order (after reducer pipeline). */
+	_events = require_stream_channel.StreamChannel.local();
+	/** @internal New-namespace discovery notifications. */
+	_discoveries = require_stream_channel.StreamChannel.local();
+	/** Monotonic counter for auto-forwarded channel events. */
+	#nextEmitSeq = 0;
+	/** Whether the mux has been closed or failed. */
+	#closed = false;
+	/** The error passed to {@link fail}, if any. */
+	#error;
+	/** Whether the run was interrupted. */
+	#interrupted = false;
+	/**
+	* Namespace of the event currently being processed by
+	* {@link push}.  Read by {@link StreamChannel} wiring callbacks so
+	* auto-forwarded events inherit the triggering event's namespace.
+	*/
+	#currentNamespace = [];
+	#transformers = [];
+	#channels = [];
+	#streamMap = /* @__PURE__ */ new Map();
+	#latestValues = /* @__PURE__ */ new Map();
+	#interrupts = [];
+	/**
+	* Final-value projection keys tracked for remote surfacing. Populated
+	* by {@link wireChannels} when a transformer's projection contains a
+	* `PromiseLike` value. Each entry is flushed as a `custom:<name>`
+	* protocol event during {@link close} so that remote clients can
+	* observe final-value transformers via `thread.extensions.<name>`.
+	*/
+	#finalValues = [];
+	/**
+	* Associates a pre-existing stream handle with a namespace so that
+	* {@link close} can resolve its values promise later.
+	*
+	* @param path - The namespace path to register.
+	* @param stream - The run stream handle for that namespace.
+	*/
+	register(path, stream) {
+		this.#streamMap.set(nsKey(path), stream);
+	}
+	/**
+	* Registers a transformer and replays all buffered events through it so
+	* it catches up with events already processed by the mux.  When the event
+	* log is empty (typical at construction time) the replay is a no-op.
+	*
+	* The transformer must already have been initialised (i.e. `init()` called
+	* and any projection wired).  The sequence is:
+	*
+	*   1. Snapshot the current event log length.
+	*   2. Append the transformer so future {@link push} calls reach it.
+	*   3. Replay events `[0, snapshot)` through `process()`.
+	*   4. If the mux is already closed, call `finalize()` (or `fail()`)
+	*      immediately so the transformer's log/channel terminates cleanly.
+	*
+	* @param transformer - An already-initialised transformer to register.
+	*/
+	addTransformer(transformer) {
+		const snapshot = this._events.size;
+		this.#transformers.push(transformer);
+		if (transformer.onRegister) transformer.onRegister({ push: (ns, event) => this.push(ns, event) });
+		for (let i = 0; i < snapshot; i += 1) transformer.process(this._events.get(i));
+		if (this.#closed) if (this.#error !== void 0) transformer.fail?.(this.#error);
+		else transformer.finalize?.();
+	}
+	/**
+	* Scans a transformer projection for streaming and final-value primitives.
+	* Remote stream channels are wired to auto-forward to the protocol event
+	* stream; local stream channels are tracked for lifecycle only.
+	*
+	* Two projection shapes are recognised:
+	*
+	*   - {@link StreamChannel} values — named channels forward each `push()`
+	*     immediately as a protocol event on the channel's declared
+	*     `channelName` method. Unnamed channels remain in-process-only.
+	*
+	*   - `PromiseLike<unknown>` values — tracked as final-value
+	*     projections and flushed on {@link close} as a single
+	*     `custom:<key>` event, where `<key>` is the projection key.
+	*     This mirrors the in-process `await run.extensions.<key>`
+	*     ergonomics on remote clients via
+	*     `await thread.extensions.<key>`.
+	*
+	* Plain values that are neither are ignored — they remain in-process-only,
+	* matching prior behaviour.
+	*
+	* @param projection - The object returned by `transformer.init()`.
+	*/
+	wireChannels(projection) {
+		for (const [key, value] of Object.entries(projection)) {
+			if (require_stream_channel.isStreamChannel(value)) {
+				this.#channels.push(value);
+				if (typeof value.channelName !== "string") continue;
+				value._wire((item) => {
+					this._events.push({
+						type: "event",
+						seq: this.#nextEmitSeq++,
+						method: value.channelName,
+						params: {
+							namespace: this.#currentNamespace,
+							timestamp: Date.now(),
+							data: item
+						}
+					});
+				});
+				continue;
+			}
+			if (isPromiseLike(value)) this.#finalValues.push({
+				name: key,
+				promise: Promise.resolve(value)
+			});
+		}
+	}
+	/**
+	* Distributes an event through the transformer pipeline, then appends it to
+	* the main event log.
+	*
+	* Subgraph discovery (materializing a {@link StreamHandle} for each
+	* newly observed top-level namespace) is handled by the
+	* {@link createSubgraphDiscoveryTransformer} when installed, not here.
+	*
+	* @param ns - The namespace path that produced the event.
+	* @param event - The protocol event to process and store.
+	*/
+	push(ns, event) {
+		if (event.method === "values") this.#latestValues.set(nsKey(ns), event.params.data);
+		const outerNamespace = this.#currentNamespace;
+		this.#currentNamespace = ns;
+		let keep = true;
+		for (const transformer of this.#transformers) if (!transformer.process(event)) keep = false;
+		this.#currentNamespace = outerNamespace;
+		if (keep) this._events.push({
+			...event,
+			seq: this.#nextEmitSeq++
+		});
+	}
+	/**
+	* Gracefully ends the stream: resolves values promises on all known
+	* streams, finalizes every transformer, auto-closes streaming
+	* channels, flushes any final-value projections as `custom:<name>`
+	* events, and closes both event logs.
+	*
+	* When final-value projections are present, `_events.close()` is
+	* deferred until every tracked projection promise has settled so
+	* remote consumers observe the flushed values before their event
+	* stream ends. Callers do not need to await — `close()` returns
+	* synchronously and any downstream consumer iterating
+	* {@link _events} naturally waits for the final events.
+	*/
+	close() {
+		this.#closed = true;
+		for (const [key, values] of this.#latestValues.entries()) {
+			const ns = key ? key.split("\0") : [];
+			this.#streamMap.get(nsKey(ns))?.[RESOLVE_VALUES](values);
+		}
+		const finalizePromises = [];
+		for (const transformer of this.#transformers) {
+			const result = transformer.finalize?.();
+			if (result != null && typeof result.then === "function") finalizePromises.push(result);
+		}
+		for (const channel of this.#channels) channel._close();
+		const finalValues = this.#finalValues;
+		if (finalValues.length === 0 && finalizePromises.length === 0) {
+			this._events.close();
+			this._discoveries.close();
+		} else Promise.allSettled([...finalizePromises, ...finalValues.map(async ({ name, promise }) => {
+			try {
+				const resolved = await promise;
+				if (!this._events.done) this._events.push({
+					type: "event",
+					seq: this.#nextEmitSeq++,
+					method: "custom",
+					params: {
+						namespace: [],
+						timestamp: Date.now(),
+						data: {
+							name,
+							payload: resolved
+						}
+					}
+				});
+			} catch {}
+		})]).then(() => {
+			this._events.close();
+			this._discoveries.close();
+		});
+		for (const stream of this.#streamMap.values()) stream[RESOLVE_VALUES](void 0);
+	}
+	/**
+	* Propagates a failure to all transformers, channels, event logs, and
+	* stream handles.
+	*
+	* @param err - The error that caused the run to fail.
+	*/
+	fail(err) {
+		this.#closed = true;
+		this.#error = err;
+		for (const transformer of this.#transformers) transformer.fail?.(err);
+		for (const channel of this.#channels) channel._fail(err);
+		this._events.fail(err);
+		this._discoveries.fail(err);
+		for (const stream of this.#streamMap.values()) stream[REJECT_VALUES](err);
+	}
+	/**
+	* Records that the run was interrupted, appending the supplied payloads
+	* for later retrieval.
+	*
+	* @param interrupts - The interrupt payloads to store.
+	*/
+	markInterrupted(interrupts) {
+		this.#interrupted = true;
+		this.#interrupts.push(...interrupts);
+	}
+	/**
+	* Whether the run ended due to an interrupt.
+	*
+	* @returns `true` if {@link markInterrupted} was called.
+	*/
+	get interrupted() {
+		return this.#interrupted;
+	}
+	/**
+	* All interrupt payloads collected during the run.
+	*
+	* @returns A readonly view of the accumulated interrupt payloads.
+	*/
+	get interrupts() {
+		return this.#interrupts;
+	}
+	/**
+	* Returns an async iterator that yields only events whose namespace
+	* starts with {@link path}.
+	*
+	* @param path - Namespace prefix to filter on.
+	* @param startAt - Zero-based index into the event log to begin from.
+	* @returns An async iterator over matching {@link ProtocolEvent}s.
+	*/
+	subscribeEvents(path, startAt = 0) {
+		const base = this._events.iterate(startAt);
+		return { async next() {
+			while (true) {
+				const result = await base.next();
+				if (result.done) return result;
+				if (hasPrefix(result.value.params.namespace, path)) return result;
+			}
+		} };
+	}
+};
+/**
+* Background consumer that drains a raw `graph.stream()` source into a
+* {@link StreamMux}.  Converts each chunk to a {@link ProtocolEvent} and
+* pushes it; calls {@link StreamMux.close} on normal completion or
+* {@link StreamMux.fail} on error.
+*
+* @param source - The async iterable of raw stream chunks from the engine.
+* @param mux - The mux instance to feed.
+* @returns A promise that resolves when the source is fully consumed.
+*/
+async function pump(source, mux) {
+	let seq = 0;
+	try {
+		for await (const chunk of source) {
+			const [ns, mode, payload, meta] = chunk;
+			if (mode === "values" && require_constants.isInterrupted(payload)) {
+				const interrupts = payload[require_constants.INTERRUPT];
+				mux.markInterrupted(interrupts.map((i) => ({
+					interruptId: i.id ?? "",
+					payload: i.value
+				})));
+			}
+			const events = require_convert.convertToProtocolEvent({
+				namespace: ns,
+				mode,
+				payload,
+				seq,
+				meta
+			});
+			seq += events.length;
+			for (const event of events) mux.push(ns, event);
+		}
+	} catch (err) {
+		mux.fail(err);
+		return;
+	}
+	mux.close();
+}
+/**
+* Serialises a {@link Namespace} array into a single string key using the
+* null byte (`\x00`) as separator, suitable for `Map`/`Set` lookups.
+*
+* @param ns - The namespace segments to join.
+* @returns A null-byte-joined string key.
+*/
+function nsKey(ns) {
+	return ns.join("\0");
+}
+/**
+* Tests whether {@link ns} starts with every segment in {@link prefix}.
+*
+* @param ns - The full namespace to check.
+* @param prefix - The prefix to match against.
+* @returns `true` if `ns` begins with `prefix` segment-by-segment.
+*/
+function hasPrefix(ns, prefix) {
+	if (prefix.length > ns.length) return false;
+	for (let i = 0; i < prefix.length; i += 1) if (ns[i] !== prefix[i]) return false;
+	return true;
+}
+//#endregion
+exports.REJECT_VALUES = REJECT_VALUES;
+exports.RESOLVE_VALUES = RESOLVE_VALUES;
+exports.StreamMux = StreamMux;
+exports.hasPrefix = hasPrefix;
+exports.nsKey = nsKey;
+exports.pump = pump;
+
+//# sourceMappingURL=mux.cjs.map