blazen 0.5.3 → 0.5.4

package/blazen.workers.js

@@ -81,6 +81,8 @@ export const AnthropicProvider = __napiModule.exports.AnthropicProvider
 export const JsAnthropicProvider = __napiModule.exports.JsAnthropicProvider
 export const ApiProtocol = __napiModule.exports.ApiProtocol
 export const JsApiProtocol = __napiModule.exports.JsApiProtocol
+export const AssignmentContext = __napiModule.exports.AssignmentContext
+export const JsAssignmentContext = __napiModule.exports.JsAssignmentContext
 export const AudioMusicProviderDefaults = __napiModule.exports.AudioMusicProviderDefaults
 export const JsAudioMusicProviderDefaults = __napiModule.exports.JsAudioMusicProviderDefaults
 export const AudioSpeechProviderDefaults = __napiModule.exports.AudioSpeechProviderDefaults
@@ -137,6 +139,12 @@ export const ContentStore = __napiModule.exports.ContentStore
 export const JsContentStore = __napiModule.exports.JsContentStore
 export const Context = __napiModule.exports.Context
 export const JsContext = __napiModule.exports.JsContext
+export const ControlPlaneClient = __napiModule.exports.ControlPlaneClient
+export const JsControlPlaneClient = __napiModule.exports.JsControlPlaneClient
+export const ControlPlaneWorker = __napiModule.exports.ControlPlaneWorker
+export const JsControlPlaneWorker = __napiModule.exports.JsControlPlaneWorker
+export const ControlPlaneWorkerConfig = __napiModule.exports.ControlPlaneWorkerConfig
+export const JsControlPlaneWorkerConfig = __napiModule.exports.JsControlPlaneWorkerConfig
 export const CustomProvider = __napiModule.exports.CustomProvider
 export const JsCustomProvider = __napiModule.exports.JsCustomProvider
 export const DeepSeekProvider = __napiModule.exports.DeepSeekProvider
@@ -422,6 +430,7 @@ export const initPrometheus = __napiModule.exports.initPrometheus
 export const internEventType = __napiModule.exports.internEventType
 export const JoinStrategy = __napiModule.exports.JoinStrategy
 export const JsJoinStrategy = __napiModule.exports.JsJoinStrategy
+export const JsAdmissionModeTag = __napiModule.exports.JsAdmissionModeTag
 export const JsAuthMethod = __napiModule.exports.JsAuthMethod
 export const JsCacheStrategy = __napiModule.exports.JsCacheStrategy
 export const JsContentKind = __napiModule.exports.JsContentKind
@@ -429,6 +438,7 @@ export const JsDiffusionScheduler = __napiModule.exports.JsDiffusionScheduler
 export const JsFalLlmEndpointKind = __napiModule.exports.JsFalLlmEndpointKind
 export const JsJobStatus = __napiModule.exports.JsJobStatus
 export const JsRole = __napiModule.exports.JsRole
+export const JsRunStatus = __napiModule.exports.JsRunStatus
 export const JsWhisperModel = __napiModule.exports.JsWhisperModel
 export const LlamaCppChatRole = __napiModule.exports.LlamaCppChatRole
 export const JsLlamaCppChatRole = __napiModule.exports.JsLlamaCppChatRole

package/error-classes.js

@@ -23,6 +23,77 @@
 
 const PROVIDER_ERROR_SENTINEL = '__BLAZEN_PROVIDER_ERROR__'
 
+// Sentinel + stash for caller-error preservation. The napi side
+// formats `__BLAZEN_CALLER_ERROR__ {json} \n [CallerError] msg` when a
+// user's tool handler threw. The JSON `ref` is a UUID that maps to an
+// entry in `callerErrorStash` (populated by `wrapToolHandlerForCallerErrors`
+// below); the stashed value is the ORIGINAL JS Error instance -- so
+// `enrichError` can re-throw it verbatim, preserving `instanceof MyError`
+// and all custom properties. See `crates/blazen-node/src/error.rs`
+// CALLER_ERROR_SENTINEL.
+const CALLER_ERROR_SENTINEL = '__BLAZEN_CALLER_ERROR__'
+
+// Module-level Map keyed by UUID strings. Values are the original
+// thrown JS Error instances. Each entry is added by
+// `wrapToolHandlerForCallerErrors` and deleted in `enrichError` after
+// re-throw (or fall-back). Entries that escape the stash because the
+// agent loop produced a non-CallerError outcome are cleaned up by the
+// `runAgent` wrapper's `.finally(...)` (see `wrapRunAgentForCallerErrors`
+// in index.js).
+const callerErrorStash = new Map()
+
+// Build a fresh UUID string suitable for Map keys. Uses the built-in
+// crypto.randomUUID() when available (Node 14.17+); falls back to a
+// simple time+random pattern otherwise.
+function freshUuid() {
+  try {
+    // eslint-disable-next-line global-require
+    const { randomUUID } = require('crypto')
+    if (typeof randomUUID === 'function') {
+      return randomUUID()
+    }
+  } catch {
+    // Fall through.
+  }
+  return `caller-${Date.now()}-${Math.random().toString(36).slice(2)}`
+}
+
+// Wrap a user-supplied tool handler so any thrown / rejected error is
+// captured as an envelope `{__blazenOk: false, errorRef: uuid, errorName,
+// errorMessage}` and stashed for `enrichError` to re-throw. Success
+// returns become `{__blazenOk: true, value: <user's return>}`.
+//
+// Returns a freshly-wrapped function (does NOT mutate the user's
+// handler). The wrapped function is what the napi `runAgent` /
+// `runAgentWithCallback` Rust side sees.
+//
+// The wrapped function returns a Promise (always) so the napi
+// `Promise<serde_json::Value>` resolution path is uniform regardless of
+// whether the user's handler is sync or async.
+function wrapToolHandlerForCallerErrors(handler) {
+  if (typeof handler !== 'function') {
+    return handler
+  }
+  return async function blazenEnvelopeToolHandler(...args) {
+    try {
+      const value = await handler.apply(this, args)
+      return { __blazenOk: true, value }
+    } catch (error) {
+      const ref = freshUuid()
+      callerErrorStash.set(ref, error)
+      const errorName =
+        (error && typeof error === 'object' && typeof error.name === 'string')
+          ? error.name
+          : undefined
+      const errorMessage =
+        (error && typeof error === 'object' && typeof error.message === 'string')
+          ? error.message
+          : String(error)
+      return { __blazenOk: false, errorRef: ref, errorName, errorMessage }
+    }
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Class hierarchy
 // ---------------------------------------------------------------------------
@@ -702,6 +773,41 @@ function enrichError(err) {
     }
   }
 
+  // Detect and strip the caller-error sentinel. If the stash has the
+  // original error, re-throw it verbatim (preserves `instanceof MyError`
+  // and all custom properties). Otherwise fall back to a generic Error
+  // carrying the name+message from the sentinel JSON.
+  if (message.startsWith(CALLER_ERROR_SENTINEL)) {
+    const newlineIdx = message.indexOf('\n')
+    let payload = null
+    if (newlineIdx !== -1) {
+      const jsonPart = message
+        .slice(CALLER_ERROR_SENTINEL.length, newlineIdx)
+        .trim()
+      try {
+        payload = JSON.parse(jsonPart)
+      } catch {
+        payload = null
+      }
+    }
+    if (payload && typeof payload.ref === 'string') {
+      const original = callerErrorStash.get(payload.ref)
+      callerErrorStash.delete(payload.ref)
+      if (original !== undefined) {
+        return original
+      }
+    }
+    // Fallback: construct a generic Error with the sentinel-embedded
+    // name and message. instanceof won't match, but `.name` / `.message`
+    // still let consumers branch on the error type.
+    const fallback = new Error((payload && payload.message) || 'caller error')
+    if (payload && typeof payload.name === 'string') {
+      fallback.name = payload.name
+    }
+    fallback.stack = err.stack
+    return fallback
+  }
+
   const match = TAG_RE.exec(message)
   if (!match) {
     return err
@@ -852,4 +958,9 @@ module.exports = {
 
   // Helper
   enrichError,
+
+  // Caller-error preservation
+  CALLER_ERROR_SENTINEL,
+  wrapToolHandlerForCallerErrors,
+  callerErrorStash,
 }

package/index.d.ts

@@ -93,6 +93,26 @@ export declare class ApiProtocol {
 }
 export type JsApiProtocol = ApiProtocol
 
+/**
+ * Per-assignment context handed to the JS handler. Mirrors
+ * [`blazen_controlplane::AssignmentContext`].
+ *
+ * Carries the run id and a sink for emitting non-terminal events back
+ * to the control plane.
+ */
+export declare class AssignmentContext {
+  /** Run identifier this context belongs to (UUID string). */
+  get runId(): string
+  /**
+   * Emit a non-terminal event back to the control plane.
+   *
+   * `data` must be a JSON-serializable JS value (object, array,
+   * string, number, boolean, null).
+   */
+  emitEvent(eventType: string, data: any): Promise<void>
+}
+export type JsAssignmentContext = AssignmentContext
+
 export declare class AudioMusicProviderDefaults {
   /** Construct role-specific defaults. */
   constructor(base?: BaseProviderDefaults | undefined | null, before?: BeforeRoleTsfn | undefined | null)
@@ -1439,6 +1459,131 @@ export declare class Context {
 }
 export type JsContext = Context
 
+/**
+ * Orchestrator-side client for the control plane. Submit / cancel /
+ * describe runs, list workers, drain workers, subscribe to events.
+ *
+ * ```typescript
+ * const client = await ControlPlaneClient.connect("http://cp:7445");
+ * const snap = await client.submitWorkflow({
+ *   workflowName: "summarize",
+ *   input: { url: "https://example.com" },
+ *   waitForWorker: true,
+ * });
+ * for await (const event of client.subscribeRunEvents(snap.runId)) {
+ *   console.log(event.eventType, event.data);
+ * }
+ * ```
+ */
+export declare class ControlPlaneClient {
+  /**
+   * Open a connection to the control plane at `endpoint`. Pass
+   * `{ mtls: { cert, key, ca } }` to use mTLS.
+   */
+  static connect(endpoint: string, opts?: JsClientConnectOptions | undefined | null): Promise<ControlPlaneClient>
+  /** Submit a workflow run. */
+  submitWorkflow(opts: JsSubmitWorkflowOptions): Promise<JsRunStateSnapshot>
+  /** Cancel an in-flight workflow run. */
+  cancelWorkflow(runId: string): Promise<JsRunStateSnapshot>
+  /** Describe the current state of a workflow run. */
+  describeWorkflow(runId: string): Promise<JsRunStateSnapshot>
+  /** List currently-connected workers. */
+  listWorkers(): Promise<Array<JsWorkerInfo>>
+  /**
+   * Drain a worker. Pass `immediate = true` to refuse new work right
+   * away; otherwise let in-flight runs finish first.
+   */
+  drainWorker(nodeId: string, immediate: boolean): Promise<void>
+  /**
+   * Subscribe to events for a specific run. The returned stream is
+   * a JS `AsyncIterableIterator<RunEvent>` (object with both `next`
+   * and `[Symbol.asyncIterator]`).
+   */
+  subscribeRunEvents(runId: string): AsyncIterableIterator<RunEvent>
+  /**
+   * Subscribe to events across all runs, optionally filtered by tag
+   * predicates. Returns an `AsyncIterableIterator<RunEvent>`.
+   */
+  subscribeAll(opts?: JsSubscribeAllOptions | undefined | null): AsyncIterableIterator<RunEvent>
+}
+export type JsControlPlaneClient = ControlPlaneClient
+
+/**
+ * Worker connection to a control-plane server. Construct via
+ * [`Self::connect`] (which validates the endpoint URI), then call
+ * [`Self::run`] with a JS handler to drive the worker forever.
+ *
+ * ```typescript
+ * const config = new ControlPlaneWorkerConfig("http://cp:7445", "node-a")
+ *   .withCapability({ kind: "workflow:summarize", version: 1 });
+ * const worker = ControlPlaneWorker.connect(config);
+ * await worker.run(async (assignment, ctx) => {
+ *   await ctx.emitEvent("started", { runId: assignment.runId });
+ *   return { ok: true };
+ * });
+ * ```
+ */
+export declare class ControlPlaneWorker {
+  /**
+   * Validate the configured endpoint URI and prepare a worker that's
+   * ready to call [`Self::run`]. Does NOT open a network connection
+   * yet — that happens on the first iteration of `run`.
+   */
+  static connect(config: ControlPlaneWorkerConfig): ControlPlaneWorker
+  /**
+   * Drive the worker forever, dispatching each assignment to the JS
+   * handler. Resolves on graceful drain or [`Self::shutdown`].
+   *
+   * The JS handler is invoked with two arguments: the assignment
+   * itself and a [`JsAssignmentContext`] that exposes the run id and
+   * an `emitEvent` method. Its return value (JSON-serialized) becomes
+   * the assignment output reported back to the server.
+   */
+  run(handler: (assignment: Assignment, ctx: AssignmentContext) => Promise<unknown>): Promise<void>
+  /**
+   * Signal the worker to stop. Idempotent.
+   *
+   * This drops the cancellation token tied to [`Self::run`]; the
+   * `run` future resolves at the next await point.
+   */
+  shutdown(): void
+}
+export type JsControlPlaneWorker = ControlPlaneWorker
+
+/**
+ * Fluent builder for a worker connection. Mirrors
+ * [`blazen_controlplane::WorkerConfig`].
+ *
+ * ```typescript
+ * const config = new ControlPlaneWorkerConfig("http://cp:7445", "node-a")
+ *   .withCapability({ kind: "workflow:summarize", version: 1 })
+ *   .withTag("region", "us-west")
+ *   .withAdmission({ type: "Fixed", maxInFlight: 4 });
+ * ```
+ */
+export declare class ControlPlaneWorkerConfig {
+  /**
+   * Build a config with the required `endpoint` URI and stable
+   * `nodeId`. Defaults: no capabilities, no tags, `Fixed { maxInFlight: 1 }`,
+   * 5s heartbeat, plaintext transport.
+   */
+  constructor(endpoint: string, nodeId: string)
+  /** Append a capability advertised at handshake. */
+  withCapability(cap: JsWorkerCapability): this
+  /**
+   * Insert a free-form `key=value` tag used by submission-time tag
+   * predicates.
+   */
+  withTag(key: string, value: string): this
+  /** Override the admission mode declared at handshake. */
+  withAdmission(mode: JsAdmissionMode): this
+  /** Override the heartbeat cadence (milliseconds). */
+  withHeartbeatIntervalMs(ms: number): this
+  /** Load a client identity + CA from PEM files and use them for mTLS. */
+  withMtls(certPath: string, keyPath: string, caPath: string): this
+}
+export type JsControlPlaneWorkerConfig = ControlPlaneWorkerConfig
+
 /**
  * A user-defined Blazen provider exposed to JavaScript.
  *
@@ -6543,6 +6688,35 @@ export interface JsAddEntry {
   metadata?: any
 }
 
+/**
+ * JS-facing admission mode. The `type` field discriminates the variant:
+ * `'Fixed'` requires `maxInFlight`, `'VramBudget'` requires `totalMb`,
+ * and `'Reactive'` has no payload fields.
+ */
+export interface JsAdmissionMode {
+  /** Discriminator: `'Fixed'`, `'Reactive'`, or `'VramBudget'`. */
+  type: JsAdmissionModeTag
+  /** In-flight cap for `Fixed`. `None` for the other variants. */
+  maxInFlight?: number
+  /**
+   * VRAM budget in megabytes for `VramBudget`. `None` for the other
+   * variants.
+   */
+  totalMb?: bigint
+}
+
+/**
+ * JS-facing label that drives [`JsAdmissionMode::r#type`]. Carries the
+ * same three variants as [`AdmissionMode`] but as a plain string union
+ * rather than a tagged enum (napi-rs `#[napi(object)]` does not yet
+ * support discriminated-union codegen for enums with associated data).
+ */
+export declare const enum JsAdmissionModeTag {
+  Fixed = 'Fixed',
+  Reactive = 'Reactive',
+  VramBudget = 'VramBudget'
+}
+
 /** Options for configuring an agent run. */
 export interface JsAgentRunOptions {
   /**
@@ -6625,6 +6799,29 @@ export interface JsArtifact {
   customKind?: string
 }
 
+/**
+ * Worker-facing view of an assignment dispatched by the control plane.
+ * JSON input is surfaced as a [`Buffer`] so handlers can decide whether
+ * to decode (single-shot) or stream the bytes onward.
+ */
+export interface JsAssignment {
+  /** Run identifier, rendered as a UUID string. */
+  runId: string
+  /** Symbolic workflow name. */
+  workflowName: string
+  /**
+   * Optional workflow version. `None` lets the worker use whichever
+   * version it has registered.
+   */
+  workflowVersion?: number
+  /** JSON-encoded initial input as raw bytes. */
+  inputJson: Buffer
+  /** Optional deadline in milliseconds. `None` = no timeout. */
+  deadlineMs?: bigint
+  /** 1-indexed attempt counter. Incremented on re-dispatch. */
+  attempt: number
+}
+
 /** Audio content for multimodal messages. */
 export interface JsAudioContent {
   source: JsImageSource
@@ -6767,6 +6964,15 @@ export interface JsCitation {
   metadata: any
 }
 
+/**
+ * Options bag passed to `ControlPlaneClient.connect`. The `mtls`
+ * field, when present, swaps the connection into mTLS mode.
+ */
+export interface JsClientConnectOptions {
+  /** mTLS configuration. `None` = plaintext. */
+  mtls?: JsMtlsOptions
+}
+
 /** Options for a chat completion request. */
 export interface JsCompletionOptions {
   temperature?: number
@@ -6866,8 +7072,9 @@ export interface JsContentMetadata {
 /**
  * A single part in a multi-part message.
  *
- * `partType` is one of `"text"`, `"image"`, `"audio"`, `"video"`. Set the
- * matching field (`text`, `image`, `audio`, `video`) accordingly.
+ * `partType` is one of `"text"`, `"image"`, `"audio"`, `"video"`, `"file"`.
+ * Set the matching field (`text`, `image`, `audio`, `video`, `file`)
+ * accordingly.
  */
 export interface JsContentPart {
   partType: string
@@ -6875,6 +7082,7 @@ export interface JsContentPart {
   image?: JsImageContent
   audio?: JsAudioContent
   video?: JsVideoContent
+  file?: FileContent
 }
 
 /** Request to dereference a remote session ref. */
@@ -7331,6 +7539,19 @@ export interface JsModelStatus {
   pool: string
 }
 
+/**
+ * PEM file paths for mTLS configuration. Used by
+ * [`crate::controlplane::client::JsControlPlaneClient::connect`].
+ */
+export interface JsMtlsOptions {
+  /** Path to the client certificate PEM file. */
+  cert: string
+  /** Path to the client private-key PEM file. */
+  key: string
+  /** Path to the CA PEM file used to authenticate the server. */
+  ca: string
+}
+
 export interface JsMusicRequest {
   prompt: string
   durationSeconds?: number
@@ -7564,6 +7785,47 @@ export declare const enum JsRole {
   Tool = 'tool'
 }
 
+/** Event emitted during a run. Mirrors [`RunEvent`]. */
+export interface JsRunEvent {
+  /** Run identifier, rendered as a UUID string. */
+  runId: string
+  /** Caller-supplied event type tag (e.g. `"step.completed"`). */
+  eventType: string
+  /** Free-form JSON payload. */
+  data: any
+  /** Wall-clock emission time in epoch milliseconds. */
+  timestampMs: bigint
+}
+
+/** Snapshot of a workflow run's state. Mirrors [`RunStateSnapshot`]. */
+export interface JsRunStateSnapshot {
+  /** Run identifier, rendered as a UUID string. */
+  runId: string
+  /** Current status. */
+  status: JsRunStatus
+  /** Wall-clock submission time in epoch milliseconds. */
+  startedAtMs: bigint
+  /** Wall-clock completion time, `None` until terminal. */
+  completedAtMs?: bigint
+  /** `Some(node_id)` once the run has been routed to a worker. */
+  assignedTo?: string
+  /** Wall-clock of the most recent event for this run, if any. */
+  lastEventAtMs?: bigint
+  /** Terminal output JSON value if `status == 'Completed'`. */
+  output?: any
+  /** Error message if `status == 'Failed'`. */
+  error?: string
+}
+
+/** JS-facing run status. Mirrors [`RunStatus`]. */
+export declare const enum JsRunStatus {
+  Pending = 'Pending',
+  Running = 'Running',
+  Completed = 'Completed',
+  Failed = 'Failed',
+  Cancelled = 'Cancelled'
+}
+
 export interface JsSpeechRequest {
   text: string
   voice?: string
@@ -7642,6 +7904,42 @@ export interface JsStreamChunk {
   artifacts: Array<JsArtifact>
 }
 
+/**
+ * Options bag for
+ * [`crate::controlplane::client::JsControlPlaneClient::submit_workflow`].
+ */
+export interface JsSubmitWorkflowOptions {
+  /** Symbolic name of the workflow to run. */
+  workflowName: string
+  /** JSON-serializable initial input. */
+  input: any
+  /** Optional workflow version. `None` = latest. */
+  workflowVersion?: number
+  /**
+   * Required tags. Each `key=value` (or `key=*`) is AND'd. `None`
+   * means no tag predicate.
+   */
+  requiredTags?: Array<string>
+  /** Optional dedupe key for at-most-one-run-per-window semantics. */
+  idempotencyKey?: string
+  /** Optional deadline in milliseconds from submission. */
+  deadlineMs?: bigint
+  /**
+   * If `true`, queue the submission until a matching worker appears.
+   * Defaults to `false`.
+   */
+  waitForWorker?: boolean
+}
+
+/**
+ * Options bag for
+ * [`crate::controlplane::client::JsControlPlaneClient::subscribe_all`].
+ */
+export interface JsSubscribeAllOptions {
+  /** Tag predicates the events must match. */
+  requiredTags?: Array<string>
+}
+
 /** Request to invoke a sub-workflow on a remote peer. */
 export interface JsSubWorkflowRequest {
   /** Symbolic name of the workflow to invoke on the remote peer. */
@@ -7918,6 +8216,37 @@ export interface JsWhisperOptions {
   cacheDir?: string
 }
 
+/**
+ * Capability advertised by a worker at handshake time. Mirrors
+ * [`blazen_core::distributed::WorkerCapability`].
+ */
+export interface JsWorkerCapability {
+  /** Capability tag, e.g. `"workflow:summarize"`. */
+  kind: string
+  /**
+   * Capability version. Workers and orchestrators only match when both
+   * values agree.
+   */
+  version: number
+}
+
+/**
+ * Summary of a connected worker returned by
+ * [`crate::controlplane::client::JsControlPlaneClient::list_workers`].
+ */
+export interface JsWorkerInfo {
+  /** Stable identifier of the worker. */
+  nodeId: string
+  /** Capabilities advertised by this worker at handshake. */
+  capabilities: Array<JsWorkerCapability>
+  /** Free-form `key=value` tags this worker advertised. */
+  tags: Record<string, string>
+  /** Last reported in-flight assignment count. */
+  inFlight: number
+  /** Wall-clock connection time in epoch milliseconds. */
+  connectedAtMs: bigint
+}
+
 /**
  * Plain-object payload accepted by `WorkflowCheckpoint.create()` for
  * constructing a checkpoint from JS.
@@ -7994,11 +8323,8 @@ export interface LlmPayload {
    * `kind: "provider_raw"`.
    */
   value?: any
-  /**
-   * Multimodal content parts (serialized `ContentPart[]`).
-   * Required for `kind: "parts"`.
-   */
-  parts?: any
+  /** Multimodal content parts. Required for `kind: "parts"`. */
+  parts?: Array<JsContentPart>
   /** Provider id string. Required for `kind: "provider_raw"`. */
   provider?: string
 }
@@ -9055,6 +9381,17 @@ export type ImageSource = JsImageSource
 export type ContentHandle = JsContentHandle
 export type ContentMetadata = JsContentMetadata
 export type ContentKind = JsContentKind
+export type WorkerCapability = JsWorkerCapability
+export type AdmissionMode = JsAdmissionMode
+export type Assignment = JsAssignment
+export type RunStatus = JsRunStatus
+export type RunStateSnapshot = JsRunStateSnapshot
+export type RunEvent = JsRunEvent
+export type WorkerInfo = JsWorkerInfo
+export type MtlsOptions = JsMtlsOptions
+export type ClientConnectOptions = JsClientConnectOptions
+export type SubmitWorkflowOptions = JsSubmitWorkflowOptions
+export type SubscribeAllOptions = JsSubscribeAllOptions
 
 // --- post-build: ContentBody / ContentHint helper types ---
 /**

package/index.js

@@ -584,6 +584,8 @@ module.exports.AnthropicProvider = nativeBinding.AnthropicProvider
 module.exports.JsAnthropicProvider = nativeBinding.JsAnthropicProvider
 module.exports.ApiProtocol = nativeBinding.ApiProtocol
 module.exports.JsApiProtocol = nativeBinding.JsApiProtocol
+module.exports.AssignmentContext = nativeBinding.AssignmentContext
+module.exports.JsAssignmentContext = nativeBinding.JsAssignmentContext
 module.exports.AudioMusicProviderDefaults = nativeBinding.AudioMusicProviderDefaults
 module.exports.JsAudioMusicProviderDefaults = nativeBinding.JsAudioMusicProviderDefaults
 module.exports.AudioSpeechProviderDefaults = nativeBinding.AudioSpeechProviderDefaults
@@ -640,6 +642,12 @@ module.exports.ContentStore = nativeBinding.ContentStore
 module.exports.JsContentStore = nativeBinding.JsContentStore
 module.exports.Context = nativeBinding.Context
 module.exports.JsContext = nativeBinding.JsContext
+module.exports.ControlPlaneClient = nativeBinding.ControlPlaneClient
+module.exports.JsControlPlaneClient = nativeBinding.JsControlPlaneClient
+module.exports.ControlPlaneWorker = nativeBinding.ControlPlaneWorker
+module.exports.JsControlPlaneWorker = nativeBinding.JsControlPlaneWorker
+module.exports.ControlPlaneWorkerConfig = nativeBinding.ControlPlaneWorkerConfig
+module.exports.JsControlPlaneWorkerConfig = nativeBinding.JsControlPlaneWorkerConfig
 module.exports.CustomProvider = nativeBinding.CustomProvider
 module.exports.JsCustomProvider = nativeBinding.JsCustomProvider
 module.exports.DeepSeekProvider = nativeBinding.DeepSeekProvider
@@ -925,6 +933,7 @@ module.exports.initPrometheus = nativeBinding.initPrometheus
 module.exports.internEventType = nativeBinding.internEventType
 module.exports.JoinStrategy = nativeBinding.JoinStrategy
 module.exports.JsJoinStrategy = nativeBinding.JsJoinStrategy
+module.exports.JsAdmissionModeTag = nativeBinding.JsAdmissionModeTag
 module.exports.JsAuthMethod = nativeBinding.JsAuthMethod
 module.exports.JsCacheStrategy = nativeBinding.JsCacheStrategy
 module.exports.JsContentKind = nativeBinding.JsContentKind
@@ -932,6 +941,7 @@ module.exports.JsDiffusionScheduler = nativeBinding.JsDiffusionScheduler
 module.exports.JsFalLlmEndpointKind = nativeBinding.JsFalLlmEndpointKind
 module.exports.JsJobStatus = nativeBinding.JsJobStatus
 module.exports.JsRole = nativeBinding.JsRole
+module.exports.JsRunStatus = nativeBinding.JsRunStatus
 module.exports.JsWhisperModel = nativeBinding.JsWhisperModel
 module.exports.LlamaCppChatRole = nativeBinding.LlamaCppChatRole
 module.exports.JsLlamaCppChatRole = nativeBinding.JsLlamaCppChatRole
@@ -1032,6 +1042,67 @@ module.exports.videoInput = nativeBinding.videoInput
     }
   }
 
+  // Specialised handling for the agent entrypoints. The user's
+  // `toolHandler` argument must be wrapped to envelope-format thrown
+  // errors (see `wrapToolHandlerForCallerErrors` in error-classes.js);
+  // `enrichError` then re-throws the original instance after the agent
+  // loop rejects with the `__BLAZEN_CALLER_ERROR__` sentinel. The
+  // generic `wrap()` loop below is skipped for these via the
+  // `__blazenCallerErrorWrapped` marker.
+  const { wrapToolHandlerForCallerErrors, callerErrorStash } = errorClasses
+  const AGENT_ENTRYPOINTS = ['runAgent', 'runAgentWithCallback']
+  for (const fnName of AGENT_ENTRYPOINTS) {
+    const orig = module.exports[fnName]
+    if (typeof orig !== 'function') continue
+    // toolHandler is positional arg index 3 for both runAgent and
+    // runAgentWithCallback in the current TS signatures.
+    const TOOL_HANDLER_ARG_INDEX = 3
+    const wrapped = function blazenAgentEntrypoint(...args) {
+      if (args.length > TOOL_HANDLER_ARG_INDEX) {
+        const userHandler = args[TOOL_HANDLER_ARG_INDEX]
+        if (typeof userHandler === 'function') {
+          args[TOOL_HANDLER_ARG_INDEX] = wrapToolHandlerForCallerErrors(userHandler)
+        }
+      }
+      // Track stash entries created during this run so we can
+      // garbage-collect any that the agent loop swallowed (e.g.
+      // succeeded after a handler threw, or the loop ended before the
+      // napi side surfaced the caller error).
+      const stashSnapshot = new Set(callerErrorStash.keys())
+      const cleanupNewStash = () => {
+        for (const key of callerErrorStash.keys()) {
+          if (!stashSnapshot.has(key)) {
+            callerErrorStash.delete(key)
+          }
+        }
+      }
+      try {
+        const result = orig.apply(this, args)
+        if (result && typeof result.then === 'function') {
+          return result.then(
+            (v) => {
+              cleanupNewStash()
+              return v
+            },
+            (e) => {
+              const enriched = enrichError(e)
+              cleanupNewStash()
+              throw enriched
+            },
+          )
+        }
+        cleanupNewStash()
+        return result
+      } catch (e) {
+        const enriched = enrichError(e)
+        cleanupNewStash()
+        throw enriched
+      }
+    }
+    wrapped.__blazenCallerErrorWrapped = true
+    module.exports[fnName] = wrapped
+  }
+
   // Wrap every top-level export. Distinguish functions (call wrap) from
   // constructors (call patchPrototype). Heuristic: a constructor has a
   // `prototype` object with own properties beyond `constructor`. When
@@ -1045,6 +1116,8 @@ module.exports.videoInput = nativeBinding.videoInput
     if (typeof orig !== 'function') continue
     // Skip the typed-error classes we are about to install.
     if (Object.prototype.hasOwnProperty.call(errorClasses, key)) continue
+    // Skip the agent entrypoints we already specialised above.
+    if (orig.__blazenCallerErrorWrapped) continue
     if (orig.prototype && typeof orig.prototype === 'object') {
       patchPrototype(orig)
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "blazen",
-  "version": "0.5.3",
+  "version": "0.5.4",
   "description": "Blazen - Event-driven AI workflow framework for Node.js/TypeScript",
   "main": "index.js",
   "types": "index.d.ts",
@@ -88,13 +88,13 @@
     "verbose": true
   },
   "optionalDependencies": {
-    "@blazen-dev/blazen-linux-x64-gnu": "0.5.3",
-    "@blazen-dev/blazen-linux-x64-musl": "0.5.3",
-    "@blazen-dev/blazen-linux-arm64-gnu": "0.5.3",
-    "@blazen-dev/blazen-linux-arm64-musl": "0.5.3",
-    "@blazen-dev/blazen-darwin-arm64": "0.5.3",
-    "@blazen-dev/blazen-win32-x64-msvc": "0.5.3",
-    "@blazen-dev/blazen-wasm32-wasi": "0.5.3"
+    "@blazen-dev/blazen-linux-x64-gnu": "0.5.4",
+    "@blazen-dev/blazen-linux-x64-musl": "0.5.4",
+    "@blazen-dev/blazen-linux-arm64-gnu": "0.5.4",
+    "@blazen-dev/blazen-linux-arm64-musl": "0.5.4",
+    "@blazen-dev/blazen-darwin-arm64": "0.5.4",
+    "@blazen-dev/blazen-win32-x64-msvc": "0.5.4",
+    "@blazen-dev/blazen-wasm32-wasi": "0.5.4"
   },
   "scripts": {
     "build": "napi build --release --platform --features local-all,langfuse --js index.js && node scripts/post-build.mjs",