@langchain/langgraph-sdk 1.8.10 → 1.9.0

package/dist/stream/discovery/subgraphs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"subgraphs.js","names":["#onValuesEvent","#promoted","#shadow","#ensureShadow","#commit"],"sources":["../../../src/stream/discovery/subgraphs.ts"],"sourcesContent":["/**\n * Root-scoped subgraph discovery.\n *\n * Watches namespaced `lifecycle` events on the root subscription and\n * assembles two views of the subgraph set:\n *\n *  - {@link SubgraphMap}: `Map<namespaceKey, SubgraphDiscoverySnapshot>`,\n *    the canonical identity-keyed view consumed by the channel\n *    registry and selector hooks.\n *  - {@link SubgraphByNodeMap}: `Map<nodeName, readonly\n *    SubgraphDiscoverySnapshot[]>`, a convenience index so callers\n *    can look up subgraphs by the graph node that produced them\n *    (`addNode(\"visualizer_0\", …)`) without parsing namespaces.\n *    Arrays preserve insertion order, which matters for parallel\n *    fan-outs that share a node name.\n *\n * # What counts as a subgraph\n *\n * The server emits a namespaced `lifecycle` event for every node\n * invocation — a plain function node (`orchestrator`) and a subgraph\n * host (`research`) look identical on the wire. We classify a\n * namespace as a subgraph iff at least one strictly-deeper namespace\n * has been observed with it as a prefix. Concretely, given a stream\n * whose lifecycle events hit the namespaces\n *\n *   `[\"orchestrator:u1\"]`\n *   `[\"research:u2\"]`\n *   `[\"research:u2\", \"researcher:u3\"]`\n *   `[\"research:u2\", \"tools:u4\"]`\n *   `[\"writer:u5\"]`\n *\n * only `[\"research:u2\"]` is promoted — it's the only namespace that\n * hosts deeper executions. `orchestrator` and `writer` are plain\n * function-node leaves; the `researcher` / `tools` entries are the\n * subgraph's internal nodes, not subgraphs in their own right.\n *\n * Promotion is monotonic (a namespace never loses subgraph status)\n * and retroactive: a namespace whose own `started` event arrived\n * before any descendant is promoted later when the first descendant\n * event lands. Latency is bounded by the gap between a parent node\n * entering and its first inner node materializing — typically tens\n * of milliseconds.\n */\nimport type { Event, LifecycleEvent, ValuesEvent } from \"@langchain/protocol\";\nimport { StreamStore } from \"../store.js\";\nimport type { SubgraphDiscoverySnapshot } from \"../types.js\";\nimport {\n  isInternalWorkNamespace,\n  isRootNamespace,\n  namespaceKey,\n} from \"../namespace.js\";\n\nexport type SubgraphMap = ReadonlyMap<string, SubgraphDiscoverySnapshot>;\nexport type SubgraphByNodeMap = ReadonlyMap<\n  string,\n  readonly SubgraphDiscoverySnapshot[]\n>;\n\ninterface MutableSubgraph {\n  id: string;\n  namespace: readonly string[];\n  nodeName: string;\n  status: \"running\" | \"complete\" | \"error\";\n  startedAt: Date;\n  completedAt: Date | null;\n}\n\n/**\n * LangGraph namespaces a node invocation as `<node_name>:<uuid>`\n * (parallel fan-outs share `<node_name>` as a prefix but each get a\n * fresh uuid). Extract the node-name half so callers can key\n * discovery lookups on names they wrote in `addNode(...)`.\n */\nfunction parseNodeName(segment: string): string {\n  const colon = segment.indexOf(\":\");\n  return colon === -1 ? segment : segment.slice(0, colon);\n}\n\nexport class SubgraphDiscovery {\n  readonly store = new StreamStore<SubgraphMap>(new Map());\n  readonly byNodeStore = new StreamStore<SubgraphByNodeMap>(new Map());\n\n  /**\n   * Latest known status for every namespaced lifecycle event we have\n   * ever observed. A shadow entry is NOT necessarily a subgraph —\n   * it is only projected into the committed stores once the same\n   * namespace also appears in {@link #promoted}.\n   */\n  #shadow = new Map<string, MutableSubgraph>();\n\n  /**\n   * Namespaces that have been observed as a strict prefix of a\n   * deeper namespace and are therefore confirmed subgraph hosts.\n   * Insertion order is preserved and becomes the iteration order\n   * of the committed snapshot maps.\n   */\n  #promoted = new Set<string>();\n\n  /** Feed a single root event. Non-discovery events are ignored. */\n  push(event: Event): void {\n    if (event.method === \"values\") {\n      this.#onValuesEvent(event as ValuesEvent);\n      return;\n    }\n    if (event.method !== \"lifecycle\") return;\n    const lifecycle = event as LifecycleEvent;\n    const namespace = lifecycle.params.namespace;\n    // Root lifecycle events describe the main run; subgraph discovery\n    // only cares about namespaced lifecycle events.\n    if (isRootNamespace(namespace)) return;\n    const id = namespaceKey(namespace);\n    const data = lifecycle.params.data as { event?: string };\n    const lastSegment = namespace[namespace.length - 1] ?? \"\";\n    const nodeName = parseNodeName(lastSegment);\n\n    let touched = false;\n\n    // Promote every strict ancestor the first time we see it as a\n    // prefix. The ancestor may or may not yet have a shadow entry;\n    // #commit() tolerates either case.\n    for (let depth = 1; depth < namespace.length; depth += 1) {\n      const ancestorId = namespaceKey(namespace.slice(0, depth));\n      if (!this.#promoted.has(ancestorId)) {\n        this.#promoted.add(ancestorId);\n        if (this.#shadow.has(ancestorId)) touched = true;\n      }\n    }\n\n    // Update shadow status for this namespace itself.\n    if (data.event === \"started\") {\n      if (!this.#shadow.has(id)) {\n        this.#shadow.set(id, {\n          id,\n          namespace: [...namespace],\n          nodeName,\n          status: \"running\",\n          startedAt: new Date(),\n          completedAt: null,\n        });\n        if (this.#promoted.has(id)) touched = true;\n      }\n    } else if (\n      data.event === \"completed\" ||\n      data.event === \"interrupted\" ||\n      data.event === \"failed\"\n    ) {\n      // Synthesize a shadow entry if we missed the `started` event\n      // (common when a late subscription attaches to a running run).\n      const entry = this.#ensureShadow(id, namespace, nodeName);\n      if (data.event === \"failed\") {\n        entry.status = \"error\";\n      } else {\n        entry.status = \"complete\";\n      }\n      entry.completedAt = new Date();\n      if (this.#promoted.has(id)) touched = true;\n    }\n\n    if (touched) this.#commit();\n  }\n\n  /**\n   * Promote subgraph host namespaces from namespaced `values` snapshots.\n   *\n   * Older protocol streams exposed subgraph structure primarily through\n   * nested `lifecycle` events: a host namespace such as\n   * `[\"research:<uuid>\"]` was promoted once a deeper namespace like\n   * `[\"research:<uuid>\", \"inner:<uuid>\"]` appeared. Some runtimes now\n   * emit the useful subgraph signal as `values` snapshots scoped directly\n   * to the host namespace instead, without forwarding inner lifecycle\n   * events to the client. In that shape, the namespace on the `values`\n   * event is already the selector target that `useMessages(stream,\n   * subgraph)` should subscribe to, so we create/promote the shadow\n   * subgraph entry from that namespace.\n   *\n   * Root `values` events are ignored because they represent the parent\n   * thread state, not a subgraph. Tool/subagent namespaces are also\n   * ignored because deep-agent task tools emit their own namespaced\n   * `values` snapshots under `tools:*` / `task:*`; those are discovered\n   * by `SubagentDiscovery` and must not be duplicated as subgraphs.\n   *\n   * A `values` event does not carry lifecycle terminal status, so the\n   * entry remains marked `running` until a matching lifecycle terminal\n   * event arrives. If no terminal arrives, the discovery map still\n   * contains the host namespace, which is the important invariant for\n   * scoped selectors.\n   */\n  #onValuesEvent(event: ValuesEvent): void {\n    const namespace = event.params.namespace;\n    if (isRootNamespace(namespace)) return;\n    if (isInternalWorkNamespace(namespace)) return;\n    const data = event.params.data;\n    if (data == null || typeof data !== \"object\" || Array.isArray(data)) return;\n\n    const id = namespaceKey(namespace);\n    const lastSegment = namespace[namespace.length - 1] ?? \"\";\n    const nodeName = parseNodeName(lastSegment);\n    const entry = this.#ensureShadow(id, namespace, nodeName);\n    entry.status = \"running\";\n\n    if (!this.#promoted.has(id)) {\n      this.#promoted.add(id);\n    }\n    this.#commit();\n  }\n\n  get snapshot(): SubgraphMap {\n    return this.store.getSnapshot();\n  }\n\n  get byNodeSnapshot(): SubgraphByNodeMap {\n    return this.byNodeStore.getSnapshot();\n  }\n\n  #ensureShadow(\n    id: string,\n    namespace: readonly string[],\n    nodeName: string\n  ): MutableSubgraph {\n    let entry = this.#shadow.get(id);\n    if (entry == null) {\n      entry = {\n        id,\n        namespace: [...namespace],\n        nodeName,\n        status: \"running\",\n        startedAt: new Date(),\n        completedAt: null,\n      };\n      this.#shadow.set(id, entry);\n    }\n    return entry;\n  }\n\n  #commit(): void {\n    const snapshots: SubgraphDiscoverySnapshot[] = [];\n    for (const id of this.#promoted) {\n      const entry = this.#shadow.get(id);\n      // A namespace can be promoted before its own lifecycle event\n      // arrives if descendant events outpace the prefix event. Skip\n      // until the shadow entry lands; the next push() promoting or\n      // updating this namespace will re-commit.\n      if (entry == null) continue;\n      snapshots.push({ ...entry });\n    }\n\n    this.store.setValue(new Map(snapshots.map((s) => [s.id, s])));\n\n    const byNode = new Map<string, SubgraphDiscoverySnapshot[]>();\n    for (const snap of snapshots) {\n      const bucket = byNode.get(snap.nodeName);\n      if (bucket == null) byNode.set(snap.nodeName, [snap]);\n      else bucket.push(snap);\n    }\n    this.byNodeStore.setValue(byNode);\n  }\n}\n"],"mappings":";;;;;;;;;AAyEA,SAAS,cAAc,SAAyB;CAC9C,MAAM,QAAQ,QAAQ,QAAQ,IAAI;AAClC,QAAO,UAAU,KAAK,UAAU,QAAQ,MAAM,GAAG,MAAM;;AAGzD,IAAa,oBAAb,MAA+B;CAC7B,QAAiB,IAAI,4BAAyB,IAAI,KAAK,CAAC;CACxD,cAAuB,IAAI,4BAA+B,IAAI,KAAK,CAAC;;;;;;;CAQpE,0BAAU,IAAI,KAA8B;;;;;;;CAQ5C,4BAAY,IAAI,KAAa;;CAG7B,KAAK,OAAoB;AACvB,MAAI,MAAM,WAAW,UAAU;AAC7B,SAAA,cAAoB,MAAqB;AACzC;;AAEF,MAAI,MAAM,WAAW,YAAa;EAClC,MAAM,YAAY;EAClB,MAAM,YAAY,UAAU,OAAO;AAGnC,MAAI,gBAAgB,UAAU,CAAE;EAChC,MAAM,KAAK,aAAa,UAAU;EAClC,MAAM,OAAO,UAAU,OAAO;EAE9B,MAAM,WAAW,cADG,UAAU,UAAU,SAAS,MAAM,GACZ;EAE3C,IAAI,UAAU;AAKd,OAAK,IAAI,QAAQ,GAAG,QAAQ,UAAU,QAAQ,SAAS,GAAG;GACxD,MAAM,aAAa,aAAa,UAAU,MAAM,GAAG,MAAM,CAAC;AAC1D,OAAI,CAAC,MAAA,SAAe,IAAI,WAAW,EAAE;AACnC,UAAA,SAAe,IAAI,WAAW;AAC9B,QAAI,MAAA,OAAa,IAAI,WAAW,CAAE,WAAU;;;AAKhD,MAAI,KAAK,UAAU;OACb,CAAC,MAAA,OAAa,IAAI,GAAG,EAAE;AACzB,UAAA,OAAa,IAAI,IAAI;KACnB;KACA,WAAW,CAAC,GAAG,UAAU;KACzB;KACA,QAAQ;KACR,2BAAW,IAAI,MAAM;KACrB,aAAa;KACd,CAAC;AACF,QAAI,MAAA,SAAe,IAAI,GAAG,CAAE,WAAU;;aAGxC,KAAK,UAAU,eACf,KAAK,UAAU,iBACf,KAAK,UAAU,UACf;GAGA,MAAM,QAAQ,MAAA,aAAmB,IAAI,WAAW,SAAS;AACzD,OAAI,KAAK,UAAU,SACjB,OAAM,SAAS;OAEf,OAAM,SAAS;AAEjB,SAAM,8BAAc,IAAI,MAAM;AAC9B,OAAI,MAAA,SAAe,IAAI,GAAG,CAAE,WAAU;;AAGxC,MAAI,QAAS,OAAA,QAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA6B7B,eAAe,OAA0B;EACvC,MAAM,YAAY,MAAM,OAAO;AAC/B,MAAI,gBAAgB,UAAU,CAAE;AAChC,MAAI,wBAAwB,UAAU,CAAE;EACxC,MAAM,OAAO,MAAM,OAAO;AAC1B,MAAI,QAAQ,QAAQ,OAAO,SAAS,YAAY,MAAM,QAAQ,KAAK,CAAE;EAErE,MAAM,KAAK,aAAa,UAAU;EAElC,MAAM,WAAW,cADG,UAAU,UAAU,SAAS,MAAM,GACZ;EAC3C,MAAM,QAAQ,MAAA,aAAmB,IAAI,WAAW,SAAS;AACzD,QAAM,SAAS;AAEf,MAAI,CAAC,MAAA,SAAe,IAAI,GAAG,CACzB,OAAA,SAAe,IAAI,GAAG;AAExB,QAAA,QAAc;;CAGhB,IAAI,WAAwB;AAC1B,SAAO,KAAK,MAAM,aAAa;;CAGjC,IAAI,iBAAoC;AACtC,SAAO,KAAK,YAAY,aAAa;;CAGvC,cACE,IACA,WACA,UACiB;EACjB,IAAI,QAAQ,MAAA,OAAa,IAAI,GAAG;AAChC,MAAI,SAAS,MAAM;AACjB,WAAQ;IACN;IACA,WAAW,CAAC,GAAG,UAAU;IACzB;IACA,QAAQ;IACR,2BAAW,IAAI,MAAM;IACrB,aAAa;IACd;AACD,SAAA,OAAa,IAAI,IAAI,MAAM;;AAE7B,SAAO;;CAGT,UAAgB;EACd,MAAM,YAAyC,EAAE;AACjD,OAAK,MAAM,MAAM,MAAA,UAAgB;GAC/B,MAAM,QAAQ,MAAA,OAAa,IAAI,GAAG;AAKlC,OAAI,SAAS,KAAM;AACnB,aAAU,KAAK,EAAE,GAAG,OAAO,CAAC;;AAG9B,OAAK,MAAM,SAAS,IAAI,IAAI,UAAU,KAAK,MAAM,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;EAE7D,MAAM,yBAAS,IAAI,KAA0C;AAC7D,OAAK,MAAM,QAAQ,WAAW;GAC5B,MAAM,SAAS,OAAO,IAAI,KAAK,SAAS;AACxC,OAAI,UAAU,KAAM,QAAO,IAAI,KAAK,UAAU,CAAC,KAAK,CAAC;OAChD,QAAO,KAAK,KAAK;;AAExB,OAAK,YAAY,SAAS,OAAO"}

package/dist/stream/index.cjs

@@ -0,0 +1,36 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_media = require("../client/stream/media.cjs");
+const require_constants = require("./constants.cjs");
+const require_store = require("./store.cjs");
+const require_channel_registry = require("./channel-registry.cjs");
+const require_subagents = require("./discovery/subagents.cjs");
+const require_subgraphs = require("./discovery/subgraphs.cjs");
+const require_assembled_to_message = require("./assembled-to-message.cjs");
+const require_controller = require("./controller.cjs");
+const require_messages = require("./projections/messages.cjs");
+const require_tool_calls = require("./projections/tool-calls.cjs");
+const require_values = require("./projections/values.cjs");
+const require_extension = require("./projections/extension.cjs");
+const require_channel = require("./projections/channel.cjs");
+const require_media$1 = require("./projections/media.cjs");
+require("./projections/index.cjs");
+exports.ChannelRegistry = require_channel_registry.ChannelRegistry;
+exports.MediaAssembler = require_media.MediaAssembler;
+exports.MediaAssemblyError = require_media.MediaAssemblyError;
+exports.NAMESPACE_SEPARATOR = require_constants.NAMESPACE_SEPARATOR;
+exports.ROOT_PUMP_CHANNELS = require_controller.ROOT_PUMP_CHANNELS;
+exports.StreamController = require_controller.StreamController;
+exports.StreamStore = require_store.StreamStore;
+exports.SubagentDiscovery = require_subagents.SubagentDiscovery;
+exports.SubgraphDiscovery = require_subgraphs.SubgraphDiscovery;
+exports.assembledMessageToBaseMessage = require_assembled_to_message.assembledMessageToBaseMessage;
+exports.assembledToBaseMessage = require_assembled_to_message.assembledToBaseMessage;
+exports.audioProjection = require_media$1.audioProjection;
+exports.channelProjection = require_channel.channelProjection;
+exports.extensionProjection = require_extension.extensionProjection;
+exports.filesProjection = require_media$1.filesProjection;
+exports.imagesProjection = require_media$1.imagesProjection;
+exports.messagesProjection = require_messages.messagesProjection;
+exports.toolCallsProjection = require_tool_calls.toolCallsProjection;
+exports.valuesProjection = require_values.valuesProjection;
+exports.videoProjection = require_media$1.videoProjection;

package/dist/stream/index.d.cts

@@ -0,0 +1,25 @@
+import { DefaultToolCall, ToolCallFromTool } from "../types.messages.cjs";
+import { AssembledToolCall, ToolCallStatus } from "../client/stream/handles/tools.cjs";
+import { AnyMediaHandle, AudioMedia, FileMedia, ImageMedia, MediaAssembler, MediaAssemblerCallbacks, MediaAssemblerOptions, MediaAssemblyError, MediaAssemblyErrorKind, MediaBase, MediaBlockType, VideoMedia } from "../client/stream/media.cjs";
+import { AgentServerAdapter, TransportAdapter } from "../client/stream/transport.cjs";
+import { AgentTypeConfigLike, CompiledSubAgentLike, DeepAgentTypeConfigLike, DefaultSubagentStates, ExtractAgentConfig, ExtractDeepAgentConfig, ExtractSubAgentMiddleware, InferAgentToolCalls, InferDeepAgentSubagents, InferSubagentByName, InferSubagentNames, InferSubagentState, IsAgentLike, IsDeepAgentLike, SubAgentLike, SubagentStateMap, SubagentToolCall } from "../ui/types.cjs";
+import { InferBag, InferNodeNames } from "../ui/stream/index.cjs";
+import { InferStateType, InferSubagentStates, InferToolCalls, WidenUpdateMessages } from "./types-inference.cjs";
+import { StoreListener, StreamStore } from "./store.cjs";
+import { AcquiredProjection, AgentServerOptions, CustomAdapterOptions, ProjectionRuntime, ProjectionSpec, RootEventBus, RootSnapshot, StateOf, StreamControllerOptions, StreamSubmitOptions, SubagentDiscoverySnapshot, SubgraphDiscoverySnapshot, Target, UseStreamCommonOptions, UseStreamOptions } from "./types.cjs";
+import { ChannelRegistry } from "./channel-registry.cjs";
+import { SubagentDiscovery, SubagentMap } from "./discovery/subagents.cjs";
+import { SubgraphByNodeMap, SubgraphDiscovery, SubgraphMap } from "./discovery/subgraphs.cjs";
+import { MessageMetadata, MessageMetadataMap } from "./message-metadata-tracker.cjs";
+import { SubmissionQueueEntry, SubmissionQueueSnapshot } from "./submit-coordinator.cjs";
+import { ROOT_PUMP_CHANNELS, StreamController } from "./controller.cjs";
+import { messagesProjection } from "./projections/messages.cjs";
+import { toolCallsProjection } from "./projections/tool-calls.cjs";
+import { valuesProjection } from "./projections/values.cjs";
+import { extensionProjection } from "./projections/extension.cjs";
+import { ChannelProjectionOptions, channelProjection } from "./projections/channel.cjs";
+import { MediaProjectionOptions, audioProjection, filesProjection, imagesProjection, videoProjection } from "./projections/media.cjs";
+import { AssembledToMessageInput, ExtendedMessageRole, assembledMessageToBaseMessage, assembledToBaseMessage } from "./assembled-to-message.cjs";
+import { NAMESPACE_SEPARATOR } from "./constants.cjs";
+import { Channel, Event } from "@langchain/protocol";
+export { type AcquiredProjection, type AgentServerAdapter, type AgentServerOptions, type AgentTypeConfigLike, type AnyMediaHandle, type AssembledToMessageInput, type AssembledToolCall, 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 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 StateOf, type StoreListener, StreamController, type StreamControllerOptions, 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, toolCallsProjection, valuesProjection, videoProjection };

package/dist/stream/index.d.ts

@@ -0,0 +1,25 @@
+import { DefaultToolCall, ToolCallFromTool } from "../types.messages.js";
+import { AssembledToolCall, ToolCallStatus } from "../client/stream/handles/tools.js";
+import { AnyMediaHandle, AudioMedia, FileMedia, ImageMedia, MediaAssembler, MediaAssemblerCallbacks, MediaAssemblerOptions, MediaAssemblyError, MediaAssemblyErrorKind, MediaBase, MediaBlockType, VideoMedia } from "../client/stream/media.js";
+import { AgentServerAdapter, TransportAdapter } from "../client/stream/transport.js";
+import { AgentTypeConfigLike, CompiledSubAgentLike, DeepAgentTypeConfigLike, DefaultSubagentStates, ExtractAgentConfig, ExtractDeepAgentConfig, ExtractSubAgentMiddleware, InferAgentToolCalls, InferDeepAgentSubagents, InferSubagentByName, InferSubagentNames, InferSubagentState, IsAgentLike, IsDeepAgentLike, SubAgentLike, SubagentStateMap, SubagentToolCall } from "../ui/types.js";
+import { InferBag, InferNodeNames } from "../ui/stream/index.js";
+import { InferStateType, InferSubagentStates, InferToolCalls, WidenUpdateMessages } from "./types-inference.js";
+import { StoreListener, StreamStore } from "./store.js";
+import { AcquiredProjection, AgentServerOptions, CustomAdapterOptions, ProjectionRuntime, ProjectionSpec, RootEventBus, RootSnapshot, StateOf, StreamControllerOptions, StreamSubmitOptions, SubagentDiscoverySnapshot, SubgraphDiscoverySnapshot, Target, UseStreamCommonOptions, UseStreamOptions } from "./types.js";
+import { ChannelRegistry } from "./channel-registry.js";
+import { SubagentDiscovery, SubagentMap } from "./discovery/subagents.js";
+import { SubgraphByNodeMap, SubgraphDiscovery, SubgraphMap } from "./discovery/subgraphs.js";
+import { MessageMetadata, MessageMetadataMap } from "./message-metadata-tracker.js";
+import { SubmissionQueueEntry, SubmissionQueueSnapshot } from "./submit-coordinator.js";
+import { ROOT_PUMP_CHANNELS, StreamController } from "./controller.js";
+import { messagesProjection } from "./projections/messages.js";
+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 { 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 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 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 StateOf, type StoreListener, StreamController, type StreamControllerOptions, 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, toolCallsProjection, valuesProjection, videoProjection };

package/dist/stream/index.js

@@ -0,0 +1,16 @@
+import { MediaAssembler, MediaAssemblyError } from "../client/stream/media.js";
+import { NAMESPACE_SEPARATOR } from "./constants.js";
+import { StreamStore } from "./store.js";
+import { ChannelRegistry } from "./channel-registry.js";
+import { SubagentDiscovery } from "./discovery/subagents.js";
+import { SubgraphDiscovery } from "./discovery/subgraphs.js";
+import { assembledMessageToBaseMessage, assembledToBaseMessage } from "./assembled-to-message.js";
+import { ROOT_PUMP_CHANNELS, StreamController } from "./controller.js";
+import { messagesProjection } from "./projections/messages.js";
+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 { 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, toolCallsProjection, valuesProjection, videoProjection };

package/dist/stream/lifecycle-loading-tracker.cjs

@@ -0,0 +1,83 @@
+const require_namespace = require("./namespace.cjs");
+//#region src/stream/lifecycle-loading-tracker.ts
+/**
+* Drives root-snapshot `isLoading` from root lifecycle events.
+*/
+var LifecycleLoadingTracker = class {
+	/** Snapshot store whose `isLoading` slot we manage. */
+	#store;
+	/**
+	* Disposal probe. Consulted from the deferred `setTimeout` so a
+	* controller torn down between scheduling and firing doesn't end
+	* up writing to a defunct store.
+	*/
+	#isDisposed;
+	/**
+	* Highest sequence number of a terminal lifecycle we've observed.
+	* `running` events at or below this seq are stale replays and
+	* are dropped to avoid flipping the loading flag back on after the
+	* run has already ended.
+	*/
+	#lastTerminalLifecycleSeq = -1;
+	/**
+	* @param params.store      - Store whose `isLoading` slot we drive.
+	* @param params.isDisposed - Disposal probe consulted from deferred callbacks.
+	*/
+	constructor(params) {
+		this.#store = params.store;
+		this.#isDisposed = params.isDisposed;
+	}
+	/**
+	* Bound listener suitable for `EventBus.subscribe`. Re-exposed as a
+	* stable property so the controller can later remove the same
+	* function reference from the bus on teardown.
+	*/
+	listener = (event) => {
+		this.handle(event);
+	};
+	/**
+	* Reset internal state when rebinding to a new thread.
+	*
+	* The terminal-seq guard is per-thread: a new thread's `running`
+	* events are not stale relative to the old thread's terminals.
+	*/
+	reset() {
+		this.#lastTerminalLifecycleSeq = -1;
+	}
+	/**
+	* Process a single protocol event.
+	*
+	* Filters down to root-namespace lifecycle events, then mutates the
+	* store's `isLoading` slot. All other events are ignored.
+	*
+	* @param event - Any protocol event from the controller's root bus.
+	*/
+	handle(event) {
+		if (event.method !== "lifecycle") return;
+		if (!require_namespace.isRootNamespace(event.params.namespace)) return;
+		const lifecycle = event.params.data;
+		const seq = typeof event.seq === "number" ? event.seq : void 0;
+		if (lifecycle?.event === "running") {
+			if (seq != null && seq <= this.#lastTerminalLifecycleSeq) return;
+			this.#store.setState((s) => s.isLoading ? s : {
+				...s,
+				isLoading: true
+			});
+			return;
+		}
+		if (lifecycle?.event === "completed" || lifecycle?.event === "failed" || lifecycle?.event === "interrupted" || lifecycle?.event === "cancelled") {
+			if (seq != null) this.#lastTerminalLifecycleSeq = Math.max(this.#lastTerminalLifecycleSeq, seq);
+			setTimeout(() => {
+				if (this.#isDisposed()) return;
+				this.#store.setState((s) => s.isLoading ? {
+					...s,
+					isLoading: false
+				} : s);
+			}, 0);
+		}
+	}
+};
+//#endregion
+exports.LifecycleLoadingTracker = LifecycleLoadingTracker;
+
+//# sourceMappingURL=lifecycle-loading-tracker.cjs.map

package/dist/stream/lifecycle-loading-tracker.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle-loading-tracker.cjs","names":["#store","#isDisposed","#lastTerminalLifecycleSeq","isRootNamespace"],"sources":["../../src/stream/lifecycle-loading-tracker.ts"],"sourcesContent":["/**\n * Drives the {@link RootSnapshot.isLoading} flag from root lifecycle\n * events.\n *\n * # What it does\n *\n * The tracker watches a stream of protocol events and flips the\n * `isLoading` slot of a {@link StreamStore} based on root-namespace\n * `lifecycle` payloads:\n *\n *   - `running`                       → `isLoading = true`\n *   - `completed` / `failed` / `interrupted` / `cancelled`\n *                                     → `isLoading = false`\n *\n * Non-root, non-lifecycle, and unknown events are ignored.\n *\n * # Why it lives in its own class\n *\n * Lifecycle handling has two subtleties that we want to keep out of\n * the {@link StreamController}'s critical path:\n *\n *   1. **Stale `running` filtering.** SSE replays older events on\n *      reconnect — including a `running` lifecycle that fired before\n *      the run terminated. Without filtering, that replay would flip\n *      `isLoading` back to `true` after a `completed` already brought\n *      it down. We track the highest terminal `seq` we've seen and\n *      drop any `running` whose `seq` is at or below it.\n *   2. **Deferred terminal flip.** The flip from `true → false` is\n *      pushed to the next macrotask (`setTimeout(..., 0)`). This\n *      gives synchronous consumers — most notably `for await`\n *      iterators in framework bindings — one event-loop tick to\n *      observe terminal-related state (e.g. the final assistant\n *      message landing in `values`) before `isLoading` settles.\n *\n * # Why it's safe to register the listener as `controller.onEvent`\n *\n * The tracker subscribes to the controller's root event bus via the\n * exported {@link listener} arrow. Because the listener is bound at\n * construction time, removing it later (`bus.delete(tracker.listener)`)\n * works without `bind()` gymnastics in the controller.\n *\n * @typeParam T - The snapshot shape; must contain an `isLoading` flag.\n */\nimport type { Event, LifecycleEvent } from \"@langchain/protocol\";\nimport { StreamStore } from \"./store.js\";\nimport { isRootNamespace } from \"./namespace.js\";\n\n/**\n * Minimal contract the snapshot must satisfy. The tracker only\n * touches `isLoading`, leaving everything else for the controller.\n */\ntype LoadingSnapshot = { readonly isLoading: boolean };\n\n/**\n * Drives root-snapshot `isLoading` from root lifecycle events.\n */\nexport class LifecycleLoadingTracker<T extends LoadingSnapshot> {\n  /** Snapshot store whose `isLoading` slot we manage. */\n  readonly #store: StreamStore<T>;\n\n  /**\n   * Disposal probe. Consulted from the deferred `setTimeout` so a\n   * controller torn down between scheduling and firing doesn't end\n   * up writing to a defunct store.\n   */\n  readonly #isDisposed: () => boolean;\n\n  /**\n   * Highest sequence number of a terminal lifecycle we've observed.\n   * `running` events at or below this seq are stale replays and\n   * are dropped to avoid flipping the loading flag back on after the\n   * run has already ended.\n   */\n  #lastTerminalLifecycleSeq = -1;\n\n  /**\n   * @param params.store      - Store whose `isLoading` slot we drive.\n   * @param params.isDisposed - Disposal probe consulted from deferred callbacks.\n   */\n  constructor(params: { store: StreamStore<T>; isDisposed: () => boolean }) {\n    this.#store = params.store;\n    this.#isDisposed = params.isDisposed;\n  }\n\n  /**\n   * Bound listener suitable for `EventBus.subscribe`. Re-exposed as a\n   * stable property so the controller can later remove the same\n   * function reference from the bus on teardown.\n   */\n  readonly listener = (event: Event): void => {\n    this.handle(event);\n  };\n\n  /**\n   * Reset internal state when rebinding to a new thread.\n   *\n   * The terminal-seq guard is per-thread: a new thread's `running`\n   * events are not stale relative to the old thread's terminals.\n   */\n  reset(): void {\n    this.#lastTerminalLifecycleSeq = -1;\n  }\n\n  /**\n   * Process a single protocol event.\n   *\n   * Filters down to root-namespace lifecycle events, then mutates the\n   * store's `isLoading` slot. All other events are ignored.\n   *\n   * @param event - Any protocol event from the controller's root bus.\n   */\n  handle(event: Event): void {\n    if (event.method !== \"lifecycle\") return;\n    if (!isRootNamespace(event.params.namespace)) return;\n    const lifecycle = (event as LifecycleEvent).params.data as {\n      event?: string;\n    };\n    const seq = typeof event.seq === \"number\" ? event.seq : undefined;\n    if (lifecycle?.event === \"running\") {\n      // Drop stale `running` replays that arrive *after* a terminal\n      // for the same run. SSE re-streams history on reconnect; without\n      // this filter the loading flag would oscillate.\n      if (seq != null && seq <= this.#lastTerminalLifecycleSeq) {\n        return;\n      }\n      this.#store.setState((s) =>\n        s.isLoading ? s : { ...s, isLoading: true }\n      );\n      return;\n    }\n    if (\n      lifecycle?.event === \"completed\" ||\n      lifecycle?.event === \"failed\" ||\n      lifecycle?.event === \"interrupted\" ||\n      lifecycle?.event === \"cancelled\"\n    ) {\n      if (seq != null) {\n        this.#lastTerminalLifecycleSeq = Math.max(\n          this.#lastTerminalLifecycleSeq,\n          seq\n        );\n      }\n      // Flip `isLoading=false` on the next macrotask so synchronous\n      // consumers iterating events get one tick to observe terminal\n      // state (the final values snapshot etc.) before the loading\n      // indicator drops.\n      setTimeout(() => {\n        if (this.#isDisposed()) return;\n        this.#store.setState((s) =>\n          s.isLoading ? { ...s, isLoading: false } : s\n        );\n      }, 0);\n    }\n  }\n}\n"],"mappings":";;;;;AAwDA,IAAa,0BAAb,MAAgE;;CAE9D;;;;;;CAOA;;;;;;;CAQA,4BAA4B;;;;;CAM5B,YAAY,QAA8D;AACxE,QAAA,QAAc,OAAO;AACrB,QAAA,aAAmB,OAAO;;;;;;;CAQ5B,YAAqB,UAAuB;AAC1C,OAAK,OAAO,MAAM;;;;;;;;CASpB,QAAc;AACZ,QAAA,2BAAiC;;;;;;;;;;CAWnC,OAAO,OAAoB;AACzB,MAAI,MAAM,WAAW,YAAa;AAClC,MAAI,CAACG,kBAAAA,gBAAgB,MAAM,OAAO,UAAU,CAAE;EAC9C,MAAM,YAAa,MAAyB,OAAO;EAGnD,MAAM,MAAM,OAAO,MAAM,QAAQ,WAAW,MAAM,MAAM,KAAA;AACxD,MAAI,WAAW,UAAU,WAAW;AAIlC,OAAI,OAAO,QAAQ,OAAO,MAAA,yBACxB;AAEF,SAAA,MAAY,UAAU,MACpB,EAAE,YAAY,IAAI;IAAE,GAAG;IAAG,WAAW;IAAM,CAC5C;AACD;;AAEF,MACE,WAAW,UAAU,eACrB,WAAW,UAAU,YACrB,WAAW,UAAU,iBACrB,WAAW,UAAU,aACrB;AACA,OAAI,OAAO,KACT,OAAA,2BAAiC,KAAK,IACpC,MAAA,0BACA,IACD;AAMH,oBAAiB;AACf,QAAI,MAAA,YAAkB,CAAE;AACxB,UAAA,MAAY,UAAU,MACpB,EAAE,YAAY;KAAE,GAAG;KAAG,WAAW;KAAO,GAAG,EAC5C;MACA,EAAE"}

package/dist/stream/lifecycle-loading-tracker.js

@@ -0,0 +1,83 @@
+import { isRootNamespace } from "./namespace.js";
+//#region src/stream/lifecycle-loading-tracker.ts
+/**
+* Drives root-snapshot `isLoading` from root lifecycle events.
+*/
+var LifecycleLoadingTracker = class {
+	/** Snapshot store whose `isLoading` slot we manage. */
+	#store;
+	/**
+	* Disposal probe. Consulted from the deferred `setTimeout` so a
+	* controller torn down between scheduling and firing doesn't end
+	* up writing to a defunct store.
+	*/
+	#isDisposed;
+	/**
+	* Highest sequence number of a terminal lifecycle we've observed.
+	* `running` events at or below this seq are stale replays and
+	* are dropped to avoid flipping the loading flag back on after the
+	* run has already ended.
+	*/
+	#lastTerminalLifecycleSeq = -1;
+	/**
+	* @param params.store      - Store whose `isLoading` slot we drive.
+	* @param params.isDisposed - Disposal probe consulted from deferred callbacks.
+	*/
+	constructor(params) {
+		this.#store = params.store;
+		this.#isDisposed = params.isDisposed;
+	}
+	/**
+	* Bound listener suitable for `EventBus.subscribe`. Re-exposed as a
+	* stable property so the controller can later remove the same
+	* function reference from the bus on teardown.
+	*/
+	listener = (event) => {
+		this.handle(event);
+	};
+	/**
+	* Reset internal state when rebinding to a new thread.
+	*
+	* The terminal-seq guard is per-thread: a new thread's `running`
+	* events are not stale relative to the old thread's terminals.
+	*/
+	reset() {
+		this.#lastTerminalLifecycleSeq = -1;
+	}
+	/**
+	* Process a single protocol event.
+	*
+	* Filters down to root-namespace lifecycle events, then mutates the
+	* store's `isLoading` slot. All other events are ignored.
+	*
+	* @param event - Any protocol event from the controller's root bus.
+	*/
+	handle(event) {
+		if (event.method !== "lifecycle") return;
+		if (!isRootNamespace(event.params.namespace)) return;
+		const lifecycle = event.params.data;
+		const seq = typeof event.seq === "number" ? event.seq : void 0;
+		if (lifecycle?.event === "running") {
+			if (seq != null && seq <= this.#lastTerminalLifecycleSeq) return;
+			this.#store.setState((s) => s.isLoading ? s : {
+				...s,
+				isLoading: true
+			});
+			return;
+		}
+		if (lifecycle?.event === "completed" || lifecycle?.event === "failed" || lifecycle?.event === "interrupted" || lifecycle?.event === "cancelled") {
+			if (seq != null) this.#lastTerminalLifecycleSeq = Math.max(this.#lastTerminalLifecycleSeq, seq);
+			setTimeout(() => {
+				if (this.#isDisposed()) return;
+				this.#store.setState((s) => s.isLoading ? {
+					...s,
+					isLoading: false
+				} : s);
+			}, 0);
+		}
+	}
+};
+//#endregion
+export { LifecycleLoadingTracker };
+
+//# sourceMappingURL=lifecycle-loading-tracker.js.map

package/dist/stream/lifecycle-loading-tracker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle-loading-tracker.js","names":["#store","#isDisposed","#lastTerminalLifecycleSeq"],"sources":["../../src/stream/lifecycle-loading-tracker.ts"],"sourcesContent":["/**\n * Drives the {@link RootSnapshot.isLoading} flag from root lifecycle\n * events.\n *\n * # What it does\n *\n * The tracker watches a stream of protocol events and flips the\n * `isLoading` slot of a {@link StreamStore} based on root-namespace\n * `lifecycle` payloads:\n *\n *   - `running`                       → `isLoading = true`\n *   - `completed` / `failed` / `interrupted` / `cancelled`\n *                                     → `isLoading = false`\n *\n * Non-root, non-lifecycle, and unknown events are ignored.\n *\n * # Why it lives in its own class\n *\n * Lifecycle handling has two subtleties that we want to keep out of\n * the {@link StreamController}'s critical path:\n *\n *   1. **Stale `running` filtering.** SSE replays older events on\n *      reconnect — including a `running` lifecycle that fired before\n *      the run terminated. Without filtering, that replay would flip\n *      `isLoading` back to `true` after a `completed` already brought\n *      it down. We track the highest terminal `seq` we've seen and\n *      drop any `running` whose `seq` is at or below it.\n *   2. **Deferred terminal flip.** The flip from `true → false` is\n *      pushed to the next macrotask (`setTimeout(..., 0)`). This\n *      gives synchronous consumers — most notably `for await`\n *      iterators in framework bindings — one event-loop tick to\n *      observe terminal-related state (e.g. the final assistant\n *      message landing in `values`) before `isLoading` settles.\n *\n * # Why it's safe to register the listener as `controller.onEvent`\n *\n * The tracker subscribes to the controller's root event bus via the\n * exported {@link listener} arrow. Because the listener is bound at\n * construction time, removing it later (`bus.delete(tracker.listener)`)\n * works without `bind()` gymnastics in the controller.\n *\n * @typeParam T - The snapshot shape; must contain an `isLoading` flag.\n */\nimport type { Event, LifecycleEvent } from \"@langchain/protocol\";\nimport { StreamStore } from \"./store.js\";\nimport { isRootNamespace } from \"./namespace.js\";\n\n/**\n * Minimal contract the snapshot must satisfy. The tracker only\n * touches `isLoading`, leaving everything else for the controller.\n */\ntype LoadingSnapshot = { readonly isLoading: boolean };\n\n/**\n * Drives root-snapshot `isLoading` from root lifecycle events.\n */\nexport class LifecycleLoadingTracker<T extends LoadingSnapshot> {\n  /** Snapshot store whose `isLoading` slot we manage. */\n  readonly #store: StreamStore<T>;\n\n  /**\n   * Disposal probe. Consulted from the deferred `setTimeout` so a\n   * controller torn down between scheduling and firing doesn't end\n   * up writing to a defunct store.\n   */\n  readonly #isDisposed: () => boolean;\n\n  /**\n   * Highest sequence number of a terminal lifecycle we've observed.\n   * `running` events at or below this seq are stale replays and\n   * are dropped to avoid flipping the loading flag back on after the\n   * run has already ended.\n   */\n  #lastTerminalLifecycleSeq = -1;\n\n  /**\n   * @param params.store      - Store whose `isLoading` slot we drive.\n   * @param params.isDisposed - Disposal probe consulted from deferred callbacks.\n   */\n  constructor(params: { store: StreamStore<T>; isDisposed: () => boolean }) {\n    this.#store = params.store;\n    this.#isDisposed = params.isDisposed;\n  }\n\n  /**\n   * Bound listener suitable for `EventBus.subscribe`. Re-exposed as a\n   * stable property so the controller can later remove the same\n   * function reference from the bus on teardown.\n   */\n  readonly listener = (event: Event): void => {\n    this.handle(event);\n  };\n\n  /**\n   * Reset internal state when rebinding to a new thread.\n   *\n   * The terminal-seq guard is per-thread: a new thread's `running`\n   * events are not stale relative to the old thread's terminals.\n   */\n  reset(): void {\n    this.#lastTerminalLifecycleSeq = -1;\n  }\n\n  /**\n   * Process a single protocol event.\n   *\n   * Filters down to root-namespace lifecycle events, then mutates the\n   * store's `isLoading` slot. All other events are ignored.\n   *\n   * @param event - Any protocol event from the controller's root bus.\n   */\n  handle(event: Event): void {\n    if (event.method !== \"lifecycle\") return;\n    if (!isRootNamespace(event.params.namespace)) return;\n    const lifecycle = (event as LifecycleEvent).params.data as {\n      event?: string;\n    };\n    const seq = typeof event.seq === \"number\" ? event.seq : undefined;\n    if (lifecycle?.event === \"running\") {\n      // Drop stale `running` replays that arrive *after* a terminal\n      // for the same run. SSE re-streams history on reconnect; without\n      // this filter the loading flag would oscillate.\n      if (seq != null && seq <= this.#lastTerminalLifecycleSeq) {\n        return;\n      }\n      this.#store.setState((s) =>\n        s.isLoading ? s : { ...s, isLoading: true }\n      );\n      return;\n    }\n    if (\n      lifecycle?.event === \"completed\" ||\n      lifecycle?.event === \"failed\" ||\n      lifecycle?.event === \"interrupted\" ||\n      lifecycle?.event === \"cancelled\"\n    ) {\n      if (seq != null) {\n        this.#lastTerminalLifecycleSeq = Math.max(\n          this.#lastTerminalLifecycleSeq,\n          seq\n        );\n      }\n      // Flip `isLoading=false` on the next macrotask so synchronous\n      // consumers iterating events get one tick to observe terminal\n      // state (the final values snapshot etc.) before the loading\n      // indicator drops.\n      setTimeout(() => {\n        if (this.#isDisposed()) return;\n        this.#store.setState((s) =>\n          s.isLoading ? { ...s, isLoading: false } : s\n        );\n      }, 0);\n    }\n  }\n}\n"],"mappings":";;;;;AAwDA,IAAa,0BAAb,MAAgE;;CAE9D;;;;;;CAOA;;;;;;;CAQA,4BAA4B;;;;;CAM5B,YAAY,QAA8D;AACxE,QAAA,QAAc,OAAO;AACrB,QAAA,aAAmB,OAAO;;;;;;;CAQ5B,YAAqB,UAAuB;AAC1C,OAAK,OAAO,MAAM;;;;;;;;CASpB,QAAc;AACZ,QAAA,2BAAiC;;;;;;;;;;CAWnC,OAAO,OAAoB;AACzB,MAAI,MAAM,WAAW,YAAa;AAClC,MAAI,CAAC,gBAAgB,MAAM,OAAO,UAAU,CAAE;EAC9C,MAAM,YAAa,MAAyB,OAAO;EAGnD,MAAM,MAAM,OAAO,MAAM,QAAQ,WAAW,MAAM,MAAM,KAAA;AACxD,MAAI,WAAW,UAAU,WAAW;AAIlC,OAAI,OAAO,QAAQ,OAAO,MAAA,yBACxB;AAEF,SAAA,MAAY,UAAU,MACpB,EAAE,YAAY,IAAI;IAAE,GAAG;IAAG,WAAW;IAAM,CAC5C;AACD;;AAEF,MACE,WAAW,UAAU,eACrB,WAAW,UAAU,YACrB,WAAW,UAAU,iBACrB,WAAW,UAAU,aACrB;AACA,OAAI,OAAO,KACT,OAAA,2BAAiC,KAAK,IACpC,MAAA,0BACA,IACD;AAMH,oBAAiB;AACf,QAAI,MAAA,YAAkB,CAAE;AACxB,UAAA,MAAY,UAAU,MACpB,EAAE,YAAY;KAAE,GAAG;KAAG,WAAW;KAAO,GAAG,EAC5C;MACA,EAAE"}

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

@@ -0,0 +1,165 @@
+const require_store = require("./store.cjs");
+const require_namespace = require("./namespace.cjs");
+//#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 require_store.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(require_namespace.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 = require_namespace.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
+exports.MessageMetadataTracker = MessageMetadataTracker;
+
+//# sourceMappingURL=message-metadata-tracker.cjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"message-metadata-tracker.cjs","names":["StreamStore","#pendingCheckpointByNamespace","namespaceKey"],"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,IAAIA,cAAAA,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,IAAIE,kBAAAA,aAAa,UAAU,EAAE,SAAS;;;;;;;;;;;;;CAc3E,kBACE,WACgC;EAChC,MAAM,MAAMA,kBAAAA,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-metadata-tracker.d.cts

@@ -0,0 +1,24 @@
+//#region src/stream/message-metadata-tracker.d.ts
+/**
+ * Metadata tracked per message id. Surfaced to applications via
+ * `useMessageMetadata(stream, messageId)`.
+ */
+interface MessageMetadata {
+  /**
+   * Checkpoint id the message's *parent* was at when this message was
+   * observed. Drives fork / edit flows
+   * (`submit(input, { forkFrom: { checkpointId } })`).
+   *
+   * `undefined` when the message was observed without a paired
+   * checkpoint envelope (e.g. before checkpoints rolled out, or when
+   * the caller stripped them upstream).
+   */
+  readonly parentCheckpointId: string | undefined;
+}
+/**
+ * Read-only map exposed via {@link MessageMetadataTracker.store}.
+ */
+type MessageMetadataMap = ReadonlyMap<string, MessageMetadata>;
+//#endregion
+export { MessageMetadata, MessageMetadataMap };
+//# sourceMappingURL=message-metadata-tracker.d.cts.map

package/dist/stream/message-metadata-tracker.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"message-metadata-tracker.d.cts","names":[],"sources":["../../src/stream/message-metadata-tracker.ts"],"mappings":";;;;;UAqDiB,eAAA;;;;;;;;;;WAUN,kBAAA;AAAA;;;;KAMC,kBAAA,GAAqB,WAAA,SAAoB,eAAA"}

package/dist/stream/message-metadata-tracker.d.ts

@@ -0,0 +1,24 @@
+//#region src/stream/message-metadata-tracker.d.ts
+/**
+ * Metadata tracked per message id. Surfaced to applications via
+ * `useMessageMetadata(stream, messageId)`.
+ */
+interface MessageMetadata {
+  /**
+   * Checkpoint id the message's *parent* was at when this message was
+   * observed. Drives fork / edit flows
+   * (`submit(input, { forkFrom: { checkpointId } })`).
+   *
+   * `undefined` when the message was observed without a paired
+   * checkpoint envelope (e.g. before checkpoints rolled out, or when
+   * the caller stripped them upstream).
+   */
+  readonly parentCheckpointId: string | undefined;
+}
+/**
+ * Read-only map exposed via {@link MessageMetadataTracker.store}.
+ */
+type MessageMetadataMap = ReadonlyMap<string, MessageMetadata>;
+//#endregion
+export { MessageMetadata, MessageMetadataMap };
+//# sourceMappingURL=message-metadata-tracker.d.ts.map

package/dist/stream/message-metadata-tracker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"message-metadata-tracker.d.ts","names":[],"sources":["../../src/stream/message-metadata-tracker.ts"],"mappings":";;;;;UAqDiB,eAAA;;;;;;;;;;WAUN,kBAAA;AAAA;;;;KAMC,kBAAA,GAAqB,WAAA,SAAoB,eAAA"}