@langchain/langgraph 1.2.8 → 1.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (166) hide show
  1. package/dist/graph/graph.cjs +6 -2
  2. package/dist/graph/graph.cjs.map +1 -1
  3. package/dist/graph/graph.d.cts +58 -7
  4. package/dist/graph/graph.d.cts.map +1 -1
  5. package/dist/graph/graph.d.ts +58 -7
  6. package/dist/graph/graph.d.ts.map +1 -1
  7. package/dist/graph/graph.js +6 -2
  8. package/dist/graph/graph.js.map +1 -1
  9. package/dist/graph/index.d.ts +3 -3
  10. package/dist/graph/state.cjs +3 -2
  11. package/dist/graph/state.cjs.map +1 -1
  12. package/dist/graph/state.d.cts +14 -6
  13. package/dist/graph/state.d.cts.map +1 -1
  14. package/dist/graph/state.d.ts +14 -6
  15. package/dist/graph/state.d.ts.map +1 -1
  16. package/dist/graph/state.js +3 -2
  17. package/dist/graph/state.js.map +1 -1
  18. package/dist/index.cjs +34 -5
  19. package/dist/index.cjs.map +1 -1
  20. package/dist/index.d.cts +16 -6
  21. package/dist/index.d.ts +16 -6
  22. package/dist/index.js +10 -1
  23. package/dist/index.js.map +1 -1
  24. package/dist/prebuilt/agent_executor.d.cts +1 -1
  25. package/dist/prebuilt/agent_executor.d.ts +1 -1
  26. package/dist/pregel/algo.cjs +6 -3
  27. package/dist/pregel/algo.cjs.map +1 -1
  28. package/dist/pregel/algo.js +6 -3
  29. package/dist/pregel/algo.js.map +1 -1
  30. package/dist/pregel/index.cjs +96 -25
  31. package/dist/pregel/index.cjs.map +1 -1
  32. package/dist/pregel/index.d.cts +25 -3
  33. package/dist/pregel/index.d.cts.map +1 -1
  34. package/dist/pregel/index.d.ts +25 -3
  35. package/dist/pregel/index.d.ts.map +1 -1
  36. package/dist/pregel/index.js +97 -26
  37. package/dist/pregel/index.js.map +1 -1
  38. package/dist/pregel/loop.cjs +51 -10
  39. package/dist/pregel/loop.cjs.map +1 -1
  40. package/dist/pregel/loop.js +51 -10
  41. package/dist/pregel/loop.js.map +1 -1
  42. package/dist/pregel/messages-v2.cjs +231 -0
  43. package/dist/pregel/messages-v2.cjs.map +1 -0
  44. package/dist/pregel/messages-v2.js +231 -0
  45. package/dist/pregel/messages-v2.js.map +1 -0
  46. package/dist/pregel/messages.cjs +14 -10
  47. package/dist/pregel/messages.cjs.map +1 -1
  48. package/dist/pregel/messages.js +14 -10
  49. package/dist/pregel/messages.js.map +1 -1
  50. package/dist/pregel/remote.cjs +15 -0
  51. package/dist/pregel/remote.cjs.map +1 -1
  52. package/dist/pregel/remote.d.cts.map +1 -1
  53. package/dist/pregel/remote.d.ts.map +1 -1
  54. package/dist/pregel/remote.js +15 -0
  55. package/dist/pregel/remote.js.map +1 -1
  56. package/dist/pregel/stream.cjs.map +1 -1
  57. package/dist/pregel/stream.d.cts +30 -0
  58. package/dist/pregel/stream.d.cts.map +1 -0
  59. package/dist/pregel/stream.d.ts +30 -1
  60. package/dist/pregel/stream.d.ts.map +1 -0
  61. package/dist/pregel/stream.js.map +1 -1
  62. package/dist/pregel/types.cjs.map +1 -1
  63. package/dist/pregel/types.d.cts +8 -1
  64. package/dist/pregel/types.d.cts.map +1 -1
  65. package/dist/pregel/types.d.ts +8 -1
  66. package/dist/pregel/types.d.ts.map +1 -1
  67. package/dist/pregel/types.js.map +1 -1
  68. package/dist/pregel/utils/config.cjs +21 -4
  69. package/dist/pregel/utils/config.cjs.map +1 -1
  70. package/dist/pregel/utils/config.d.cts.map +1 -1
  71. package/dist/pregel/utils/config.d.ts.map +1 -1
  72. package/dist/pregel/utils/config.js +21 -5
  73. package/dist/pregel/utils/config.js.map +1 -1
  74. package/dist/pregel/utils/index.d.ts +0 -1
  75. package/dist/pregel/utils/index.d.ts.map +1 -1
  76. package/dist/state/index.d.ts +1 -1
  77. package/dist/state/schema.d.cts +1 -1
  78. package/dist/state/schema.d.ts +1 -1
  79. package/dist/stream/convert.cjs +207 -0
  80. package/dist/stream/convert.cjs.map +1 -0
  81. package/dist/stream/convert.d.cts +69 -0
  82. package/dist/stream/convert.d.cts.map +1 -0
  83. package/dist/stream/convert.d.ts +69 -0
  84. package/dist/stream/convert.d.ts.map +1 -0
  85. package/dist/stream/convert.js +206 -0
  86. package/dist/stream/convert.js.map +1 -0
  87. package/dist/stream/index.cjs +11 -0
  88. package/dist/stream/index.d.cts +12 -0
  89. package/dist/stream/index.d.ts +12 -0
  90. package/dist/stream/index.js +12 -0
  91. package/dist/stream/mux.cjs +350 -0
  92. package/dist/stream/mux.cjs.map +1 -0
  93. package/dist/stream/mux.d.cts +160 -0
  94. package/dist/stream/mux.d.cts.map +1 -0
  95. package/dist/stream/mux.d.ts +160 -0
  96. package/dist/stream/mux.d.ts.map +1 -0
  97. package/dist/stream/mux.js +345 -0
  98. package/dist/stream/mux.js.map +1 -0
  99. package/dist/stream/run-stream.cjs +439 -0
  100. package/dist/stream/run-stream.cjs.map +1 -0
  101. package/dist/stream/run-stream.d.cts +286 -0
  102. package/dist/stream/run-stream.d.cts.map +1 -0
  103. package/dist/stream/run-stream.d.ts +285 -0
  104. package/dist/stream/run-stream.d.ts.map +1 -0
  105. package/dist/stream/run-stream.js +434 -0
  106. package/dist/stream/run-stream.js.map +1 -0
  107. package/dist/stream/stream-channel.cjs +208 -0
  108. package/dist/stream/stream-channel.cjs.map +1 -0
  109. package/dist/stream/stream-channel.d.cts +129 -0
  110. package/dist/stream/stream-channel.d.cts.map +1 -0
  111. package/dist/stream/stream-channel.d.ts +129 -0
  112. package/dist/stream/stream-channel.d.ts.map +1 -0
  113. package/dist/stream/stream-channel.js +207 -0
  114. package/dist/stream/stream-channel.js.map +1 -0
  115. package/dist/stream/transformers/index.cjs +4 -0
  116. package/dist/stream/transformers/index.d.ts +5 -0
  117. package/dist/stream/transformers/index.js +5 -0
  118. package/dist/stream/transformers/lifecycle.cjs +326 -0
  119. package/dist/stream/transformers/lifecycle.cjs.map +1 -0
  120. package/dist/stream/transformers/lifecycle.d.cts +53 -0
  121. package/dist/stream/transformers/lifecycle.d.cts.map +1 -0
  122. package/dist/stream/transformers/lifecycle.d.ts +53 -0
  123. package/dist/stream/transformers/lifecycle.d.ts.map +1 -0
  124. package/dist/stream/transformers/lifecycle.js +325 -0
  125. package/dist/stream/transformers/lifecycle.js.map +1 -0
  126. package/dist/stream/transformers/messages.cjs +94 -0
  127. package/dist/stream/transformers/messages.cjs.map +1 -0
  128. package/dist/stream/transformers/messages.d.cts +23 -0
  129. package/dist/stream/transformers/messages.d.cts.map +1 -0
  130. package/dist/stream/transformers/messages.d.ts +23 -0
  131. package/dist/stream/transformers/messages.d.ts.map +1 -0
  132. package/dist/stream/transformers/messages.js +94 -0
  133. package/dist/stream/transformers/messages.js.map +1 -0
  134. package/dist/stream/transformers/subgraphs.cjs +125 -0
  135. package/dist/stream/transformers/subgraphs.cjs.map +1 -0
  136. package/dist/stream/transformers/subgraphs.d.cts +95 -0
  137. package/dist/stream/transformers/subgraphs.d.cts.map +1 -0
  138. package/dist/stream/transformers/subgraphs.d.ts +95 -0
  139. package/dist/stream/transformers/subgraphs.d.ts.map +1 -0
  140. package/dist/stream/transformers/subgraphs.js +124 -0
  141. package/dist/stream/transformers/subgraphs.js.map +1 -0
  142. package/dist/stream/transformers/types.d.cts +89 -0
  143. package/dist/stream/transformers/types.d.cts.map +1 -0
  144. package/dist/stream/transformers/types.d.ts +89 -0
  145. package/dist/stream/transformers/types.d.ts.map +1 -0
  146. package/dist/stream/transformers/values.cjs +39 -0
  147. package/dist/stream/transformers/values.cjs.map +1 -0
  148. package/dist/stream/transformers/values.d.cts +21 -0
  149. package/dist/stream/transformers/values.d.cts.map +1 -0
  150. package/dist/stream/transformers/values.d.ts +21 -0
  151. package/dist/stream/transformers/values.d.ts.map +1 -0
  152. package/dist/stream/transformers/values.js +39 -0
  153. package/dist/stream/transformers/values.js.map +1 -0
  154. package/dist/stream/types.cjs +11 -0
  155. package/dist/stream/types.cjs.map +1 -0
  156. package/dist/stream/types.d.cts +255 -0
  157. package/dist/stream/types.d.cts.map +1 -0
  158. package/dist/stream/types.d.ts +255 -0
  159. package/dist/stream/types.d.ts.map +1 -0
  160. package/dist/stream/types.js +11 -0
  161. package/dist/stream/types.js.map +1 -0
  162. package/dist/web.cjs +39 -9
  163. package/dist/web.d.cts +16 -6
  164. package/dist/web.d.ts +16 -6
  165. package/dist/web.js +10 -1
  166. package/package.json +9 -8
@@ -0,0 +1,89 @@
1
+ import { ChatModelStreamHandle, Namespace } from "../types.cjs";
2
+ import { StreamChannel } from "../stream-channel.cjs";
3
+ import { AgentStatus, LifecycleData } from "@langchain/protocol";
4
+
5
+ //#region src/stream/transformers/types.d.ts
6
+ /**
7
+ * The projection shape merged into a run stream by the messages transformer.
8
+ * Exposes a `messages` async iterable that yields one message stream handle
9
+ * per AI message lifecycle observed during the run.
10
+ */
11
+ interface MessagesTransformerProjection {
12
+ messages: AsyncIterable<ChatModelStreamHandle>;
13
+ }
14
+ /**
15
+ * The projection shape merged into a run stream by the values transformer.
16
+ * Exposes the underlying local {@link StreamChannel} so that `StreamMux` can
17
+ * resolve the final output value on close.
18
+ */
19
+ interface ValuesTransformerProjection {
20
+ _valuesLog: StreamChannel<Record<string, unknown>>;
21
+ }
22
+ /**
23
+ * Single lifecycle entry surfaced by the in-process
24
+ * `GraphRunStream.lifecycle` projection. Combines the CDDL
25
+ * {@link LifecycleData} payload with the namespace it applies to so
26
+ * consumers can filter or correlate without dipping into raw
27
+ * `ProtocolEvent`s.
28
+ */
29
+ interface LifecycleEntry extends LifecycleData {
30
+ /** Namespace the lifecycle event applies to. */
31
+ readonly namespace: Namespace;
32
+ /** Wall-clock timestamp (milliseconds) of the emission. */
33
+ readonly timestamp: number;
34
+ }
35
+ /**
36
+ * Configuration knobs for {@link createLifecycleTransformer}.
37
+ */
38
+ interface LifecycleTransformerOptions {
39
+ /**
40
+ * Human-readable name for the root graph. Used as `graph_name` for
41
+ * the root lifecycle event.
42
+ *
43
+ * @defaultValue `"root"`
44
+ */
45
+ rootGraphName?: string;
46
+ /**
47
+ * Lifecycle status emitted for the root namespace when
48
+ * {@link LifecycleTransformerOptions.emitRootOnRegister} is `true`.
49
+ *
50
+ * @defaultValue `"running"`
51
+ */
52
+ initialStatus?: AgentStatus;
53
+ /**
54
+ * When `true`, the transformer emits the root `lifecycle.started` (or
55
+ * `.running`) event synchronously from `onRegister` and emits the
56
+ * terminal root event from `finalize`/`fail`. Set to `false` when an
57
+ * outer authority (e.g. `RunProtocolSession`) is responsible for
58
+ * root lifecycle emission; in that case the transformer still tracks
59
+ * root status internally for cascade purposes but does not write to
60
+ * the wire.
61
+ *
62
+ * @defaultValue `true`
63
+ */
64
+ emitRootOnRegister?: boolean;
65
+ /**
66
+ * Resolves a human-readable graph name for a non-root namespace.
67
+ * The default uses the last segment of the namespace, stripping any
68
+ * `:suffix` (e.g. `["tools:abc"]` -> `"tools"`).
69
+ */
70
+ getGraphName?: (ns: Namespace) => string;
71
+ /**
72
+ * Optional async hook consulted by `finalize()` to override the
73
+ * computed terminal status. Returning a status here wins over the
74
+ * pending-interrupt heuristic. Useful for carriers (like the API
75
+ * session) that have authoritative knowledge of thread state.
76
+ */
77
+ getTerminalStatusOverride?: () => Promise<AgentStatus | undefined>;
78
+ /**
79
+ * Converts an unknown failure value to a string for the
80
+ * `lifecycle.failed` `error` field.
81
+ *
82
+ * @defaultValue a default implementation that handles `Error` and
83
+ * primitives.
84
+ */
85
+ serializeError?: (err: unknown) => string;
86
+ }
87
+ //#endregion
88
+ export { LifecycleEntry, LifecycleTransformerOptions, MessagesTransformerProjection, ValuesTransformerProjection };
89
+ //# sourceMappingURL=types.d.cts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"types.d.cts","names":[],"sources":["../../../src/stream/transformers/types.ts"],"mappings":";;;;;;;AAUA;;;UAAiB,6BAAA;EACf,QAAA,EAAU,aAAA,CAAc,qBAAA;AAAA;;;;AAQ1B;;UAAiB,2BAAA;EACf,UAAA,EAAY,aAAA,CAAc,MAAA;AAAA;;;;;AAU5B;;;UAAiB,cAAA,SAAuB,aAAA;EAAA;EAAA,SAE7B,SAAA,EAAW,SAAA;EAAA;EAAA,SAEX,SAAA;AAAA;;AAMX;;UAAiB,2BAAA;EAeC;;;;;;EARhB,aAAA;EAQA;;;;;;EAAA,aAAA,GAAgB,WAAA;EA4BkB;;;;;;;;;;;EAflC,kBAAA;;;;;;EAOA,YAAA,IAAgB,EAAA,EAAI,SAAA;;;;;;;EAQpB,yBAAA,SAAkC,OAAA,CAAQ,WAAA;;;;;;;;EAS1C,cAAA,IAAkB,GAAA;AAAA"}
@@ -0,0 +1,89 @@
1
+ import { ChatModelStreamHandle, Namespace } from "../types.js";
2
+ import { StreamChannel } from "../stream-channel.js";
3
+ import { AgentStatus, LifecycleData } from "@langchain/protocol";
4
+
5
+ //#region src/stream/transformers/types.d.ts
6
+ /**
7
+ * The projection shape merged into a run stream by the messages transformer.
8
+ * Exposes a `messages` async iterable that yields one message stream handle
9
+ * per AI message lifecycle observed during the run.
10
+ */
11
+ interface MessagesTransformerProjection {
12
+ messages: AsyncIterable<ChatModelStreamHandle>;
13
+ }
14
+ /**
15
+ * The projection shape merged into a run stream by the values transformer.
16
+ * Exposes the underlying local {@link StreamChannel} so that `StreamMux` can
17
+ * resolve the final output value on close.
18
+ */
19
+ interface ValuesTransformerProjection {
20
+ _valuesLog: StreamChannel<Record<string, unknown>>;
21
+ }
22
+ /**
23
+ * Single lifecycle entry surfaced by the in-process
24
+ * `GraphRunStream.lifecycle` projection. Combines the CDDL
25
+ * {@link LifecycleData} payload with the namespace it applies to so
26
+ * consumers can filter or correlate without dipping into raw
27
+ * `ProtocolEvent`s.
28
+ */
29
+ interface LifecycleEntry extends LifecycleData {
30
+ /** Namespace the lifecycle event applies to. */
31
+ readonly namespace: Namespace;
32
+ /** Wall-clock timestamp (milliseconds) of the emission. */
33
+ readonly timestamp: number;
34
+ }
35
+ /**
36
+ * Configuration knobs for {@link createLifecycleTransformer}.
37
+ */
38
+ interface LifecycleTransformerOptions {
39
+ /**
40
+ * Human-readable name for the root graph. Used as `graph_name` for
41
+ * the root lifecycle event.
42
+ *
43
+ * @defaultValue `"root"`
44
+ */
45
+ rootGraphName?: string;
46
+ /**
47
+ * Lifecycle status emitted for the root namespace when
48
+ * {@link LifecycleTransformerOptions.emitRootOnRegister} is `true`.
49
+ *
50
+ * @defaultValue `"running"`
51
+ */
52
+ initialStatus?: AgentStatus;
53
+ /**
54
+ * When `true`, the transformer emits the root `lifecycle.started` (or
55
+ * `.running`) event synchronously from `onRegister` and emits the
56
+ * terminal root event from `finalize`/`fail`. Set to `false` when an
57
+ * outer authority (e.g. `RunProtocolSession`) is responsible for
58
+ * root lifecycle emission; in that case the transformer still tracks
59
+ * root status internally for cascade purposes but does not write to
60
+ * the wire.
61
+ *
62
+ * @defaultValue `true`
63
+ */
64
+ emitRootOnRegister?: boolean;
65
+ /**
66
+ * Resolves a human-readable graph name for a non-root namespace.
67
+ * The default uses the last segment of the namespace, stripping any
68
+ * `:suffix` (e.g. `["tools:abc"]` -> `"tools"`).
69
+ */
70
+ getGraphName?: (ns: Namespace) => string;
71
+ /**
72
+ * Optional async hook consulted by `finalize()` to override the
73
+ * computed terminal status. Returning a status here wins over the
74
+ * pending-interrupt heuristic. Useful for carriers (like the API
75
+ * session) that have authoritative knowledge of thread state.
76
+ */
77
+ getTerminalStatusOverride?: () => Promise<AgentStatus | undefined>;
78
+ /**
79
+ * Converts an unknown failure value to a string for the
80
+ * `lifecycle.failed` `error` field.
81
+ *
82
+ * @defaultValue a default implementation that handles `Error` and
83
+ * primitives.
84
+ */
85
+ serializeError?: (err: unknown) => string;
86
+ }
87
+ //#endregion
88
+ export { LifecycleEntry, LifecycleTransformerOptions, MessagesTransformerProjection, ValuesTransformerProjection };
89
+ //# sourceMappingURL=types.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"types.d.ts","names":[],"sources":["../../../src/stream/transformers/types.ts"],"mappings":";;;;;;;AAUA;;;UAAiB,6BAAA;EACf,QAAA,EAAU,aAAA,CAAc,qBAAA;AAAA;;;;AAQ1B;;UAAiB,2BAAA;EACf,UAAA,EAAY,aAAA,CAAc,MAAA;AAAA;;;;;AAU5B;;;UAAiB,cAAA,SAAuB,aAAA;EAAA;EAAA,SAE7B,SAAA,EAAW,SAAA;EAAA;EAAA,SAEX,SAAA;AAAA;;AAMX;;UAAiB,2BAAA;EAeC;;;;;;EARhB,aAAA;EAQA;;;;;;EAAA,aAAA,GAAgB,WAAA;EA4BkB;;;;;;;;;;;EAflC,kBAAA;;;;;;EAOA,YAAA,IAAgB,EAAA,EAAI,SAAA;;;;;;;EAQpB,yBAAA,SAAkC,OAAA,CAAQ,WAAA;;;;;;;;EAS1C,cAAA,IAAkB,GAAA;AAAA"}
@@ -0,0 +1,39 @@
1
+ const require_stream_channel = require("../stream-channel.cjs");
2
+ const require_mux = require("../mux.cjs");
3
+ //#region src/stream/transformers/values.ts
4
+ /**
5
+ * Creates a {@link StreamTransformer} that captures `values` channel events
6
+ * into a local {@link StreamChannel}. Only events whose namespace exactly
7
+ * matches {@link path} are recorded; events from child or sibling namespaces
8
+ * are ignored.
9
+ *
10
+ * The final snapshot is resolved by {@link StreamMux.close} directly;
11
+ * this transformer only accumulates intermediate values.
12
+ *
13
+ * @param path - Namespace prefix to match against incoming events.
14
+ * @returns A `StreamTransformer` whose projection contains the internal
15
+ * `_valuesLog` local channel.
16
+ */
17
+ function createValuesTransformer(path) {
18
+ const valuesLog = require_stream_channel.StreamChannel.local();
19
+ return {
20
+ init: () => ({ _valuesLog: valuesLog }),
21
+ process(event) {
22
+ if (event.method !== "values") return true;
23
+ if (event.params.namespace.length !== path.length) return true;
24
+ if (!require_mux.hasPrefix(event.params.namespace, path)) return true;
25
+ valuesLog.push(event.params.data);
26
+ return true;
27
+ },
28
+ finalize() {
29
+ valuesLog.close();
30
+ },
31
+ fail(err) {
32
+ valuesLog.fail(err);
33
+ }
34
+ };
35
+ }
36
+ //#endregion
37
+ exports.createValuesTransformer = createValuesTransformer;
38
+
39
+ //# sourceMappingURL=values.cjs.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"values.cjs","names":["StreamChannel","hasPrefix"],"sources":["../../../src/stream/transformers/values.ts"],"sourcesContent":["import { hasPrefix } from \"../mux.js\";\nimport { StreamChannel } from \"../stream-channel.js\";\nimport type { Namespace, ProtocolEvent, StreamTransformer } from \"../types.js\";\nimport type { ValuesTransformerProjection } from \"./types.js\";\n\n/**\n * Creates a {@link StreamTransformer} that captures `values` channel events\n * into a local {@link StreamChannel}. Only events whose namespace exactly\n * matches {@link path} are recorded; events from child or sibling namespaces\n * are ignored.\n *\n * The final snapshot is resolved by {@link StreamMux.close} directly;\n * this transformer only accumulates intermediate values.\n *\n * @param path - Namespace prefix to match against incoming events.\n * @returns A `StreamTransformer` whose projection contains the internal\n * `_valuesLog` local channel.\n */\nexport function createValuesTransformer(\n path: Namespace\n): StreamTransformer<ValuesTransformerProjection> {\n const valuesLog = StreamChannel.local<Record<string, unknown>>();\n\n return {\n init: () => ({ _valuesLog: valuesLog }),\n\n process(event: ProtocolEvent): boolean {\n if (event.method !== \"values\") return true;\n if (event.params.namespace.length !== path.length) return true;\n if (!hasPrefix(event.params.namespace, path)) return true;\n valuesLog.push(event.params.data as Record<string, unknown>);\n return true;\n },\n\n finalize(): void {\n valuesLog.close();\n },\n\n fail(err: unknown): void {\n valuesLog.fail(err);\n },\n };\n}\n"],"mappings":";;;;;;;;;;;;;;;;AAkBA,SAAgB,wBACd,MACgD;CAChD,MAAM,YAAYA,uBAAAA,cAAc,OAAgC;AAEhE,QAAO;EACL,aAAa,EAAE,YAAY,WAAW;EAEtC,QAAQ,OAA+B;AACrC,OAAI,MAAM,WAAW,SAAU,QAAO;AACtC,OAAI,MAAM,OAAO,UAAU,WAAW,KAAK,OAAQ,QAAO;AAC1D,OAAI,CAACC,YAAAA,UAAU,MAAM,OAAO,WAAW,KAAK,CAAE,QAAO;AACrD,aAAU,KAAK,MAAM,OAAO,KAAgC;AAC5D,UAAO;;EAGT,WAAiB;AACf,aAAU,OAAO;;EAGnB,KAAK,KAAoB;AACvB,aAAU,KAAK,IAAI;;EAEtB"}
@@ -0,0 +1,21 @@
1
+ import { Namespace, StreamTransformer } from "../types.cjs";
2
+ import { ValuesTransformerProjection } from "./types.cjs";
3
+
4
+ //#region src/stream/transformers/values.d.ts
5
+ /**
6
+ * Creates a {@link StreamTransformer} that captures `values` channel events
7
+ * into a local {@link StreamChannel}. Only events whose namespace exactly
8
+ * matches {@link path} are recorded; events from child or sibling namespaces
9
+ * are ignored.
10
+ *
11
+ * The final snapshot is resolved by {@link StreamMux.close} directly;
12
+ * this transformer only accumulates intermediate values.
13
+ *
14
+ * @param path - Namespace prefix to match against incoming events.
15
+ * @returns A `StreamTransformer` whose projection contains the internal
16
+ * `_valuesLog` local channel.
17
+ */
18
+ declare function createValuesTransformer(path: Namespace): StreamTransformer<ValuesTransformerProjection>;
19
+ //#endregion
20
+ export { createValuesTransformer };
21
+ //# sourceMappingURL=values.d.cts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"values.d.cts","names":[],"sources":["../../../src/stream/transformers/values.ts"],"mappings":";;;;;;AAkBA;;;;;;;;;;;iBAAgB,uBAAA,CACd,IAAA,EAAM,SAAA,GACL,iBAAA,CAAkB,2BAAA"}
@@ -0,0 +1,21 @@
1
+ import { Namespace, StreamTransformer } from "../types.js";
2
+ import { ValuesTransformerProjection } from "./types.js";
3
+
4
+ //#region src/stream/transformers/values.d.ts
5
+ /**
6
+ * Creates a {@link StreamTransformer} that captures `values` channel events
7
+ * into a local {@link StreamChannel}. Only events whose namespace exactly
8
+ * matches {@link path} are recorded; events from child or sibling namespaces
9
+ * are ignored.
10
+ *
11
+ * The final snapshot is resolved by {@link StreamMux.close} directly;
12
+ * this transformer only accumulates intermediate values.
13
+ *
14
+ * @param path - Namespace prefix to match against incoming events.
15
+ * @returns A `StreamTransformer` whose projection contains the internal
16
+ * `_valuesLog` local channel.
17
+ */
18
+ declare function createValuesTransformer(path: Namespace): StreamTransformer<ValuesTransformerProjection>;
19
+ //#endregion
20
+ export { createValuesTransformer };
21
+ //# sourceMappingURL=values.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"values.d.ts","names":[],"sources":["../../../src/stream/transformers/values.ts"],"mappings":";;;;;;AAkBA;;;;;;;;;;;iBAAgB,uBAAA,CACd,IAAA,EAAM,SAAA,GACL,iBAAA,CAAkB,2BAAA"}
@@ -0,0 +1,39 @@
1
+ import { StreamChannel } from "../stream-channel.js";
2
+ import { hasPrefix } from "../mux.js";
3
+ //#region src/stream/transformers/values.ts
4
+ /**
5
+ * Creates a {@link StreamTransformer} that captures `values` channel events
6
+ * into a local {@link StreamChannel}. Only events whose namespace exactly
7
+ * matches {@link path} are recorded; events from child or sibling namespaces
8
+ * are ignored.
9
+ *
10
+ * The final snapshot is resolved by {@link StreamMux.close} directly;
11
+ * this transformer only accumulates intermediate values.
12
+ *
13
+ * @param path - Namespace prefix to match against incoming events.
14
+ * @returns A `StreamTransformer` whose projection contains the internal
15
+ * `_valuesLog` local channel.
16
+ */
17
+ function createValuesTransformer(path) {
18
+ const valuesLog = StreamChannel.local();
19
+ return {
20
+ init: () => ({ _valuesLog: valuesLog }),
21
+ process(event) {
22
+ if (event.method !== "values") return true;
23
+ if (event.params.namespace.length !== path.length) return true;
24
+ if (!hasPrefix(event.params.namespace, path)) return true;
25
+ valuesLog.push(event.params.data);
26
+ return true;
27
+ },
28
+ finalize() {
29
+ valuesLog.close();
30
+ },
31
+ fail(err) {
32
+ valuesLog.fail(err);
33
+ }
34
+ };
35
+ }
36
+ //#endregion
37
+ export { createValuesTransformer };
38
+
39
+ //# sourceMappingURL=values.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"values.js","names":[],"sources":["../../../src/stream/transformers/values.ts"],"sourcesContent":["import { hasPrefix } from \"../mux.js\";\nimport { StreamChannel } from \"../stream-channel.js\";\nimport type { Namespace, ProtocolEvent, StreamTransformer } from \"../types.js\";\nimport type { ValuesTransformerProjection } from \"./types.js\";\n\n/**\n * Creates a {@link StreamTransformer} that captures `values` channel events\n * into a local {@link StreamChannel}. Only events whose namespace exactly\n * matches {@link path} are recorded; events from child or sibling namespaces\n * are ignored.\n *\n * The final snapshot is resolved by {@link StreamMux.close} directly;\n * this transformer only accumulates intermediate values.\n *\n * @param path - Namespace prefix to match against incoming events.\n * @returns A `StreamTransformer` whose projection contains the internal\n * `_valuesLog` local channel.\n */\nexport function createValuesTransformer(\n path: Namespace\n): StreamTransformer<ValuesTransformerProjection> {\n const valuesLog = StreamChannel.local<Record<string, unknown>>();\n\n return {\n init: () => ({ _valuesLog: valuesLog }),\n\n process(event: ProtocolEvent): boolean {\n if (event.method !== \"values\") return true;\n if (event.params.namespace.length !== path.length) return true;\n if (!hasPrefix(event.params.namespace, path)) return true;\n valuesLog.push(event.params.data as Record<string, unknown>);\n return true;\n },\n\n finalize(): void {\n valuesLog.close();\n },\n\n fail(err: unknown): void {\n valuesLog.fail(err);\n },\n };\n}\n"],"mappings":";;;;;;;;;;;;;;;;AAkBA,SAAgB,wBACd,MACgD;CAChD,MAAM,YAAY,cAAc,OAAgC;AAEhE,QAAO;EACL,aAAa,EAAE,YAAY,WAAW;EAEtC,QAAQ,OAA+B;AACrC,OAAI,MAAM,WAAW,SAAU,QAAO;AACtC,OAAI,MAAM,OAAO,UAAU,WAAW,KAAK,OAAQ,QAAO;AAC1D,OAAI,CAAC,UAAU,MAAM,OAAO,WAAW,KAAK,CAAE,QAAO;AACrD,aAAU,KAAK,MAAM,OAAO,KAAgC;AAC5D,UAAO;;EAGT,WAAiB;AACf,aAAU,OAAO;;EAGnB,KAAK,KAAoB;AACvB,aAAU,KAAK,IAAI;;EAEtB"}
@@ -0,0 +1,11 @@
1
+ //#region src/stream/types.ts
2
+ /**
3
+ * Type guard that tests whether a transformer is a {@link NativeStreamTransformer}.
4
+ */
5
+ function isNativeTransformer(t) {
6
+ return "__native" in t && t.__native === true;
7
+ }
8
+ //#endregion
9
+ exports.isNativeTransformer = isNativeTransformer;
10
+
11
+ //# sourceMappingURL=types.cjs.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"types.cjs","names":[],"sources":["../../src/stream/types.ts"],"sourcesContent":["/**\n * Core type definitions for the v2 streaming interface.\n *\n * Channel event data types (`MessagesEventData`, `ToolsEventData`,\n * `UpdatesEventData`, `UsageInfo`, `Checkpoint`, `CheckpointSource`) are\n * re-exported from `@langchain/protocol` — the generated TypeScript\n * bindings for the canonical CDDL schema. Stream-specific types\n * (`StreamTransformer`, `ChatModelStream`, `ToolCallStream`,\n * `InterruptPayload`) are defined here.\n */\n\nimport type { ChatModelStream as CoreChatModelStream } from \"@langchain/core/language_models/stream\";\nimport type { ChatModelStreamEvent as CoreChatModelStreamEvent } from \"@langchain/core/language_models/event\";\nimport type { StreamMode } from \"../pregel/types.js\";\n\n/**\n * Re-exports from `@langchain/protocol`.\n *\n * These are the canonical wire-format types generated from `protocol.cddl`.\n * They are re-exported with local aliases so that consumers of this module\n * do not need a direct dependency on `@langchain/protocol`.\n */\nexport type {\n MessagesData as MessagesEventData,\n ToolsData as ToolsEventData,\n UpdatesData as UpdatesEventData,\n UsageInfo,\n MessageStartData,\n ContentBlockStartData,\n ContentBlockDeltaData,\n ContentBlockFinishData,\n MessageFinishData,\n MessageErrorData,\n ToolStartedData,\n ToolOutputDeltaData,\n ToolFinishedData,\n ToolErrorData,\n Checkpoint,\n CheckpointSource,\n AgentStatus,\n LifecycleData,\n LifecycleCause,\n} from \"@langchain/protocol\";\n\n/**\n * Hierarchical path identifying a position in the agent tree.\n *\n * Each element is one segment; longer arrays mean deeper nesting (e.g.\n * subgraph or multi-agent scopes).\n */\nexport type Namespace = string[];\n\n/**\n * Channels that can appear on a protocol event. Beyond the raw\n * {@link StreamMode} channels emitted by the Pregel stream, the v2\n * protocol layer synthesizes additional channels (e.g. `lifecycle`,\n * `input`) via built-in {@link StreamTransformer}s and exposes\n * user-defined channels created with {@link StreamChannel}.\n */\nexport type ProtocolMethod = StreamMode | \"lifecycle\" | \"input\" | (string & {});\n\n/**\n * Single envelope for a streaming protocol emission: sequence, channel\n * (`method`), and payload (`params`).\n */\nexport interface ProtocolEvent {\n /** Discriminator; always `\"event\"` for this shape. */\n readonly type: \"event\";\n\n /** Monotonic sequence number for ordering and deduplication within a run. */\n readonly seq: number;\n\n /**\n * Logical stream channel. Built-in channels match {@link StreamMode}\n * (e.g. `messages`, `updates`); transformer-synthesized channels\n * include `lifecycle` and `input`; user-defined channels carry their\n * {@link StreamChannel.channelName}.\n */\n readonly method: ProtocolMethod;\n\n /** Channel-specific payload and routing metadata. */\n readonly params: {\n /** Namespace of the node or scope that emitted this event. */\n readonly namespace: Namespace;\n\n /** Wall-clock or logical timestamp for the emission (milliseconds). */\n readonly timestamp: number;\n\n /**\n * Graph node id when the engine can attribute the event to a single node;\n * omitted for run-level or ambiguous emissions.\n */\n readonly node?: string;\n\n /** Opaque channel payload; shape depends on `method`. */\n readonly data: unknown;\n };\n}\n\n/**\n * Infers the merged extensions type from a tuple of transformer factory functions.\n *\n * Given `[() => StreamTransformer<{ a: number }>, () => StreamTransformer<{ b: string }>]`,\n * produces `{ a: number } & { b: string }`.\n */\nexport type InferExtensions<\n // eslint-disable-next-line @typescript-eslint/no-explicit-any\n T extends ReadonlyArray<() => StreamTransformer<any>>,\n> = T extends readonly []\n ? Record<string, never>\n : T extends readonly [\n () => StreamTransformer<infer P>,\n // eslint-disable-next-line @typescript-eslint/no-explicit-any\n ...infer Rest extends ReadonlyArray<() => StreamTransformer<any>>,\n ]\n ? P & InferExtensions<Rest>\n : Record<string, unknown>;\n\n/**\n * Observes {@link ProtocolEvent}s during a graph run and builds typed derived\n * projections (secondary event logs, promises, etc.).\n *\n * Data is surfaced to consumers through **projections** returned from\n * `init()`. Projections are merged into `GraphRunStream.extensions` for\n * in-process consumers. Use {@link StreamChannel.local} for local streaming\n * values, {@link StreamChannel.remote} for values that should also be visible\n * to remote clients, or `Promise<T>` for final values.\n *\n * To make projection data available to **remote** clients (SDK consumers\n * over WebSocket / SSE), create a named channel with\n * `StreamChannel.remote(name)`. The {@link StreamMux} detects named\n * `StreamChannel` instances in the `init()` return and auto-forwards every\n * `push()` as a {@link ProtocolEvent} on the channel's named method. Remote\n * clients subscribe via `session.subscribe(\"custom:<name>\")`.\n *\n * `finalize` and `fail` are optional. When a transformer uses\n * `StreamChannel`, the mux auto-closes/fails the channels on run\n * completion — no manual lifecycle management needed. Implement\n * `finalize`/`fail` only for non-channel teardown (e.g. resolving a\n * `Promise`).\n *\n * @typeParam TProjection - Shape returned by {@link init}, merged into\n * `GraphRunStream.extensions`.\n */\nexport interface StreamTransformer<TProjection = unknown> {\n /**\n * Called once before the run starts.\n *\n * @returns Initial projection merged into `GraphRunStream.extensions`.\n * Any named {@link StreamChannel} instances in the return value are\n * automatically wired to the protocol event stream by the mux. Unnamed\n * channels stay in-process-only.\n */\n init(): TProjection;\n\n /**\n * Optional hook invoked by {@link StreamMux.addTransformer} immediately\n * after the transformer is attached to the mux. Receives a limited\n * handle that exposes only {@link StreamEmitter.push} — enough for\n * the transformer to emit synthesized {@link ProtocolEvent}s on any\n * namespace it chooses (e.g. a deepagents `SubagentTransformer`\n * fabricating `lifecycle`/`messages`/`values` events under a\n * `[\"tools:<tool_call_id>\"]` namespace when a `task` tool starts).\n *\n * Transformers that do not synthesize events can omit this hook.\n *\n * The {@link StreamEmitter} handle is only safe to call *from within*\n * {@link StreamTransformer.process}. Emitting from an unrelated async\n * context (e.g. after `process` has returned, from a `setTimeout`,\n * etc.) races with the mux's close/fail cycle and may land events in\n * an already-closed log.\n */\n onRegister?(emitter: StreamEmitter): void;\n\n /**\n * Called for each {@link ProtocolEvent} before it is appended to the main log.\n *\n * @param event - Next protocol envelope for this run.\n * @returns `false` to drop the original event from the main log (use\n * sparingly; prefer keeping events visible and adding derived data\n * alongside).\n */\n process(event: ProtocolEvent): boolean;\n\n /**\n * Called once when the underlying Pregel run completes without throwing.\n * Optional — only needed for non-channel teardown (e.g. resolving promises).\n *\n * May return a `PromiseLike<void>` to defer the main event log close\n * until the async work (e.g. emitting terminal lifecycle events) has\n * completed. The mux awaits all returned promises before closing its\n * event log.\n */\n finalize?(): void | PromiseLike<void>;\n\n /**\n * Called once when the run fails; `err` is the rejection or error value.\n * Optional — only needed for non-channel teardown (e.g. rejecting promises).\n *\n * @param err - Failure reason from the engine or user code.\n */\n fail?(err: unknown): void;\n}\n\n/**\n * Narrow capability handle passed to\n * {@link StreamTransformer.onRegister}. Exposes only the minimal mux\n * surface required for synthetic event emission — intentionally does\n * not expose close/fail/register/etc. to keep the transformer contract\n * small and tamper-resistant.\n */\nexport interface StreamEmitter {\n /**\n * Injects a new {@link ProtocolEvent} into the mux pipeline. The\n * event is routed through every registered transformer (including\n * the emitting transformer — implementers must guard against\n * re-entrant self-processing) and, if not suppressed, appended to\n * the main event log.\n *\n * @param ns - Target namespace for the synthetic event.\n * @param event - The event envelope to inject. ``event.seq`` is\n * overwritten by the mux; callers can pass any placeholder.\n */\n push(ns: Namespace, event: ProtocolEvent): void;\n}\n\nexport type ChatModelStream = Omit<\n CoreChatModelStream,\n typeof Symbol.asyncIterator\n> & {\n /** Namespace of the graph node that produced this stream. */\n readonly namespace: Namespace;\n\n /** Graph node id for this stream, if the runtime attributed it. */\n readonly node: string | undefined;\n\n /**\n * Low-level async iteration over message lifecycle events.\n *\n * @returns Iterator yielding Core-compatible chat model stream events.\n */\n [Symbol.asyncIterator](): AsyncIterator<CoreChatModelStreamEvent>;\n};\n\n/**\n * Public view yielded by `run.messages`.\n *\n * `ChatModelStream` is PromiseLike to mirror Core, but TypeScript applies\n * `Awaited<T>` to values produced by `for await`. Exposing a non-thenable view\n * keeps loop variables typed as the streaming handle instead of `AIMessage`.\n */\nexport type ChatModelStreamHandle = Omit<ChatModelStream, \"then\">;\n\n/**\n * High-level outcome of a single tool call for UI or aggregators.\n */\nexport type ToolCallStatus =\n /** Invocation in flight or output still streaming. */\n | \"running\"\n /** Completed without error. */\n | \"finished\"\n /** Failed or aborted; see {@link ToolCallStream.error}. */\n | \"error\";\n\n/**\n * Stable handle for one tool call: name, arguments, and async results.\n *\n * Emitted when `content-block-finish` delivers a finalized `tool_call` block.\n *\n * @typeParam TName - Registered tool name.\n * @typeParam TInput - Parsed or raw input type for the call.\n * @typeParam TOutput - Successful result type after the tool returns.\n */\nexport interface ToolCallStream<\n TName extends string = string,\n TInput = unknown,\n TOutput = unknown,\n> {\n /** Tool identifier as registered on the graph or model schema. */\n readonly name: TName;\n\n /** Correlates with protocol `toolCallId` when the runtime provides one. */\n readonly callId: string;\n\n /** Arguments passed to the tool (finalized when the call is observable). */\n readonly input: TInput;\n\n /**\n * Resolves to the tool return value on success.\n *\n * @remarks\n * Rejection or hang semantics depend on the runner; pairing with\n * {@link ToolCallStream.status} and {@link ToolCallStream.error} is recommended.\n */\n readonly output: Promise<TOutput>;\n\n /**\n * Resolves to {@link ToolCallStatus} when the call leaves the running state.\n */\n readonly status: Promise<ToolCallStatus>;\n\n /**\n * Resolves to an error message string if {@link ToolCallStream.status} is\n * `\"error\"`, otherwise `undefined`.\n */\n readonly error: Promise<string | undefined>;\n}\n\n/**\n * Marker interface for transformers provided by internal LangChain products\n * (e.g. ReactAgent's ToolCallTransformer, DeepAgent's SubagentTransformer).\n *\n * Native transformers differ from user-defined extension transformers in\n * where their projection lands on the run stream:\n *\n * - **Native** — projections become direct getters on a\n * `GraphRunStream` subclass (e.g. `run.toolCalls`, `run.subagents`).\n * They emit events on protocol-defined channels (`tools`, `lifecycle`,\n * `tasks`, etc.).\n *\n * - **Extension** (user-defined) — projections are merged into\n * `run.extensions`. Events emitted via `emit()` use an\n * application-chosen method name (e.g. `emit(\"a2a\", data)`) and are\n * accessible to remote clients via `session.subscribe(\"custom:<name>\")`.\n *\n * The `__native` brand is used by downstream stream factory functions\n * to distinguish native transformers from extension transformers at\n * registration time. See `docs/native-stream-transformers.md` for the\n * full pattern.\n */\nexport interface NativeStreamTransformer<\n TProjection = unknown,\n> extends StreamTransformer<TProjection> {\n readonly __native: true;\n}\n\n/**\n * Type guard that tests whether a transformer is a {@link NativeStreamTransformer}.\n */\nexport function isNativeTransformer(\n t: StreamTransformer<unknown>\n): t is NativeStreamTransformer {\n return \"__native\" in t && (t as NativeStreamTransformer).__native === true;\n}\n\n/**\n * Human-in-the-loop interrupt: stable id plus opaque payload for resume UIs.\n */\nexport interface InterruptPayload<TPayload = unknown> {\n /** Idempotent key for this interrupt instance within the run. */\n interruptId: string;\n\n /** Arbitrary data supplied by the graph (e.g. questions, draft state). */\n payload: TPayload;\n}\n"],"mappings":";;;;AAmVA,SAAgB,oBACd,GAC8B;AAC9B,QAAO,cAAc,KAAM,EAA8B,aAAa"}
@@ -0,0 +1,255 @@
1
+ import { StreamMode } from "../pregel/types.cjs";
2
+ import { ChatModelStream } from "@langchain/core/language_models/stream";
3
+ import { ChatModelStreamEvent } from "@langchain/core/language_models/event";
4
+ import { AgentStatus as AgentStatus$1, Checkpoint, LifecycleCause, LifecycleData as LifecycleData$1, MessagesData as MessagesEventData, ToolsData as ToolsEventData, UpdatesData as UpdatesEventData, UsageInfo } from "@langchain/protocol";
5
+
6
+ //#region src/stream/types.d.ts
7
+ /**
8
+ * Hierarchical path identifying a position in the agent tree.
9
+ *
10
+ * Each element is one segment; longer arrays mean deeper nesting (e.g.
11
+ * subgraph or multi-agent scopes).
12
+ */
13
+ type Namespace = string[];
14
+ /**
15
+ * Channels that can appear on a protocol event. Beyond the raw
16
+ * {@link StreamMode} channels emitted by the Pregel stream, the v2
17
+ * protocol layer synthesizes additional channels (e.g. `lifecycle`,
18
+ * `input`) via built-in {@link StreamTransformer}s and exposes
19
+ * user-defined channels created with {@link StreamChannel}.
20
+ */
21
+ type ProtocolMethod = StreamMode | "lifecycle" | "input" | (string & {});
22
+ /**
23
+ * Single envelope for a streaming protocol emission: sequence, channel
24
+ * (`method`), and payload (`params`).
25
+ */
26
+ interface ProtocolEvent {
27
+ /** Discriminator; always `"event"` for this shape. */
28
+ readonly type: "event";
29
+ /** Monotonic sequence number for ordering and deduplication within a run. */
30
+ readonly seq: number;
31
+ /**
32
+ * Logical stream channel. Built-in channels match {@link StreamMode}
33
+ * (e.g. `messages`, `updates`); transformer-synthesized channels
34
+ * include `lifecycle` and `input`; user-defined channels carry their
35
+ * {@link StreamChannel.channelName}.
36
+ */
37
+ readonly method: ProtocolMethod;
38
+ /** Channel-specific payload and routing metadata. */
39
+ readonly params: {
40
+ /** Namespace of the node or scope that emitted this event. */readonly namespace: Namespace; /** Wall-clock or logical timestamp for the emission (milliseconds). */
41
+ readonly timestamp: number;
42
+ /**
43
+ * Graph node id when the engine can attribute the event to a single node;
44
+ * omitted for run-level or ambiguous emissions.
45
+ */
46
+ readonly node?: string; /** Opaque channel payload; shape depends on `method`. */
47
+ readonly data: unknown;
48
+ };
49
+ }
50
+ /**
51
+ * Infers the merged extensions type from a tuple of transformer factory functions.
52
+ *
53
+ * Given `[() => StreamTransformer<{ a: number }>, () => StreamTransformer<{ b: string }>]`,
54
+ * produces `{ a: number } & { b: string }`.
55
+ */
56
+ type InferExtensions<T extends ReadonlyArray<() => StreamTransformer<any>>> = T extends readonly [] ? Record<string, never> : T extends readonly [() => StreamTransformer<infer P>, ...infer Rest extends ReadonlyArray<() => StreamTransformer<any>>] ? P & InferExtensions<Rest> : Record<string, unknown>;
57
+ /**
58
+ * Observes {@link ProtocolEvent}s during a graph run and builds typed derived
59
+ * projections (secondary event logs, promises, etc.).
60
+ *
61
+ * Data is surfaced to consumers through **projections** returned from
62
+ * `init()`. Projections are merged into `GraphRunStream.extensions` for
63
+ * in-process consumers. Use {@link StreamChannel.local} for local streaming
64
+ * values, {@link StreamChannel.remote} for values that should also be visible
65
+ * to remote clients, or `Promise<T>` for final values.
66
+ *
67
+ * To make projection data available to **remote** clients (SDK consumers
68
+ * over WebSocket / SSE), create a named channel with
69
+ * `StreamChannel.remote(name)`. The {@link StreamMux} detects named
70
+ * `StreamChannel` instances in the `init()` return and auto-forwards every
71
+ * `push()` as a {@link ProtocolEvent} on the channel's named method. Remote
72
+ * clients subscribe via `session.subscribe("custom:<name>")`.
73
+ *
74
+ * `finalize` and `fail` are optional. When a transformer uses
75
+ * `StreamChannel`, the mux auto-closes/fails the channels on run
76
+ * completion — no manual lifecycle management needed. Implement
77
+ * `finalize`/`fail` only for non-channel teardown (e.g. resolving a
78
+ * `Promise`).
79
+ *
80
+ * @typeParam TProjection - Shape returned by {@link init}, merged into
81
+ * `GraphRunStream.extensions`.
82
+ */
83
+ interface StreamTransformer<TProjection = unknown> {
84
+ /**
85
+ * Called once before the run starts.
86
+ *
87
+ * @returns Initial projection merged into `GraphRunStream.extensions`.
88
+ * Any named {@link StreamChannel} instances in the return value are
89
+ * automatically wired to the protocol event stream by the mux. Unnamed
90
+ * channels stay in-process-only.
91
+ */
92
+ init(): TProjection;
93
+ /**
94
+ * Optional hook invoked by {@link StreamMux.addTransformer} immediately
95
+ * after the transformer is attached to the mux. Receives a limited
96
+ * handle that exposes only {@link StreamEmitter.push} — enough for
97
+ * the transformer to emit synthesized {@link ProtocolEvent}s on any
98
+ * namespace it chooses (e.g. a deepagents `SubagentTransformer`
99
+ * fabricating `lifecycle`/`messages`/`values` events under a
100
+ * `["tools:<tool_call_id>"]` namespace when a `task` tool starts).
101
+ *
102
+ * Transformers that do not synthesize events can omit this hook.
103
+ *
104
+ * The {@link StreamEmitter} handle is only safe to call *from within*
105
+ * {@link StreamTransformer.process}. Emitting from an unrelated async
106
+ * context (e.g. after `process` has returned, from a `setTimeout`,
107
+ * etc.) races with the mux's close/fail cycle and may land events in
108
+ * an already-closed log.
109
+ */
110
+ onRegister?(emitter: StreamEmitter): void;
111
+ /**
112
+ * Called for each {@link ProtocolEvent} before it is appended to the main log.
113
+ *
114
+ * @param event - Next protocol envelope for this run.
115
+ * @returns `false` to drop the original event from the main log (use
116
+ * sparingly; prefer keeping events visible and adding derived data
117
+ * alongside).
118
+ */
119
+ process(event: ProtocolEvent): boolean;
120
+ /**
121
+ * Called once when the underlying Pregel run completes without throwing.
122
+ * Optional — only needed for non-channel teardown (e.g. resolving promises).
123
+ *
124
+ * May return a `PromiseLike<void>` to defer the main event log close
125
+ * until the async work (e.g. emitting terminal lifecycle events) has
126
+ * completed. The mux awaits all returned promises before closing its
127
+ * event log.
128
+ */
129
+ finalize?(): void | PromiseLike<void>;
130
+ /**
131
+ * Called once when the run fails; `err` is the rejection or error value.
132
+ * Optional — only needed for non-channel teardown (e.g. rejecting promises).
133
+ *
134
+ * @param err - Failure reason from the engine or user code.
135
+ */
136
+ fail?(err: unknown): void;
137
+ }
138
+ /**
139
+ * Narrow capability handle passed to
140
+ * {@link StreamTransformer.onRegister}. Exposes only the minimal mux
141
+ * surface required for synthetic event emission — intentionally does
142
+ * not expose close/fail/register/etc. to keep the transformer contract
143
+ * small and tamper-resistant.
144
+ */
145
+ interface StreamEmitter {
146
+ /**
147
+ * Injects a new {@link ProtocolEvent} into the mux pipeline. The
148
+ * event is routed through every registered transformer (including
149
+ * the emitting transformer — implementers must guard against
150
+ * re-entrant self-processing) and, if not suppressed, appended to
151
+ * the main event log.
152
+ *
153
+ * @param ns - Target namespace for the synthetic event.
154
+ * @param event - The event envelope to inject. ``event.seq`` is
155
+ * overwritten by the mux; callers can pass any placeholder.
156
+ */
157
+ push(ns: Namespace, event: ProtocolEvent): void;
158
+ }
159
+ type ChatModelStream$1 = Omit<ChatModelStream, typeof Symbol.asyncIterator> & {
160
+ /** Namespace of the graph node that produced this stream. */readonly namespace: Namespace; /** Graph node id for this stream, if the runtime attributed it. */
161
+ readonly node: string | undefined;
162
+ /**
163
+ * Low-level async iteration over message lifecycle events.
164
+ *
165
+ * @returns Iterator yielding Core-compatible chat model stream events.
166
+ */
167
+ [Symbol.asyncIterator](): AsyncIterator<ChatModelStreamEvent>;
168
+ };
169
+ /**
170
+ * Public view yielded by `run.messages`.
171
+ *
172
+ * `ChatModelStream` is PromiseLike to mirror Core, but TypeScript applies
173
+ * `Awaited<T>` to values produced by `for await`. Exposing a non-thenable view
174
+ * keeps loop variables typed as the streaming handle instead of `AIMessage`.
175
+ */
176
+ type ChatModelStreamHandle = Omit<ChatModelStream$1, "then">;
177
+ /**
178
+ * High-level outcome of a single tool call for UI or aggregators.
179
+ */
180
+ type ToolCallStatus = /** Invocation in flight or output still streaming. */"running" /** Completed without error. */ | "finished" /** Failed or aborted; see {@link ToolCallStream.error}. */ | "error";
181
+ /**
182
+ * Stable handle for one tool call: name, arguments, and async results.
183
+ *
184
+ * Emitted when `content-block-finish` delivers a finalized `tool_call` block.
185
+ *
186
+ * @typeParam TName - Registered tool name.
187
+ * @typeParam TInput - Parsed or raw input type for the call.
188
+ * @typeParam TOutput - Successful result type after the tool returns.
189
+ */
190
+ interface ToolCallStream<TName extends string = string, TInput = unknown, TOutput = unknown> {
191
+ /** Tool identifier as registered on the graph or model schema. */
192
+ readonly name: TName;
193
+ /** Correlates with protocol `toolCallId` when the runtime provides one. */
194
+ readonly callId: string;
195
+ /** Arguments passed to the tool (finalized when the call is observable). */
196
+ readonly input: TInput;
197
+ /**
198
+ * Resolves to the tool return value on success.
199
+ *
200
+ * @remarks
201
+ * Rejection or hang semantics depend on the runner; pairing with
202
+ * {@link ToolCallStream.status} and {@link ToolCallStream.error} is recommended.
203
+ */
204
+ readonly output: Promise<TOutput>;
205
+ /**
206
+ * Resolves to {@link ToolCallStatus} when the call leaves the running state.
207
+ */
208
+ readonly status: Promise<ToolCallStatus>;
209
+ /**
210
+ * Resolves to an error message string if {@link ToolCallStream.status} is
211
+ * `"error"`, otherwise `undefined`.
212
+ */
213
+ readonly error: Promise<string | undefined>;
214
+ }
215
+ /**
216
+ * Marker interface for transformers provided by internal LangChain products
217
+ * (e.g. ReactAgent's ToolCallTransformer, DeepAgent's SubagentTransformer).
218
+ *
219
+ * Native transformers differ from user-defined extension transformers in
220
+ * where their projection lands on the run stream:
221
+ *
222
+ * - **Native** — projections become direct getters on a
223
+ * `GraphRunStream` subclass (e.g. `run.toolCalls`, `run.subagents`).
224
+ * They emit events on protocol-defined channels (`tools`, `lifecycle`,
225
+ * `tasks`, etc.).
226
+ *
227
+ * - **Extension** (user-defined) — projections are merged into
228
+ * `run.extensions`. Events emitted via `emit()` use an
229
+ * application-chosen method name (e.g. `emit("a2a", data)`) and are
230
+ * accessible to remote clients via `session.subscribe("custom:<name>")`.
231
+ *
232
+ * The `__native` brand is used by downstream stream factory functions
233
+ * to distinguish native transformers from extension transformers at
234
+ * registration time. See `docs/native-stream-transformers.md` for the
235
+ * full pattern.
236
+ */
237
+ interface NativeStreamTransformer<TProjection = unknown> extends StreamTransformer<TProjection> {
238
+ readonly __native: true;
239
+ }
240
+ /**
241
+ * Type guard that tests whether a transformer is a {@link NativeStreamTransformer}.
242
+ */
243
+ declare function isNativeTransformer(t: StreamTransformer<unknown>): t is NativeStreamTransformer;
244
+ /**
245
+ * Human-in-the-loop interrupt: stable id plus opaque payload for resume UIs.
246
+ */
247
+ interface InterruptPayload<TPayload = unknown> {
248
+ /** Idempotent key for this interrupt instance within the run. */
249
+ interruptId: string;
250
+ /** Arbitrary data supplied by the graph (e.g. questions, draft state). */
251
+ payload: TPayload;
252
+ }
253
+ //#endregion
254
+ export { type AgentStatus$1 as AgentStatus, ChatModelStream$1 as ChatModelStream, ChatModelStreamHandle, type Checkpoint, InferExtensions, InterruptPayload, type LifecycleCause, type LifecycleData$1 as LifecycleData, type MessagesEventData, Namespace, NativeStreamTransformer, ProtocolEvent, StreamEmitter, StreamTransformer, ToolCallStatus, ToolCallStream, type ToolsEventData, type UpdatesEventData, type UsageInfo, isNativeTransformer };
255
+ //# sourceMappingURL=types.d.cts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"types.d.cts","names":[],"sources":["../../src/stream/types.ts"],"mappings":";;;;;;;;;;;;KAkDY,SAAA;;;;;AAuDZ;;;KA9CY,cAAA,GAAiB,UAAA;;;;;UAMZ,aAAA;EAgDiC;EAAA,SA9CvC,IAAA;EAgDL;EAAA,SA7CK,GAAA;EA6CD;;;;;;EAAA,SArCC,MAAA,EAAQ,cAAA;EA8Bf;EAAA,SA3BO,MAAA;IA6BP,uEA3BS,SAAA,EAAW,SAAA,EA4Bc;IAAA,SAzBzB,SAAA;IA2BiB;;;;IAAA,SArBjB,IAAA,WAwBP;IAAA,SArBO,IAAA;EAAA;AAAA;;;;;;;KAUD,eAAA,WAEA,aAAA,OAAoB,iBAAA,UAC5B,CAAA,uBACA,MAAA,kBACA,CAAA,yBACU,iBAAA,iCAEgB,aAAA,OAAoB,iBAAA,UAE5C,CAAA,GAAI,eAAA,CAAgB,IAAA,IACpB,MAAA;;;;;;;;;;;;;;AA+FN;;;;;;;;;;;AAeA;;UAlFiB,iBAAA;EAmFf;;;;;;;;EA1EA,IAAA,IAAQ,WAAA;EA0ER;;;;;;;;;;;;;AAwBF;;;;EA/EE,UAAA,EAAY,OAAA,EAAS,aAAA;EAoFX;;;;;AAiBZ;;;EA3FE,OAAA,CAAQ,KAAA,EAAO,aAAA;EAuGC;;;;;;;;;EA5FhB,QAAA,YAAoB,WAAA;EAmFpB;;;;;;EA3EA,IAAA,EAAM,GAAA;AAAA;;;;;;;;UAUS,aAAA;EAuHA;;;;;;;;;;AASjB;EApHE,IAAA,CAAK,EAAA,EAAI,SAAA,EAAW,KAAA,EAAO,aAAA;AAAA;AAAA,KAGjB,iBAAA,GAAkB,IAAA,CAC5B,eAAA,SACO,MAAA,CAAO,aAAA;EAgHX,sEA7GM,SAAA,EAAW,SAAA,EA8GnB;EAAA,SA3GQ,IAAA;EA2GoB;;AAO/B;;;EAP+B,CApG5B,MAAA,CAAO,aAAP,KAAyB,aAAA,CAAc,oBAAA;AAAA;;;;;;;;KAU9B,qBAAA,GAAwB,IAAA,CAAK,iBAAA;;;;KAK7B,cAAA;;;;;;;;;;UAiBK,cAAA;;WAMN,IAAA,EAAM,KAAA;;WAGN,MAAA;;WAGA,KAAA,EAAO,MAAA;;;;;;;;WASP,MAAA,EAAQ,OAAA,CAAQ,OAAA;;;;WAKhB,MAAA,EAAQ,OAAA,CAAQ,cAAA;;;;;WAMhB,KAAA,EAAO,OAAA;AAAA;;;;;;;;;;;;;;;;;;;;;;;UAyBD,uBAAA,gCAEP,iBAAA,CAAkB,WAAA;EAAA,SACjB,QAAA;AAAA;;;;iBAMK,mBAAA,CACd,CAAA,EAAG,iBAAA,YACF,CAAA,IAAK,uBAAA;;;;UAOS,gBAAA;;EAEf,WAAA;;EAGA,OAAA,EAAS,QAAA;AAAA"}