blazen 0.1.156 → 0.1.158

package/index.d.ts

@@ -901,6 +901,113 @@ export declare class CompletionModel {
 }
 export type JsCompletionModel = CompletionModel
 
+/**
+ * Pluggable registry for multimodal content. Wraps
+ * [`Arc<dyn blazen_llm::content::ContentStore>`].
+ *
+ * Construct via the static factories (e.g. `ContentStore.inMemory()`,
+ * `ContentStore.custom({ put, resolve, fetchBytes })`) or by extending
+ * `ContentStore` and overriding the async methods. Stores are cheap to
+ * clone — internally an `Arc` — so passing the same instance across
+ * multiple agents / requests is fine.
+ */
+export declare class ContentStore {
+  /**
+   * Base-class constructor. Call from your subclass via `super()`.
+   * On its own, the base class is not useful — the default method
+   * implementations raise.
+   */
+  constructor()
+  /** Build a default ephemeral in-memory store. */
+  static inMemory(): ContentStore
+  /** Build a store backed by the `OpenAI` Files API. */
+  static openaiFiles(apiKey: string, baseUrl?: string | undefined | null): ContentStore
+  /** Build a store backed by the Anthropic Files API. */
+  static anthropicFiles(apiKey: string, baseUrl?: string | undefined | null): ContentStore
+  /** Build a store backed by the Gemini Files API. */
+  static geminiFiles(apiKey: string, baseUrl?: string | undefined | null): ContentStore
+  /** Build a store backed by fal.ai's storage API. */
+  static falStorage(apiKey: string, baseUrl?: string | undefined | null): ContentStore
+  /**
+   * Build a store backed by user-supplied async callbacks.
+   *
+   * Mirrors the Rust [`CustomContentStore::builder`] API. The
+   * `options` object must provide at least `put`, `resolve`, and
+   * `fetchBytes`; `fetchStream` and `delete` are optional. All
+   * callbacks must be `async` (or return a `Promise`).
+   *
+   * Argument shapes seen by JS:
+   *
+   * - `put(body, hint)`: `body` is a JSON-tagged
+   *   [`ContentBody`] (`{type: "bytes", data: number[]}`,
+   *   `{type: "url", url: string}`, `{type: "local_path", path: string}`,
+   *   or `{type: "provider_file", provider: string, id: string}`).
+   *   `hint` is a [`ContentHint`] dict (all fields optional). Must
+   *   resolve with a [`ContentHandle`]-shaped object
+   *   `{id, kind, mimeType?, byteSize?, displayName?}`.
+   * - `resolve(handle)`: `handle` is a [`ContentHandle`] dict. Must
+   *   resolve with a serialized [`MediaSource`] object
+   *   (e.g. `{type: "url", url: "..."}`).
+   * - `fetchBytes(handle)`: must resolve with a `Buffer`,
+   *   `Uint8Array`, or `number[]` of bytes.
+   * - `fetchStream(handle)` (optional): may resolve with either bytes
+   *   (`Buffer` / `Uint8Array` / `number[]` / base64 string) or an
+   *   `AsyncIterable<Uint8Array>` for chunk-by-chunk streaming.
+   * - `delete(handle)` (optional): must resolve with `undefined`.
+   */
+  static custom(options: CustomContentStoreOptions): ContentStore
+  /**
+   * Persist content and return a freshly-issued handle.
+   *
+   * `body` is either:
+   * - a `Buffer` — inline bytes uploaded to the store, or
+   * - a `string` — interpreted as a URL when it contains `"://"` (the
+   *   store records the reference) and as a local filesystem path
+   *   otherwise (the store reads or copies the file as needed).
+   */
+  put(body: Buffer | string, options: PutOptions): Promise<JsContentHandle>
+  /**
+   * Resolve a handle to a wire-renderable [`MediaSource`] (returned as a
+   * JS object — the same JSON shape Blazen's request builders accept).
+   */
+  resolve(handle: JsContentHandle): Promise<any>
+  /**
+   * Fetch raw bytes for a handle. Tools that need to operate on the
+   * actual content (parse a PDF, transcribe audio) call this; most tools
+   * reason over the handle and let `resolve` produce the wire form.
+   */
+  fetchBytes(handle: JsContentHandle): Promise<Buffer>
+  /**
+   * Stream raw bytes for a handle chunk-by-chunk.
+   *
+   * Returns a `Promise<AsyncIterable<Uint8Array>>`. Each `next()` call on
+   * the iterator pulls one chunk from the underlying [`ByteStream`]; the
+   * iterator is automatically `done` once the stream completes. Errors
+   * surfaced mid-stream reject the corresponding `next()` promise.
+   *
+   * Useful for large payloads where holding the entire body in a
+   * [`Buffer`] would be wasteful — pipe directly into a file, an HTTP
+   * response, or another transform without buffering.
+   *
+   * Built-in stores that lack a native streaming path fall back to a
+   * single-chunk iterator over [`Self::fetch_bytes`].
+   */
+  fetchStream(handle: JsContentHandle): Promise<AsyncIterable<Uint8Array>>
+  /** Cheap metadata lookup without materializing the bytes. */
+  metadata(handle: JsContentHandle): Promise<JsContentMetadata>
+  /**
+   * Optional cleanup — remove the handle from the store. Default
+   * implementations on most stores are no-ops.
+   */
+  delete(handle: JsContentHandle): Promise<void>
+  /**
+   * Build a filesystem-backed store rooted at `root`. The directory is
+   * created if it doesn't yet exist.
+   */
+  static localFile(root: string): ContentStore
+}
+export type JsContentStore = ContentStore
+
 /**
  * Shared workflow context accessible by all steps.
  *
@@ -1752,6 +1859,54 @@ export declare class HttpClient {
 }
 export type JsHttpClient = HttpClient
 
+/**
+ * HTTP/JSON peer client. Mirrors
+ * [`crate::peer::client::JsBlazenPeerClient`]'s method surface but speaks
+ * pure HTTP/JSON to a peer (or peer-shim) at `baseUrl`. Available on every
+ * target — including `wasm32-wasip1*` where the gRPC client doesn't
+ * compile.
+ *
+ * ```typescript
+ * const client = HttpPeerClient.newHttp("https://peer.example.com", "node-a");
+ * const resp = await client.invokeSubWorkflow({
+ *     workflowName: "summarize",
+ *     stepIds: ["fetch", "summarize"],
+ *     input: { url: "https://example.com" },
+ *     timeoutSecs: 60,
+ * });
+ * ```
+ */
+export declare class HttpPeerClient {
+  /**
+   * Build a new HTTP/JSON peer client.
+   *
+   * `baseUrl` is the peer's HTTP root (e.g.
+   * `https://peer.example.com`); a trailing slash is tolerated and
+   * trimmed before each request. `nodeId` identifies this caller in
+   * trace logs and is sent to the peer as the
+   * `X-Blazen-Peer-Node-Id` header.
+   *
+   * On wasi the underlying HTTP client comes from a
+   * [`blazen_llm::http_napi_wasi::LazyHttpClient`] proxy that defers
+   * to whatever the host registered via `setDefaultHttpClient`. On
+   * native a stock [`blazen_llm::ReqwestHttpClient`] is used.
+   */
+  static newHttp(baseUrl: string, nodeId: string): HttpPeerClient
+  /** Invoke a sub-workflow on the connected peer. */
+  invokeSubWorkflow(request: JsSubWorkflowRequest): Promise<JsSubWorkflowResponse>
+  /**
+   * Dereference a remote session ref. Returns the raw bytes of the
+   * underlying value and the envelope version of the response.
+   */
+  derefSessionRef(request: JsDerefRequest): Promise<JsDerefResponse>
+  /**
+   * Release (drop) a remote session ref. Returns whether the ref was
+   * found and released on the origin node.
+   */
+  releaseSessionRef(request: JsReleaseRequest): Promise<JsReleaseResponse>
+}
+export type JsHttpPeerClient = HttpPeerClient
+
 /**
  * Base class for custom image-generation providers.
  *
@@ -2236,20 +2391,12 @@ export declare class Memory {
    * @param backend  - An `InMemoryBackend` instance.
    */
   constructor(embedder: EmbeddingModel, backend: InMemoryBackend)
-  /** Create a memory store with an embedding model and a `JsonlBackend`. */
-  static withJsonl(embedder: EmbeddingModel, backend: JsonlBackend): Memory
-  /** Create a memory store with an embedding model and a `ValkeyBackend`. */
-  static withValkey(embedder: EmbeddingModel, backend: ValkeyBackend): Memory
   /**
    * Create a memory store in local-only mode (no embedding model) with an `InMemoryBackend`.
    *
    * Only `searchLocal()` is available; `search()` will throw.
    */
   static local(backend: InMemoryBackend): Memory
-  /** Create a memory store in local-only mode with a `JsonlBackend`. */
-  static localJsonl(backend: JsonlBackend): Memory
-  /** Create a memory store in local-only mode with a `ValkeyBackend`. */
-  static localValkey(backend: ValkeyBackend): Memory
   /**
    * Add a text entry to the memory store.
    *
@@ -2305,6 +2452,18 @@ export declare class Memory {
   delete(id: string): Promise<boolean>
   /** Return the number of entries in the store. */
   count(): Promise<number>
+  /** Create a memory store with an embedding model and a `JsonlBackend`. */
+  static withJsonl(embedder: EmbeddingModel, backend: JsonlBackend): Memory
+  /** Create a memory store with an embedding model and a `ValkeyBackend`. */
+  static withValkey(embedder: EmbeddingModel, backend: ValkeyBackend): Memory
+  /** Create a memory store in local-only mode with a `JsonlBackend`. */
+  static localJsonl(backend: JsonlBackend): Memory
+  /** Create a memory store in local-only mode with a `ValkeyBackend`. */
+  static localValkey(backend: ValkeyBackend): Memory
+  /** Create a memory store with an embedding model and an `UpstashBackend`. */
+  static withUpstash(embedder: EmbeddingModel, backend: UpstashBackend): Memory
+  /** Create a memory store in local-only mode with an `UpstashBackend`. */
+  static localUpstash(backend: UpstashBackend): Memory
 }
 export type JsMemory = Memory
 
@@ -2954,6 +3113,48 @@ export declare class ParallelSubWorkflowsStep {
 }
 export type JsParallelSubWorkflowsStep = ParallelSubWorkflowsStep
 
+/**
+ * Abstract base class for custom peer-client transports.
+ *
+ * Mirrors [`blazen_core::distributed::PeerClient`]. Subclass and
+ * override `invokeSubWorkflow`, `derefSessionRef`, and
+ * `releaseSessionRef` to plug a JS-side transport into Blazen's
+ * distributed-execution surface. The canonical gRPC implementation
+ * lives in `BlazenPeerClient`
+ * ([`crate::peer::JsBlazenPeerClient`]); this base exists for callers
+ * who want to swap in a different transport (HTTP, NATS, an in-process
+ * mock for tests, etc.) without touching the Rust core.
+ *
+ * ```javascript
+ * class MyTransport extends PeerClient {
+ *   async invokeSubWorkflow(request) { /* ... *\/ }
+ *   async derefSessionRef(refUuid) { /* ... *\/ }
+ *   async releaseSessionRef(refUuid) { /* ... *\/ }
+ * }
+ * ```
+ */
+export declare class PeerClient {
+  /** Create a new peer-client base instance. */
+  constructor()
+  /**
+   * Invoke a sub-workflow on the remote peer. Subclasses **must**
+   * override this method.
+   */
+  invokeSubWorkflow(request: JsRemoteWorkflowRequest): Promise<JsRemoteWorkflowResponse>
+  /**
+   * Dereference a remote session ref by UUID. Returns the raw
+   * payload bytes. Subclasses **must** override this method.
+   */
+  derefSessionRef(refUuid: string): Promise<Buffer>
+  /**
+   * Release (drop) a remote session ref on the origin node.
+   * Returns `true` when the ref was found and dropped, `false` when
+   * it was already gone. Subclasses **must** override this method.
+   */
+  releaseSessionRef(refUuid: string): Promise<boolean>
+}
+export type JsPeerClient = PeerClient
+
 /** A Perplexity chat completion provider. */
 export declare class PerplexityProvider {
   /** Create a new Perplexity provider. */
@@ -3486,8 +3687,10 @@ export declare class RetryMemoryBackend {
   static wrapJsonl(backend: JsonlBackend, config?: JsRetryConfig | undefined | null): RetryMemoryBackend
   /** Wrap a `ValkeyBackend` with retry-on-transient-error behaviour. */
   static wrapValkey(backend: ValkeyBackend, config?: JsRetryConfig | undefined | null): RetryMemoryBackend
+  /** Wrap an `UpstashBackend` with retry-on-transient-error behaviour. */
+  static wrapUpstash(backend: UpstashBackend, config?: JsRetryConfig | undefined | null): RetryMemoryBackend
   /**
-   * Generic factory accepting any of the three concrete backends. Useful
+   * Generic factory accepting any of the four concrete backends. Useful
    * when the caller doesn't statically know which backend is in hand.
    */
   static wrap(backend: AnyBackend, config?: JsRetryConfig | undefined | null): RetryMemoryBackend
@@ -3996,6 +4199,35 @@ export declare class ThreeDProvider {
 }
 export type JsThreeDProvider = ThreeDProvider
 
+/**
+ * Exact BPE token counter backed by `tiktoken-rs`.
+ *
+ * Mirrors the per-message overhead rules documented by `OpenAI` for GPT-3.5,
+ * GPT-4, GPT-4.1, and o-series models. Unknown model names return an error.
+ *
+ * ```javascript
+ * const counter = TiktokenCounter.forModel("gpt-4o");
+ * const n = counter.countTokens("Hello, world!");
+ * ```
+ */
+export declare class TiktokenCounter {
+  /**
+   * Create a counter tuned for the given model name.
+   *
+   * Throws if the model is unknown to `tiktoken-rs`.
+   */
+  static forModel(model: string): TiktokenCounter
+  /** Count tokens in a raw text string. */
+  countTokens(text: string): number
+  /** Count tokens for an array of chat messages, including per-message overhead. */
+  countMessageTokens(messages: Array<ChatMessage>): number
+  /** The model's context window size in tokens. */
+  contextSize(): number
+  /** Tokens remaining after the given prompt, saturating at zero. */
+  remainingTokens(messages: Array<ChatMessage>): number
+}
+export type JsTiktokenCounter = TiktokenCounter
+
 /** A Together AI chat completion provider. */
 export declare class TogetherProvider {
   /** Create a new Together provider. */
@@ -4341,6 +4573,37 @@ export declare class TypedTool {
 }
 export type JsTypedTool = TypedTool
 
+/**
+ * An Upstash Redis REST-backed backend for the memory store.
+ *
+ * Wasi-compatible alternative to [`JsValkeyBackend`] for Cloudflare Workers,
+ * Deno, and other wasi hosts that cannot use raw TCP. Talks to Upstash's
+ * REST API over the host-registered HTTP client (set via
+ * `setDefaultHttpClient`).
+ *
+ * ```javascript
+ * const backend = UpstashBackend.create("https://us1-merry-cat-32242.upstash.io", "AYAg...");
+ * const memory = Memory.withUpstash(embedder, backend);
+ * ```
+ */
+export declare class UpstashBackend {
+  /**
+   * Create an Upstash REST backend.
+   *
+   * `restUrl` is the Upstash REST endpoint (e.g.
+   * `https://us1-merry-cat-32242.upstash.io`). `restToken` is the REST
+   * token, sent as a `Bearer` token on every request. The HTTP client is
+   * resolved via `setDefaultHttpClient` — call that before issuing any
+   * memory operations.
+   *
+   * `prefix` overrides the default key prefix (`blazen:memory:`). Pass
+   * `null`/`undefined` for the default. Useful when running multiple
+   * logical stores against the same Upstash database.
+   */
+  static create(restUrl: string, restToken: string, prefix?: string | undefined | null): UpstashBackend
+}
+export type JsUpstashBackend = UpstashBackend
+
 /**
  * A sink for emitted [`JsUsageEvent`]s.
  *
@@ -4827,21 +5090,6 @@ export declare class WorkflowBuilder {
    * `crates/blazen-node/Cargo.toml`.
    */
   withHistory(): this
-  /**
-   * Attach a checkpoint store to the workflow.
-   *
-   * Mirrors [`blazen_core::WorkflowBuilder::checkpoint_store`]. The
-   * underlying call is gated on the `persist` feature of
-   * `blazen-core`, which is **not** currently enabled in the Node
-   * binding's compilation. The flag is recorded on the builder for
-   * forward compatibility but does not yet flow into the core
-   * engine — pass a [`JsCheckpointStore`] (typically a concrete
-   * subclass like `RedbCheckpointStore` or `ValkeyCheckpointStore`)
-   * so the JS API is stable; the binding will start forwarding the
-   * store once the `blazen-core/persist` feature is enabled in
-   * `crates/blazen-node/Cargo.toml`.
-   */
-  checkpointStore(store: CheckpointStore): this
   /**
    * Enable or disable automatic checkpointing after each step
    * completes. Same forward-compatibility caveat as
@@ -4861,6 +5109,21 @@ export declare class WorkflowBuilder {
    * are enabled in the Node binding's `Cargo.toml`.
    */
   build(): Workflow
+  /**
+   * Attach a checkpoint store to the workflow.
+   *
+   * Mirrors [`blazen_core::WorkflowBuilder::checkpoint_store`]. The
+   * underlying call is gated on the `persist` feature of
+   * `blazen-core`, which is **not** currently enabled in the Node
+   * binding's compilation. The flag is recorded on the builder for
+   * forward compatibility but does not yet flow into the core
+   * engine — pass a [`JsCheckpointStore`] (typically a concrete
+   * subclass like `RedbCheckpointStore` or `ValkeyCheckpointStore`)
+   * so the JS API is stable; the binding will start forwarding the
+   * store once the `blazen-core/persist` feature is enabled in
+   * `crates/blazen-node/Cargo.toml`.
+   */
+  checkpointStore(store: CheckpointStore): this
 }
 export type JsWorkflowBuilder = WorkflowBuilder
 
@@ -5181,6 +5444,12 @@ export interface AgentEvent {
   hadToolCalls?: boolean
 }
 
+/** Build a JSON Schema declaring a single required audio-handle input. */
+export declare function audioInput(name: string, description: string): any
+
+/** Build a JSON Schema declaring a single required CAD-file-handle input. */
+export declare function cadInput(name: string, description: string): any
+
 /** Configuration passed to any capability provider constructor. */
 export interface CapabilityProviderConfig {
   /** Short identifier for this provider (e.g. `"elevenlabs"`, `"fal"`). */
@@ -5410,6 +5679,45 @@ export declare function computeVideoCost(modelId: string, seconds: number): numb
  */
 export declare function countMessageTokens(messages: Array<ChatMessage>, contextSize?: number | undefined | null): number
 
+/**
+ * Plain object passed to [`JsContentStore::custom`].
+ *
+ * Each property is the JS-side implementation of one of the trait's
+ * methods. `put`, `resolve`, and `fetchBytes` are required; `fetchStream`
+ * and `delete` are optional.
+ *
+ * All callbacks must be `async` (or return a `Promise`) and accept the
+ * JSON shapes defined by [`ContentBody`] / [`ContentHint`] /
+ * [`ContentHandle`] on the input side; outputs are deserialized into the
+ * matching Rust types. See [`JsHostContentStore`] for the per-method
+ * payload shapes.
+ *
+ * `name` is a short identifier used in error / tracing messages; defaults
+ * to `"custom"`.
+ */
+export interface CustomContentStoreOptions {
+  /** Required: persist content, return a handle. */
+  put: (body: ContentBody, hint: ContentHint) => Promise<ContentHandle>
+  /** Required: turn a handle into a wire-renderable [`MediaSource`]. */
+  resolve: (handle: ContentHandle) => Promise<MediaSource>
+  /**
+   * Required: fetch raw bytes for a handle (`Buffer` | `Uint8Array` |
+   * `number[]`).
+   */
+  fetchBytes: (handle: ContentHandle) => Promise<Buffer | Uint8Array | number[] | string>
+  /**
+   * Optional: stream raw bytes; absent falls back to `fetchBytes`. May
+   * resolve with bytes (`Buffer` / `Uint8Array` / `number[]` / base64
+   * string) or an `AsyncIterable<Uint8Array>` for true chunk-by-chunk
+   * streaming.
+   */
+  fetchStream?: (handle: ContentHandle) => Promise<Buffer | Uint8Array | number[] | string | AsyncIterable<Uint8Array>>
+  /** Optional: cleanup hook; absent is a no-op. */
+  delete?: (handle: ContentHandle) => Promise<void>
+  /** Optional human-readable identifier for logs (default: `"custom"`). */
+  name?: string
+}
+
 /** Optional configuration for a [`JsCustomProvider`]. */
 export interface CustomProviderOptions {
   /**
@@ -5520,6 +5828,9 @@ export interface FileContent {
   filename?: string
 }
 
+/** Build a JSON Schema declaring a single required document/file-handle input. */
+export declare function fileInput(name: string, description: string): any
+
 /**
  * Canonical name of the built-in `finish_workflow` exit tool. Mirrors
  * [`blazen_llm::FINISH_WORKFLOW_TOOL_NAME`].
@@ -5634,6 +5945,15 @@ export interface HttpClientConfig {
   userAgent?: string
 }
 
+/**
+ * Build a JSON Schema declaring a single required image-handle input.
+ *
+ * The model fills the property with a content-handle id string; Blazen
+ * resolves it against the active [`super::store::JsContentStore`] before
+ * the tool's handler runs.
+ */
+export declare function imageInput(name: string, description: string): any
+
 /**
  * Initialize the Langfuse exporter and install it as a layer on the global
  * `tracing` subscriber.
@@ -5647,6 +5967,32 @@ export interface HttpClientConfig {
  */
 export declare function initLangfuse(config: LangfuseConfig): void
 
+/**
+ * Initialize the OTLP trace exporter and install the global tracing
+ * subscriber.
+ *
+ * Calling this more than once in a single process will fail because the
+ * global subscriber can only be installed once.
+ */
+export declare function initOtlp(config: OtlpConfig): void
+
+/**
+ * Initialize the Prometheus metrics exporter and start its HTTP listener
+ * on `0.0.0.0:{port}`.
+ *
+ * After calling this, every workflow / step / LLM span emitted via the
+ * `tracing` infrastructure feeds into counters and histograms exposed at
+ * `http://0.0.0.0:{port}/metrics` for Prometheus to scrape.
+ *
+ * ```javascript
+ * initPrometheus(9100);
+ * ```
+ *
+ * Calling this more than once in a single process will fail because the
+ * global recorder can only be installed once.
+ */
+export declare function initPrometheus(port: number): void
+
 /**
  * A request for human input emitted by a workflow step.
  *
@@ -5986,6 +6332,59 @@ export interface JsComputeResult {
   metadata: any
 }
 
+/**
+ * Reference to content stored in a [`super::store::JsContentStore`].
+ *
+ * Mirrors [`blazen_llm::content::ContentHandle`]. Pass instances to a
+ * store's `resolve` / `fetchBytes` / `metadata` / `delete` methods, or
+ * embed the `id` in tool arguments where a content reference is expected.
+ */
+export interface JsContentHandle {
+  /** Opaque, store-defined identifier. Treat as a black box. */
+  id: string
+  /** What kind of content this handle refers to. */
+  kind: JsContentKind
+  /** MIME type if known. */
+  mimeType?: string
+  /** Byte size if known. `i64` because napi has no `u64`. */
+  byteSize?: number
+  /** Human-readable display name (e.g. original filename). */
+  displayName?: string
+}
+
+/**
+ * Taxonomy of multimodal content kinds. Mirrors
+ * [`blazen_llm::content::ContentKind`].
+ *
+ * String values match the JSON / `serde` tag (`"image"`, `"three_d_model"`,
+ * etc.) so they can be round-tripped against any Blazen API that accepts a
+ * kind string.
+ */
+export declare const enum JsContentKind {
+  Image = 'image',
+  Audio = 'audio',
+  Video = 'video',
+  Document = 'document',
+  ThreeDModel = 'three_d_model',
+  Cad = 'cad',
+  Archive = 'archive',
+  Font = 'font',
+  Code = 'code',
+  Data = 'data',
+  Other = 'other'
+}
+
+/**
+ * Cheap metadata summary returned by
+ * [`JsContentStore::metadata`](JsContentStore::metadata).
+ */
+export interface JsContentMetadata {
+  kind: JsContentKind
+  mimeType?: string
+  byteSize?: number
+  displayName?: string
+}
+
 /**
  * A single part in a multi-part message.
  *
@@ -6268,11 +6667,38 @@ export interface JsImageResult {
   metadata: any
 }
 
-/** How an image is provided (URL or base64). */
+/**
+ * How an image / audio / video / file is provided.
+ *
+ * `sourceType` is one of:
+ * - `"url"` — set `url` to a public URL.
+ * - `"base64"` — set `data` to the base64-encoded payload.
+ * - `"file"` — set `url` to a local filesystem path (local backends only).
+ * - `"providerFile"` — set `provider` and `id` to reference an
+ *   already-uploaded file in a provider's file API (`OpenAI` Files,
+ *   Anthropic Files, Gemini Files, fal.ai storage).
+ * - `"handle"` — set `handleId` (and optionally `handleKind`) to reference
+ *   content registered with a `ContentStore`. The store resolves the
+ *   handle at request-build time.
+ */
 export interface JsImageSource {
   sourceType: string
   url?: string
   data?: string
+  /**
+   * Provider name for `sourceType: "providerFile"` (e.g. `"openai"`,
+   * `"anthropic"`, `"gemini"`, `"fal"`).
+   */
+  provider?: string
+  /** Provider-issued file id for `sourceType: "providerFile"`. */
+  id?: string
+  /** Content handle id for `sourceType: "handle"`. */
+  handleId?: string
+  /**
+   * Content handle kind for `sourceType: "handle"` (e.g. `"image"`,
+   * `"audio"`, `"three_d_model"`). See `ContentKind` for the full set.
+   */
+  handleKind?: string
 }
 
 export interface JsJobHandle {
@@ -6561,6 +6987,52 @@ export interface JsReleaseResponse {
   released: boolean
 }
 
+/**
+ * Transport-agnostic request for invoking a sub-workflow on a remote
+ * peer.
+ *
+ * Mirrors [`blazen_core::distributed::RemoteWorkflowRequest`]. Concrete
+ * transports (gRPC, HTTP, NATS, etc.) serialize this into whatever
+ * wire format they require.
+ */
+export interface JsRemoteWorkflowRequest {
+  /** Symbolic name of the workflow to invoke on the remote peer. */
+  workflowName: string
+  /** Ordered list of step IDs to execute as part of this sub-workflow. */
+  stepIds: Array<string>
+  /** Initial input value passed to the workflow's first step. */
+  input: any
+  /**
+   * Optional timeout in seconds. `None` means "use the server's
+   * default deadline".
+   */
+  timeoutSecs?: number
+}
+
+/**
+ * Transport-agnostic response from a remote sub-workflow invocation.
+ *
+ * Mirrors [`blazen_core::distributed::RemoteWorkflowResponse`].
+ */
+export interface JsRemoteWorkflowResponse {
+  /**
+   * Optional terminal result. `None` when the workflow exited
+   * without producing one.
+   */
+  result?: any
+  /**
+   * Descriptors for any session refs the sub-workflow registered
+   * that the parent should be able to dereference remotely. Keyed
+   * by the registry UUID rendered as a string.
+   */
+  remoteRefs: Record<string, any>
+  /**
+   * Error message if the sub-workflow failed. When `Some`, callers
+   * should ignore `result`.
+   */
+  error?: string
+}
+
 export interface JsRequestTiming {
   queueMs?: number
   executionMs?: number
@@ -7193,6 +7665,35 @@ export declare function newRetryStack(): RetryStack
  */
 export declare function newUsageEvent(provider: string, model: string, runId: string): UsageEvent
 
+/**
+ * Configuration for the OTLP exporter.
+ *
+ * ```javascript
+ * initOtlp({
+ *   endpoint: "http://localhost:4317",
+ *   serviceName: "my-service",
+ *   serviceVersion: "1.0.0",
+ *   headers: { "x-api-key": "secret" },
+ * });
+ * ```
+ */
+export interface OtlpConfig {
+  /** The OTLP endpoint URL (e.g. `"http://localhost:4317"`). */
+  endpoint: string
+  /** The service name reported to the backend. */
+  serviceName: string
+  /**
+   * Service version reported to the backend (recorded for forward
+   * compatibility; not yet forwarded by the underlying exporter).
+   */
+  serviceVersion?: string
+  /**
+   * Additional headers to attach to OTLP requests (recorded for forward
+   * compatibility; not yet forwarded by the underlying exporter).
+   */
+  headers?: Record<string, string>
+}
+
 /**
  * Why a workflow was paused.
  *
@@ -7376,6 +7877,24 @@ export declare const enum ProviderId {
   Fal = 'fal'
 }
 
+/**
+ * Optional hints attached to a `put` call.
+ *
+ * Mirrors [`blazen_llm::content::ContentHint`] minus its builder API. Every
+ * field is optional; the store may auto-detect from the bytes when a hint is
+ * missing.
+ */
+export interface PutOptions {
+  /** MIME type, if known. */
+  mimeType?: string
+  /** Caller's preferred classification — overrides any auto-detection. */
+  kind?: JsContentKind
+  /** Human-readable display name (filename, caption). */
+  displayName?: string
+  /** Byte size, if known up-front. `i64` since napi has no `u64`. */
+  byteSize?: number
+}
+
 /** Options for constructing a [`JsReasoningTraceClass`] from JavaScript. */
 export interface ReasoningTraceOptions {
   /** Plain-text rendering of the reasoning content. */
@@ -7819,6 +8338,9 @@ export declare const enum TemplateRole {
   Assistant = 'Assistant'
 }
 
+/** Build a JSON Schema declaring a single required 3D-model-handle input. */
+export declare function threeDInput(name: string, description: string): any
+
 /** Options for constructing a [`JsTokenUsageClass`] from JavaScript. */
 export interface TokenUsageOptions {
   promptTokens: number
@@ -7977,9 +8499,40 @@ export interface UsageEvent {
 /** Returns the version of the blazen library. */
 export declare function version(): string
 
+/** Build a JSON Schema declaring a single required video-handle input. */
+export declare function videoInput(name: string, description: string): any
+
 // --- post-build: type aliases mirroring blazen-llm ---
 export type MediaSource = JsImageSource
 export type ImageSource = JsImageSource
+export type ContentHandle = JsContentHandle
+export type ContentMetadata = JsContentMetadata
+export type ContentKind = JsContentKind
+
+// --- post-build: ContentBody / ContentHint helper types ---
+/**
+ * JSON-tagged body passed to a custom store's `put` callback.
+ *
+ * Mirrors `blazen_llm::content::ContentBody`. The `stream` variant
+ * carries a live `AsyncIterable<Uint8Array>` so chunks flow lazily
+ * from Rust into JS without staging the whole payload in memory.
+ */
+export type ContentBody =
+  | { type: 'bytes'; data: Buffer | Uint8Array | number[] }
+  | { type: 'url'; url: string }
+  | { type: 'local_path'; path: string }
+  | { type: 'provider_file'; provider: string; id: string }
+  | { type: 'stream'; stream: AsyncIterable<Uint8Array>; sizeHint: number | null }
+/**
+ * Optional hints passed alongside a `ContentBody` into `put`.
+ * Mirrors `blazen_llm::content::ContentHint` (every field optional).
+ */
+export interface ContentHint {
+  mimeType?: string | null
+  kind?: ContentKind | null
+  displayName?: string | null
+  byteSize?: number | null
+}
 
 // --- post-build: typed error classes ---
 export class BlazenError extends Error {}

package/index.js

@@ -622,6 +622,8 @@ module.exports.CohereProvider = nativeBinding.CohereProvider
 module.exports.JsCohereProvider = nativeBinding.JsCohereProvider
 module.exports.CompletionModel = nativeBinding.CompletionModel
 module.exports.JsCompletionModel = nativeBinding.JsCompletionModel
+module.exports.ContentStore = nativeBinding.ContentStore
+module.exports.JsContentStore = nativeBinding.JsContentStore
 module.exports.Context = nativeBinding.Context
 module.exports.JsContext = nativeBinding.JsContext
 module.exports.CustomProvider = nativeBinding.CustomProvider
@@ -658,6 +660,8 @@ module.exports.HostDispatch = nativeBinding.HostDispatch
 module.exports.JsHostDispatch = nativeBinding.JsHostDispatch
 module.exports.HttpClient = nativeBinding.HttpClient
 module.exports.JsHttpClient = nativeBinding.JsHttpClient
+module.exports.HttpPeerClient = nativeBinding.HttpPeerClient
+module.exports.JsHttpPeerClient = nativeBinding.JsHttpPeerClient
 module.exports.ImageModel = nativeBinding.ImageModel
 module.exports.JsImageModel = nativeBinding.JsImageModel
 module.exports.ImageProvider = nativeBinding.ImageProvider
@@ -736,6 +740,8 @@ module.exports.ParallelStage = nativeBinding.ParallelStage
 module.exports.JsParallelStage = nativeBinding.JsParallelStage
 module.exports.ParallelSubWorkflowsStep = nativeBinding.ParallelSubWorkflowsStep
 module.exports.JsParallelSubWorkflowsStep = nativeBinding.JsParallelSubWorkflowsStep
+module.exports.PeerClient = nativeBinding.PeerClient
+module.exports.JsPeerClient = nativeBinding.JsPeerClient
 module.exports.PerplexityProvider = nativeBinding.PerplexityProvider
 module.exports.JsPerplexityProvider = nativeBinding.JsPerplexityProvider
 module.exports.Pipeline = nativeBinding.Pipeline
@@ -802,6 +808,8 @@ module.exports.SubWorkflowStep = nativeBinding.SubWorkflowStep
 module.exports.JsSubWorkflowStep = nativeBinding.JsSubWorkflowStep
 module.exports.ThreeDProvider = nativeBinding.ThreeDProvider
 module.exports.JsThreeDProvider = nativeBinding.JsThreeDProvider
+module.exports.TiktokenCounter = nativeBinding.TiktokenCounter
+module.exports.JsTiktokenCounter = nativeBinding.JsTiktokenCounter
 module.exports.TogetherProvider = nativeBinding.TogetherProvider
 module.exports.JsTogetherProvider = nativeBinding.JsTogetherProvider
 module.exports.TokenCounter = nativeBinding.TokenCounter
@@ -822,6 +830,8 @@ module.exports.TTSProvider = nativeBinding.TTSProvider
 module.exports.JsTTSProvider = nativeBinding.JsTTSProvider
 module.exports.TypedTool = nativeBinding.TypedTool
 module.exports.JsTypedTool = nativeBinding.JsTypedTool
+module.exports.UpstashBackend = nativeBinding.UpstashBackend
+module.exports.JsUpstashBackend = nativeBinding.JsUpstashBackend
 module.exports.UsageEmitter = nativeBinding.UsageEmitter
 module.exports.JsUsageEmitter = nativeBinding.JsUsageEmitter
 module.exports.UsageRecordingCompletionModel = nativeBinding.UsageRecordingCompletionModel
@@ -853,6 +863,8 @@ module.exports.JsWorkflowSnapshot = nativeBinding.JsWorkflowSnapshot
 module.exports.XaiProvider = nativeBinding.XaiProvider
 module.exports.JsXaiProvider = nativeBinding.JsXaiProvider
 module.exports.addUsageToTokenUsage = nativeBinding.addUsageToTokenUsage
+module.exports.audioInput = nativeBinding.audioInput
+module.exports.cadInput = nativeBinding.cadInput
 module.exports.ChatRole = nativeBinding.ChatRole
 module.exports.JsChatRole = nativeBinding.JsChatRole
 module.exports.completeBatch = nativeBinding.completeBatch
@@ -868,6 +880,7 @@ module.exports.defaultHttpClientConfig = nativeBinding.defaultHttpClientConfig
 module.exports.envVarForProvider = nativeBinding.envVarForProvider
 module.exports.estimateTokens = nativeBinding.estimateTokens
 module.exports.extractInlineArtifacts = nativeBinding.extractInlineArtifacts
+module.exports.fileInput = nativeBinding.fileInput
 module.exports.FINISH_WORKFLOW_TOOL_NAME = nativeBinding.FINISH_WORKFLOW_TOOL_NAME
 module.exports.finishWorkflowTool = nativeBinding.finishWorkflowTool
 module.exports.finishWorkflowToolDef = nativeBinding.finishWorkflowToolDef
@@ -875,12 +888,16 @@ module.exports.formatProviderHttpTail = nativeBinding.formatProviderHttpTail
 module.exports.getContextWindow = nativeBinding.getContextWindow
 module.exports.HistoryEventKindTag = nativeBinding.HistoryEventKindTag
 module.exports.JsHistoryEventKindTag = nativeBinding.JsHistoryEventKindTag
+module.exports.imageInput = nativeBinding.imageInput
 module.exports.initLangfuse = nativeBinding.initLangfuse
+module.exports.initOtlp = nativeBinding.initOtlp
+module.exports.initPrometheus = nativeBinding.initPrometheus
 module.exports.internEventType = nativeBinding.internEventType
 module.exports.JoinStrategy = nativeBinding.JoinStrategy
 module.exports.JsJoinStrategy = nativeBinding.JsJoinStrategy
 module.exports.JsAuthMethod = nativeBinding.JsAuthMethod
 module.exports.JsCacheStrategy = nativeBinding.JsCacheStrategy
+module.exports.JsContentKind = nativeBinding.JsContentKind
 module.exports.JsDiffusionScheduler = nativeBinding.JsDiffusionScheduler
 module.exports.JsFalLlmEndpointKind = nativeBinding.JsFalLlmEndpointKind
 module.exports.JsJobStatus = nativeBinding.JsJobStatus
@@ -927,10 +944,12 @@ module.exports.StepOutputKind = nativeBinding.StepOutputKind
 module.exports.JsStepOutputKind = nativeBinding.JsStepOutputKind
 module.exports.TemplateRole = nativeBinding.TemplateRole
 module.exports.JsTemplateRole = nativeBinding.JsTemplateRole
+module.exports.threeDInput = nativeBinding.threeDInput
 module.exports.tryDeserializeEvent = nativeBinding.tryDeserializeEvent
 module.exports.typedToolSimple = nativeBinding.typedToolSimple
 module.exports.unlimitedHttpClientConfig = nativeBinding.unlimitedHttpClientConfig
 module.exports.version = nativeBinding.version
+module.exports.videoInput = nativeBinding.videoInput
 
 // --- post-build: typed-error wrapping ---
 ;(() => {
@@ -1001,9 +1020,27 @@ module.exports.version = nativeBinding.version
     // emits classes with PascalCase names; we leave those callable as-is
     // so `new ClassName(...)` keeps working but their methods are
     // already patched above.
-    const isLikelyClass =
+    //
+    // Detect "class-ness" via either prototype methods OR own static
+    // properties beyond the built-in function metadata fields. Without the
+    // static-property check, a class whose only public surface is a static
+    // factory (e.g. `UpstashBackend.create`) would slip through and get
+    // replaced with a `wrap()`-returned function that loses the static
+    // method.
+    const FUNCTION_BUILTIN_PROPS = new Set([
+      'length',
+      'name',
+      'arguments',
+      'caller',
+      'prototype',
+    ])
+    const ownStaticPropNames = Object.getOwnPropertyNames(orig).filter(
+      (p) => !FUNCTION_BUILTIN_PROPS.has(p),
+    )
+    const hasPrototypeMethods =
       orig.prototype &&
       Object.getOwnPropertyNames(orig.prototype).some((p) => p !== 'constructor')
+    const isLikelyClass = hasPrototypeMethods || ownStaticPropNames.length > 0
     if (!isLikelyClass) {
       module.exports[key] = wrap(orig)
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "blazen",
-  "version": "0.1.156",
+  "version": "0.1.158",
   "description": "Blazen - Event-driven AI workflow framework for Node.js/TypeScript",
   "main": "index.js",
   "types": "index.d.ts",
@@ -13,7 +13,8 @@
       "aarch64-unknown-linux-gnu",
       "aarch64-unknown-linux-musl",
       "aarch64-apple-darwin",
-      "x86_64-pc-windows-msvc"
+      "x86_64-pc-windows-msvc",
+      "wasm32-wasi"
     ]
   },
   "publishConfig": {
@@ -39,8 +40,12 @@
     "error-classes.js"
   ],
   "devDependencies": {
-    "@napi-rs/cli": "^3.0.0",
     "@biomejs/biome": "^2",
+    "@emnapi/core": "^1.10.0",
+    "@emnapi/runtime": "^1.10.0",
+    "@napi-rs/cli": "^3.0.0",
+    "@napi-rs/wasm-runtime": "^1.1.4",
+    "@tybys/wasm-util": "^0.10.2",
     "ava": "^6.4.1"
   },
   "engines": {
@@ -58,12 +63,13 @@
     "verbose": true
   },
   "optionalDependencies": {
-    "@blazen-dev/blazen-linux-x64-gnu": "0.1.156",
-    "@blazen-dev/blazen-linux-x64-musl": "0.1.156",
-    "@blazen-dev/blazen-linux-arm64-gnu": "0.1.156",
-    "@blazen-dev/blazen-linux-arm64-musl": "0.1.156",
-    "@blazen-dev/blazen-darwin-arm64": "0.1.156",
-    "@blazen-dev/blazen-win32-x64-msvc": "0.1.156"
+    "@blazen-dev/blazen-linux-x64-gnu": "0.1.158",
+    "@blazen-dev/blazen-linux-x64-musl": "0.1.158",
+    "@blazen-dev/blazen-linux-arm64-gnu": "0.1.158",
+    "@blazen-dev/blazen-linux-arm64-musl": "0.1.158",
+    "@blazen-dev/blazen-darwin-arm64": "0.1.158",
+    "@blazen-dev/blazen-win32-x64-msvc": "0.1.158",
+    "@blazen-dev/blazen-wasm32-wasi": "0.1.158"
   },
   "scripts": {
     "build": "napi build --release --platform --features local-all,langfuse --js index.js && node scripts/post-build.mjs",