@langchain/langgraph-sdk 1.8.10 → 1.9.1

package/dist/client/stream/media.d.cts

@@ -0,0 +1,164 @@
+import { MessagesEvent } from "@langchain/protocol";
+
+//#region src/client/stream/media.d.ts
+/**
+ * Block types this assembler knows how to reassemble into media handles.
+ */
+type MediaBlockType = "audio" | "image" | "video" | "file";
+/**
+ * Kinds of failure that can terminate a media handle prematurely.
+ *
+ * - `"message-error"` — the upstream message emitted an `error` event
+ *   before completion.
+ * - `"stream-closed"` — the transport stream closed before
+ *   `message-finish` arrived (thread closed, transport dropped, etc.).
+ * - `"fetch-failed"` — the block was `url`-sourced and the lazy
+ *   `fetch()` rejected (CORS, 404, 5xx, network).
+ */
+type MediaAssemblyErrorKind = "message-error" | "stream-closed" | "fetch-failed";
+/**
+ * Typed error thrown through `media.stream` / rejected from
+ * `media.blob` / `media.objectURL` when a handle fails before its
+ * message completes. Carries the bytes accumulated up to the failure
+ * point on `partialBytes` for callers that want to salvage or diagnose.
+ */
+declare class MediaAssemblyError extends Error {
+  readonly kind: MediaAssemblyErrorKind;
+  readonly messageId: string;
+  readonly partialBytes: Uint8Array;
+  readonly cause?: unknown;
+  constructor(kind: MediaAssemblyErrorKind, messageId: string, partialBytes: Uint8Array, message?: string, options?: {
+    cause?: unknown;
+  });
+}
+/**
+ * Shared surface across every media handle returned by
+ * {@link MediaAssembler}.
+ *
+ * The handle is live while its parent message is active:
+ *  - `partialBytes` is a snapshot of all bytes received so far.
+ *  - `stream` is a lazy, single-consumer byte stream (see
+ *    accessor docstring).
+ *  - `blob` / `objectURL` settle on `message-finish`.
+ *  - `error` becomes set if the handle terminates in any of the
+ *    {@link MediaAssemblyErrorKind} failure modes.
+ */
+interface MediaBase {
+  readonly messageId: string;
+  readonly namespace: string[];
+  readonly node?: string;
+  /** `id` from the originating content block, if the provider sent one. */
+  readonly id?: string;
+  readonly mimeType?: string;
+  /**
+   * Present iff the originating block carried `url` (not `data`).
+   * When set, `blob` / `stream` / `objectURL` lazily fetch from here
+   * on first access.
+   */
+  readonly url?: string;
+  /**
+   * Live byte stream.
+   *
+   * Lazy: not materialised unless accessed. On first access the
+   * stream is seeded with every byte already accumulated
+   * (`partialBytes`) and then wired to future chunks. For URL-sourced
+   * blocks, first access triggers `fetch()` and pipes the response
+   * body through.
+   *
+   * Repeated access returns the same {@link ReadableStream} reference
+   * — you can safely read it once, release the lock, and re-acquire a
+   * reader later (e.g. React StrictMode effect re-invokes). The
+   * standard `ReadableStream.locked` semantics prevent concurrent
+   * readers; use `stream.tee()` when you truly need multiple live
+   * consumers.
+   */
+  readonly stream: ReadableStream<Uint8Array>;
+  /** Resolves on `message-finish` with the concatenated {@link Blob}. */
+  readonly blob: Promise<Blob>;
+  /**
+   * Lazy {@link URL.createObjectURL} over {@link blob}. Cached: first
+   * access creates the URL, subsequent accesses return the same one.
+   * Call {@link revoke} to free the URL slot; the next access creates
+   * a fresh URL. `ThreadStream.close()` auto-revokes as a safety net.
+   */
+  readonly objectURL: Promise<string>;
+  /** Live view of accumulated bytes. Settles with final bytes on finish. */
+  readonly partialBytes: Uint8Array;
+  /** Set iff the handle settled in an error state. */
+  readonly error?: MediaAssemblyError;
+  /** Diagnostic: `false` if block indices arrived out of order. */
+  readonly monotonic: boolean;
+  /**
+   * Revoke the currently-cached object URL (if any). Subsequent
+   * accesses to {@link objectURL} create a fresh URL from the Blob.
+   * Idempotent.
+   */
+  revoke(): void;
+}
+interface AudioMedia extends MediaBase {
+  readonly type: "audio";
+  /**
+   * Concatenated transcript across every audio block in this message.
+   * Resolves on `message-finish` with the joined string, or `undefined`
+   * when no block carried a transcript.
+   */
+  readonly transcript: Promise<string | undefined>;
+}
+interface ImageMedia extends MediaBase {
+  readonly type: "image";
+  /** Pixel width, if the provider sent it on the originating block. */
+  readonly width?: number;
+  /** Pixel height, if the provider sent it on the originating block. */
+  readonly height?: number;
+}
+interface VideoMedia extends MediaBase {
+  readonly type: "video";
+}
+interface FileMedia extends MediaBase {
+  readonly type: "file";
+  /** File name hint, if the provider sent it on the originating block. */
+  readonly filename?: string;
+}
+type AnyMediaHandle = AudioMedia | ImageMedia | VideoMedia | FileMedia;
+/**
+ * Dispatch callbacks receive a freshly-started handle on its first
+ * matching `content-block-start`. Exactly one callback fires per
+ * `(messageId, blockType)` pair.
+ */
+interface MediaAssemblerCallbacks {
+  onAudio?: (media: AudioMedia) => void;
+  onImage?: (media: ImageMedia) => void;
+  onVideo?: (media: VideoMedia) => void;
+  onFile?: (media: FileMedia) => void;
+  /**
+   * Invoked for every type; receives the same handle as the typed
+   * callback. Useful for writing one "all media" consumer without
+   * registering four type-specific callbacks.
+   */
+  onMedia?: (media: AnyMediaHandle) => void;
+}
+interface MediaAssemblerOptions extends MediaAssemblerCallbacks {
+  /**
+   * Injected `fetch` used for URL-sourced blocks. Defaults to the
+   * global `fetch`. Throws on first URL access if neither is present.
+   */
+  fetch?: typeof fetch;
+}
+declare class MediaAssembler {
+  #private;
+  constructor(options?: MediaAssemblerOptions);
+  /**
+   * Fold a single `messages` event. Non-media blocks and
+   * informational events (e.g. `content-block-finish`) are no-ops.
+   */
+  consume(event: MessagesEvent): void;
+  /**
+   * Abort all outstanding handles with a `stream-closed` error.
+   * Called when the upstream event source terminates before the
+   * messages it was assembling had a chance to finish.
+   */
+  close(): void;
+}
+//#endregion
+export { AnyMediaHandle, AudioMedia, FileMedia, ImageMedia, MediaAssembler, MediaAssemblerCallbacks, MediaAssemblerOptions, MediaAssemblyError, MediaAssemblyErrorKind, MediaBase, MediaBlockType, VideoMedia };
+//# sourceMappingURL=media.d.cts.map

package/dist/client/stream/media.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"media.d.cts","names":[],"sources":["../../../src/client/stream/media.ts"],"mappings":";;;;;AAYA;KAAY,cAAA;;;;AAmBZ;;;;;AAWA;;KAXY,sBAAA;;;;;;;cAWC,kBAAA,SAA2B,KAAA;EAAA,SAC7B,IAAA,EAAM,sBAAA;EAAA,SACN,SAAA;EAAA,SACA,YAAA,EAAc,UAAA;EAAA,SAEd,KAAA;EAET,WAAA,CACE,IAAA,EAAM,sBAAA,EACN,SAAA,UACA,YAAA,EAAc,UAAA,EACd,OAAA,WACA,OAAA;IAAY,KAAA;EAAA;AAAA;;;;;;;;;;;AAuBhB;;UAAiB,SAAA;EAAA,SACN,SAAA;EAAA,SACA,SAAA;EAAA,SACA,IAAA;EA8BM;EAAA,SA5BN,EAAA;EAAA,SACA,QAAA;EAyCQ;;;;;EAAA,SAnCR,GAAA;EAPA;;;;;;;;;;;;;;;;EAAA,SAyBA,MAAA,EAAQ,cAAA,CAAe,UAAA;EA2B1B;EAAA,SAxBG,IAAA,EAAM,OAAA,CAAQ,IAAA;EA2BR;;;;;;EAAA,SAnBN,SAAA,EAAW,OAAA;EA0BC;EAAA,SAvBZ,YAAA,EAAc,UAAA;EAuBK;EAAA,SApBnB,KAAA,GAAQ,kBAAA;EAuBS;EAAA,SApBjB,SAAA;EAoBkC;;;;;EAb3C,MAAA;AAAA;AAAA,UAGe,UAAA,SAAmB,SAAA;EAAA,SACzB,IAAA;;;;AAqBX;;WAfW,UAAA,EAAY,OAAA;AAAA;AAAA,UAGN,UAAA,SAAmB,SAAA;EAAA,SACzB,IAAA;EAcA;EAAA,SAZA,KAAA;EAYQ;EAAA,SAVR,MAAA;AAAA;AAAA,UAGM,UAAA,SAAmB,SAAA;EAAA,SACzB,IAAA;AAAA;AAAA,UAGM,SAAA,SAAkB,SAAA;EAAA,SACxB,IAAA;EAKkE;EAAA,SAHlE,QAAA;AAAA;AAAA,KAGC,cAAA,GAAiB,UAAA,GAAa,UAAA,GAAa,UAAA,GAAa,SAAA;;;;;AA+apE;UAAiB,uBAAA;EACf,OAAA,IAAW,KAAA,EAAO,UAAA;EAClB,OAAA,IAAW,KAAA,EAAO,UAAA;EAClB,OAAA,IAAW,KAAA,EAAO,UAAA;EAClB,MAAA,IAAU,KAAA,EAAO,SAAA;EAAA;;;;;EAMjB,OAAA,IAAW,KAAA,EAAO,cAAA;AAAA;AAAA,UAGH,qBAAA,SAA8B,uBAAA;EAX3B;;;;EAgBlB,KAAA,UAAe,KAAA;AAAA;AAAA,cAgDJ,cAAA;EAAA;EAcX,WAAA,CAAY,OAAA,GAAS,qBAAA;EAtEH;;;;EA2FlB,OAAA,CAAQ,KAAA,EAAO,aAAA;EAxFsB;;;;;EAiXrC,KAAA,CAAA;AAAA"}

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

@@ -0,0 +1,164 @@
+import { MessagesEvent } from "@langchain/protocol";
+
+//#region src/client/stream/media.d.ts
+/**
+ * Block types this assembler knows how to reassemble into media handles.
+ */
+type MediaBlockType = "audio" | "image" | "video" | "file";
+/**
+ * Kinds of failure that can terminate a media handle prematurely.
+ *
+ * - `"message-error"` — the upstream message emitted an `error` event
+ *   before completion.
+ * - `"stream-closed"` — the transport stream closed before
+ *   `message-finish` arrived (thread closed, transport dropped, etc.).
+ * - `"fetch-failed"` — the block was `url`-sourced and the lazy
+ *   `fetch()` rejected (CORS, 404, 5xx, network).
+ */
+type MediaAssemblyErrorKind = "message-error" | "stream-closed" | "fetch-failed";
+/**
+ * Typed error thrown through `media.stream` / rejected from
+ * `media.blob` / `media.objectURL` when a handle fails before its
+ * message completes. Carries the bytes accumulated up to the failure
+ * point on `partialBytes` for callers that want to salvage or diagnose.
+ */
+declare class MediaAssemblyError extends Error {
+  readonly kind: MediaAssemblyErrorKind;
+  readonly messageId: string;
+  readonly partialBytes: Uint8Array;
+  readonly cause?: unknown;
+  constructor(kind: MediaAssemblyErrorKind, messageId: string, partialBytes: Uint8Array, message?: string, options?: {
+    cause?: unknown;
+  });
+}
+/**
+ * Shared surface across every media handle returned by
+ * {@link MediaAssembler}.
+ *
+ * The handle is live while its parent message is active:
+ *  - `partialBytes` is a snapshot of all bytes received so far.
+ *  - `stream` is a lazy, single-consumer byte stream (see
+ *    accessor docstring).
+ *  - `blob` / `objectURL` settle on `message-finish`.
+ *  - `error` becomes set if the handle terminates in any of the
+ *    {@link MediaAssemblyErrorKind} failure modes.
+ */
+interface MediaBase {
+  readonly messageId: string;
+  readonly namespace: string[];
+  readonly node?: string;
+  /** `id` from the originating content block, if the provider sent one. */
+  readonly id?: string;
+  readonly mimeType?: string;
+  /**
+   * Present iff the originating block carried `url` (not `data`).
+   * When set, `blob` / `stream` / `objectURL` lazily fetch from here
+   * on first access.
+   */
+  readonly url?: string;
+  /**
+   * Live byte stream.
+   *
+   * Lazy: not materialised unless accessed. On first access the
+   * stream is seeded with every byte already accumulated
+   * (`partialBytes`) and then wired to future chunks. For URL-sourced
+   * blocks, first access triggers `fetch()` and pipes the response
+   * body through.
+   *
+   * Repeated access returns the same {@link ReadableStream} reference
+   * — you can safely read it once, release the lock, and re-acquire a
+   * reader later (e.g. React StrictMode effect re-invokes). The
+   * standard `ReadableStream.locked` semantics prevent concurrent
+   * readers; use `stream.tee()` when you truly need multiple live
+   * consumers.
+   */
+  readonly stream: ReadableStream<Uint8Array>;
+  /** Resolves on `message-finish` with the concatenated {@link Blob}. */
+  readonly blob: Promise<Blob>;
+  /**
+   * Lazy {@link URL.createObjectURL} over {@link blob}. Cached: first
+   * access creates the URL, subsequent accesses return the same one.
+   * Call {@link revoke} to free the URL slot; the next access creates
+   * a fresh URL. `ThreadStream.close()` auto-revokes as a safety net.
+   */
+  readonly objectURL: Promise<string>;
+  /** Live view of accumulated bytes. Settles with final bytes on finish. */
+  readonly partialBytes: Uint8Array;
+  /** Set iff the handle settled in an error state. */
+  readonly error?: MediaAssemblyError;
+  /** Diagnostic: `false` if block indices arrived out of order. */
+  readonly monotonic: boolean;
+  /**
+   * Revoke the currently-cached object URL (if any). Subsequent
+   * accesses to {@link objectURL} create a fresh URL from the Blob.
+   * Idempotent.
+   */
+  revoke(): void;
+}
+interface AudioMedia extends MediaBase {
+  readonly type: "audio";
+  /**
+   * Concatenated transcript across every audio block in this message.
+   * Resolves on `message-finish` with the joined string, or `undefined`
+   * when no block carried a transcript.
+   */
+  readonly transcript: Promise<string | undefined>;
+}
+interface ImageMedia extends MediaBase {
+  readonly type: "image";
+  /** Pixel width, if the provider sent it on the originating block. */
+  readonly width?: number;
+  /** Pixel height, if the provider sent it on the originating block. */
+  readonly height?: number;
+}
+interface VideoMedia extends MediaBase {
+  readonly type: "video";
+}
+interface FileMedia extends MediaBase {
+  readonly type: "file";
+  /** File name hint, if the provider sent it on the originating block. */
+  readonly filename?: string;
+}
+type AnyMediaHandle = AudioMedia | ImageMedia | VideoMedia | FileMedia;
+/**
+ * Dispatch callbacks receive a freshly-started handle on its first
+ * matching `content-block-start`. Exactly one callback fires per
+ * `(messageId, blockType)` pair.
+ */
+interface MediaAssemblerCallbacks {
+  onAudio?: (media: AudioMedia) => void;
+  onImage?: (media: ImageMedia) => void;
+  onVideo?: (media: VideoMedia) => void;
+  onFile?: (media: FileMedia) => void;
+  /**
+   * Invoked for every type; receives the same handle as the typed
+   * callback. Useful for writing one "all media" consumer without
+   * registering four type-specific callbacks.
+   */
+  onMedia?: (media: AnyMediaHandle) => void;
+}
+interface MediaAssemblerOptions extends MediaAssemblerCallbacks {
+  /**
+   * Injected `fetch` used for URL-sourced blocks. Defaults to the
+   * global `fetch`. Throws on first URL access if neither is present.
+   */
+  fetch?: typeof fetch;
+}
+declare class MediaAssembler {
+  #private;
+  constructor(options?: MediaAssemblerOptions);
+  /**
+   * Fold a single `messages` event. Non-media blocks and
+   * informational events (e.g. `content-block-finish`) are no-ops.
+   */
+  consume(event: MessagesEvent): void;
+  /**
+   * Abort all outstanding handles with a `stream-closed` error.
+   * Called when the upstream event source terminates before the
+   * messages it was assembling had a chance to finish.
+   */
+  close(): void;
+}
+//#endregion
+export { AnyMediaHandle, AudioMedia, FileMedia, ImageMedia, MediaAssembler, MediaAssemblerCallbacks, MediaAssemblerOptions, MediaAssemblyError, MediaAssemblyErrorKind, MediaBase, MediaBlockType, VideoMedia };
+//# sourceMappingURL=media.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"media.d.ts","names":[],"sources":["../../../src/client/stream/media.ts"],"mappings":";;;;;AAYA;KAAY,cAAA;;;;AAmBZ;;;;;AAWA;;KAXY,sBAAA;;;;;;;cAWC,kBAAA,SAA2B,KAAA;EAAA,SAC7B,IAAA,EAAM,sBAAA;EAAA,SACN,SAAA;EAAA,SACA,YAAA,EAAc,UAAA;EAAA,SAEd,KAAA;EAET,WAAA,CACE,IAAA,EAAM,sBAAA,EACN,SAAA,UACA,YAAA,EAAc,UAAA,EACd,OAAA,WACA,OAAA;IAAY,KAAA;EAAA;AAAA;;;;;;;;;;;AAuBhB;;UAAiB,SAAA;EAAA,SACN,SAAA;EAAA,SACA,SAAA;EAAA,SACA,IAAA;EA8BM;EAAA,SA5BN,EAAA;EAAA,SACA,QAAA;EAyCQ;;;;;EAAA,SAnCR,GAAA;EAPA;;;;;;;;;;;;;;;;EAAA,SAyBA,MAAA,EAAQ,cAAA,CAAe,UAAA;EA2B1B;EAAA,SAxBG,IAAA,EAAM,OAAA,CAAQ,IAAA;EA2BR;;;;;;EAAA,SAnBN,SAAA,EAAW,OAAA;EA0BC;EAAA,SAvBZ,YAAA,EAAc,UAAA;EAuBK;EAAA,SApBnB,KAAA,GAAQ,kBAAA;EAuBS;EAAA,SApBjB,SAAA;EAoBkC;;;;;EAb3C,MAAA;AAAA;AAAA,UAGe,UAAA,SAAmB,SAAA;EAAA,SACzB,IAAA;;;;AAqBX;;WAfW,UAAA,EAAY,OAAA;AAAA;AAAA,UAGN,UAAA,SAAmB,SAAA;EAAA,SACzB,IAAA;EAcA;EAAA,SAZA,KAAA;EAYQ;EAAA,SAVR,MAAA;AAAA;AAAA,UAGM,UAAA,SAAmB,SAAA;EAAA,SACzB,IAAA;AAAA;AAAA,UAGM,SAAA,SAAkB,SAAA;EAAA,SACxB,IAAA;EAKkE;EAAA,SAHlE,QAAA;AAAA;AAAA,KAGC,cAAA,GAAiB,UAAA,GAAa,UAAA,GAAa,UAAA,GAAa,SAAA;;;;;AA+apE;UAAiB,uBAAA;EACf,OAAA,IAAW,KAAA,EAAO,UAAA;EAClB,OAAA,IAAW,KAAA,EAAO,UAAA;EAClB,OAAA,IAAW,KAAA,EAAO,UAAA;EAClB,MAAA,IAAU,KAAA,EAAO,SAAA;EAAA;;;;;EAMjB,OAAA,IAAW,KAAA,EAAO,cAAA;AAAA;AAAA,UAGH,qBAAA,SAA8B,uBAAA;EAX3B;;;;EAgBlB,KAAA,UAAe,KAAA;AAAA;AAAA,cAgDJ,cAAA;EAAA;EAcX,WAAA,CAAY,OAAA,GAAS,qBAAA;EAtEH;;;;EA2FlB,OAAA,CAAQ,KAAA,EAAO,aAAA;EAxFsB;;;;;EAiXrC,KAAA,CAAA;AAAA"}