@nodetool-ai/runtime 0.7.0-rc.23 → 0.8.1

package/README.md

@@ -0,0 +1,29 @@
+# @nodetool-ai/runtime
+
+Processing context, LLM providers, message queue, agent memory, output
+normalization, and telemetry for the NodeTool runtime.
+
+## Responsibilities
+
+- `ProcessingContext` — the per-run context passed to every node/executor,
+  including `context.memory` (`AgentMemory`).
+- LLM providers in `src/providers/` (Anthropic, OpenAI, Gemini, Ollama, …) all
+  extending `BaseProvider`.
+- Output normalization, message queue, cost tracking, and OpenTelemetry tracing.
+
+## Usage
+
+```ts
+import { ProcessingContext, BaseProvider } from "@nodetool-ai/runtime";
+```
+
+## Develop
+
+```bash
+npm run build --workspace=packages/runtime
+npm run test  --workspace=packages/runtime
+npm run lint  --workspace=packages/runtime
+```
+
+See [packages/agents/AGENTS.md](../agents/AGENTS.md) for the agent-memory model
+and the root [AGENTS.md](../../AGENTS.md) for provider/telemetry details.

package/dist/.nodetool-build-stamp

@@ -0,0 +1 @@
+2026-09-28T09:19:04.443Z

package/dist/agent-memory.d.ts

@@ -0,0 +1,118 @@
+/**
+ * AgentMemory — unified, structured key/value store for agent results.
+ *
+ * One memory instance lives on every {@link ProcessingContext}. It is the
+ * single source of truth for everything that flows between agents, tasks and
+ * steps:
+ *
+ *   - **inputs** seeded by the caller
+ *   - **step_result** entries written by {@link StepExecutor}
+ *   - **task_result** entries written by {@link StepExecutor} for finish-task
+ *     steps and by {@link ParallelTaskExecutor} when a task completes
+ *   - **shared** entries written by tools or by the user for cross-agent
+ *     communication
+ *
+ * Keys use namespaced prefixes (`step:`, `task:`, `input:`, `shared:`) so the
+ * different kinds never collide. The {@link AgentMemory.formatForPrompt}
+ * helper renders selected entries as a Markdown block ready to inject into a
+ * user/system prompt — the canonical way agents discover prior results.
+ *
+ * Design goals (2026 agent patterns):
+ *
+ *   - **Single store, single API**: no parallel maps in executors.
+ *   - **Discoverable**: every step/task/sub-agent can list and read all
+ *     prior results via the same calls.
+ *   - **Structured**: entries carry kind, source, title and description so
+ *     prompts render consistently.
+ *   - **Reactive**: subscribers can react to writes.
+ */
+export type MemoryKind = "task_result" | "step_result" | "input" | "shared";
+export interface MemoryEntry {
+    /** Globally unique key. Use {@link memoryKeys} for canonical namespacing. */
+    key: string;
+    /** Categorization used for filtering and prompt rendering. */
+    kind: MemoryKind;
+    /** Stored value (any JSON-serializable structure). */
+    value: unknown;
+    /** Optional ID of the producer (task / step / agent / tool). */
+    source?: string;
+    /** Optional human-readable title used as the heading in prompt rendering. */
+    title?: string;
+    /** Optional brief description rendered alongside the title. */
+    description?: string;
+    /** Wall-clock ms when the entry was first written. */
+    createdAt: number;
+}
+export interface MemoryFilter {
+    /** One or more kinds to include. Omit to include all kinds. */
+    kind?: MemoryKind | MemoryKind[];
+    /** Only include entries whose key is in this list. */
+    keys?: string[];
+    /** Only include entries whose key starts with this prefix. */
+    keyPrefix?: string;
+    /** Only include entries whose source matches one of these IDs. */
+    sources?: string[];
+}
+export type MemoryListener = (entry: MemoryEntry) => void;
+/**
+ * Canonical key builders. Every namespace has its own helper so callers
+ * never invent free-form keys that drift between writers and readers.
+ */
+export declare const memoryKeys: {
+    readonly step: (id: string) => string;
+    readonly task: (id: string) => string;
+    readonly input: (key: string) => string;
+    readonly shared: (key: string) => string;
+};
+export declare class AgentMemory {
+    private readonly entries;
+    private readonly listeners;
+    /**
+     * Write an entry. If a value already exists for {@link MemoryEntry.key} it
+     * is overwritten. The original `createdAt` is preserved unless the caller
+     * supplies a new one.
+     */
+    set(input: Omit<MemoryEntry, "createdAt"> & {
+        createdAt?: number;
+    }): MemoryEntry;
+    /** Get the full entry, or undefined if no such key. */
+    get(key: string): MemoryEntry | undefined;
+    /** Get just the stored value, or undefined if no such key. */
+    getValue<T = unknown>(key: string): T | undefined;
+    has(key: string): boolean;
+    delete(key: string): boolean;
+    size(): number;
+    /** List entries matching an optional filter, in insertion order. */
+    list(filter?: MemoryFilter): MemoryEntry[];
+    /**
+     * Render selected entries as a Markdown block suitable for injection into
+     * a user/system prompt. Returns an empty string when no entries match.
+     *
+     * Each entry is rendered as:
+     *
+     *     ## [kind] title (key)
+     *     description (if any)
+     *     ```
+     *     value (JSON-serialized for non-strings)
+     *     ```
+     */
+    formatForPrompt(filter?: MemoryFilter): string;
+    /** Remove all entries (or those matching a filter). */
+    clear(filter?: MemoryFilter): void;
+    /** Subscribe to writes. Returns an unsubscribe function. */
+    subscribe(listener: MemoryListener): () => void;
+    /** Snapshot all entries (insertion order). */
+    snapshot(): MemoryEntry[];
+    /**
+     * Rehydrate from a prior {@link snapshot}. This is the durability seam:
+     * callers can persist `snapshot()` to disk/DB at checkpoints and rebuild the
+     * store after a crash or process restart, without coupling AgentMemory to
+     * any particular storage backend.
+     *
+     * Each entry is written through {@link set}, so its original `createdAt` is
+     * preserved and listeners are notified (reactive consumers can rebuild
+     * derived state). Existing keys are overwritten.
+     */
+    restore(entries: readonly MemoryEntry[]): void;
+}
+//# sourceMappingURL=agent-memory.d.ts.map

package/dist/agent-memory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-memory.d.ts","sourceRoot":"","sources":["../src/agent-memory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAIH,MAAM,MAAM,UAAU,GAAG,aAAa,GAAG,aAAa,GAAG,OAAO,GAAG,QAAQ,CAAC;AAE5E,MAAM,WAAW,WAAW;IAC1B,6EAA6E;IAC7E,GAAG,EAAE,MAAM,CAAC;IACZ,8DAA8D;IAC9D,IAAI,EAAE,UAAU,CAAC;IACjB,sDAAsD;IACtD,KAAK,EAAE,OAAO,CAAC;IACf,gEAAgE;IAChE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,6EAA6E;IAC7E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,+DAA+D;IAC/D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,sDAAsD;IACtD,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,YAAY;IAC3B,+DAA+D;IAC/D,IAAI,CAAC,EAAE,UAAU,GAAG,UAAU,EAAE,CAAC;IACjC,sDAAsD;IACtD,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,8DAA8D;IAC9D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,kEAAkE;IAClE,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,MAAM,MAAM,cAAc,GAAG,CAAC,KAAK,EAAE,WAAW,KAAK,IAAI,CAAC;AAE1D;;;GAGG;AACH,eAAO,MAAM,UAAU;aACrB,IAAI,OAAO,MAAM,KAAG,MAAM;aAC1B,IAAI,OAAO,MAAM,KAAG,MAAM;aAC1B,KAAK,QAAQ,MAAM,KAAG,MAAM;aAC5B,MAAM,QAAQ,MAAM,KAAG,MAAM;CACrB,CAAC;AAEX,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAkC;IAC1D,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA6B;IAEvD;;;;OAIG;IACH,GAAG,CAAC,KAAK,EAAE,IAAI,CAAC,WAAW,EAAE,WAAW,CAAC,GAAG;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,WAAW,CAuB/E;IAED,uDAAuD;IACvD,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,CAExC;IAED,8DAA8D;IAC9D,QAAQ,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS,CAEhD;IAED,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAExB;IAED,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAE3B;IAED,IAAI,IAAI,MAAM,CAEb;IAED,oEAAoE;IACpE,IAAI,CAAC,MAAM,CAAC,EAAE,YAAY,GAAG,WAAW,EAAE,CAqBzC;IAED;;;;;;;;;;;OAWG;IACH,eAAe,CAAC,MAAM,CAAC,EAAE,YAAY,GAAG,MAAM,CAoB7C;IAED,uDAAuD;IACvD,KAAK,CAAC,MAAM,CAAC,EAAE,YAAY,GAAG,IAAI,CASjC;IAED,4DAA4D;IAC5D,SAAS,CAAC,QAAQ,EAAE,cAAc,GAAG,MAAM,IAAI,CAK9C;IAED,8CAA8C;IAC9C,QAAQ,IAAI,WAAW,EAAE,CAExB;IAED;;;;;;;;;OASG;IACH,OAAO,CAAC,OAAO,EAAE,SAAS,WAAW,EAAE,GAAG,IAAI,CAI7C;CACF"}

package/dist/agent-memory.js

@@ -0,0 +1,186 @@
+/**
+ * AgentMemory — unified, structured key/value store for agent results.
+ *
+ * One memory instance lives on every {@link ProcessingContext}. It is the
+ * single source of truth for everything that flows between agents, tasks and
+ * steps:
+ *
+ *   - **inputs** seeded by the caller
+ *   - **step_result** entries written by {@link StepExecutor}
+ *   - **task_result** entries written by {@link StepExecutor} for finish-task
+ *     steps and by {@link ParallelTaskExecutor} when a task completes
+ *   - **shared** entries written by tools or by the user for cross-agent
+ *     communication
+ *
+ * Keys use namespaced prefixes (`step:`, `task:`, `input:`, `shared:`) so the
+ * different kinds never collide. The {@link AgentMemory.formatForPrompt}
+ * helper renders selected entries as a Markdown block ready to inject into a
+ * user/system prompt — the canonical way agents discover prior results.
+ *
+ * Design goals (2026 agent patterns):
+ *
+ *   - **Single store, single API**: no parallel maps in executors.
+ *   - **Discoverable**: every step/task/sub-agent can list and read all
+ *     prior results via the same calls.
+ *   - **Structured**: entries carry kind, source, title and description so
+ *     prompts render consistently.
+ *   - **Reactive**: subscribers can react to writes.
+ */
+import { isString } from "@nodetool-ai/protocol";
+/**
+ * Canonical key builders. Every namespace has its own helper so callers
+ * never invent free-form keys that drift between writers and readers.
+ */
+export const memoryKeys = {
+    step: (id) => `step:${id}`,
+    task: (id) => `task:${id}`,
+    input: (key) => `input:${key}`,
+    shared: (key) => `shared:${key}`
+};
+export class AgentMemory {
+    entries = new Map();
+    listeners = new Set();
+    /**
+     * Write an entry. If a value already exists for {@link MemoryEntry.key} it
+     * is overwritten. The original `createdAt` is preserved unless the caller
+     * supplies a new one.
+     */
+    set(input) {
+        const existing = this.entries.get(input.key);
+        const entry = {
+            key: input.key,
+            kind: input.kind,
+            value: input.value,
+            source: input.source,
+            title: input.title,
+            description: input.description,
+            createdAt: input.createdAt ?? existing?.createdAt ?? Date.now()
+        };
+        this.entries.set(entry.key, entry);
+        for (const listener of this.listeners) {
+            try {
+                listener(entry);
+            }
+            catch (error) {
+                console.error("AgentMemory listener failed", {
+                    key: entry.key,
+                    error
+                });
+            }
+        }
+        return entry;
+    }
+    /** Get the full entry, or undefined if no such key. */
+    get(key) {
+        return this.entries.get(key);
+    }
+    /** Get just the stored value, or undefined if no such key. */
+    getValue(key) {
+        return this.entries.get(key)?.value;
+    }
+    has(key) {
+        return this.entries.has(key);
+    }
+    delete(key) {
+        return this.entries.delete(key);
+    }
+    size() {
+        return this.entries.size;
+    }
+    /** List entries matching an optional filter, in insertion order. */
+    list(filter) {
+        if (!filter)
+            return [...this.entries.values()];
+        const kindArr = filter.kind === undefined
+            ? null
+            : Array.isArray(filter.kind)
+                ? filter.kind
+                : [filter.kind];
+        const keysSet = filter.keys ? new Set(filter.keys) : null;
+        const sourcesSet = filter.sources ? new Set(filter.sources) : null;
+        const out = [];
+        for (const entry of this.entries.values()) {
+            if (kindArr && !kindArr.includes(entry.kind))
+                continue;
+            if (keysSet && !keysSet.has(entry.key))
+                continue;
+            if (filter.keyPrefix && !entry.key.startsWith(filter.keyPrefix))
+                continue;
+            if (sourcesSet && (!entry.source || !sourcesSet.has(entry.source)))
+                continue;
+            out.push(entry);
+        }
+        return out;
+    }
+    /**
+     * Render selected entries as a Markdown block suitable for injection into
+     * a user/system prompt. Returns an empty string when no entries match.
+     *
+     * Each entry is rendered as:
+     *
+     *     ## [kind] title (key)
+     *     description (if any)
+     *     ```
+     *     value (JSON-serialized for non-strings)
+     *     ```
+     */
+    formatForPrompt(filter) {
+        const entries = this.list(filter);
+        if (entries.length === 0)
+            return "";
+        const sorted = [...entries].sort((a, b) => a.createdAt - b.createdAt);
+        const lines = ["# Memory (results from prior steps and tasks)"];
+        for (const entry of sorted) {
+            const heading = entry.title ?? entry.key;
+            lines.push("");
+            lines.push(`## [${entry.kind}] ${heading} (${entry.key})`);
+            if (entry.description)
+                lines.push(entry.description);
+            const valueStr = isString(entry.value)
+                ? entry.value
+                : JSON.stringify(entry.value, null, 2);
+            lines.push("```");
+            lines.push(valueStr);
+            lines.push("```");
+        }
+        return lines.join("\n");
+    }
+    /** Remove all entries (or those matching a filter). */
+    clear(filter) {
+        // Stryker disable next-line ConditionalExpression,BlockStatement: fast path — the loop below with an undefined filter lists and deletes every entry too, so skipping/emptying this block is equivalent.
+        if (!filter) {
+            this.entries.clear();
+            return;
+        }
+        for (const key of this.list(filter).map((e) => e.key)) {
+            this.entries.delete(key);
+        }
+    }
+    /** Subscribe to writes. Returns an unsubscribe function. */
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => {
+            this.listeners.delete(listener);
+        };
+    }
+    /** Snapshot all entries (insertion order). */
+    snapshot() {
+        return [...this.entries.values()];
+    }
+    /**
+     * Rehydrate from a prior {@link snapshot}. This is the durability seam:
+     * callers can persist `snapshot()` to disk/DB at checkpoints and rebuild the
+     * store after a crash or process restart, without coupling AgentMemory to
+     * any particular storage backend.
+     *
+     * Each entry is written through {@link set}, so its original `createdAt` is
+     * preserved and listeners are notified (reactive consumers can rebuild
+     * derived state). Existing keys are overwritten.
+     */
+    restore(entries) {
+        for (const entry of entries) {
+            this.set({ ...entry });
+        }
+    }
+}
+//# sourceMappingURL=agent-memory.js.map

package/dist/agent-memory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-memory.js","sourceRoot":"","sources":["../src/agent-memory.ts"],"names":[],"mappings":"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"}

package/dist/async-local-storage.d.ts

@@ -0,0 +1,20 @@
+/**
+ * `node:async_hooks`, lazily, with a browser/Edge fallback.
+ *
+ * The runtime package is bundled for non-Node targets too, where a static
+ * `import "node:async_hooks"` throws at module load. The fallback holder keeps
+ * the API working there; what it loses is concurrency safety, so a consumer
+ * that depends on per-async-context isolation must say what that costs it.
+ */
+/** The `AsyncLocalStorage` surface this package uses — all the fallback can offer. */
+interface AsyncContextStore<T> {
+    getStore(): T | undefined;
+    run<R>(value: T, callback: () => R): R;
+}
+/** Constructor of an {@link AsyncContextStore}. */
+interface AsyncContextStoreConstructor {
+    new <T>(): AsyncContextStore<T>;
+}
+export declare const AsyncLocalStorage: AsyncContextStoreConstructor;
+export {};
+//# sourceMappingURL=async-local-storage.d.ts.map

package/dist/async-local-storage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"async-local-storage.d.ts","sourceRoot":"","sources":["../src/async-local-storage.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAwBH,sFAAsF;AACtF,UAAU,iBAAiB,CAAC,CAAC;IAC3B,QAAQ,IAAI,CAAC,GAAG,SAAS,CAAC;IAC1B,GAAG,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC;CACxC;AAED,mDAAmD;AACnD,UAAU,4BAA4B;IACpC,KAAK,CAAC,KAAK,iBAAiB,CAAC,CAAC,CAAC,CAAC;CACjC;AAED,eAAO,MAAM,iBAAiB,EAAE,4BACiB,CAAC"}

package/dist/async-local-storage.js

@@ -0,0 +1,28 @@
+/**
+ * `node:async_hooks`, lazily, with a browser/Edge fallback.
+ *
+ * The runtime package is bundled for non-Node targets too, where a static
+ * `import "node:async_hooks"` throws at module load. The fallback holder keeps
+ * the API working there; what it loses is concurrency safety, so a consumer
+ * that depends on per-async-context isolation must say what that costs it.
+ */
+import { getNodeBuiltinSync } from "@nodetool-ai/config";
+const _asyncHooks = getNodeBuiltinSync("node:async_hooks");
+class FallbackStore {
+    _value;
+    getStore() {
+        return this._value;
+    }
+    run(value, callback) {
+        const prev = this._value;
+        this._value = value;
+        try {
+            return callback();
+        }
+        finally {
+            this._value = prev;
+        }
+    }
+}
+export const AsyncLocalStorage = _asyncHooks?.AsyncLocalStorage ?? FallbackStore;
+//# sourceMappingURL=async-local-storage.js.map

package/dist/async-local-storage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"async-local-storage.js","sourceRoot":"","sources":["../src/async-local-storage.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAEzD,MAAM,WAAW,GAAG,kBAAkB,CACpC,kBAAkB,CACnB,CAAC;AAEF,MAAM,aAAa;IACT,MAAM,CAAgB;IAC9B,QAAQ;QACN,OAAO,IAAI,CAAC,MAAM,CAAC;IACrB,CAAC;IACD,GAAG,CAAI,KAAQ,EAAE,QAAiB;QAChC,MAAM,IAAI,GAAG,IAAI,CAAC,MAAM,CAAC;QACzB,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC;QACpB,IAAI,CAAC;YACH,OAAO,QAAQ,EAAE,CAAC;QACpB,CAAC;gBAAS,CAAC;YACT,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC;QACrB,CAAC;IACH,CAAC;CACF;AAaD,MAAM,CAAC,MAAM,iBAAiB,GAC5B,WAAW,EAAE,iBAAiB,IAAI,aAAa,CAAC"}

package/dist/blender-executor.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Blender worker executor — runs a `BlenderJob` on a GPU worker over the
+ * Python bridge, the transport half of Stage 4a (D6).
+ *
+ * This is the worker-tier counterpart of `LocalBlenderRunner` in
+ * `@nodetool-ai/blender-nodes` (which this package must not import — the
+ * dependency runs the other way, so the job travels here as a structural
+ * type). `WorkerBlenderRunner` (Stage 4b) wraps this function behind the
+ * `BlenderRunner` interface; nodes never call it directly.
+ *
+ * Contract, mirroring the local tier step for step (D6):
+ *
+ *  - inputs travel as bridge blobs: the request carries the verbatim `job`,
+ *    an `inputs` manifest mapping each logical input name to its blob key,
+ *    the input bytes under those keys, and a worker-side `timeout`.
+ *  - outputs come back as bridge blobs on the terminal `result` frame.
+ *  - the same output caps apply as on the local tier, enforced from the
+ *    worker's declared `sizes` BEFORE any blob bytes are consumed — and
+ *    re-checked against the actual byte lengths, so a lying worker cannot
+ *    bypass them either way.
+ *  - a name in the worker's result that the job did not declare is ignored
+ *    and logged at warn, exactly as `LocalBlenderRunner` does.
+ *  - `blender.event` progress frames become `onProgress(frame, total)` calls.
+ *  - the run is abortable through an `AbortSignal`: aborting sends the
+ *    worker a `cancel` frame for this exact request (it does not just abandon
+ *    the local promise) and rejects with the signal's reason, unwrapped —
+ *    the same way the local tier rejects with the abort reason.
+ *
+ * Error codes are the local tier's codes verbatim (`render_failed`,
+ * `missing_output`, `output_too_large`, `bad_job`, `bad_result`, …): the
+ * worker's op failure (`ok: false`) preserves its code, and a transport or
+ * malformed-result failure is `bad_result`, the way a crashed Blender is.
+ * Stage 4b maps these into `BlenderJobError`; this module cannot throw that
+ * class itself without a dependency cycle.
+ */
+import type { BlenderExecuteJob, PythonBridge } from "./python-bridge-types.js";
+/**
+ * Structural `BlenderJob` (`packages/blender-nodes/src/job.ts`). Kept local
+ * so this package never imports `@nodetool-ai/blender-nodes`: every field a
+ * real `BlenderJob` carries satisfies these shapes, and the worker's
+ * `run_job.py` owns the op schema.
+ */
+export type BlenderWorkerJob = BlenderExecuteJob;
+export interface BlenderExecutorOptions {
+    /** Wall clock for the run. Sent to the worker as whole seconds. */
+    timeoutMs: number;
+    /** Abort: the cancel reaches the worker, the promise rejects with `reason`. */
+    signal?: AbortSignal;
+    onProgress?: (frame: number, total: number) => void;
+    /** Per-output byte cap — the local tier's `MAX_OUTPUT_BYTES`. */
+    maxOutputBytes: number;
+    /** Cap on the sum of all outputs — the local tier's `MAX_TOTAL_OUTPUT_BYTES`. */
+    maxTotalOutputBytes: number;
+    /**
+     * Additional worker-owned files sent as blobs, keyed by their relative
+     * paths. `WorkerBlenderRunner` uses this for the Blender op tree; these are
+     * deliberately outside `job.inputs`, which remains the complete manifest
+     * of workflow-provided inputs.
+     */
+    extraBlobs?: Record<string, Uint8Array>;
+}
+export interface BlenderExecutorStats {
+    blender_version: string;
+    render_seconds: number;
+    frames?: number;
+    objects?: number;
+    depth_near?: number;
+    depth_far?: number;
+    camera?: string;
+    [key: string]: unknown;
+}
+export interface BlenderExecutorResult {
+    /** Keyed by the job's logical output names. Only declared outputs. */
+    outputs: Record<string, Uint8Array>;
+    stats: BlenderExecutorStats;
+}
+/**
+ * Worker-tier Blender failure. `code` is the local tier's code for the same
+ * case, so Stage 4b can map it one-to-one into `BlenderJobError`.
+ */
+export declare class BlenderExecutorError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+/**
+ * Run one Blender job on a worker bridge and collect its outputs.
+ *
+ * Route only to a bridge whose {@link PythonBridge.supportsBlender} is true —
+ * an older worker answers `blender.execute` with `Unknown message type`,
+ * which surfaces here as `bad_result`.
+ */
+export declare function executeBlender(bridge: PythonBridge, job: BlenderWorkerJob, inputs: Record<string, Uint8Array>, options: BlenderExecutorOptions): Promise<BlenderExecutorResult>;
+//# sourceMappingURL=blender-executor.d.ts.map

package/dist/blender-executor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"blender-executor.d.ts","sourceRoot":"","sources":["../src/blender-executor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAOH,OAAO,KAAK,EACV,iBAAiB,EAEjB,YAAY,EACb,MAAM,0BAA0B,CAAC;AAIlC;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,GAAG,iBAAiB,CAAC;AAEjD,MAAM,WAAW,sBAAsB;IACrC,mEAAmE;IACnE,SAAS,EAAE,MAAM,CAAC;IAClB,+EAA+E;IAC/E,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACpD,iEAAiE;IACjE,cAAc,EAAE,MAAM,CAAC;IACvB,iFAAiF;IACjF,mBAAmB,EAAE,MAAM,CAAC;IAC5B;;;;;OAKG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;CACzC;AAED,MAAM,WAAW,oBAAoB;IACnC,eAAe,EAAE,MAAM,CAAC;IACxB,cAAc,EAAE,MAAM,CAAC;IACvB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,qBAAqB;IACpC,sEAAsE;IACtE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IACpC,KAAK,EAAE,oBAAoB,CAAC;CAC7B;AAED;;;GAGG;AACH,qBAAa,oBAAqB,SAAQ,KAAK;IAC7C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,YAAY,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAIxC;CACF;AAED;;;;;;GAMG;AACH,wBAAsB,cAAc,CAClC,MAAM,EAAE,YAAY,EACpB,GAAG,EAAE,gBAAgB,EACrB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,EAClC,OAAO,EAAE,sBAAsB,GAC9B,OAAO,CAAC,qBAAqB,CAAC,CAgJhC"}