@langchain/langgraph-sdk 1.8.10 → 1.9.0

package/dist/stream/message-metadata-tracker.js

@@ -0,0 +1,165 @@
+import { StreamStore } from "./store.js";
+import { namespaceKey } from "./namespace.js";
+//#region src/stream/message-metadata-tracker.ts
+/**
+* Per-message checkpoint metadata projection.
+*
+* # What this module is
+*
+* The protocol emits a `checkpoints` event immediately *before* its
+* companion `values` event for the same superstep:
+*
+*   1. `checkpoints` — `{ id, parent_id?, step?, source? }`
+*   2. `values`      — `{ messages, ... }`  (same namespace)
+*
+* Both events carry the same `seq` ordering but live on different
+* channels, so the controller can't atomically observe them. This
+* tracker bridges the gap by buffering each `checkpoints` envelope
+* keyed on its namespace, then consuming it when the matching values
+* payload arrives. Once paired, the consumer (typically the
+* controller) writes a {@link MessageMetadata} record under each
+* message id.
+*
+* # Why fork / edit flows need this
+*
+* Surfacing `parentCheckpointId` per-message lets UI flows like
+* "edit a message and re-run" call
+* `submit(input, { forkFrom: { checkpointId } })` without making the
+* caller juggle thread state. Each message remembers the checkpoint
+* it was first observed at, so a "fork from this message" UI can read
+* `useMessageMetadata(stream, msg.id)` directly.
+*
+* # Lifecycle
+*
+*   - `bufferCheckpoint(ns, data)` — store the envelope until the
+*     companion values event arrives.
+*   - `consumeCheckpoint(ns)`      — read-and-clear the envelope when
+*     the values event lands. Returning `undefined` signals "no
+*     metadata to attach" — older snapshots without a paired
+*     checkpoint are still applied to the store, just without
+*     `parentCheckpointId`.
+*   - `recordMessages(msgs, meta)` — write metadata for the supplied
+*     message ids if it differs from what's already stored.
+*   - `reset()`                    — clear everything (called on
+*     thread rebind / dispose).
+*
+* The buffer is read-and-cleared on consumption so a values event that
+* arrives without a fresh checkpoint envelope doesn't reuse stale
+* metadata from a previous superstep.
+*/
+/**
+* Frozen empty map used as the store's initial value. Keeping the
+* reference stable avoids spurious `setSnapshot` notifications on
+* `reset()` for consumers that haven't observed any metadata yet.
+*/
+const EMPTY_METADATA_MAP = /* @__PURE__ */ new Map();
+/**
+* Tracks checkpoint-derived metadata for messages.
+*
+* Owns one {@link StreamStore} mapping `messageId → MessageMetadata`
+* plus a per-namespace buffer of pending checkpoint envelopes. The
+* controller wires it up via three call sites:
+*
+*   1. `controller.#onRootEvent("checkpoints")`
+*      → `bufferCheckpoint(namespace, data)`
+*   2. `controller.#onRootEvent("values")`
+*      → `consumeCheckpoint(namespace)` then
+*      `recordMessages(values.messages, { parentCheckpointId })`
+*   3. `controller.#teardownThread`
+*      → `reset()`
+*
+* @see useMessageMetadata - The framework hook that reads from
+*   {@link MessageMetadataTracker.store}.
+*/
+var MessageMetadataTracker = class {
+	/** Observable map of messageId → metadata for framework consumers. */
+	store = new StreamStore(EMPTY_METADATA_MAP);
+	/**
+	* Pending checkpoint envelopes awaiting their companion values
+	* event. Keyed by `namespaceKey(namespace)` so a deeply-nested
+	* checkpoint at one namespace doesn't collide with a root-level
+	* checkpoint emitted in the same tick.
+	*/
+	#pendingCheckpointByNamespace = /* @__PURE__ */ new Map();
+	/**
+	* Drop all buffered checkpoints and reset the metadata map to the
+	* shared empty instance. Called on thread rebind / dispose so a new
+	* thread's metadata can't bleed into the old one.
+	*/
+	reset() {
+		this.#pendingCheckpointByNamespace.clear();
+		this.store.setState(() => EMPTY_METADATA_MAP);
+	}
+	/**
+	* Buffer a `checkpoints` event for later pairing with its values
+	* companion.
+	*
+	* Defensive against missing / malformed payloads:
+	*
+	*   - `data == null`     → no-op (some upstream nodes elide the
+	*     payload entirely; we keep the previous buffered envelope so
+	*     the next consume call still wins).
+	*   - `id` not a string  → no-op.
+	*   - `parent_id` not a string → omitted from the envelope.
+	*
+	* @param namespace - Event namespace (used as the buffer key).
+	* @param data      - Raw checkpoints payload.
+	*/
+	bufferCheckpoint(namespace, data) {
+		if (data == null || typeof data.id !== "string") return;
+		const envelope = { id: data.id };
+		if (typeof data.parent_id === "string") envelope.parent_id = data.parent_id;
+		this.#pendingCheckpointByNamespace.set(namespaceKey(namespace), envelope);
+	}
+	/**
+	* Read-and-clear the buffered checkpoint envelope for `namespace`.
+	*
+	* Always pairs with a single {@link bufferCheckpoint} call: a values
+	* event without a matching buffered checkpoint returns `undefined`
+	* (meaning "no metadata to attach"), and the next checkpoint event
+	* starts fresh rather than reusing stale data.
+	*
+	* @param namespace - Event namespace to consume.
+	* @returns The buffered envelope, or `undefined` when none was buffered.
+	*/
+	consumeCheckpoint(namespace) {
+		const key = namespaceKey(namespace);
+		const checkpoint = this.#pendingCheckpointByNamespace.get(key);
+		if (checkpoint != null) this.#pendingCheckpointByNamespace.delete(key);
+		return checkpoint;
+	}
+	/**
+	* Record metadata for a list of messages.
+	*
+	* Skips messages whose existing entry already matches `metadata`;
+	* those without an `id` (or with a non-string id) are silently
+	* ignored — there's nothing to key the metadata on. The store is
+	* only updated when at least one entry actually changed, so
+	* reapplying the same values snapshot is cheap.
+	*
+	* @param messages - Messages from the latest values payload.
+	* @param metadata - Metadata to attach (currently just
+	*   `parentCheckpointId`).
+	*/
+	recordMessages(messages, metadata) {
+		const current = this.store.getSnapshot();
+		let changed = false;
+		const next = new Map(current);
+		for (const msg of messages) {
+			const id = msg?.id;
+			if (typeof id !== "string" || id.length === 0) continue;
+			const prev = next.get(id);
+			if (prev != null && prev.parentCheckpointId === metadata.parentCheckpointId) continue;
+			next.set(id, {
+				...prev,
+				...metadata
+			});
+			changed = true;
+		}
+		if (changed) this.store.setState(() => next);
+	}
+};
+//#endregion
+export { MessageMetadataTracker };
+
+//# sourceMappingURL=message-metadata-tracker.js.map

package/dist/stream/message-metadata-tracker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"message-metadata-tracker.js","names":["#pendingCheckpointByNamespace"],"sources":["../../src/stream/message-metadata-tracker.ts"],"sourcesContent":["/**\n * Per-message checkpoint metadata projection.\n *\n * # What this module is\n *\n * The protocol emits a `checkpoints` event immediately *before* its\n * companion `values` event for the same superstep:\n *\n *   1. `checkpoints` — `{ id, parent_id?, step?, source? }`\n *   2. `values`      — `{ messages, ... }`  (same namespace)\n *\n * Both events carry the same `seq` ordering but live on different\n * channels, so the controller can't atomically observe them. This\n * tracker bridges the gap by buffering each `checkpoints` envelope\n * keyed on its namespace, then consuming it when the matching values\n * payload arrives. Once paired, the consumer (typically the\n * controller) writes a {@link MessageMetadata} record under each\n * message id.\n *\n * # Why fork / edit flows need this\n *\n * Surfacing `parentCheckpointId` per-message lets UI flows like\n * \"edit a message and re-run\" call\n * `submit(input, { forkFrom: { checkpointId } })` without making the\n * caller juggle thread state. Each message remembers the checkpoint\n * it was first observed at, so a \"fork from this message\" UI can read\n * `useMessageMetadata(stream, msg.id)` directly.\n *\n * # Lifecycle\n *\n *   - `bufferCheckpoint(ns, data)` — store the envelope until the\n *     companion values event arrives.\n *   - `consumeCheckpoint(ns)`      — read-and-clear the envelope when\n *     the values event lands. Returning `undefined` signals \"no\n *     metadata to attach\" — older snapshots without a paired\n *     checkpoint are still applied to the store, just without\n *     `parentCheckpointId`.\n *   - `recordMessages(msgs, meta)` — write metadata for the supplied\n *     message ids if it differs from what's already stored.\n *   - `reset()`                    — clear everything (called on\n *     thread rebind / dispose).\n *\n * The buffer is read-and-cleared on consumption so a values event that\n * arrives without a fresh checkpoint envelope doesn't reuse stale\n * metadata from a previous superstep.\n */\nimport { StreamStore } from \"./store.js\";\nimport { namespaceKey } from \"./namespace.js\";\n\n/**\n * Metadata tracked per message id. Surfaced to applications via\n * `useMessageMetadata(stream, messageId)`.\n */\nexport interface MessageMetadata {\n  /**\n   * Checkpoint id the message's *parent* was at when this message was\n   * observed. Drives fork / edit flows\n   * (`submit(input, { forkFrom: { checkpointId } })`).\n   *\n   * `undefined` when the message was observed without a paired\n   * checkpoint envelope (e.g. before checkpoints rolled out, or when\n   * the caller stripped them upstream).\n   */\n  readonly parentCheckpointId: string | undefined;\n}\n\n/**\n * Read-only map exposed via {@link MessageMetadataTracker.store}.\n */\nexport type MessageMetadataMap = ReadonlyMap<string, MessageMetadata>;\n\n/**\n * Lightweight envelope mirroring the on-wire `checkpoints` event.\n *\n * The protocol payload may include additional fields (`step`,\n * `source`, etc.) — we only carry what the per-message metadata\n * actually needs.\n */\nexport interface CheckpointEnvelope {\n  /** Checkpoint id this superstep wrote. */\n  readonly id: string;\n  /**\n   * Parent checkpoint id, when present. Becomes\n   * {@link MessageMetadata.parentCheckpointId} on the next values event.\n   */\n  readonly parent_id?: string;\n}\n\n/**\n * Frozen empty map used as the store's initial value. Keeping the\n * reference stable avoids spurious `setSnapshot` notifications on\n * `reset()` for consumers that haven't observed any metadata yet.\n */\nconst EMPTY_METADATA_MAP: MessageMetadataMap = new Map();\n\n/**\n * Tracks checkpoint-derived metadata for messages.\n *\n * Owns one {@link StreamStore} mapping `messageId → MessageMetadata`\n * plus a per-namespace buffer of pending checkpoint envelopes. The\n * controller wires it up via three call sites:\n *\n *   1. `controller.#onRootEvent(\"checkpoints\")`\n *      → `bufferCheckpoint(namespace, data)`\n *   2. `controller.#onRootEvent(\"values\")`\n *      → `consumeCheckpoint(namespace)` then\n *      `recordMessages(values.messages, { parentCheckpointId })`\n *   3. `controller.#teardownThread`\n *      → `reset()`\n *\n * @see useMessageMetadata - The framework hook that reads from\n *   {@link MessageMetadataTracker.store}.\n */\nexport class MessageMetadataTracker {\n  /** Observable map of messageId → metadata for framework consumers. */\n  readonly store = new StreamStore<MessageMetadataMap>(EMPTY_METADATA_MAP);\n\n  /**\n   * Pending checkpoint envelopes awaiting their companion values\n   * event. Keyed by `namespaceKey(namespace)` so a deeply-nested\n   * checkpoint at one namespace doesn't collide with a root-level\n   * checkpoint emitted in the same tick.\n   */\n  readonly #pendingCheckpointByNamespace = new Map<\n    string,\n    CheckpointEnvelope\n  >();\n\n  /**\n   * Drop all buffered checkpoints and reset the metadata map to the\n   * shared empty instance. Called on thread rebind / dispose so a new\n   * thread's metadata can't bleed into the old one.\n   */\n  reset(): void {\n    this.#pendingCheckpointByNamespace.clear();\n    this.store.setState(() => EMPTY_METADATA_MAP);\n  }\n\n  /**\n   * Buffer a `checkpoints` event for later pairing with its values\n   * companion.\n   *\n   * Defensive against missing / malformed payloads:\n   *\n   *   - `data == null`     → no-op (some upstream nodes elide the\n   *     payload entirely; we keep the previous buffered envelope so\n   *     the next consume call still wins).\n   *   - `id` not a string  → no-op.\n   *   - `parent_id` not a string → omitted from the envelope.\n   *\n   * @param namespace - Event namespace (used as the buffer key).\n   * @param data      - Raw checkpoints payload.\n   */\n  bufferCheckpoint(\n    namespace: readonly string[],\n    data: { id?: unknown; parent_id?: unknown } | null\n  ): void {\n    if (data == null || typeof data.id !== \"string\") return;\n    const envelope: CheckpointEnvelope = { id: data.id };\n    if (typeof data.parent_id === \"string\") {\n      (envelope as { parent_id?: string }).parent_id = data.parent_id;\n    }\n    this.#pendingCheckpointByNamespace.set(namespaceKey(namespace), envelope);\n  }\n\n  /**\n   * Read-and-clear the buffered checkpoint envelope for `namespace`.\n   *\n   * Always pairs with a single {@link bufferCheckpoint} call: a values\n   * event without a matching buffered checkpoint returns `undefined`\n   * (meaning \"no metadata to attach\"), and the next checkpoint event\n   * starts fresh rather than reusing stale data.\n   *\n   * @param namespace - Event namespace to consume.\n   * @returns The buffered envelope, or `undefined` when none was buffered.\n   */\n  consumeCheckpoint(\n    namespace: readonly string[]\n  ): CheckpointEnvelope | undefined {\n    const key = namespaceKey(namespace);\n    const checkpoint = this.#pendingCheckpointByNamespace.get(key);\n    if (checkpoint != null) this.#pendingCheckpointByNamespace.delete(key);\n    return checkpoint;\n  }\n\n  /**\n   * Record metadata for a list of messages.\n   *\n   * Skips messages whose existing entry already matches `metadata`;\n   * those without an `id` (or with a non-string id) are silently\n   * ignored — there's nothing to key the metadata on. The store is\n   * only updated when at least one entry actually changed, so\n   * reapplying the same values snapshot is cheap.\n   *\n   * @param messages - Messages from the latest values payload.\n   * @param metadata - Metadata to attach (currently just\n   *   `parentCheckpointId`).\n   */\n  recordMessages(\n    messages: Array<{ id?: string }>,\n    metadata: MessageMetadata\n  ): void {\n    const current = this.store.getSnapshot();\n    let changed = false;\n    const next = new Map(current);\n    for (const msg of messages) {\n      const id = msg?.id;\n      if (typeof id !== \"string\" || id.length === 0) continue;\n      const prev = next.get(id);\n      if (\n        prev != null &&\n        prev.parentCheckpointId === metadata.parentCheckpointId\n      ) {\n        continue;\n      }\n      next.set(id, { ...prev, ...metadata });\n      changed = true;\n    }\n    if (changed) this.store.setState(() => next);\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6FA,MAAM,qCAAyC,IAAI,KAAK;;;;;;;;;;;;;;;;;;;AAoBxD,IAAa,yBAAb,MAAoC;;CAElC,QAAiB,IAAI,YAAgC,mBAAmB;;;;;;;CAQxE,gDAAyC,IAAI,KAG1C;;;;;;CAOH,QAAc;AACZ,QAAA,6BAAmC,OAAO;AAC1C,OAAK,MAAM,eAAe,mBAAmB;;;;;;;;;;;;;;;;;CAkB/C,iBACE,WACA,MACM;AACN,MAAI,QAAQ,QAAQ,OAAO,KAAK,OAAO,SAAU;EACjD,MAAM,WAA+B,EAAE,IAAI,KAAK,IAAI;AACpD,MAAI,OAAO,KAAK,cAAc,SAC3B,UAAoC,YAAY,KAAK;AAExD,QAAA,6BAAmC,IAAI,aAAa,UAAU,EAAE,SAAS;;;;;;;;;;;;;CAc3E,kBACE,WACgC;EAChC,MAAM,MAAM,aAAa,UAAU;EACnC,MAAM,aAAa,MAAA,6BAAmC,IAAI,IAAI;AAC9D,MAAI,cAAc,KAAM,OAAA,6BAAmC,OAAO,IAAI;AACtE,SAAO;;;;;;;;;;;;;;;CAgBT,eACE,UACA,UACM;EACN,MAAM,UAAU,KAAK,MAAM,aAAa;EACxC,IAAI,UAAU;EACd,MAAM,OAAO,IAAI,IAAI,QAAQ;AAC7B,OAAK,MAAM,OAAO,UAAU;GAC1B,MAAM,KAAK,KAAK;AAChB,OAAI,OAAO,OAAO,YAAY,GAAG,WAAW,EAAG;GAC/C,MAAM,OAAO,KAAK,IAAI,GAAG;AACzB,OACE,QAAQ,QACR,KAAK,uBAAuB,SAAS,mBAErC;AAEF,QAAK,IAAI,IAAI;IAAE,GAAG;IAAM,GAAG;IAAU,CAAC;AACtC,aAAU;;AAEZ,MAAI,QAAS,MAAK,MAAM,eAAe,KAAK"}

package/dist/stream/message-reconciliation.cjs

@@ -0,0 +1,118 @@
+//#region src/stream/message-reconciliation.ts
+/**
+* Merge an authoritative `values.messages` snapshot with the current streamed
+* message projection.
+*
+* Values remain authoritative for ordering and removals. Streamed messages
+* remain authoritative for in-flight content until the server echoes them in a
+* values snapshot, and stream-only messages are preserved until they either
+* appear in values or are known to have been removed.
+*/
+function reconcileMessagesFromValues({ valueMessages, currentMessages, currentIndexById, previousValueMessageIds, streamedMessageIds, preferValuesMessage }) {
+	const valueMessageIds = /* @__PURE__ */ new Set();
+	const merged = [];
+	for (const valuesMessage of valueMessages) {
+		const id = normalizedMessageId(valuesMessage);
+		if (id == null) {
+			merged.push(valuesMessage);
+			continue;
+		}
+		valueMessageIds.add(id);
+		const streamIdx = currentIndexById.get(id);
+		const streamedMessage = streamIdx != null && (streamedMessageIds == null || streamedMessageIds.has(id)) ? currentMessages[streamIdx] : void 0;
+		if (streamedMessage != null && preferValuesMessage?.(valuesMessage, streamedMessage) !== true) merged.push(streamedMessage);
+		else merged.push(valuesMessage);
+	}
+	for (const existing of currentMessages) {
+		const id = normalizedMessageId(existing);
+		if (id == null) continue;
+		if (valueMessageIds.has(id)) continue;
+		if (previousValueMessageIds.has(id)) continue;
+		if (streamedMessageIds != null && !streamedMessageIds.has(id)) continue;
+		merged.push(existing);
+	}
+	return {
+		messages: messagesEqualList(currentMessages, merged) ? currentMessages : merged,
+		valueMessageIds
+	};
+}
+/**
+* Build a position index for keyed messages.
+*/
+function buildMessageIndex(messages) {
+	const index = /* @__PURE__ */ new Map();
+	messages.forEach((message, idx) => {
+		const id = normalizedMessageId(message);
+		if (id != null) index.set(id, idx);
+	});
+	return index;
+}
+/**
+* Decide whether a values message carries tool-call data missing from the
+* streamed message.
+*/
+function shouldPreferValuesMessageForToolCalls(valuesMessage, streamedMessage) {
+	const valuesToolCalls = getMessageToolCalls(valuesMessage);
+	if (valuesToolCalls.length === 0) return false;
+	const streamedToolCalls = getMessageToolCalls(streamedMessage);
+	if (streamedToolCalls.length < valuesToolCalls.length) return true;
+	const streamedIds = new Set(streamedToolCalls.map((toolCall) => toolCall.id).filter((id) => typeof id === "string" && id.length > 0));
+	return valuesToolCalls.some((toolCall) => {
+		return typeof toolCall.id === "string" && !streamedIds.has(toolCall.id);
+	});
+}
+function messagesEqualList(previous, next) {
+	if (previous === next) return true;
+	if (previous.length !== next.length) return false;
+	for (let i = 0; i < previous.length; i += 1) if (!messagesEqual(previous[i], next[i])) return false;
+	return true;
+}
+function messagesEqual(previous, next) {
+	if (previous === next) return true;
+	if (previous == null || next == null) return false;
+	const previousRecord = previous;
+	const nextRecord = next;
+	const previousType = typeof previous.getType === "function" ? previous.getType() : previousRecord.type;
+	const nextType = typeof next.getType === "function" ? next.getType() : nextRecord.type;
+	return previous.id === next.id && previousType === nextType && jsonishEqual(previous.content, next.content) && previousRecord.tool_call_id === nextRecord.tool_call_id && previousRecord.status === nextRecord.status && jsonishEqual(previousRecord.additional_kwargs, nextRecord.additional_kwargs) && jsonishEqual(previousRecord.response_metadata, nextRecord.response_metadata) && jsonishEqual(previousRecord.tool_calls, nextRecord.tool_calls) && jsonishEqual(previousRecord.tool_call_chunks, nextRecord.tool_call_chunks) && jsonishEqual(previousRecord.usage_metadata, nextRecord.usage_metadata);
+}
+function normalizedMessageId(message) {
+	return typeof message.id === "string" && message.id.length > 0 ? message.id : void 0;
+}
+function getMessageToolCalls(message) {
+	const raw = message.tool_calls;
+	if (!Array.isArray(raw)) return [];
+	return raw.filter((toolCall) => toolCall != null && typeof toolCall === "object");
+}
+function jsonishEqual(previous, next) {
+	return jsonishEqualAtDepth(previous, next, 0);
+}
+function jsonishEqualAtDepth(previous, next, depth) {
+	if (Object.is(previous, next)) return true;
+	if (previous == null || next == null) return false;
+	if (typeof previous !== "object" || typeof next !== "object") return false;
+	if (depth >= 4) return false;
+	if (Array.isArray(previous) || Array.isArray(next)) {
+		if (!Array.isArray(previous) || !Array.isArray(next)) return false;
+		if (previous.length !== next.length) return false;
+		for (let i = 0; i < previous.length; i += 1) if (!jsonishEqualAtDepth(previous[i], next[i], depth + 1)) return false;
+		return true;
+	}
+	const previousRecord = previous;
+	const nextRecord = next;
+	const previousKeys = Object.keys(previousRecord).filter((key) => typeof previousRecord[key] !== "function");
+	const nextKeys = Object.keys(nextRecord).filter((key) => typeof nextRecord[key] !== "function");
+	if (previousKeys.length !== nextKeys.length) return false;
+	for (const key of previousKeys) {
+		if (!Object.prototype.hasOwnProperty.call(nextRecord, key)) return false;
+		if (!jsonishEqualAtDepth(previousRecord[key], nextRecord[key], depth + 1)) return false;
+	}
+	return true;
+}
+//#endregion
+exports.buildMessageIndex = buildMessageIndex;
+exports.messagesEqual = messagesEqual;
+exports.reconcileMessagesFromValues = reconcileMessagesFromValues;
+exports.shouldPreferValuesMessageForToolCalls = shouldPreferValuesMessageForToolCalls;
+
+//# sourceMappingURL=message-reconciliation.cjs.map

package/dist/stream/message-reconciliation.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"message-reconciliation.cjs","names":[],"sources":["../../src/stream/message-reconciliation.ts"],"sourcesContent":["import type { BaseMessage } from \"@langchain/core/messages\";\n\nexport interface ReconcileMessagesFromValuesOptions {\n  /**\n   * Messages from the authoritative `values.messages` snapshot.\n   */\n  readonly valueMessages: readonly BaseMessage[];\n  /**\n   * Current message projection, including stream-assembled in-flight messages.\n   */\n  readonly currentMessages: readonly BaseMessage[];\n  /**\n   * Index from message id to current message position.\n   */\n  readonly currentIndexById: ReadonlyMap<string, number>;\n  /**\n   * Ids observed in the most recent previous `values.messages` snapshot.\n   * If one of these ids is missing from the next snapshot, it is treated as\n   * an explicit server-side removal.\n   */\n  readonly previousValueMessageIds: ReadonlySet<string>;\n  /**\n   * Optional stream-id filter. When supplied, only these current ids are\n   * eligible to override the values snapshot. When omitted, any id present in\n   * `currentIndexById` is eligible, preserving the root controller's historic\n   * behavior.\n   */\n  readonly streamedMessageIds?: ReadonlySet<string>;\n  /**\n   * Allows callers to keep a values message even when a streamed message with\n   * the same id exists. Used by the root controller when the values message\n   * carries finalized tool-call data missing from the streamed message.\n   */\n  readonly preferValuesMessage?: (\n    valuesMessage: BaseMessage,\n    streamedMessage: BaseMessage\n  ) => boolean;\n}\n\nexport interface ReconciledMessages {\n  readonly messages: readonly BaseMessage[];\n  readonly valueMessageIds: Set<string>;\n}\n\n/**\n * Merge an authoritative `values.messages` snapshot with the current streamed\n * message projection.\n *\n * Values remain authoritative for ordering and removals. Streamed messages\n * remain authoritative for in-flight content until the server echoes them in a\n * values snapshot, and stream-only messages are preserved until they either\n * appear in values or are known to have been removed.\n */\nexport function reconcileMessagesFromValues({\n  valueMessages,\n  currentMessages,\n  currentIndexById,\n  previousValueMessageIds,\n  streamedMessageIds,\n  preferValuesMessage,\n}: ReconcileMessagesFromValuesOptions): ReconciledMessages {\n  const valueMessageIds = new Set<string>();\n  const merged: BaseMessage[] = [];\n\n  for (const valuesMessage of valueMessages) {\n    const id = normalizedMessageId(valuesMessage);\n    if (id == null) {\n      merged.push(valuesMessage);\n      continue;\n    }\n\n    valueMessageIds.add(id);\n    const streamIdx = currentIndexById.get(id);\n    const canUseStreamed =\n      streamIdx != null &&\n      (streamedMessageIds == null || streamedMessageIds.has(id));\n    const streamedMessage = canUseStreamed\n      ? currentMessages[streamIdx]\n      : undefined;\n\n    if (\n      streamedMessage != null &&\n      preferValuesMessage?.(valuesMessage, streamedMessage) !== true\n    ) {\n      merged.push(streamedMessage);\n    } else {\n      merged.push(valuesMessage);\n    }\n  }\n\n  for (const existing of currentMessages) {\n    const id = normalizedMessageId(existing);\n    if (id == null) continue;\n    if (valueMessageIds.has(id)) continue;\n    if (previousValueMessageIds.has(id)) continue;\n    if (streamedMessageIds != null && !streamedMessageIds.has(id)) continue;\n    merged.push(existing);\n  }\n\n  return {\n    messages: messagesEqualList(currentMessages, merged)\n      ? currentMessages\n      : merged,\n    valueMessageIds,\n  };\n}\n\n/**\n * Build a position index for keyed messages.\n */\nexport function buildMessageIndex(\n  messages: readonly BaseMessage[]\n): Map<string, number> {\n  const index = new Map<string, number>();\n  messages.forEach((message, idx) => {\n    const id = normalizedMessageId(message);\n    if (id != null) index.set(id, idx);\n  });\n  return index;\n}\n\n/**\n * Decide whether a values message carries tool-call data missing from the\n * streamed message.\n */\nexport function shouldPreferValuesMessageForToolCalls(\n  valuesMessage: BaseMessage,\n  streamedMessage: BaseMessage\n): boolean {\n  const valuesToolCalls = getMessageToolCalls(valuesMessage);\n  if (valuesToolCalls.length === 0) return false;\n\n  const streamedToolCalls = getMessageToolCalls(streamedMessage);\n  if (streamedToolCalls.length < valuesToolCalls.length) return true;\n\n  const streamedIds = new Set(\n    streamedToolCalls\n      .map((toolCall) => toolCall.id)\n      .filter((id): id is string => typeof id === \"string\" && id.length > 0)\n  );\n  return valuesToolCalls.some((toolCall) => {\n    return typeof toolCall.id === \"string\" && !streamedIds.has(toolCall.id);\n  });\n}\n\nexport function 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\nexport function messagesEqual(\n  previous: BaseMessage | undefined,\n  next: BaseMessage | undefined\n): boolean {\n  if (previous === next) return true;\n  if (previous == null || next == null) return false;\n  const previousRecord = previous as unknown as Record<string, unknown>;\n  const nextRecord = next as unknown as Record<string, unknown>;\n  const previousType =\n    typeof previous.getType === \"function\"\n      ? previous.getType()\n      : previousRecord.type;\n  const nextType =\n    typeof next.getType === \"function\" ? next.getType() : nextRecord.type;\n\n  return (\n    previous.id === next.id &&\n    previousType === nextType &&\n    jsonishEqual(previous.content, next.content) &&\n    previousRecord.tool_call_id === nextRecord.tool_call_id &&\n    previousRecord.status === nextRecord.status &&\n    jsonishEqual(\n      previousRecord.additional_kwargs,\n      nextRecord.additional_kwargs\n    ) &&\n    jsonishEqual(\n      previousRecord.response_metadata,\n      nextRecord.response_metadata\n    ) &&\n    jsonishEqual(previousRecord.tool_calls, nextRecord.tool_calls) &&\n    jsonishEqual(\n      previousRecord.tool_call_chunks,\n      nextRecord.tool_call_chunks\n    ) &&\n    jsonishEqual(previousRecord.usage_metadata, nextRecord.usage_metadata)\n  );\n}\n\nfunction normalizedMessageId(message: BaseMessage): string | undefined {\n  return typeof message.id === \"string\" && message.id.length > 0\n    ? message.id\n    : undefined;\n}\n\nfunction getMessageToolCalls(\n  message: BaseMessage\n): Array<{ id?: string; name?: string }> {\n  const raw = (message as unknown as { tool_calls?: unknown }).tool_calls;\n  if (!Array.isArray(raw)) return [];\n  return raw.filter(\n    (toolCall): toolCall is { id?: string; name?: string } =>\n      toolCall != null && typeof toolCall === \"object\"\n  );\n}\n\nfunction jsonishEqual(previous: unknown, next: unknown): boolean {\n  return jsonishEqualAtDepth(previous, next, 0);\n}\n\nfunction jsonishEqualAtDepth(\n  previous: unknown,\n  next: unknown,\n  depth: number\n): boolean {\n  if (Object.is(previous, next)) return true;\n  if (previous == null || next == null) return false;\n  if (typeof previous !== \"object\" || typeof next !== \"object\") return false;\n  if (depth >= 4) return false;\n\n  if (Array.isArray(previous) || Array.isArray(next)) {\n    if (!Array.isArray(previous) || !Array.isArray(next)) return false;\n    if (previous.length !== next.length) return false;\n    for (let i = 0; i < previous.length; i += 1) {\n      if (!jsonishEqualAtDepth(previous[i], next[i], depth + 1)) return false;\n    }\n    return true;\n  }\n\n  const previousRecord = previous as Record<string, unknown>;\n  const nextRecord = next as Record<string, unknown>;\n  const previousKeys = Object.keys(previousRecord).filter(\n    (key) => typeof previousRecord[key] !== \"function\"\n  );\n  const nextKeys = Object.keys(nextRecord).filter(\n    (key) => typeof nextRecord[key] !== \"function\"\n  );\n  if (previousKeys.length !== nextKeys.length) return false;\n\n  for (const key of previousKeys) {\n    if (!Object.prototype.hasOwnProperty.call(nextRecord, key)) return false;\n    if (!jsonishEqualAtDepth(previousRecord[key], nextRecord[key], depth + 1)) {\n      return false;\n    }\n  }\n  return true;\n}\n"],"mappings":";;;;;;;;;;AAqDA,SAAgB,4BAA4B,EAC1C,eACA,iBACA,kBACA,yBACA,oBACA,uBACyD;CACzD,MAAM,kCAAkB,IAAI,KAAa;CACzC,MAAM,SAAwB,EAAE;AAEhC,MAAK,MAAM,iBAAiB,eAAe;EACzC,MAAM,KAAK,oBAAoB,cAAc;AAC7C,MAAI,MAAM,MAAM;AACd,UAAO,KAAK,cAAc;AAC1B;;AAGF,kBAAgB,IAAI,GAAG;EACvB,MAAM,YAAY,iBAAiB,IAAI,GAAG;EAI1C,MAAM,kBAFJ,aAAa,SACZ,sBAAsB,QAAQ,mBAAmB,IAAI,GAAG,IAEvD,gBAAgB,aAChB,KAAA;AAEJ,MACE,mBAAmB,QACnB,sBAAsB,eAAe,gBAAgB,KAAK,KAE1D,QAAO,KAAK,gBAAgB;MAE5B,QAAO,KAAK,cAAc;;AAI9B,MAAK,MAAM,YAAY,iBAAiB;EACtC,MAAM,KAAK,oBAAoB,SAAS;AACxC,MAAI,MAAM,KAAM;AAChB,MAAI,gBAAgB,IAAI,GAAG,CAAE;AAC7B,MAAI,wBAAwB,IAAI,GAAG,CAAE;AACrC,MAAI,sBAAsB,QAAQ,CAAC,mBAAmB,IAAI,GAAG,CAAE;AAC/D,SAAO,KAAK,SAAS;;AAGvB,QAAO;EACL,UAAU,kBAAkB,iBAAiB,OAAO,GAChD,kBACA;EACJ;EACD;;;;;AAMH,SAAgB,kBACd,UACqB;CACrB,MAAM,wBAAQ,IAAI,KAAqB;AACvC,UAAS,SAAS,SAAS,QAAQ;EACjC,MAAM,KAAK,oBAAoB,QAAQ;AACvC,MAAI,MAAM,KAAM,OAAM,IAAI,IAAI,IAAI;GAClC;AACF,QAAO;;;;;;AAOT,SAAgB,sCACd,eACA,iBACS;CACT,MAAM,kBAAkB,oBAAoB,cAAc;AAC1D,KAAI,gBAAgB,WAAW,EAAG,QAAO;CAEzC,MAAM,oBAAoB,oBAAoB,gBAAgB;AAC9D,KAAI,kBAAkB,SAAS,gBAAgB,OAAQ,QAAO;CAE9D,MAAM,cAAc,IAAI,IACtB,kBACG,KAAK,aAAa,SAAS,GAAG,CAC9B,QAAQ,OAAqB,OAAO,OAAO,YAAY,GAAG,SAAS,EAAE,CACzE;AACD,QAAO,gBAAgB,MAAM,aAAa;AACxC,SAAO,OAAO,SAAS,OAAO,YAAY,CAAC,YAAY,IAAI,SAAS,GAAG;GACvE;;AAGJ,SAAgB,kBACd,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,CAAC,cAAc,SAAS,IAAI,KAAK,GAAG,CAAE,QAAO;AAEnD,QAAO;;AAGT,SAAgB,cACd,UACA,MACS;AACT,KAAI,aAAa,KAAM,QAAO;AAC9B,KAAI,YAAY,QAAQ,QAAQ,KAAM,QAAO;CAC7C,MAAM,iBAAiB;CACvB,MAAM,aAAa;CACnB,MAAM,eACJ,OAAO,SAAS,YAAY,aACxB,SAAS,SAAS,GAClB,eAAe;CACrB,MAAM,WACJ,OAAO,KAAK,YAAY,aAAa,KAAK,SAAS,GAAG,WAAW;AAEnE,QACE,SAAS,OAAO,KAAK,MACrB,iBAAiB,YACjB,aAAa,SAAS,SAAS,KAAK,QAAQ,IAC5C,eAAe,iBAAiB,WAAW,gBAC3C,eAAe,WAAW,WAAW,UACrC,aACE,eAAe,mBACf,WAAW,kBACZ,IACD,aACE,eAAe,mBACf,WAAW,kBACZ,IACD,aAAa,eAAe,YAAY,WAAW,WAAW,IAC9D,aACE,eAAe,kBACf,WAAW,iBACZ,IACD,aAAa,eAAe,gBAAgB,WAAW,eAAe;;AAI1E,SAAS,oBAAoB,SAA0C;AACrE,QAAO,OAAO,QAAQ,OAAO,YAAY,QAAQ,GAAG,SAAS,IACzD,QAAQ,KACR,KAAA;;AAGN,SAAS,oBACP,SACuC;CACvC,MAAM,MAAO,QAAgD;AAC7D,KAAI,CAAC,MAAM,QAAQ,IAAI,CAAE,QAAO,EAAE;AAClC,QAAO,IAAI,QACR,aACC,YAAY,QAAQ,OAAO,aAAa,SAC3C;;AAGH,SAAS,aAAa,UAAmB,MAAwB;AAC/D,QAAO,oBAAoB,UAAU,MAAM,EAAE;;AAG/C,SAAS,oBACP,UACA,MACA,OACS;AACT,KAAI,OAAO,GAAG,UAAU,KAAK,CAAE,QAAO;AACtC,KAAI,YAAY,QAAQ,QAAQ,KAAM,QAAO;AAC7C,KAAI,OAAO,aAAa,YAAY,OAAO,SAAS,SAAU,QAAO;AACrE,KAAI,SAAS,EAAG,QAAO;AAEvB,KAAI,MAAM,QAAQ,SAAS,IAAI,MAAM,QAAQ,KAAK,EAAE;AAClD,MAAI,CAAC,MAAM,QAAQ,SAAS,IAAI,CAAC,MAAM,QAAQ,KAAK,CAAE,QAAO;AAC7D,MAAI,SAAS,WAAW,KAAK,OAAQ,QAAO;AAC5C,OAAK,IAAI,IAAI,GAAG,IAAI,SAAS,QAAQ,KAAK,EACxC,KAAI,CAAC,oBAAoB,SAAS,IAAI,KAAK,IAAI,QAAQ,EAAE,CAAE,QAAO;AAEpE,SAAO;;CAGT,MAAM,iBAAiB;CACvB,MAAM,aAAa;CACnB,MAAM,eAAe,OAAO,KAAK,eAAe,CAAC,QAC9C,QAAQ,OAAO,eAAe,SAAS,WACzC;CACD,MAAM,WAAW,OAAO,KAAK,WAAW,CAAC,QACtC,QAAQ,OAAO,WAAW,SAAS,WACrC;AACD,KAAI,aAAa,WAAW,SAAS,OAAQ,QAAO;AAEpD,MAAK,MAAM,OAAO,cAAc;AAC9B,MAAI,CAAC,OAAO,UAAU,eAAe,KAAK,YAAY,IAAI,CAAE,QAAO;AACnE,MAAI,CAAC,oBAAoB,eAAe,MAAM,WAAW,MAAM,QAAQ,EAAE,CACvE,QAAO;;AAGX,QAAO"}

package/dist/stream/message-reconciliation.js

@@ -0,0 +1,115 @@
+//#region src/stream/message-reconciliation.ts
+/**
+* Merge an authoritative `values.messages` snapshot with the current streamed
+* message projection.
+*
+* Values remain authoritative for ordering and removals. Streamed messages
+* remain authoritative for in-flight content until the server echoes them in a
+* values snapshot, and stream-only messages are preserved until they either
+* appear in values or are known to have been removed.
+*/
+function reconcileMessagesFromValues({ valueMessages, currentMessages, currentIndexById, previousValueMessageIds, streamedMessageIds, preferValuesMessage }) {
+	const valueMessageIds = /* @__PURE__ */ new Set();
+	const merged = [];
+	for (const valuesMessage of valueMessages) {
+		const id = normalizedMessageId(valuesMessage);
+		if (id == null) {
+			merged.push(valuesMessage);
+			continue;
+		}
+		valueMessageIds.add(id);
+		const streamIdx = currentIndexById.get(id);
+		const streamedMessage = streamIdx != null && (streamedMessageIds == null || streamedMessageIds.has(id)) ? currentMessages[streamIdx] : void 0;
+		if (streamedMessage != null && preferValuesMessage?.(valuesMessage, streamedMessage) !== true) merged.push(streamedMessage);
+		else merged.push(valuesMessage);
+	}
+	for (const existing of currentMessages) {
+		const id = normalizedMessageId(existing);
+		if (id == null) continue;
+		if (valueMessageIds.has(id)) continue;
+		if (previousValueMessageIds.has(id)) continue;
+		if (streamedMessageIds != null && !streamedMessageIds.has(id)) continue;
+		merged.push(existing);
+	}
+	return {
+		messages: messagesEqualList(currentMessages, merged) ? currentMessages : merged,
+		valueMessageIds
+	};
+}
+/**
+* Build a position index for keyed messages.
+*/
+function buildMessageIndex(messages) {
+	const index = /* @__PURE__ */ new Map();
+	messages.forEach((message, idx) => {
+		const id = normalizedMessageId(message);
+		if (id != null) index.set(id, idx);
+	});
+	return index;
+}
+/**
+* Decide whether a values message carries tool-call data missing from the
+* streamed message.
+*/
+function shouldPreferValuesMessageForToolCalls(valuesMessage, streamedMessage) {
+	const valuesToolCalls = getMessageToolCalls(valuesMessage);
+	if (valuesToolCalls.length === 0) return false;
+	const streamedToolCalls = getMessageToolCalls(streamedMessage);
+	if (streamedToolCalls.length < valuesToolCalls.length) return true;
+	const streamedIds = new Set(streamedToolCalls.map((toolCall) => toolCall.id).filter((id) => typeof id === "string" && id.length > 0));
+	return valuesToolCalls.some((toolCall) => {
+		return typeof toolCall.id === "string" && !streamedIds.has(toolCall.id);
+	});
+}
+function messagesEqualList(previous, next) {
+	if (previous === next) return true;
+	if (previous.length !== next.length) return false;
+	for (let i = 0; i < previous.length; i += 1) if (!messagesEqual(previous[i], next[i])) return false;
+	return true;
+}
+function messagesEqual(previous, next) {
+	if (previous === next) return true;
+	if (previous == null || next == null) return false;
+	const previousRecord = previous;
+	const nextRecord = next;
+	const previousType = typeof previous.getType === "function" ? previous.getType() : previousRecord.type;
+	const nextType = typeof next.getType === "function" ? next.getType() : nextRecord.type;
+	return previous.id === next.id && previousType === nextType && jsonishEqual(previous.content, next.content) && previousRecord.tool_call_id === nextRecord.tool_call_id && previousRecord.status === nextRecord.status && jsonishEqual(previousRecord.additional_kwargs, nextRecord.additional_kwargs) && jsonishEqual(previousRecord.response_metadata, nextRecord.response_metadata) && jsonishEqual(previousRecord.tool_calls, nextRecord.tool_calls) && jsonishEqual(previousRecord.tool_call_chunks, nextRecord.tool_call_chunks) && jsonishEqual(previousRecord.usage_metadata, nextRecord.usage_metadata);
+}
+function normalizedMessageId(message) {
+	return typeof message.id === "string" && message.id.length > 0 ? message.id : void 0;
+}
+function getMessageToolCalls(message) {
+	const raw = message.tool_calls;
+	if (!Array.isArray(raw)) return [];
+	return raw.filter((toolCall) => toolCall != null && typeof toolCall === "object");
+}
+function jsonishEqual(previous, next) {
+	return jsonishEqualAtDepth(previous, next, 0);
+}
+function jsonishEqualAtDepth(previous, next, depth) {
+	if (Object.is(previous, next)) return true;
+	if (previous == null || next == null) return false;
+	if (typeof previous !== "object" || typeof next !== "object") return false;
+	if (depth >= 4) return false;
+	if (Array.isArray(previous) || Array.isArray(next)) {
+		if (!Array.isArray(previous) || !Array.isArray(next)) return false;
+		if (previous.length !== next.length) return false;
+		for (let i = 0; i < previous.length; i += 1) if (!jsonishEqualAtDepth(previous[i], next[i], depth + 1)) return false;
+		return true;
+	}
+	const previousRecord = previous;
+	const nextRecord = next;
+	const previousKeys = Object.keys(previousRecord).filter((key) => typeof previousRecord[key] !== "function");
+	const nextKeys = Object.keys(nextRecord).filter((key) => typeof nextRecord[key] !== "function");
+	if (previousKeys.length !== nextKeys.length) return false;
+	for (const key of previousKeys) {
+		if (!Object.prototype.hasOwnProperty.call(nextRecord, key)) return false;
+		if (!jsonishEqualAtDepth(previousRecord[key], nextRecord[key], depth + 1)) return false;
+	}
+	return true;
+}
+//#endregion
+export { buildMessageIndex, messagesEqual, reconcileMessagesFromValues, shouldPreferValuesMessageForToolCalls };
+
+//# sourceMappingURL=message-reconciliation.js.map

package/dist/stream/message-reconciliation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"message-reconciliation.js","names":[],"sources":["../../src/stream/message-reconciliation.ts"],"sourcesContent":["import type { BaseMessage } from \"@langchain/core/messages\";\n\nexport interface ReconcileMessagesFromValuesOptions {\n  /**\n   * Messages from the authoritative `values.messages` snapshot.\n   */\n  readonly valueMessages: readonly BaseMessage[];\n  /**\n   * Current message projection, including stream-assembled in-flight messages.\n   */\n  readonly currentMessages: readonly BaseMessage[];\n  /**\n   * Index from message id to current message position.\n   */\n  readonly currentIndexById: ReadonlyMap<string, number>;\n  /**\n   * Ids observed in the most recent previous `values.messages` snapshot.\n   * If one of these ids is missing from the next snapshot, it is treated as\n   * an explicit server-side removal.\n   */\n  readonly previousValueMessageIds: ReadonlySet<string>;\n  /**\n   * Optional stream-id filter. When supplied, only these current ids are\n   * eligible to override the values snapshot. When omitted, any id present in\n   * `currentIndexById` is eligible, preserving the root controller's historic\n   * behavior.\n   */\n  readonly streamedMessageIds?: ReadonlySet<string>;\n  /**\n   * Allows callers to keep a values message even when a streamed message with\n   * the same id exists. Used by the root controller when the values message\n   * carries finalized tool-call data missing from the streamed message.\n   */\n  readonly preferValuesMessage?: (\n    valuesMessage: BaseMessage,\n    streamedMessage: BaseMessage\n  ) => boolean;\n}\n\nexport interface ReconciledMessages {\n  readonly messages: readonly BaseMessage[];\n  readonly valueMessageIds: Set<string>;\n}\n\n/**\n * Merge an authoritative `values.messages` snapshot with the current streamed\n * message projection.\n *\n * Values remain authoritative for ordering and removals. Streamed messages\n * remain authoritative for in-flight content until the server echoes them in a\n * values snapshot, and stream-only messages are preserved until they either\n * appear in values or are known to have been removed.\n */\nexport function reconcileMessagesFromValues({\n  valueMessages,\n  currentMessages,\n  currentIndexById,\n  previousValueMessageIds,\n  streamedMessageIds,\n  preferValuesMessage,\n}: ReconcileMessagesFromValuesOptions): ReconciledMessages {\n  const valueMessageIds = new Set<string>();\n  const merged: BaseMessage[] = [];\n\n  for (const valuesMessage of valueMessages) {\n    const id = normalizedMessageId(valuesMessage);\n    if (id == null) {\n      merged.push(valuesMessage);\n      continue;\n    }\n\n    valueMessageIds.add(id);\n    const streamIdx = currentIndexById.get(id);\n    const canUseStreamed =\n      streamIdx != null &&\n      (streamedMessageIds == null || streamedMessageIds.has(id));\n    const streamedMessage = canUseStreamed\n      ? currentMessages[streamIdx]\n      : undefined;\n\n    if (\n      streamedMessage != null &&\n      preferValuesMessage?.(valuesMessage, streamedMessage) !== true\n    ) {\n      merged.push(streamedMessage);\n    } else {\n      merged.push(valuesMessage);\n    }\n  }\n\n  for (const existing of currentMessages) {\n    const id = normalizedMessageId(existing);\n    if (id == null) continue;\n    if (valueMessageIds.has(id)) continue;\n    if (previousValueMessageIds.has(id)) continue;\n    if (streamedMessageIds != null && !streamedMessageIds.has(id)) continue;\n    merged.push(existing);\n  }\n\n  return {\n    messages: messagesEqualList(currentMessages, merged)\n      ? currentMessages\n      : merged,\n    valueMessageIds,\n  };\n}\n\n/**\n * Build a position index for keyed messages.\n */\nexport function buildMessageIndex(\n  messages: readonly BaseMessage[]\n): Map<string, number> {\n  const index = new Map<string, number>();\n  messages.forEach((message, idx) => {\n    const id = normalizedMessageId(message);\n    if (id != null) index.set(id, idx);\n  });\n  return index;\n}\n\n/**\n * Decide whether a values message carries tool-call data missing from the\n * streamed message.\n */\nexport function shouldPreferValuesMessageForToolCalls(\n  valuesMessage: BaseMessage,\n  streamedMessage: BaseMessage\n): boolean {\n  const valuesToolCalls = getMessageToolCalls(valuesMessage);\n  if (valuesToolCalls.length === 0) return false;\n\n  const streamedToolCalls = getMessageToolCalls(streamedMessage);\n  if (streamedToolCalls.length < valuesToolCalls.length) return true;\n\n  const streamedIds = new Set(\n    streamedToolCalls\n      .map((toolCall) => toolCall.id)\n      .filter((id): id is string => typeof id === \"string\" && id.length > 0)\n  );\n  return valuesToolCalls.some((toolCall) => {\n    return typeof toolCall.id === \"string\" && !streamedIds.has(toolCall.id);\n  });\n}\n\nexport function 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\nexport function messagesEqual(\n  previous: BaseMessage | undefined,\n  next: BaseMessage | undefined\n): boolean {\n  if (previous === next) return true;\n  if (previous == null || next == null) return false;\n  const previousRecord = previous as unknown as Record<string, unknown>;\n  const nextRecord = next as unknown as Record<string, unknown>;\n  const previousType =\n    typeof previous.getType === \"function\"\n      ? previous.getType()\n      : previousRecord.type;\n  const nextType =\n    typeof next.getType === \"function\" ? next.getType() : nextRecord.type;\n\n  return (\n    previous.id === next.id &&\n    previousType === nextType &&\n    jsonishEqual(previous.content, next.content) &&\n    previousRecord.tool_call_id === nextRecord.tool_call_id &&\n    previousRecord.status === nextRecord.status &&\n    jsonishEqual(\n      previousRecord.additional_kwargs,\n      nextRecord.additional_kwargs\n    ) &&\n    jsonishEqual(\n      previousRecord.response_metadata,\n      nextRecord.response_metadata\n    ) &&\n    jsonishEqual(previousRecord.tool_calls, nextRecord.tool_calls) &&\n    jsonishEqual(\n      previousRecord.tool_call_chunks,\n      nextRecord.tool_call_chunks\n    ) &&\n    jsonishEqual(previousRecord.usage_metadata, nextRecord.usage_metadata)\n  );\n}\n\nfunction normalizedMessageId(message: BaseMessage): string | undefined {\n  return typeof message.id === \"string\" && message.id.length > 0\n    ? message.id\n    : undefined;\n}\n\nfunction getMessageToolCalls(\n  message: BaseMessage\n): Array<{ id?: string; name?: string }> {\n  const raw = (message as unknown as { tool_calls?: unknown }).tool_calls;\n  if (!Array.isArray(raw)) return [];\n  return raw.filter(\n    (toolCall): toolCall is { id?: string; name?: string } =>\n      toolCall != null && typeof toolCall === \"object\"\n  );\n}\n\nfunction jsonishEqual(previous: unknown, next: unknown): boolean {\n  return jsonishEqualAtDepth(previous, next, 0);\n}\n\nfunction jsonishEqualAtDepth(\n  previous: unknown,\n  next: unknown,\n  depth: number\n): boolean {\n  if (Object.is(previous, next)) return true;\n  if (previous == null || next == null) return false;\n  if (typeof previous !== \"object\" || typeof next !== \"object\") return false;\n  if (depth >= 4) return false;\n\n  if (Array.isArray(previous) || Array.isArray(next)) {\n    if (!Array.isArray(previous) || !Array.isArray(next)) return false;\n    if (previous.length !== next.length) return false;\n    for (let i = 0; i < previous.length; i += 1) {\n      if (!jsonishEqualAtDepth(previous[i], next[i], depth + 1)) return false;\n    }\n    return true;\n  }\n\n  const previousRecord = previous as Record<string, unknown>;\n  const nextRecord = next as Record<string, unknown>;\n  const previousKeys = Object.keys(previousRecord).filter(\n    (key) => typeof previousRecord[key] !== \"function\"\n  );\n  const nextKeys = Object.keys(nextRecord).filter(\n    (key) => typeof nextRecord[key] !== \"function\"\n  );\n  if (previousKeys.length !== nextKeys.length) return false;\n\n  for (const key of previousKeys) {\n    if (!Object.prototype.hasOwnProperty.call(nextRecord, key)) return false;\n    if (!jsonishEqualAtDepth(previousRecord[key], nextRecord[key], depth + 1)) {\n      return false;\n    }\n  }\n  return true;\n}\n"],"mappings":"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"}

package/dist/stream/namespace.cjs

@@ -0,0 +1,54 @@
+require("./constants.cjs");
+//#region src/stream/namespace.ts
+/**
+* Stable string key for a protocol namespace tuple.
+*/
+function namespaceKey(namespace) {
+	return namespace.join("\0");
+}
+/**
+* True when an event is scoped to the root namespace.
+*/
+function isRootNamespace(namespace) {
+	return namespace.length === 0;
+}
+/**
+* True when a namespace segment points at a tool execution namespace.
+*/
+function isToolNamespaceSegment(segment) {
+	return segment.startsWith("tools:");
+}
+/**
+* True when a namespace segment points at a legacy task/subagent namespace.
+*/
+function isTaskNamespaceSegment(segment) {
+	return segment.startsWith("task:");
+}
+/**
+* True when a namespace belongs to tool/subagent-internal work.
+*/
+function isInternalWorkNamespace(namespace) {
+	return namespace.some((segment) => isTaskNamespaceSegment(segment) || isToolNamespaceSegment(segment));
+}
+/**
+* True when a namespace includes the legacy task/subagent convention.
+*/
+function isLegacySubagentNamespace(namespace) {
+	return namespace.some(isTaskNamespaceSegment);
+}
+/**
+* True when the namespace itself is a concrete tool execution namespace.
+*/
+function isConcreteToolNamespace(namespace) {
+	const last = namespace.at(-1);
+	return last != null && isToolNamespaceSegment(last);
+}
+//#endregion
+exports.isConcreteToolNamespace = isConcreteToolNamespace;
+exports.isInternalWorkNamespace = isInternalWorkNamespace;
+exports.isLegacySubagentNamespace = isLegacySubagentNamespace;
+exports.isRootNamespace = isRootNamespace;
+exports.isToolNamespaceSegment = isToolNamespaceSegment;
+exports.namespaceKey = namespaceKey;
+
+//# sourceMappingURL=namespace.cjs.map

package/dist/stream/namespace.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"namespace.cjs","names":[],"sources":["../../src/stream/namespace.ts"],"sourcesContent":["import { NAMESPACE_SEPARATOR } from \"./constants.js\";\n\n/**\n * Stable string key for a protocol namespace tuple.\n */\nexport function namespaceKey(namespace: readonly string[]): string {\n  return namespace.join(NAMESPACE_SEPARATOR);\n}\n\n/**\n * True when an event is scoped to the root namespace.\n */\nexport function isRootNamespace(namespace: readonly string[]): boolean {\n  return namespace.length === 0;\n}\n\n/**\n * True when a namespace segment points at a tool execution namespace.\n */\nexport function isToolNamespaceSegment(segment: string): boolean {\n  return segment.startsWith(\"tools:\");\n}\n\n/**\n * True when a namespace segment points at a legacy task/subagent namespace.\n */\nexport function isTaskNamespaceSegment(segment: string): boolean {\n  return segment.startsWith(\"task:\");\n}\n\n/**\n * True when a namespace belongs to tool/subagent-internal work.\n */\nexport function isInternalWorkNamespace(namespace: readonly string[]): boolean {\n  return namespace.some(\n    (segment) =>\n      isTaskNamespaceSegment(segment) || isToolNamespaceSegment(segment)\n  );\n}\n\n/**\n * True when a namespace includes the legacy task/subagent convention.\n */\nexport function isLegacySubagentNamespace(\n  namespace: readonly string[]\n): boolean {\n  return namespace.some(isTaskNamespaceSegment);\n}\n\n/**\n * True when the namespace itself is a concrete tool execution namespace.\n */\nexport function isConcreteToolNamespace(namespace: readonly string[]): boolean {\n  const last = namespace.at(-1);\n  return last != null && isToolNamespaceSegment(last);\n}\n"],"mappings":";;;;;AAKA,SAAgB,aAAa,WAAsC;AACjE,QAAO,UAAU,KAAA,KAAyB;;;;;AAM5C,SAAgB,gBAAgB,WAAuC;AACrE,QAAO,UAAU,WAAW;;;;;AAM9B,SAAgB,uBAAuB,SAA0B;AAC/D,QAAO,QAAQ,WAAW,SAAS;;;;;AAMrC,SAAgB,uBAAuB,SAA0B;AAC/D,QAAO,QAAQ,WAAW,QAAQ;;;;;AAMpC,SAAgB,wBAAwB,WAAuC;AAC7E,QAAO,UAAU,MACd,YACC,uBAAuB,QAAQ,IAAI,uBAAuB,QAAQ,CACrE;;;;;AAMH,SAAgB,0BACd,WACS;AACT,QAAO,UAAU,KAAK,uBAAuB;;;;;AAM/C,SAAgB,wBAAwB,WAAuC;CAC7E,MAAM,OAAO,UAAU,GAAG,GAAG;AAC7B,QAAO,QAAQ,QAAQ,uBAAuB,KAAK"}

package/dist/stream/namespace.js

@@ -0,0 +1,49 @@
+import "./constants.js";
+//#region src/stream/namespace.ts
+/**
+* Stable string key for a protocol namespace tuple.
+*/
+function namespaceKey(namespace) {
+	return namespace.join("\0");
+}
+/**
+* True when an event is scoped to the root namespace.
+*/
+function isRootNamespace(namespace) {
+	return namespace.length === 0;
+}
+/**
+* True when a namespace segment points at a tool execution namespace.
+*/
+function isToolNamespaceSegment(segment) {
+	return segment.startsWith("tools:");
+}
+/**
+* True when a namespace segment points at a legacy task/subagent namespace.
+*/
+function isTaskNamespaceSegment(segment) {
+	return segment.startsWith("task:");
+}
+/**
+* True when a namespace belongs to tool/subagent-internal work.
+*/
+function isInternalWorkNamespace(namespace) {
+	return namespace.some((segment) => isTaskNamespaceSegment(segment) || isToolNamespaceSegment(segment));
+}
+/**
+* True when a namespace includes the legacy task/subagent convention.
+*/
+function isLegacySubagentNamespace(namespace) {
+	return namespace.some(isTaskNamespaceSegment);
+}
+/**
+* True when the namespace itself is a concrete tool execution namespace.
+*/
+function isConcreteToolNamespace(namespace) {
+	const last = namespace.at(-1);
+	return last != null && isToolNamespaceSegment(last);
+}
+//#endregion
+export { isConcreteToolNamespace, isInternalWorkNamespace, isLegacySubagentNamespace, isRootNamespace, isToolNamespaceSegment, namespaceKey };
+
+//# sourceMappingURL=namespace.js.map

package/dist/stream/namespace.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"namespace.js","names":[],"sources":["../../src/stream/namespace.ts"],"sourcesContent":["import { NAMESPACE_SEPARATOR } from \"./constants.js\";\n\n/**\n * Stable string key for a protocol namespace tuple.\n */\nexport function namespaceKey(namespace: readonly string[]): string {\n  return namespace.join(NAMESPACE_SEPARATOR);\n}\n\n/**\n * True when an event is scoped to the root namespace.\n */\nexport function isRootNamespace(namespace: readonly string[]): boolean {\n  return namespace.length === 0;\n}\n\n/**\n * True when a namespace segment points at a tool execution namespace.\n */\nexport function isToolNamespaceSegment(segment: string): boolean {\n  return segment.startsWith(\"tools:\");\n}\n\n/**\n * True when a namespace segment points at a legacy task/subagent namespace.\n */\nexport function isTaskNamespaceSegment(segment: string): boolean {\n  return segment.startsWith(\"task:\");\n}\n\n/**\n * True when a namespace belongs to tool/subagent-internal work.\n */\nexport function isInternalWorkNamespace(namespace: readonly string[]): boolean {\n  return namespace.some(\n    (segment) =>\n      isTaskNamespaceSegment(segment) || isToolNamespaceSegment(segment)\n  );\n}\n\n/**\n * True when a namespace includes the legacy task/subagent convention.\n */\nexport function isLegacySubagentNamespace(\n  namespace: readonly string[]\n): boolean {\n  return namespace.some(isTaskNamespaceSegment);\n}\n\n/**\n * True when the namespace itself is a concrete tool execution namespace.\n */\nexport function isConcreteToolNamespace(namespace: readonly string[]): boolean {\n  const last = namespace.at(-1);\n  return last != null && isToolNamespaceSegment(last);\n}\n"],"mappings":";;;;;AAKA,SAAgB,aAAa,WAAsC;AACjE,QAAO,UAAU,KAAA,KAAyB;;;;;AAM5C,SAAgB,gBAAgB,WAAuC;AACrE,QAAO,UAAU,WAAW;;;;;AAM9B,SAAgB,uBAAuB,SAA0B;AAC/D,QAAO,QAAQ,WAAW,SAAS;;;;;AAMrC,SAAgB,uBAAuB,SAA0B;AAC/D,QAAO,QAAQ,WAAW,QAAQ;;;;;AAMpC,SAAgB,wBAAwB,WAAuC;AAC7E,QAAO,UAAU,MACd,YACC,uBAAuB,QAAQ,IAAI,uBAAuB,QAAQ,CACrE;;;;;AAMH,SAAgB,0BACd,WACS;AACT,QAAO,UAAU,KAAK,uBAAuB;;;;;AAM/C,SAAgB,wBAAwB,WAAuC;CAC7E,MAAM,OAAO,UAAU,GAAG,GAAG;AAC7B,QAAO,QAAQ,QAAQ,uBAAuB,KAAK"}

package/dist/stream/projections/channel.cjs

@@ -0,0 +1,53 @@
+const require_namespace = require("../namespace.cjs");
+const require_runtime = require("./runtime.cjs");
+//#region src/stream/projections/channel.ts
+/** Max events retained per raw subscription. Older events are dropped. */
+const DEFAULT_BUFFER = 4096;
+function channelProjection(channels, namespace, options = {}) {
+	const chs = [...channels].sort();
+	const ns = [...namespace];
+	const bufferSize = options.bufferSize ?? DEFAULT_BUFFER;
+	const replay = options.replay ?? true;
+	return {
+		key: `channel|${bufferSize}|${replay ? "replay" : "live"}|${chs.join(",")}|${require_namespace.namespaceKey(ns)}`,
+		namespace: ns,
+		initial: [],
+		open({ thread, store, rootBus }) {
+			if (!replay && require_namespace.isRootNamespace(ns) && chs.every((c) => rootBus.channels.includes(c))) {
+				const requestedSet = new Set(chs);
+				const namedCustom = /* @__PURE__ */ new Set();
+				for (const channel of chs) if (channel.startsWith("custom:")) namedCustom.add(channel.slice(7));
+				const matches = (event) => {
+					if (requestedSet.has(event.method)) return true;
+					if (event.method !== "custom" || namedCustom.size === 0) return false;
+					const data = event.params.data;
+					return typeof data?.name === "string" && namedCustom.has(data.name);
+				};
+				const push = (event) => {
+					if (!matches(event)) return;
+					const current = store.getSnapshot();
+					const next = current.length >= bufferSize ? [...current.slice(current.length - bufferSize + 1), event] : [...current, event];
+					store.setValue(next);
+				};
+				const unsubscribe = rootBus.subscribe(push);
+				return { dispose() {
+					unsubscribe();
+				} };
+			}
+			return require_runtime.openProjectionSubscription({
+				thread,
+				channels: chs,
+				namespace: ns,
+				onEvent(event) {
+					const current = store.getSnapshot();
+					const next = current.length >= bufferSize ? [...current.slice(current.length - bufferSize + 1), event] : [...current, event];
+					store.setValue(next);
+				}
+			});
+		}
+	};
+}
+//#endregion
+exports.channelProjection = channelProjection;
+
+//# sourceMappingURL=channel.cjs.map