@langchain/langgraph-sdk 1.8.10 → 1.9.0

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

@@ -0,0 +1,238 @@
+import { AssembledToolCall, ToolCallStatus } from "./handles/tools.js";
+import { AssembledMessage, MessageAssembler, MessageAssemblyUpdate, StreamingMessage, StreamingMessageHandle } from "./messages.js";
+import { AnyMediaHandle, AudioMedia, FileMedia, ImageMedia, MediaAssembler, MediaAssemblerCallbacks, MediaAssemblerOptions, MediaAssemblyError, MediaAssemblyErrorKind, MediaBase, MediaBlockType, VideoMedia } from "./media.js";
+import { AgentServerAdapter, TransportAdapter } from "./transport.js";
+import { EventForChannel, EventForChannels, EventMethodByChannel, EventSubscription, ExtendedRunStartParams, InputModule, InterruptPayload, MessageSubscription, SessionOrderingState, StateModule, SubscribeOptions, ThreadExtension, ThreadExtensions, ThreadModules, ThreadStreamOptions, ThreadStreamTransport, ThreadStreamTransportKind, UnwrapExtension, YieldForChannel, YieldForChannels } from "./types.js";
+import { SubagentHandle } from "./handles/subagents.js";
+import { SubgraphHandle, Subscribable } from "./handles/subgraphs.js";
+import { inferChannel, matchesSubscription } from "./subscription.js";
+import { ProtocolError } from "./error.js";
+import { Channel, Event, RunResult, SubscribeParams } from "@langchain/protocol";
+
+//#region src/client/stream/index.d.ts
+/**
+ * Async iterable handle for raw event subscriptions.
+ *
+ * An optional `transform` maps each incoming event before it is queued
+ * or delivered to a waiting consumer. This is used by named custom
+ * channel subscriptions (e.g. `"custom:a2a"`) to unwrap the payload
+ * so callers receive the raw emitted data instead of the protocol
+ * event envelope.
+ */
+declare class SubscriptionHandle<TEvent extends Event = Event, TYield = TEvent> implements AsyncIterable<TYield>, EventSubscription<TYield> {
+  readonly subscriptionId: string;
+  readonly params: SubscribeParams;
+  private readonly queue;
+  private readonly waiters;
+  private closed;
+  private paused;
+  private resumeResolve?;
+  private readonly onUnsubscribe;
+  private readonly transform;
+  constructor(subscriptionId: string, params: SubscribeParams, onUnsubscribe: (id: string) => Promise<void>, transform?: (event: TEvent) => TYield);
+  push(event: TEvent): void;
+  /**
+   * Pause the subscription: resolve all waiting iterators with `done: true`
+   * so `for await` loops exit, but keep the subscription alive. New events
+   * arriving while paused are still buffered. Call `resume()` to allow
+   * iterators to consume again.
+   */
+  pause(): void;
+  /**
+   * Resume a paused subscription so new `for await` loops can consume
+   * buffered and future events.
+   */
+  resume(): void;
+  /**
+   * Returns a promise that resolves when `resume()` is called. Resolves
+   * immediately if not currently paused.
+   */
+  waitForResume(): Promise<void>;
+  get isPaused(): boolean;
+  close(): void;
+  unsubscribe(): Promise<void>;
+  [Symbol.asyncIterator](): AsyncIterator<TYield>;
+}
+/**
+ * High-level wrapper around a protocol connection to a specific thread.
+ *
+ * In the thread-centric protocol, threads are durable (backed by
+ * checkpoints) and connections are ephemeral. A `ThreadStream` is the
+ * client-side handle for interacting with a thread: starting runs,
+ * subscribing to events, consuming assembled projections (`messages`,
+ * `values`, `toolCalls`, etc.), and responding to interrupts.
+ *
+ * Construct via `client.threads.stream(threadId?, { assistantId? })`.
+ *
+ * @typeParam TExtensions - Optional map of `{ name: payload }` pairs
+ *   describing the transformer projections the bound assistant exposes
+ *   on `custom:<name>` channels. Narrows `thread.extensions.<name>` to
+ *   `ThreadExtension<payload>`. Defaults to `Record<string, unknown>`.
+ */
+declare class ThreadStream<TExtensions extends Record<string, unknown> = Record<string, unknown>> {
+  #private;
+  readonly threadId: string;
+  readonly ordering: SessionOrderingState;
+  readonly run: ThreadModules["run"];
+  readonly agent: ThreadModules["agent"];
+  readonly input: ThreadModules["input"];
+  readonly state: ThreadModules["state"];
+  /**
+   * Whether the run was interrupted (a lifecycle "interrupted" event
+   * was received). Mirrors the in-process `run.interrupted`.
+   */
+  interrupted: boolean;
+  /**
+   * Interrupt payloads collected during the run, if any.
+   * Mirrors the in-process `run.interrupts`.
+   */
+  readonly interrupts: InterruptPayload[];
+  readonly assistantId: string;
+  constructor(transportAdapter: TransportAdapter, options: ThreadStreamOptions);
+  /**
+   * Streaming messages. Each `for await` loop gets an independent cursor
+   * over the shared buffer; late consumers see all previously emitted
+   * messages.  Mirrors the in-process `run.messages`.
+   */
+  get messages(): AsyncIterable<StreamingMessageHandle>;
+  /**
+   * State values. Iterable for intermediate snapshots; also
+   * `PromiseLike` — `await thread.values` resolves with the final
+   * state.  Mirrors the in-process `run.values`.
+   */
+  get values(): AsyncIterable<unknown> & PromiseLike<unknown>;
+  /**
+   * Tool calls with promise-based output/status/error.
+   * Mirrors the in-process `run.toolCalls`.
+   */
+  get toolCalls(): AsyncIterable<AssembledToolCall>;
+  /**
+   * Discovered subgraphs. Mirrors the in-process `run.subgraphs`.
+   */
+  get subgraphs(): AsyncIterable<SubgraphHandle>;
+  /**
+   * Discovered subagents.
+   */
+  get subagents(): AsyncIterable<SubagentHandle>;
+  /**
+   * Audio media handles, one per message containing at least one
+   * `AudioBlock`. Each `for await` opens an independent cursor over
+   * the shared buffer; late consumers replay every previously emitted
+   * audio handle.
+   *
+   * Yields one item per message on the first matching
+   * `content-block-start` — messages with no audio blocks are skipped.
+   */
+  get audio(): AsyncIterable<AudioMedia>;
+  /**
+   * Image media handles, one per message containing at least one
+   * `ImageBlock`. See {@link audio} for shared semantics.
+   */
+  get images(): AsyncIterable<ImageMedia>;
+  /**
+   * Video media handles, one per message containing at least one
+   * `VideoBlock`. See {@link audio} for shared semantics.
+   */
+  get video(): AsyncIterable<VideoMedia>;
+  /**
+   * File media handles, one per message containing at least one
+   * `FileBlock`. See {@link audio} for shared semantics.
+   */
+  get files(): AsyncIterable<FileMedia>;
+  /**
+   * Promise that resolves with the final state value when the run
+   * completes.  Shares the `values` getter's SSE connection.
+   * Mirrors the in-process `run.output`.
+   */
+  get output(): Promise<unknown>;
+  /**
+   * Proxy over compile-time {@link StreamTransformer} projections
+   * exposed by the bound assistant on `custom:<name>` channels.
+   *
+   * Each access (e.g. `thread.extensions.toolActivity`) lazily opens a
+   * dedicated `custom:<name>` subscription, returns a cached
+   * {@link ThreadExtension} handle that is both `AsyncIterable<T>`
+   * (streaming items as they arrive) and `PromiseLike<T>` (resolves
+   * with the final value when the run terminates), and reuses the same
+   * handle on subsequent access.
+   *
+   * Mirrors the in-process `run.extensions.<name>` shape.
+   */
+  get extensions(): ThreadExtensions<TExtensions>;
+  /**
+   * Start a run without the v1 eager lazy-getter shims.
+   *
+   * `run.start` (the v1 entry point) eagerly opens a wildcard `values`
+   * projection so `thread.output` / `thread.values` resolve regardless
+   * of access order, and calls `#ensureLifecycleTracking` which opens
+   * another wildcard `["lifecycle", "input"]` subscription. Both
+   * subscriptions widen `#computeUnionFilter` to wildcard, defeating
+   * the progressive-expansion rotation strategy.
+   *
+   * `submitRun` skips those shims — callers that manage their own
+   * content subscriptions (such as `StreamController`) get the narrow
+   * union filter they asked for. Lifecycle / interrupt tracking is
+   * instead served by the dedicated `#startLifecycleWatcher`, which
+   * opens a wildcard `["lifecycle", "input"]` stream alongside the
+   * narrow content pump on both SSE and WebSocket transports.
+   */
+  submitRun(params: {
+    input?: unknown;
+    config?: unknown;
+    metadata?: Record<string, unknown>;
+    /**
+     * Fork the new run from an explicit checkpoint instead of the
+     * thread's latest. Forwarded verbatim on the `/run.start` protocol
+     * message; the API layer picks it up and routes it to
+     * `graph.streamEvents(input, { version: "v3", forkFrom })`
+     * (see plan-roadmap.md R2.4 / A0.1).
+     */
+    forkFrom?: {
+      checkpointId: string;
+    };
+    /**
+     * Controls how concurrent submissions on the same thread are
+     * handled by the server (`reject` | `rollback` | `interrupt` |
+     * `enqueue`). Forwarded to the server; the SDK does not interpret
+     * it locally (see plan-roadmap.md S1.3 / A0.3).
+     */
+    multitaskStrategy?: "reject" | "rollback" | "interrupt" | "enqueue";
+  }): Promise<RunResult>;
+  /**
+   * Respond to an interrupt without the v1 eager lazy-getter shims.
+   * See {@link submitRun} for why this exists alongside
+   * {@link input.respond}.
+   */
+  respondInput(params: {
+    namespace: readonly string[];
+    interrupt_id: string;
+    response: unknown;
+  }): Promise<void>;
+  /**
+   * Register a listener for every globally-unique event on the thread.
+   *
+   * Fires exactly once per `event_id` across both the content pump
+   * (user `subscribe()` calls) and the lifecycle watcher. Events
+   * without an `event_id` always fire through (dedup is best-effort).
+   *
+   * Returns an unsubscribe function. Primary consumer is
+   * `StreamController`, which uses the listener to feed discovery
+   * runners and pick up deeply-nested interrupts that the narrow
+   * content pump wouldn't deliver.
+   */
+  onEvent(listener: (event: Event) => void): () => void;
+  close(): Promise<void>;
+  /**
+   * Subscribe to raw wire channels and receive protocol events.
+   *
+   * For assembled projections, use the lazy getters instead:
+   * `thread.messages`, `thread.values`, `thread.toolCalls`,
+   * `thread.subgraphs`, `thread.subagents`, `thread.output`.
+   */
+  subscribe<TChannel extends Channel>(channel: TChannel, options?: SubscribeOptions): Promise<SubscriptionHandle<EventForChannel<TChannel>, YieldForChannel<TChannel>>>;
+  subscribe<const TChannels extends readonly Channel[]>(channels: TChannels, options?: SubscribeOptions): Promise<SubscriptionHandle<EventForChannels<TChannels>, YieldForChannels<TChannels>>>;
+  subscribe(params: SubscribeParams): Promise<SubscriptionHandle<Event>>;
+}
+//#endregion
+export { SubscriptionHandle, ThreadStream };
+//# sourceMappingURL=index.d.ts.map

package/dist/client/stream/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../../src/client/stream/index.ts"],"mappings":";;;;;;;;;;;;;;;;;;AAyUA;;;cAAa,kBAAA,gBAAkC,KAAA,GAAQ,KAAA,WAAgB,MAAA,aAC1D,aAAA,CAAc,MAAA,GAAS,iBAAA,CAAkB,MAAA;EAAA,SAE3C,cAAA;EAAA,SACA,MAAA,EAAQ,eAAA;EAAA,iBACA,KAAA;EAAA,iBACA,OAAA;EAAA,QACT,MAAA;EAAA,QACA,MAAA;EAAA,QACA,aAAA;EAAA,iBACS,aAAA;EAAA,iBACA,SAAA;EAEjB,WAAA,CACE,cAAA,UACA,MAAA,EAAQ,eAAA,EACR,aAAA,GAAgB,EAAA,aAAe,OAAA,QAC/B,SAAA,IAAa,KAAA,EAAO,MAAA,KAAW,MAAA;EAQjC,IAAA,CAAK,KAAA,EAAO,MAAA;EAmES;;;;;;EAhDrB,KAAA,CAAA;EA3CmD;;;;EAuDnD,MAAA,CAAA;EAxDqE;;;;EAkErE,aAAA,CAAA,GAAiB,OAAA;EAAA,IAOb,QAAA,CAAA;EAIJ,KAAA,CAAA;EAeM,WAAA,CAAA,GAAe,OAAA;EAAA,CAQpB,MAAA,CAAO,aAAA,KAAkB,aAAA,CAAc,MAAA;AAAA;;;;;;;;;;;;;;;;;cAsC7B,YAAA,qBACS,MAAA,oBAA0B,MAAA;EAAA;WAErC,QAAA;EAAA,SACA,QAAA,EAAU,oBAAA;EAAA,SACV,GAAA,EAAK,aAAA;EAAA,SACL,KAAA,EAAO,aAAA;EAAA,SACP,KAAA,EAAO,aAAA;EAAA,SACP,KAAA,EAAO,aAAA;EArEhB;;;;EA2EA,WAAA;EApD0B;;;;EAAA,SA0DjB,UAAA,EAAY,gBAAA;EAAA,SAEZ,WAAA;EA+HT,WAAA,CACE,gBAAA,EAAkB,gBAAA,EAClB,OAAA,EAAS,mBAAA;EAtJS;;;;;EAAA,IA6ShB,QAAA,CAAA,GAAY,aAAA,CAAc,sBAAA;EAtSd;;;;;EAAA,IA4TZ,MAAA,CAAA,GAAU,aAAA,YAAyB,WAAA;EAAzB;;;;EAAA,IAyCV,SAAA,CAAA,GAAa,aAAA,CAAc,iBAAA;EAoBd;;;EAAA,IAAb,SAAA,CAAA,GAAa,aAAA,CAAc,cAAA;EA8ClB;;;EAAA,IA1BT,SAAA,CAAA,GAAa,aAAA,CAAc,cAAA;EA4ClB;;;;;;;;;EAAA,IAlBT,KAAA,CAAA,GAAS,aAAA,CAAc,UAAA;EA6WD;;;;EAAA,IApWtB,MAAA,CAAA,GAAU,aAAA,CAAc,UAAA;EAwmBS;;;;EAAA,IA/lBjC,KAAA,CAAA,GAAS,aAAA,CAAc,UAAA;EA8lBxB;;;;EAAA,IArlBC,KAAA,CAAA,GAAS,aAAA,CAAc,SAAA;EA4lBN;;;;;EAAA,IAllBjB,MAAA,CAAA,GAAU,OAAA;EAolBuD;;;;;;;;;;;;;EAAA,IAjkBjE,UAAA,CAAA,GAAc,gBAAA,CAAiB,WAAA;EAje1B;;;;;;;;;;;;;;;;;EA4tBH,SAAA,CAAU,MAAA;IACd,KAAA;IACA,MAAA;IACA,QAAA,GAAW,MAAA;IAxXT;;;;;;;IAgYF,QAAA;MAAa,YAAA;IAAA;IA9TF;;;;;;IAqUX,iBAAA;EAAA,IACE,OAAA,CAAQ,SAAA;EA3SR;;;;;EAyTE,YAAA,CAAa,MAAA;IACjB,SAAA;IACA,YAAA;IACA,QAAA;EAAA,IACE,OAAA;EAnCF;;;;;;;;;;;;EAwDF,OAAA,CAAQ,QAAA,GAAW,KAAA,EAAO,KAAA;EAyLpB,KAAA,CAAA,GAAS,OAAA;EA9MX;;;;;;;EAqRE,SAAA,kBAA2B,OAAA,CAAA,CAC/B,OAAA,EAAS,QAAA,EACT,OAAA,GAAU,gBAAA,GACT,OAAA,CACD,kBAAA,CAAmB,eAAA,CAAgB,QAAA,GAAW,eAAA,CAAgB,QAAA;EAE1D,SAAA,kCAA2C,OAAA,GAAA,CAC/C,QAAA,EAAU,SAAA,EACV,OAAA,GAAU,gBAAA,GACT,OAAA,CACD,kBAAA,CAAmB,gBAAA,CAAiB,SAAA,GAAY,gBAAA,CAAiB,SAAA;EAE7D,SAAA,CAAU,MAAA,EAAQ,eAAA,GAAkB,OAAA,CAAQ,kBAAA,CAAmB,KAAA;AAAA"}