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

package/dist/context.js

@@ -1,18 +1,86 @@
+import { getRunTraceScope } from "./run-trace-context.js";
+import { withSpan } from "./tracing-helpers.js";
+import { assetFileNameCandidates, buildAssetGenerationMetadata, isShortResourceId, packageAssetHttpPath, parsePackageAssetUri } from "@nodetool-ai/protocol";
+import { AgentMemory } from "./agent-memory.js";
+import { recordInvocationAsset, recordInvocationCost } from "./invocation-account.js";
+import { VariableChannel } from "./variable-channel.js";
+import { loadMediaRefBytes } from "./media-ref-bytes.js";
+import { objectTrackingRequestSchema, parseObjectTrackingResult } from "./providers/object-tracking.js";
+import { requestVideoToAudio, VIDEO_TO_AUDIO_TASK, VideoToAudioRequest } from "./providers/video-to-audio.js";
+import { encodeRawImageRef, validateImageEvidence } from "./image-codec.js";
+import { extForImageMime, sniffImageMime } from "./providers/image-mime.js";
+import { GenerationScopeError, isAuthoritativeProviderTerminalError, runWithGenerationReceipt } from "./generation-receipt.js";
+import { generationRegistry } from "./generation-registry.js";
+import { redactGenerationParams } from "./redact-params.js";
+import { isCallable, isBoolean, isNonEmptyString, isObjectLike, isNumber, isRecord, isString } from "@nodetool-ai/protocol";
+import { expandAssetReferences, expandEntityRefs, inlineTextAssetRefs } from "./prompt-asset-refs.js";
+import { getNodeBuiltinSync } from "@nodetool-ai/config";
+// `node:fs/promises`, `node:path`, `node:url`, `node:crypto` are loaded
+// lazily so this module loads in browser / Edge runtimes. `resolveWorkspacePath`
+// and the `randomUUID` fallback both degrade gracefully when these are
+// unavailable.
 /**
- * ProcessingContext – runtime context for node execution.
- *
- * Port of src/nodetool/workflows/processing_context.py.
- *
- * Provides:
- *   - Message queue for emitting ProcessingMessages.
- *   - Cache get/set interface.
- *   - Output normalization (sanitize memory URIs, etc.).
- *   - Asset handling with pluggable storage adapters.
+ * ProcessingContext variable key carrying the provider/model the currently
+ * running agent loop is itself talking to. Every loop that executes tools
+ * (chat turns, `StepExecutor` sub-agents) stamps it, so a tool that launches
+ * another harness inherits the caller's model by default instead of demanding
+ * one or falling back to a server env default.
+ */
+export const ACTIVE_MODEL_CONTEXT_KEY = "active_agent_model";
+const nodeCrypto = getNodeBuiltinSync("node:crypto");
+const nodeFsP = getNodeBuiltinSync("node:fs/promises");
+const nodePath = getNodeBuiltinSync("node:path");
+const nodeUrl = getNodeBuiltinSync("node:url");
+const randomUUID = nodeCrypto?.randomUUID
+    ? nodeCrypto.randomUUID
+    : () => {
+        const g = globalThis;
+        if (g.crypto?.randomUUID)
+            return g.crypto.randomUUID();
+        return `id_${Date.now().toString(36)}_${Math.random()
+            .toString(36)
+            .slice(2, 10)}`;
+    };
+/**
+ * `process` is undefined in browser/edge runtimes. Reading `process.env`
+ * directly there throws `ReferenceError`, so this context (constructed by the
+ * in-browser workflow runner too) reads env through this guard instead.
  */
-import { randomUUID } from "node:crypto";
-import { access, mkdir, readFile, writeFile } from "node:fs/promises";
-import { basename, dirname, extname, isAbsolute, join, normalize, relative, resolve, sep } from "node:path";
-import { fileURLToPath, pathToFileURL } from "node:url";
+const safeProcessEnv = () => typeof process !== "undefined" && process.env ? process.env : {};
+function waitForRetry(delayMs, signal) {
+    return new Promise((resolveWait, rejectWait) => {
+        if (signal?.aborted) {
+            rejectWait(signal.reason ?? new Error("HTTP request aborted"));
+            return;
+        }
+        const onAbort = () => {
+            clearTimeout(timer);
+            rejectWait(signal?.reason ?? new Error("HTTP request aborted"));
+        };
+        const timer = setTimeout(() => {
+            signal?.removeEventListener("abort", onAbort);
+            resolveWait();
+        }, delayMs);
+        signal?.addEventListener("abort", onAbort, { once: true });
+    });
+}
+// Eager local bindings; unavailable off-Node, throw at call time.
+function notOnNode(api) {
+    throw new Error(`${api} is unavailable in this runtime — configure a StorageAdapter instead`);
+}
+const mkdir = (...a) => nodeFsP ? nodeFsP.mkdir(...a) : notOnNode("node:fs/promises.mkdir");
+const readFile = (...a) => nodeFsP ? nodeFsP.readFile(...a) : notOnNode("node:fs/promises.readFile");
+const writeFile = (...a) => nodeFsP ? nodeFsP.writeFile(...a) : notOnNode("node:fs/promises.writeFile");
+const basename = (p, ext) => nodePath ? nodePath.basename(p, ext) : notOnNode("node:path.basename");
+const dirname = (p) => nodePath ? nodePath.dirname(p) : notOnNode("node:path.dirname");
+const extname = (p) => nodePath ? nodePath.extname(p) : notOnNode("node:path.extname");
+const isAbsolute = (p) => nodePath ? nodePath.isAbsolute(p) : notOnNode("node:path.isAbsolute");
+const join = (...parts) => nodePath ? nodePath.join(...parts) : notOnNode("node:path.join");
+const relative = (from, to) => nodePath ? nodePath.relative(from, to) : notOnNode("node:path.relative");
+const resolve = (...parts) => nodePath ? nodePath.resolve(...parts) : notOnNode("node:path.resolve");
+const pathToFileURL = (p) => nodeUrl ? nodeUrl.pathToFileURL(p) : notOnNode("node:url.pathToFileURL");
+import { CONTENT_FILTER_MAX_RETRIES, contentFilterRetryDelayMs, isContentFilterRefusal } from "./providers/content-filter.js";
+import { getProcessSandboxModuleCatalog } from "./sandbox-module-catalog.js";
 /**
  * In-memory cache adapter (default for tests and single-process execution).
  */
@@ -26,6 +94,8 @@ export class MemoryCache {
             this._store.delete(key);
             return undefined;
         }
+        // SAFETY: `TValue` is what the caller stored under this key; a cache
+        // hands back exactly the value `set` was given for it.
         return entry.value;
     }
     async set(key, value, ttlSeconds) {
@@ -39,195 +109,173 @@ export class MemoryCache {
         this._store.delete(key);
     }
 }
+/** Raised by a durable host when an idempotent request is already owned. */
+export class GenerationAlreadyAcceptedError extends Error {
+    generationId;
+    constructor(generationId) {
+        super(`Generation ${generationId} was already accepted`);
+        this.generationId = generationId;
+        this.name = "GenerationAlreadyAcceptedError";
+    }
+}
+let defaultModelInterfaces = null;
+/**
+ * Install the model interfaces every context in this process falls back to.
+ *
+ * A host installs its persistence once at startup instead of each entrance
+ * remembering to wire it onto the context it builds. That forgetting is a
+ * defect generator: `nodetool debug` wired none while `workflows run` wired
+ * four, so a workflow that saves an image ran under one command and threw
+ * under the other. A context that sets its own interfaces still wins — this
+ * is the floor, not an override.
+ *
+ * Pass `null` to uninstall (a test restoring global state).
+ */
+export function setDefaultModelInterfaces(interfaces) {
+    defaultModelInterfaces = interfaces;
+}
+/** The process-wide default, or null when no host installed one. */
+export function getDefaultModelInterfaces() {
+    return defaultModelInterfaces;
+}
 function isWithinRoot(root, target) {
     const rel = relative(root, target);
     return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
 }
-function normalizeStorageKey(key) {
-    const cleaned = normalize(key.replaceAll("\\", "/")).replace(/^\/+/, "");
-    if (!cleaned ||
-        cleaned === "." ||
-        cleaned.startsWith("..") ||
-        cleaned.includes(`..${sep}`)) {
-        throw new Error(`Invalid storage key: ${key}`);
-    }
-    return cleaned;
-}
-function joinStorageKey(prefix, key) {
-    const normalizedKey = normalizeStorageKey(key);
-    if (!prefix)
-        return normalizedKey;
-    const normalizedPrefix = normalizeStorageKey(prefix);
-    return `${normalizedPrefix}/${normalizedKey}`;
-}
 /**
- * In-memory storage adapter useful for tests and single-process ephemeral runs.
+ * Deterministic JSON serialization with object keys sorted at every depth.
+ * Unlike `JSON.stringify(value, sortedKeys)` (a recursive replacer allow-list
+ * that drops nested values), this preserves the full nested structure, so two
+ * values are equal-keyed iff they are deeply equal.
  */
-export class InMemoryStorageAdapter {
-    _store = new Map();
-    async store(key, data, _contentType) {
-        const normalized = normalizeStorageKey(key);
-        this._store.set(normalized, new Uint8Array(data));
-        return `memory://${normalized}`;
-    }
-    async retrieve(uri) {
-        if (!uri.startsWith("memory://"))
-            return null;
-        const key = uri.slice("memory://".length);
-        const value = this._store.get(key);
-        return value ? new Uint8Array(value) : null;
+function stableStringifyDeep(value) {
+    if (!isObjectLike(value)) {
+        return JSON.stringify(value ?? null);
     }
-    async exists(uri) {
-        if (!uri.startsWith("memory://"))
-            return false;
-        const key = uri.slice("memory://".length);
-        return this._store.has(key);
+    if (Array.isArray(value)) {
+        return `[${value.map((v) => stableStringifyDeep(v)).join(",")}]`;
     }
+    const entries = Object.keys(value)
+        .sort()
+        .map((k) => `${JSON.stringify(k)}:${stableStringifyDeep(value[k])}`);
+    return `{${entries.join(",")}}`;
 }
 /**
- * File-system storage adapter rooted to a single base directory.
+ * Normalize the image input for image-to-image / image-to-video predictions
+ * into a list of byte buffers. Accepts the modern `images` array as well as
+ * the legacy singular `image` field so older callers keep working.
  */
-export class FileStorageAdapter {
-    rootDir;
-    constructor(rootDir) {
-        this.rootDir = resolve(rootDir);
-    }
-    resolvePathFromKey(key) {
-        const normalized = normalizeStorageKey(key);
-        const absolute = resolve(join(this.rootDir, normalized));
-        if (!isWithinRoot(this.rootDir, absolute)) {
-            throw new Error(`Storage key escapes root: ${key}`);
-        }
-        return absolute;
-    }
-    resolvePathFromUri(uri) {
-        let absolute = null;
-        if (uri.startsWith("file://")) {
-            try {
-                absolute = resolve(fileURLToPath(uri));
-            }
-            catch {
-                // Invalid file:// URI — treat as unresolvable.
-                return null;
-            }
-        }
-        else if (uri.startsWith("/api/storage/") ||
-            uri.startsWith("api/storage/")) {
-            const key = uri.replace(/^\/?api\/storage\//, "");
-            absolute = this.resolvePathFromKey(key);
-        }
-        else if (/^https?:\/\//.test(uri)) {
-            try {
-                const parsed = new URL(uri);
-                if (parsed.pathname.startsWith("/api/storage/")) {
-                    const key = parsed.pathname.replace(/^\/api\/storage\//, "");
-                    absolute = this.resolvePathFromKey(key);
-                }
-            }
-            catch {
-                // Malformed URL — treat as unresolvable.
-                return null;
-            }
-        }
-        else {
-            return null;
-        }
-        if (absolute === null || !isWithinRoot(this.rootDir, absolute)) {
-            return null;
-        }
-        return absolute;
-    }
-    async store(key, data, _contentType) {
-        const absolutePath = this.resolvePathFromKey(key);
-        await mkdir(dirname(absolutePath), { recursive: true });
-        await writeFile(absolutePath, data);
-        return pathToFileURL(absolutePath).toString();
-    }
-    async retrieve(uri) {
-        const absolutePath = this.resolvePathFromUri(uri);
-        if (!absolutePath)
-            return null;
-        try {
-            return await readFile(absolutePath);
-        }
-        catch {
-            // File not found or unreadable — caller handles null.
-            return null;
-        }
-    }
-    async exists(uri) {
-        const absolutePath = this.resolvePathFromUri(uri);
-        if (!absolutePath)
-            return false;
-        try {
-            await access(absolutePath);
-            return true;
-        }
-        catch {
-            // File does not exist or is inaccessible.
-            return false;
-        }
+function coerceImageList(params) {
+    const list = params.images;
+    if (Array.isArray(list)) {
+        return list.filter((b) => b instanceof Uint8Array);
     }
+    const single = params.image;
+    return single instanceof Uint8Array ? [single] : [];
+}
+/**
+ * Read an outpaint padding bag off the loose params. Only the four side keys
+ * are read, and only when numeric: a caller that passes nothing gets
+ * `undefined`, which lets the provider fall back to its endpoint's default
+ * expansion rather than sending zeros that would outpaint nothing.
+ */
+function coerceOutpaintPadding(value) {
+    if (!isObjectLike(value))
+        return undefined;
+    const side = (key) => isNumber(value[key]) ? value[key] : undefined;
+    const padding = {
+        left: side("left"),
+        right: side("right"),
+        top: side("top"),
+        bottom: side("bottom")
+    };
+    return Object.values(padding).some((v) => v !== undefined)
+        ? padding
+        : undefined;
+}
+function coerceByteList(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.filter((item) => item instanceof Uint8Array && item.byteLength > 0);
+}
+function coerceStringList(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.filter(isNonEmptyString);
+}
+function firstNonEmptyByteList(value) {
+    return value.find((bytes) => bytes.byteLength > 0) ?? new Uint8Array();
+}
+function isAbortSignal(value) {
+    return (isObjectLike(value) &&
+        isBoolean(value.aborted) &&
+        isCallable(value.addEventListener));
 }
 /**
- * S3-backed storage adapter with injected client operations.
+ * Normalize `params.entities` into provider-level {@link EntityReference}s.
  *
- * This avoids hard-coupling runtime to any specific SDK while providing
- * predictable URI behavior (`s3://bucket/key`).
+ * Consumers send entities in whatever shape they hold: a full protocol Entity
+ * (`reference_images` list), a lean `{name, descriptor, image}` where `image`
+ * is bytes, an ImageRef-like object, or a bare URI string. Images are resolved
+ * to bytes here — the last point with a ProcessingContext — so providers only
+ * ever see `Uint8Array`s. Entities without a name are dropped; an unresolvable
+ * image degrades to a text-only entity (the descriptor still applies).
  */
-export class S3StorageAdapter {
-    bucket;
-    prefix;
-    client;
-    constructor(opts) {
-        if (!opts.bucket) {
-            throw new Error("S3 bucket is required");
-        }
-        this.bucket = opts.bucket;
-        this.client = opts.client;
-        this.prefix = opts.prefix ? normalizeStorageKey(opts.prefix) : null;
-    }
-    keyForStore(key) {
-        return joinStorageKey(this.prefix ?? undefined, key);
-    }
-    parseUri(uri) {
-        if (!uri.startsWith("s3://"))
-            return null;
-        const withoutScheme = uri.slice("s3://".length);
-        const slashIndex = withoutScheme.indexOf("/");
-        if (slashIndex <= 0 || slashIndex === withoutScheme.length - 1) {
-            return null;
+async function coerceEntityList(params, context) {
+    const raw = params.entities;
+    if (!Array.isArray(raw) || raw.length === 0)
+        return undefined;
+    const out = [];
+    for (const item of raw) {
+        if (!isObjectLike(item))
+            continue;
+        const entity = item;
+        const name = isString(entity.name) ? entity.name.trim() : "";
+        if (!name)
+            continue;
+        const descriptor = isString(entity.descriptor)
+            ? entity.descriptor
+            : undefined;
+        const imageSource = entity.image ??
+            (Array.isArray(entity.reference_images)
+                ? entity.reference_images[0]
+                : undefined);
+        let image;
+        if (imageSource instanceof Uint8Array) {
+            image = imageSource;
+        }
+        else if (isNonEmptyString(imageSource)) {
+            image =
+                (await loadMediaRefBytes({ type: "image", uri: imageSource }, context)) ?? undefined;
+        }
+        else if (isObjectLike(imageSource)) {
+            image =
+                (await loadMediaRefBytes(imageSource, context)) ??
+                    undefined;
+        }
+        out.push({ name, descriptor, image });
+    }
+    return out.length > 0 ? out : undefined;
+}
+export function normalizeStorageKey(key) {
+    const segments = [];
+    for (const segment of key.replaceAll("\\", "/").split("/")) {
+        if (!segment || segment === ".")
+            continue;
+        if (segment === "..") {
+            if (segments.length === 0) {
+                throw new Error(`Invalid storage key: ${key}`);
+            }
+            segments.pop();
+            continue;
         }
-        const bucket = withoutScheme.slice(0, slashIndex);
-        const key = withoutScheme.slice(slashIndex + 1);
-        return { bucket, key };
-    }
-    async store(key, data, contentType) {
-        const objectKey = this.keyForStore(key);
-        await this.client.putObject({
-            bucket: this.bucket,
-            key: objectKey,
-            body: data,
-            contentType
-        });
-        return `s3://${this.bucket}/${objectKey}`;
-    }
-    async retrieve(uri) {
-        const parsed = this.parseUri(uri);
-        if (!parsed)
-            return null;
-        if (parsed.bucket !== this.bucket)
-            return null;
-        return this.client.getObject(parsed);
+        segments.push(segment);
     }
-    async exists(uri) {
-        const parsed = this.parseUri(uri);
-        if (!parsed)
-            return false;
-        if (parsed.bucket !== this.bucket)
-            return false;
-        return this.client.headObject(parsed);
+    const cleaned = segments.join("/");
+    if (!cleaned) {
+        throw new Error(`Invalid storage key: ${key}`);
     }
+    return cleaned;
 }
 /**
  * Resolve paths relative to a configured workspace root.
@@ -272,32 +320,158 @@ export function resolveWorkspacePath(workspaceDir, path) {
     }
     return absPath;
 }
-// ---------------------------------------------------------------------------
-// ProcessingContext
-// ---------------------------------------------------------------------------
+let workspaceFactory = (opts) => opts.workspace ?? null;
+/** Installed once by `storage-workspace.ts`; see {@link ProcessingContext.workspace}. */
+export function setWorkspaceFactory(factory) {
+    workspaceFactory = factory;
+}
+function resolveWorkspaceOption(opts) {
+    return workspaceFactory(opts);
+}
+/**
+ * The listed entry holding the asset `bareId`, or undefined.
+ *
+ * A short resource id is a prefix of the stored id, so the key continues with
+ * more hex before its extension; a full id is followed by the extension
+ * itself. A hierarchical id (`user-1/image`) lives in the full key, a flat id
+ * in the last segment — both forms are matched. Generated thumbnails
+ * (`<id>_thumb.<ext>`) are skipped unless they are the id being resolved, so a
+ * legit `banner_thumb` still matches instead of being dropped by a substring
+ * test. Preview proxies (`<id>_proxy.<ext>`) are skipped the same way.
+ */
+function findListedAsset(entries, bareId) {
+    const bareEndsWithThumb = bareId.endsWith("_thumb");
+    const needle = isShortResourceId(bareId) ? bareId : `${bareId}.`;
+    return entries.find((entry) => {
+        const key = entry.key;
+        const lastSegment = key.split("/").pop() ?? "";
+        if (!key.startsWith(needle) && !lastSegment.startsWith(needle)) {
+            return false;
+        }
+        // A preview proxy (`<id>_proxy.mp4`) and its manifest sit next to the
+        // asset. A short id must never resolve to them: renders read the original.
+        if (/_proxy\.[^./]+$/.test(lastSegment) && !bareId.endsWith("_proxy")) {
+            return false;
+        }
+        const isThumb = /_thumb\.[^./]+$/.test(lastSegment);
+        return !isThumb || bareEndsWithThumb;
+    });
+}
 export class ProcessingContext {
     jobId;
     workflowId;
+    /** Chat thread id, when this context is serving a chat-driven agent run. */
+    threadId;
     userId;
     workspaceDir;
     assetOutputMode;
+    /**
+     * Whether Output nodes should turn transient media into durable Asset rows.
+     * Hosts can disable this for explicitly temporary SDK executions.
+     */
+    persistOutputAssets;
     environment;
+    /** Bearer token for authenticated calls back to the owning NodeTool API. */
+    authToken;
+    /** Read-only sandbox module catalog supplied by the execution host. */
+    sandboxModuleCatalog;
+    /**
+     * Run-level cancellation. Set by the kernel to the signal
+     * `WorkflowRunner.cancel()` aborts, so long-running node work (agent loops,
+     * provider calls) can be interrupted rather than merely having its result
+     * discarded. Nodes reached through the streaming `run()` path can also read
+     * the same signal via `inputs.signal`.
+     *
+     * Defaults to a never-aborted signal so contexts built outside a kernel run
+     * (tools, tests, CLI) need not supply one.
+     */
+    signal = new AbortController().signal;
+    /**
+     * Wake-up payload for a trigger-driven run. Set by the kernel
+     * (`WorkflowRunner._runImpl`) from `RunJobRequest.trigger_event` at the
+     * start of each run, alongside {@link signal} — so it must be a mutable
+     * property, not a constructor-only value. The trigger node's actor reads
+     * `triggerEvent?.node_id === this.id` to enter its event-emitting entry
+     * point instead of the normal streaming path. `null` for interactive/
+     * live-test runs.
+     */
+    triggerEvent;
     /** Message queue: all emitted processing messages. */
     _messages = [];
+    /** Whether emit() feeds the pull queue (see constructor option). */
+    _retainMessageQueue = true;
     /** Latest node status by node id. */
     _nodeStatuses = new Map();
     /** Latest edge status by edge id. */
     _edgeStatuses = new Map();
-    /** Optional message listener (for real-time streaming). */
-    _onMessage = null;
+    /** Message listeners (for real-time streaming). */
+    _messageListeners = new Set();
+    /**
+     * One media object can appear in both a live output_update and the
+     * authoritative terminal result. Reuse its materialization within this
+     * execution instead of encoding/storing the same large payload twice.
+     */
+    _normalizedOutputAssets = new WeakMap();
     /** Cache adapter. */
     cache;
     /** Storage adapter (optional, for asset handling). */
     storage;
+    /**
+     * Asset storage adapter — where user assets (`asset://<id>.<ext>`) live.
+     * Separate from {@link storage}, which servers point at the *temp* store:
+     * without this, an `asset://` reference could only be resolved over HTTP
+     * through `/api/storage`, which authorizes by `x-user-id` and 404s for
+     * anyone but user `1`. Null falls back to {@link storage}.
+     */
+    assetStorage;
+    /**
+     * Workspace storage adapter — the agent's working directory abstracted
+     * behind {@link StorageAdapter}. Tools that read/write/list files use
+     * this adapter so the same code paths work locally (FS-backed) and in
+     * cloud deployments (S3/Supabase-backed).
+     *
+     * If null, file-tool operations should return a clear error rather than
+     * fall back to direct FS access — there is no implicit workspace.
+     */
+    /**
+     * @deprecated Use {@link workspace}, which works on a cloud deployment too.
+     * Only set when a host passed a bare adapter; a host that passes a
+     * `workspace` leaves this null.
+     */
+    workspaceStorage;
+    /**
+     * The run's workspace as an interface — the way to read and write run files.
+     *
+     * Null when the host wired none, in which case a file operation must report
+     * that plainly rather than reaching for the process working directory.
+     * Prefer this over {@link workspaceDir}, which is only non-null when the
+     * workspace happens to be a real folder: a cloud run's workspace lives in
+     * object storage and has no path.
+     */
+    workspace;
+    /** Project captured when this run started. */
+    projectId;
+    /**
+     * Unified, structured agent memory. The single source of truth for results
+     * shared between agents, tasks, steps and tools. Keys use the namespaces
+     * `step:`, `task:`, `input:`, `shared:` (see {@link memoryKeys}).
+     */
+    memory = new AgentMemory();
     /** Variables shared across node execution. */
     _variables;
+    /** Named async channels backing Set/Get Variable (see {@link getChannel}). */
+    _channels = new Map();
+    /** Remaining Set Variable writers per channel; channel closes at zero. */
+    _channelWriters = new Map();
     /** Optional async secret resolver. */
     _secretResolver = null;
+    /** Every secret value the resolver handed out this run (see {@link ProcessingContext.getResolvedSecretValues}). */
+    _resolvedSecrets = new Set();
+    /** Identity shared by all work beneath an app operation. */
+    appRunContext;
+    runTraceContext;
+    appRunCostAccount;
+    _appRunDocuments = new Map();
     /** Fetch function used by HTTP helpers. */
     _fetch;
     /** Optional temporary URL resolver for stored assets. */
@@ -308,10 +482,21 @@ export class ProcessingContext {
     _modelInterfaces = null;
     /** Provider cache keyed by provider id. */
     _providers = new Map();
+    _providerPromises = new Map();
     /** In-context memory URI cache (memory:// key-value objects). */
     _memory = new Map();
     /** Optional control event dispatcher (set by workflow runner). */
     _sendControlEvent = null;
+    /**
+     * Executable tools supplied by the caller that owns this run (set by the
+     * agent workflow runner). Agent nodes merge these into their own tool list
+     * by name, so a node that selects `read_file` gets the caller's live,
+     * fully-wired tool instead of a builtin stub. Tools the caller does not
+     * provide fall back to builtin hydration.
+     */
+    _injectedTools = [];
+    /** Provider charge (USD) reported by the current node execution (e.g. FAL/KIE generation). */
+    _providerCost = null;
     /** Optional executor resolver for sub-workflow execution. */
     _resolveExecutor = null;
     /** Optional node type resolver for sub-workflow graph hydration. */
@@ -320,48 +505,119 @@ export class ProcessingContext {
     _totalCost = 0;
     /** Per-operation cost entries. */
     _operationCosts = [];
+    _generationLifecycle;
     constructor(opts) {
         this.jobId = opts.jobId;
         this.workflowId = opts.workflowId ?? null;
+        this.projectId = opts.projectId ?? null;
+        this.threadId = opts.threadId ?? null;
         this.userId = opts.userId ?? "default";
-        this.workspaceDir = opts.workspaceDir ?? null;
-        this.assetOutputMode = opts.assetOutputMode ?? "python";
+        this.workspace = resolveWorkspaceOption(opts);
+        this.workspaceDir = this.workspace?.localDir ?? opts.workspaceDir ?? null;
+        this.assetOutputMode = opts.assetOutputMode ?? "native";
+        this.persistOutputAssets = opts.persistOutputAssets ?? true;
+        this._generationLifecycle = opts.generationLifecycle ?? null;
+        this.appRunContext = opts.appRunContext ? Object.freeze({ ...opts.appRunContext }) : null;
+        this.runTraceContext = opts.runTraceContext ?? getRunTraceScope() ?? null;
+        if (this.runTraceContext?.secretValues instanceof Set) {
+            this._resolvedSecrets = this.runTraceContext.secretValues;
+        }
+        this.appRunCostAccount = opts.appRunCostAccount ?? (this.appRunContext ? { llmCostUsd: 0, unpriced: false } : null);
         this.cache = opts.cache ?? new MemoryCache();
         this.storage = opts.storage ?? null;
-        this._onMessage = opts.onMessage ?? null;
+        this.assetStorage = opts.assetStorage ?? null;
+        this.workspaceStorage = opts.workspaceStorage ?? null;
+        if (opts.onMessage) {
+            this._messageListeners.add(opts.onMessage);
+        }
         this._variables = { ...(opts.variables ?? {}) };
         const env = {};
-        for (const [k, v] of Object.entries(process.env)) {
-            if (typeof v === "string")
+        for (const [k, v] of Object.entries(safeProcessEnv())) {
+            if (v != null)
                 env[k] = v;
         }
         this.environment = { ...env, ...(opts.environment ?? {}) };
+        this.authToken = opts.authToken ?? null;
+        // An explicit option — including null — wins over the host default.
+        this.sandboxModuleCatalog =
+            opts.sandboxModuleCatalog !== undefined
+                ? opts.sandboxModuleCatalog
+                : getProcessSandboxModuleCatalog();
         this._secretResolver = opts.secretResolver ?? null;
         this._fetch =
             opts.fetchFn ??
                 ((input, init) => fetch(input, init));
         this._tempUrlResolver = opts.tempUrlResolver ?? null;
         this._modelInterfaces = opts.modelInterfaces ?? null;
+        this._retainMessageQueue = opts.retainMessageQueue ?? true;
+        this.triggerEvent = opts.triggerEvent ?? null;
     }
-    copy() {
+    /**
+     * Derive a child context.
+     *
+     * Defaults to full isolation: fresh agent memory, fresh message queue, the
+     * parent's message listeners inherited. Two opt-ins exist because a child
+     * that must *not* be isolated in one respect should not have to reach around
+     * the copy:
+     *
+     *   - `shareMemory` shares the parent's {@link AgentMemory} instance, so a
+     *     scoped run (own injected tools, own emit fan-out) still reads and
+     *     writes the same step/task results.
+     *   - `inheritMessageListeners: false` drops the parent's listeners, for a
+     *     child that forwards messages itself and would otherwise double-notify.
+     *
+     * The run-level cancellation {@link signal} always carries over: a child that
+     * cannot observe the parent's Stop keeps burning provider calls after the
+     * user cancelled.
+     */
+    copy(opts) {
         const next = new ProcessingContext({
-            jobId: this.jobId,
-            workflowId: this.workflowId,
+            jobId: opts?.jobId ?? this.jobId,
+            projectId: this.projectId,
+            workflowId: opts?.workflowId !== undefined ? opts.workflowId : this.workflowId,
+            threadId: this.threadId,
             userId: this.userId,
-            workspaceDir: this.workspaceDir,
+            workspace: opts?.workspace !== undefined ? opts.workspace : this.workspace,
             assetOutputMode: this.assetOutputMode,
+            persistOutputAssets: this.persistOutputAssets,
             cache: this.cache,
             storage: this.storage,
-            onMessage: this._onMessage ?? undefined,
+            assetStorage: this.assetStorage,
+            workspaceStorage: this.workspaceStorage,
             variables: { ...this._variables },
             environment: { ...this.environment },
+            authToken: this.authToken,
+            sandboxModuleCatalog: this.sandboxModuleCatalog,
             fetchFn: this._fetch,
             secretResolver: this._secretResolver ?? undefined,
-            tempUrlResolver: this._tempUrlResolver ?? undefined
+            tempUrlResolver: this._tempUrlResolver ?? undefined,
+            modelInterfaces: this._modelInterfaces ?? undefined,
+            retainMessageQueue: this._retainMessageQueue,
+            triggerEvent: this.triggerEvent,
+            generationLifecycle: opts?.generationLifecycle ?? this._generationLifecycle ?? undefined,
+            appRunContext: opts?.appRunContext ?? this.appRunContext ?? undefined,
+            runTraceContext: opts?.runTraceContext ?? this.runTraceContext ?? undefined,
+            appRunCostAccount: !opts?.appRunContext || opts.appRunContext.appRunId === this.appRunContext?.appRunId ? this.appRunCostAccount ?? undefined : undefined
         });
+        if (opts?.inheritMessageListeners !== false) {
+            for (const listener of this._messageListeners) {
+                next.addMessageListener(listener);
+            }
+        }
+        if (opts?.shareMemory) {
+            next.memory = this.memory;
+        }
+        if (!opts?.runTraceContext) {
+            next._resolvedSecrets = this._resolvedSecrets;
+        }
+        if (next.appRunContext?.appRunId === this.appRunContext?.appRunId) {
+            next._appRunDocuments = this._appRunDocuments;
+        }
+        next.signal = this.signal;
         next._providerResolver = this._providerResolver;
         next._modelInterfaces = this._modelInterfaces;
         next._sendControlEvent = this._sendControlEvent;
+        next._injectedTools = this._injectedTools;
         next._providers = new Map(this._providers);
         next._totalCost = this._totalCost;
         next._operationCosts = this._operationCosts.map((c) => ({ ...c }));
@@ -373,9 +629,66 @@ export class ProcessingContext {
     setProviderResolver(resolver) {
         this._providerResolver = resolver;
     }
+    /**
+     * Whether this context serves providers from an injected resolver rather
+     * than the process-wide registry.
+     *
+     * When it does, {@link getProvider} never reaches the registry and never
+     * reads a credential — so a credential the run will not use is not a reason
+     * to refuse the run. The execution preflight reads this to decide whether
+     * its credential check applies at all.
+     */
+    get hasProviderResolver() {
+        return this._providerResolver !== null;
+    }
     setModelInterfaces(modelInterfaces) {
         this._modelInterfaces = modelInterfaces;
     }
+    /**
+     * The interfaces this context answers with: its own when a caller wired
+     * them, else the host's process-wide default.
+     *
+     * The default is what keeps a run from depending on which entrance built
+     * its context. Six hosts assembled these by hand and three of them forgot
+     * `createAsset`, so the same workflow saved an image under `workflows run`
+     * and died under `debug` with "model interface is not configured".
+     *
+     * The two compose key by key, the context's own winning, so wiring one
+     * interface does not uninstall the rest of the floor.
+     */
+    modelInterfaces() {
+        const own = this._modelInterfaces;
+        const floor = getDefaultModelInterfaces();
+        if (!own)
+            return floor;
+        if (!floor)
+            return own;
+        // Per key, not per object: a host that wires two interfaces of its own
+        // keeps the other twelve. Replacing wholesale is how the HTTP run route
+        // lost `getTimelineSequence` while setting only the asset pair.
+        return { ...floor, ...own };
+    }
+    /**
+     * Whether a given model interface is wired for this context — its own or
+     * the host default. Lets callers decide between the DB-backed path
+     * (interface present — let errors propagate) and an in-memory fallback
+     * (interface absent — hermetic CLI runs, tests) without invoking a method
+     * that would throw when unwired.
+     */
+    hasModelInterface(name) {
+        return isCallable(this.modelInterfaces()?.[name]);
+    }
+    /** Read a user setting, falling back to this run's environment. */
+    async getSetting(key) {
+        const fn = this.modelInterfaces()?.getSetting;
+        if (fn) {
+            const value = await fn({ userId: this.userId, key });
+            if (value !== null && value.length > 0)
+                return value;
+        }
+        const value = this.environment[key];
+        return value !== undefined && value.length > 0 ? value : null;
+    }
     // -----------------------------------------------------------------------
     // Control event dispatch
     // -----------------------------------------------------------------------
@@ -396,6 +709,19 @@ export class ProcessingContext {
             return null;
         return this._sendControlEvent(targetNodeId, properties);
     }
+    /**
+     * Supply the live tool set for this run. Agent nodes match their selected
+     * tool names against these and prefer them over builtin hydration, so tools
+     * that only the caller can wire (MCP, workspace, skills, security-gated
+     * wrappers) reach nodes the caller did not author.
+     */
+    setInjectedTools(tools) {
+        this._injectedTools = tools;
+    }
+    /** Injected tool matching `name`, or null when the caller supplied none. */
+    getInjectedTool(name) {
+        return this._injectedTools.find((tool) => tool.name === name) ?? null;
+    }
     // -----------------------------------------------------------------------
     // Sub-workflow executor resolution
     // -----------------------------------------------------------------------
@@ -411,9 +737,6 @@ export class ProcessingContext {
     get resolveNodeType() {
         return this._resolveNodeType;
     }
-    /**
-     * Check if control event dispatch is available.
-     */
     get hasControlEventSupport() {
         return this._sendControlEvent !== null;
     }
@@ -427,40 +750,32 @@ export class ProcessingContext {
         const cached = this._providers.get(providerId);
         if (cached)
             return cached;
-        if (!this._providerResolver) {
-            const { getRegisteredProvider } = await import("./providers/index.js");
-            const reg = getRegisteredProvider(providerId);
-            if (!reg) {
-                throw new Error(`No provider registered for "${providerId}"`);
-            }
-            // Resolve any missing secret kwargs from the context's own secret resolver
-            const kwargs = { ...reg.kwargs };
-            for (const [key, value] of Object.entries(kwargs)) {
-                if (!value) {
-                    const envVal = process.env[key];
-                    if (envVal) {
-                        kwargs[key] = envVal;
-                    }
-                    else {
-                        const secret = await this.getSecret(key);
-                        if (secret) {
-                            kwargs[key] = secret;
-                        }
-                    }
-                }
-            }
-            const resolved = new reg.cls(kwargs);
+        const pending = this._providerPromises.get(providerId);
+        if (pending)
+            return pending;
+        const resolution = (async () => {
+            const resolved = this._providerResolver
+                ? await this._providerResolver(providerId)
+                : await import("./providers/index.js").then(({ getProvider }) => getProvider(providerId, (key) => this.getSecret(key)));
             this._providers.set(providerId, resolved);
             resolved.setMessageEmitter((msg) => this.postMessage(msg));
             return resolved;
+        })();
+        this._providerPromises.set(providerId, resolution);
+        try {
+            return await resolution;
+        }
+        finally {
+            this._providerPromises.delete(providerId);
         }
-        const resolved = await this._providerResolver(providerId);
-        this._providers.set(providerId, resolved);
-        resolved.setMessageEmitter((msg) => this.postMessage(msg));
-        return resolved;
     }
-    async get_provider(providerId) {
-        return this.getProvider(providerId);
+    /**
+     * Check whether a registered provider has all required credentials
+     * resolvable through this context (DB/keychain/env).
+     */
+    async isProviderConfigured(providerId) {
+        const { isProviderConfigured: check } = await import("./providers/index.js");
+        return check(providerId, (key) => this.getSecret(key));
     }
     // -----------------------------------------------------------------------
     // Secrets / Variables API
@@ -471,12 +786,55 @@ export class ProcessingContext {
     setTempUrlResolver(resolver) {
         this._tempUrlResolver = resolver;
     }
+    /**
+     * Resolve a raw storage URI (e.g. `file:///.../storage/<key>`) to a URL the
+     * UI can fetch (e.g. `/api/storage/<key>`). Falls back to returning the URI
+     * unchanged when no resolver is wired (DSL / tests).
+     *
+     * Use this from tools that write binary output via `context.storage.store()`
+     * and want to surface a UI-renderable URL in their result.
+     */
+    async resolveTempUrl(uri) {
+        if (!this._tempUrlResolver)
+            return uri;
+        const resolvedUri = await this._tempUrlResolver(uri);
+        if (ProcessingContext.isClientFetchableResolvedAssetUri(uri, resolvedUri)) {
+            return resolvedUri;
+        }
+        throw new Error(`Temp URL resolver returned an unsafe URL for '${uri}': '${resolvedUri}'`);
+    }
+    /**
+     * Whether this run can reach a secret store at all.
+     *
+     * {@link getSecret} answers `null` both for "no store is wired" and for "the
+     * store does not hold this key", which a caller asking *which* of a list of
+     * credentials exists cannot tell apart — and reporting every declared
+     * credential as missing because no store was reachable is exactly the
+     * false alarm the graph validator's `missing_secret` check refuses to raise.
+     * A host installs the availability callback only when this is true.
+     */
+    get hasSecretResolver() {
+        return this._secretResolver !== null;
+    }
     async getSecret(key) {
         if (!this._secretResolver)
             return null;
         const value = await this._secretResolver(key, this.userId);
+        if (value != null && value.length > 0) {
+            this._resolvedSecrets.add(value);
+        }
         return value ?? null;
     }
+    /**
+     * Every secret value handed out during this run. The supervisor's escalation
+     * constructor masks against this set — without it, "mask every secret" has no
+     * subject, because the resolver forgets each key as soon as it answers.
+     * Values shorter than `MIN_MASKABLE_SECRET_LENGTH` are not recorded: masking
+     * a two-character value would redact unrelated text everywhere it occurs.
+     */
+    getResolvedSecretValues() {
+        return this._resolvedSecrets;
+    }
     async getSecretRequired(key) {
         const value = await this.getSecret(key);
         if (value === null || value === "") {
@@ -484,12 +842,6 @@ export class ProcessingContext {
         }
         return value;
     }
-    async get_secret(key) {
-        return this.getSecret(key);
-    }
-    async get_secret_required(key) {
-        return this.getSecretRequired(key);
-    }
     get(key, defaultValue) {
         if (Object.prototype.hasOwnProperty.call(this._variables, key)) {
             return this._variables[key];
@@ -498,72 +850,93 @@ export class ProcessingContext {
     }
     set(key, value) {
         this._variables[key] = value;
-        void this.persistVariableIfNeeded(key, value);
         if (key.startsWith("memory://")) {
             this._memory.set(key, value);
         }
     }
-    async storeStepResult(key, value) {
-        const path = this.workspacePathFor(`${key}.json`);
-        await mkdir(dirname(path), { recursive: true });
-        await writeFile(path, JSON.stringify(value, null, 2), "utf8");
-        this._variables[key] = { __workspace_result__: `${key}.json` };
-        return path;
+    /** Whether a shared variable with this name has been set. */
+    hasVariable(key) {
+        return Object.prototype.hasOwnProperty.call(this._variables, key);
     }
-    async loadStepResult(key, defaultValue) {
-        const marker = this._variables[key];
-        if (marker &&
-            typeof marker === "object" &&
-            "__workspace_result__" in marker) {
-            const rel = marker
-                .__workspace_result__;
-            const path = this.workspacePathFor(String(rel));
-            try {
-                const raw = await readFile(path, "utf8");
-                return JSON.parse(raw);
-            }
-            catch {
-                // File missing or corrupt — fall back to default.
-                return defaultValue;
+    /**
+     * Snapshot of all shared variables (name → value). Used by nodes that
+     * resolve variable references against the workflow's shared context — e.g.
+     * the Prompt node merges these into its `{{ name }}` template variables so a
+     * Set Variable node upstream can supply values without an explicit wire.
+     */
+    getVariables() {
+        return { ...this._variables };
+    }
+    // -----------------------------------------------------------------------
+    // Variable channels (Set/Get Variable)
+    // -----------------------------------------------------------------------
+    /**
+     * Declare how many Set Variable nodes write to `name`. The runner calls this
+     * before any actor runs so a channel with no writers can close immediately
+     * (readers get end-of-stream instead of hanging).
+     */
+    registerChannelWriters(name, count) {
+        this._channelWriters.set(name, (this._channelWriters.get(name) ?? 0) + count);
+    }
+    /**
+     * Get (or lazily create) the named variable channel. A channel created for a
+     * name with no registered writers is returned already closed, so a reader
+     * referencing an undefined variable resolves immediately rather than waiting
+     * forever.
+     */
+    getChannel(name) {
+        let channel = this._channels.get(name);
+        if (!channel) {
+            channel = new VariableChannel();
+            this._channels.set(name, channel);
+            if ((this._channelWriters.get(name) ?? 0) === 0) {
+                channel.close();
             }
         }
-        if (Object.prototype.hasOwnProperty.call(this._variables, key)) {
-            return this._variables[key];
-        }
-        return defaultValue;
+        return channel;
     }
-    workspacePathFor(fileName) {
-        if (!this.workspaceDir) {
-            throw new Error("workspace_dir is required to persist workflow variables");
+    /**
+     * Record that one Set Variable writer for `name` has finished. When the last
+     * writer finishes, the channel closes — readers drain the buffered values
+     * then end. The runner calls this from each Set Variable actor's completion.
+     */
+    markChannelWriterDone(name) {
+        const remaining = (this._channelWriters.get(name) ?? 0) - 1;
+        this._channelWriters.set(name, Math.max(0, remaining));
+        if (remaining <= 0) {
+            this.getChannel(name).close();
         }
-        return resolveWorkspacePath(this.workspaceDir, fileName);
     }
-    async persistVariableIfNeeded(key, value) {
-        if (!this.workspaceDir)
-            return;
-        if (value === undefined || value === null)
-            return;
-        if (typeof value === "function" ||
-            typeof value === "symbol" ||
-            typeof value === "bigint")
-            return;
-        const filePath = this.workspacePathFor(`var_${key}.json`);
-        try {
-            await mkdir(dirname(filePath), { recursive: true });
-            await writeFile(filePath, JSON.stringify(value, null, 2), "utf8");
+    /** Close every channel — a teardown backstop so no reader is left waiting. */
+    closeAllChannels() {
+        for (const channel of this._channels.values()) {
+            channel.close();
         }
-        catch {
-            // Best-effort persistence.
+    }
+    /** Whether any Set Variable node was registered as writing to `name`. */
+    hasChannelWriters(name) {
+        return (this._channelWriters.get(name) ?? 0) > 0;
+    }
+    async storeStepResult(key, value) {
+        this._variables[key] = value;
+        return "";
+    }
+    async loadStepResult(key, defaultValue) {
+        if (Object.prototype.hasOwnProperty.call(this._variables, key)) {
+            return this._variables[key];
         }
+        return defaultValue;
     }
     // -----------------------------------------------------------------------
     // Node result cache helpers
     // -----------------------------------------------------------------------
     generateNodeCacheKey(nodeType, nodeProps) {
-        const normalizedProps = nodeProps && typeof nodeProps === "object"
-            ? JSON.stringify(nodeProps, Object.keys(nodeProps).sort())
-            : JSON.stringify(nodeProps ?? null);
-        return `${this.userId}:${nodeType}:${normalizedProps}`;
+        // Deep, deterministic serialization: keys are sorted at EVERY nesting
+        // level. The previous `JSON.stringify(props, sortedTopLevelKeys)` form used
+        // the key array as a recursive replacer allow-list, which silently dropped
+        // every nested value — so nodes differing only in a nested prop collided on
+        // the same key and returned each other's cached (wrong) results.
+        return `${this.userId}:${nodeType}:${stableStringifyDeep(nodeProps ?? null)}`;
     }
     async getCachedResult(nodeType, nodeProps) {
         const key = this.generateNodeCacheKey(nodeType, nodeProps);
@@ -576,12 +949,20 @@ export class ProcessingContext {
     // -----------------------------------------------------------------------
     // Message queue API
     // -----------------------------------------------------------------------
+    addMessageListener(listener) {
+        this._messageListeners.add(listener);
+        return () => {
+            this._messageListeners.delete(listener);
+        };
+    }
     /**
      * Emit a processing message.
-     * Appended to the internal queue and forwarded to listener if set.
+     * Appended to the internal queue and forwarded to listeners if set.
      */
     emit(msg) {
-        this._messages.push(msg);
+        if (this._retainMessageQueue) {
+            this._messages.push(msg);
+        }
         this._notifyMessage();
         if (msg.type === "node_update" && msg.node_id) {
             this._nodeStatuses.set(msg.node_id, msg);
@@ -589,17 +970,29 @@ export class ProcessingContext {
         if (msg.type === "edge_update" && msg.edge_id) {
             this._edgeStatuses.set(msg.edge_id, msg);
         }
-        if (this._onMessage) {
-            this._onMessage(msg);
+        for (const listener of this._messageListeners) {
+            try {
+                listener(msg);
+            }
+            catch {
+                // Listeners are observers and must not interrupt workflow execution.
+            }
         }
     }
     postMessage(msg) {
         this.emit(msg);
     }
-    post_message(msg) {
-        this.emit(msg);
+    /** Record actual provider charge for the current node run (attached to completed NodeUpdate). */
+    setProviderCost(provider, amount, unit, details) {
+        this._providerCost = { provider, amount, unit, ...details };
+        recordInvocationCost(amount);
+    }
+    getProviderCost() {
+        return this._providerCost;
+    }
+    clearProviderCost() {
+        this._providerCost = null;
     }
-    /** Get all emitted messages. */
     getMessages() {
         return this._messages;
     }
@@ -609,39 +1002,31 @@ export class ProcessingContext {
     popMessage() {
         return this._messages.shift();
     }
-    _messageResolve = null;
+    _messageWaiters = [];
     /** Notify that a new message has been pushed. */
     _notifyMessage() {
-        if (this._messageResolve) {
-            const resolve = this._messageResolve;
-            this._messageResolve = null;
+        const waiters = this._messageWaiters;
+        this._messageWaiters = [];
+        for (const resolve of waiters)
             resolve();
-        }
     }
     async popMessageAsync() {
         while (this._messages.length === 0) {
             await new Promise((r) => {
-                this._messageResolve = r;
+                this._messageWaiters.push(r);
             });
         }
         return this._messages.shift();
     }
-    async pop_message_async() {
-        return this.popMessageAsync();
-    }
     getNodeStatuses() {
         return Object.fromEntries(this._nodeStatuses);
     }
     getEdgeStatuses() {
         return Object.fromEntries(this._edgeStatuses);
     }
-    /** Clear the message queue. */
     clearMessages() {
         this._messages = [];
     }
-    clear_messages() {
-        this.clearMessages();
-    }
     trackOperationCost(operation, cost, metadata) {
         const safeCost = Number.isFinite(cost) ? cost : 0;
         this._totalCost += safeCost;
@@ -663,6 +1048,26 @@ export class ProcessingContext {
     getTotalCost() {
         return this._totalCost;
     }
+    /** Null means at least one LLM call could not be priced. */
+    getAppRunLlmCost() {
+        return this.appRunCostAccount && !this.appRunCostAccount.unpriced
+            ? this.appRunCostAccount.llmCostUsd
+            : null;
+    }
+    getAppRunDocuments() {
+        return [...this._appRunDocuments.values()].map((reference) => ({
+            ...reference
+        }));
+    }
+    recordAppRunDocument(kind, document) {
+        if (this.appRunContext && document) {
+            this._appRunDocuments.set(`${kind}:${document.id}`, {
+                kind,
+                id: document.id
+            });
+        }
+        return document;
+    }
     getOperationCosts() {
         return this._operationCosts;
     }
@@ -694,6 +1099,10 @@ export class ProcessingContext {
     // -----------------------------------------------------------------------
     // HTTP helpers
     // -----------------------------------------------------------------------
+    /**
+     * Issue an HTTP request with the retry/backoff policy every node shares.
+     * `httpGet` is the GET shorthand; other verbs go through this directly.
+     */
     async httpRequestWithRetries(method, url, opts = {}) {
         const retry = opts.retry ?? {};
         const maxRetries = retry.maxRetries ?? 3;
@@ -719,22 +1128,38 @@ export class ProcessingContext {
                     const retryAfter = response.headers.get("Retry-After");
                     const retryDelay = retryAfter ? Number(retryAfter) * 1000 : NaN;
                     const delayMs = Number.isFinite(retryDelay)
-                        ? retryDelay
+                        ? Math.min(Math.max(0, retryDelay), 30_000)
                         : backoffMs * 2 ** attempt;
-                    await new Promise((r) => setTimeout(r, Math.max(0, delayMs)));
+                    // Drain/cancel the unconsumed body before retrying, or under undici
+                    // the socket stays checked out of the connection pool (leaked until
+                    // GC) and emits a "body not consumed" warning.
+                    await response.body?.cancel().catch(() => { });
+                    await waitForRetry(Math.max(0, delayMs), opts.signal);
                     continue;
                 }
                 if (!response.ok) {
-                    throw new Error(`HTTP ${response.status} ${response.statusText} for ${method} ${url}`);
+                    // Non-retryable HTTP error (status not in retryStatuses): fail fast.
+                    // Throwing into the generic catch below would treat it like a network
+                    // error and retry it, hammering 4xx responses maxRetries times.
+                    const nonRetryable = new Error(`HTTP ${response.status} ${response.statusText} for ${method} ${url}`);
+                    nonRetryable.nonRetryable = true;
+                    await response.body?.cancel().catch(() => { });
+                    throw nonRetryable;
                 }
                 return response;
             }
             catch (error) {
                 lastError = error;
+                if (opts.signal?.aborted)
+                    break;
+                // A non-retryable HTTP error must not loop; only thrown fetch/network
+                // errors and retryable statuses are retried.
+                if (error?.nonRetryable)
+                    break;
                 if (attempt >= maxRetries - 1)
                     break;
                 const delayMs = backoffMs * 2 ** attempt;
-                await new Promise((r) => setTimeout(r, delayMs));
+                await waitForRetry(delayMs, opts.signal);
             }
         }
         throw lastError instanceof Error
@@ -744,50 +1169,13 @@ export class ProcessingContext {
     async httpGet(url, opts = {}) {
         return this.httpRequestWithRetries("GET", url, opts);
     }
-    async httpPost(url, opts = {}) {
-        return this.httpRequestWithRetries("POST", url, opts);
-    }
-    async httpPatch(url, opts = {}) {
-        return this.httpRequestWithRetries("PATCH", url, opts);
-    }
-    async httpPut(url, opts = {}) {
-        return this.httpRequestWithRetries("PUT", url, opts);
-    }
-    async httpDelete(url, opts = {}) {
-        return this.httpRequestWithRetries("DELETE", url, opts);
-    }
-    async httpHead(url, opts = {}) {
-        return this.httpRequestWithRetries("HEAD", url, opts);
-    }
     async downloadFile(url, opts = {}) {
         const response = await this.httpGet(url, opts);
         const arr = await response.arrayBuffer();
         return new Uint8Array(arr);
     }
-    async downloadText(url, opts = {}) {
-        const response = await this.httpGet(url, opts);
-        return response.text();
-    }
-    async http_get(url, opts = {}) {
-        return this.httpGet(url, opts);
-    }
-    async http_post(url, opts = {}) {
-        return this.httpPost(url, opts);
-    }
-    async http_patch(url, opts = {}) {
-        return this.httpPatch(url, opts);
-    }
-    async http_put(url, opts = {}) {
-        return this.httpPut(url, opts);
-    }
-    async http_delete(url, opts = {}) {
-        return this.httpDelete(url, opts);
-    }
-    async http_head(url, opts = {}) {
-        return this.httpHead(url, opts);
-    }
     requireModelInterface(name) {
-        const fn = this._modelInterfaces?.[name];
+        const fn = this.modelInterfaces()?.[name];
         if (!fn) {
             throw new Error(`ProcessingContext model interface '${String(name)}' is not configured`);
         }
@@ -797,34 +1185,155 @@ export class ProcessingContext {
         const fn = this.requireModelInterface("getJob");
         return fn({ userId: this.userId, jobId });
     }
-    async get_job(jobId) {
-        return this.getJob(jobId);
-    }
+    /**
+     * HOLDOUT (anti-slop/no-unknown-returns): see the `createAsset` port above —
+     * narrowing the result breaks the `as Record<string, unknown>` assertions in
+     * `image-nodes` and `audio-nodes`.
+     */
     async createAsset(args) {
         const fn = this.requireModelInterface("createAsset");
         const content = args.content ?? args.instructions;
         if (!content) {
             throw new Error("Asset content is required");
         }
+        recordInvocationAsset();
         return fn({
             userId: this.userId,
             workflowId: this.workflowId,
             jobId: this.jobId,
+            projectId: this.projectId,
             name: args.name,
             contentType: args.contentType,
             content,
             parentId: args.parentId ?? null,
-            nodeId: args.nodeId ?? null
+            nodeId: args.nodeId ?? null,
+            metadata: args.metadata ?? null
         });
     }
-    async create_asset(args) {
-        return this.createAsset(args);
+    /**
+     * Replace an owned asset's bytes, keeping its id. Null when the asset is
+     * missing or belongs to someone else.
+     */
+    async updateAssetBytes(args) {
+        const fn = this.requireModelInterface("updateAssetBytes");
+        return fn({ userId: this.userId, ...args });
+    }
+    /** Load a persisted sketch (image document) owned by the current user. */
+    async getImageDocument(id) {
+        const fn = this.requireModelInterface("getImageDocument");
+        return fn({ userId: this.userId, id });
+    }
+    /** Create a persisted sketch (image document) owned by the current user. */
+    async createImageDocument(args) {
+        const fn = this.requireModelInterface("createImageDocument");
+        const document = await fn({ userId: this.userId, ...args });
+        return this.recordAppRunDocument("sketch", document);
+    }
+    /** Load a persisted timeline sequence owned by the current user. */
+    async getTimelineSequence(id) {
+        const fn = this.requireModelInterface("getTimelineSequence");
+        return fn({ userId: this.userId, id });
+    }
+    /** Create a persisted timeline sequence owned by the current user. */
+    async createTimelineSequence(sequence) {
+        const fn = this.requireModelInterface("createTimelineSequence");
+        const document = await fn({ userId: this.userId, sequence });
+        return this.recordAppRunDocument("timeline", document);
+    }
+    /** Replace a persisted timeline sequence's document. */
+    async updateTimelineSequence(id, sequence) {
+        const fn = this.requireModelInterface("updateTimelineSequence");
+        const document = await fn({ userId: this.userId, id, sequence });
+        return this.recordAppRunDocument("timeline", document);
+    }
+    /** Load a persisted script owned by the current user. */
+    async getScript(id) {
+        const fn = this.requireModelInterface("getScript");
+        return fn({ userId: this.userId, id });
+    }
+    /** Create a persisted script owned by the current user. */
+    async createScript(args) {
+        const fn = this.requireModelInterface("createScript");
+        const document = await fn({ userId: this.userId, ...args });
+        return this.recordAppRunDocument("script", document);
+    }
+    /** Replace a persisted script's document (and optional timeline link). */
+    async updateScript(id, args) {
+        const fn = this.requireModelInterface("updateScript");
+        const document = await fn({ userId: this.userId, id, ...args });
+        return this.recordAppRunDocument("script", document);
+    }
+    /** Load a persisted storyboard owned by the current user. */
+    async getStoryboard(id) {
+        const fn = this.requireModelInterface("getStoryboard");
+        return fn({ userId: this.userId, id });
+    }
+    /** The current user's storyboards, narrowed by the given filters. */
+    async listStoryboards(args = {}) {
+        const fn = this.requireModelInterface("listStoryboards");
+        return fn({ userId: this.userId, ...args });
+    }
+    /** The copy this user derived from a template for one recast mapping. */
+    async findRecastStoryboard(args) {
+        const fn = this.requireModelInterface("findRecastStoryboard");
+        return fn({ userId: this.userId, ...args });
+    }
+    /** Create a persisted storyboard owned by the current user. */
+    async createStoryboard(args) {
+        const fn = this.requireModelInterface("createStoryboard");
+        const document = await fn({ userId: this.userId, ...args });
+        return this.recordAppRunDocument("storyboard", document);
+    }
+    /** Replace a persisted storyboard's document (and optional timeline link). */
+    async updateStoryboard(id, args) {
+        const fn = this.requireModelInterface("updateStoryboard");
+        const document = await fn({ userId: this.userId, id, ...args });
+        return this.recordAppRunDocument("storyboard", document);
+    }
+    /** The current user's entity library, narrowed by the given filters. */
+    async listEntities(args = {}) {
+        const fn = this.requireModelInterface("listEntities");
+        return fn({ userId: this.userId, ...args });
+    }
+    /** Read one entity owned by the current user. */
+    async getEntity(id) {
+        const fn = this.requireModelInterface("getEntity");
+        return fn({ userId: this.userId, id });
+    }
+    /** Create or update one entity in the current user's library. */
+    async upsertEntity(args) {
+        const fn = this.requireModelInterface("upsertEntity");
+        return fn({ userId: this.userId, ...args });
     }
-    resolveSandboxFilePath(path) {
-        if (this.workspaceDir == null || this.workspaceDir === "") {
-            throw new Error("workspaceDir is required for sandbox file operations");
-        }
-        const workspaceRoot = resolve(this.workspaceDir);
+    /**
+     * Recursively list the non-folder assets in `folderId`, or `null` when the id
+     * is not a folder. Backed by the optional `listFolderAssets` model interface;
+     * returns `null` when that interface is not configured.
+     */
+    async listFolderAssets(folderId) {
+        const fn = this._modelInterfaces?.listFolderAssets;
+        if (!fn) {
+            return null;
+        }
+        return fn({ userId: this.userId, folderId });
+    }
+    /**
+     * Look up one owned asset's identity + metadata, or `null` when missing /
+     * not owned. Backed by the optional `getAssetInfo` model interface; returns
+     * `null` when that interface is not configured.
+     */
+    async getAssetInfo(assetId) {
+        const fn = this.modelInterfaces()?.getAssetInfo;
+        if (!fn) {
+            return null;
+        }
+        return fn({ userId: this.userId, assetId });
+    }
+    resolveSandboxFilePath(path) {
+        if (this.workspaceDir == null || this.workspaceDir === "") {
+            throw new Error("workspaceDir is required for sandbox file operations");
+        }
+        const workspaceRoot = resolve(this.workspaceDir);
         const normalizedPath = path.replaceAll("\\", "/");
         if ((isAbsolute(normalizedPath) || /^[A-Za-z]:\//.test(normalizedPath)) &&
             isWithinRoot(workspaceRoot, resolve(normalizedPath))) {
@@ -876,110 +1385,393 @@ export class ProcessingContext {
         if (!trimmed) {
             return [];
         }
-        const raw = trimmed.startsWith("asset://") ? trimmed.slice("asset://".length) : trimmed;
-        const primary = raw.split(/[/?#]/)[0];
+        // Strip a leading reference prefix down to the bare storage key. `asset://`
+        // is the ref scheme; `/api/storage/` (and its slash-less variant) is the
+        // browser-facing storage route that older messages / callers still carry —
+        // treating that whole path as the id probes a bogus key and builds a
+        // double-prefixed, percent-encoded HTTP url that 404s.
+        let raw = trimmed;
+        if (raw.startsWith("asset://")) {
+            raw = raw.slice("asset://".length);
+        }
+        else if (raw.startsWith("/api/storage/")) {
+            raw = raw.slice("/api/storage/".length);
+        }
+        else if (raw.startsWith("api/storage/")) {
+            raw = raw.slice("api/storage/".length);
+        }
+        // Preserve sub-paths: `asset://user-1/image.png` -> primary `user-1/image.png`,
+        // so storage keys with hierarchical layouts still resolve. Drop any
+        // `?query`/`#hash` before deriving the key.
+        const primary = raw.split(/[?#]/)[0];
         if (!primary) {
             return [];
         }
-        const withoutExt = primary.replace(/\.[^.]+$/, "");
+        // Strip the extension from the LAST path segment only. A `.` in an earlier
+        // segment (`folder.v2/img`) is part of the id, not an extension — slicing
+        // across `/` would yield a wrong-bytes candidate (`folder`).
+        const slash = primary.lastIndexOf("/");
+        const dir = slash >= 0 ? primary.slice(0, slash + 1) : "";
+        const lastSegment = slash >= 0 ? primary.slice(slash + 1) : primary;
+        const withoutExt = dir + lastSegment.replace(/\.[^.]+$/, "");
         return Array.from(new Set([primary, withoutExt].filter(Boolean)));
     }
-    async assetToSandbox(assetId, path) {
-        const outputPath = this.resolveSandboxFilePath(path);
-        const uriCandidates = new Set();
-        const idCandidates = this.parseAssetIdCandidates(assetId);
-        const trimmed = assetId.trim();
-        const resolutionAttempts = [];
-        if (trimmed.includes("://") && !trimmed.startsWith("asset://")) {
-            uriCandidates.add(trimmed);
+    /**
+     * The adapters an asset reference is looked up in. Assets live in the asset
+     * store; `this.storage` is the *temp* store on server paths. The asset
+     * adapter goes first and the temp adapter stays as the fallback so
+     * runtime-materialized refs still resolve.
+     */
+    assetAdapters() {
+        return [this.assetStorage, this.storage].filter((adapter, index, all) => adapter !== null && all.indexOf(adapter) === index);
+    }
+    /**
+     * Keys an asset id candidate may be stored under: `<userId>/<id>.<ext>`
+     * (uploads — the current owner-prefixed layout), `<id>.<ext>` (the flat
+     * legacy layout) and `assets/<id>` (runtime-materialized refs). The
+     * owner-prefixed key goes first: without it every reference misses all the
+     * exact lookups and falls through to the prefix listing, which degrades to
+     * `list("")` — a full recursive walk / whole-bucket `listObjectsV2` across
+     * every tenant, on every asset reference.
+     */
+    assetKeysFor(candidate) {
+        const keys = [candidate, `assets/${candidate}`];
+        if (this.userId && !candidate.startsWith(`${this.userId}/`)) {
+            keys.unshift(`${this.userId}/${candidate}`);
         }
-        for (const candidate of idCandidates) {
-            for (const prefix of ["memory://", "file://", "s3://"]) {
-                uriCandidates.add(`${prefix}${candidate}`);
-                uriCandidates.add(`${prefix}assets/${candidate}`);
+        return keys;
+    }
+    /**
+     * Prefixes to list, narrowest first, when no exact key matched.
+     *
+     * S3 treats `list(<owner>/<bareId>)` as a raw-string prefix match — bounded
+     * to a handful of entries. `list("")` is the last resort: it is a
+     * multi-thousand-object scan on production S3 backends, and on Supabase it
+     * lists only the bucket's immediate children — which under the
+     * owner-prefixed layout are folders, so it never sees an asset at all.
+     *
+     * The owner prefix is what makes this work for uploads. They are stored at
+     * `<userId>/<id>.<ext>`, and a ref that carries no extension (`asset://<id>`,
+     * or a bare `asset_id`) misses every exact-key lookup. Listing the owner's
+     * own folder finds it on every adapter: hierarchical ones
+     * (file/supabase/memory) list its children, and prefix-matching ones (S3)
+     * stay scoped to that one user.
+     */
+    assetListingPrefixes(bareId) {
+        const owner = this.userId;
+        return owner && !bareId.startsWith(`${owner}/`)
+            ? [`${owner}/${bareId}`, bareId, owner, ""]
+            : [bareId, ""];
+    }
+    /**
+     * Resolve an asset reference to a local file holding its bytes — the path
+     * counterpart of {@link resolveAssetBytes}, for callers such as ffmpeg that
+     * read a file in place instead of loading it into memory.
+     *
+     * Looks the reference up in the same adapters and under the same keys,
+     * including the extension-tolerant listing, and asks each adapter for
+     * `localPath`. That finds a managed file under the local asset root and an
+     * external asset's in-place file. Returns null when no adapter keeps a local
+     * file for it (object stores, the in-memory store, HTTP-only and
+     * `package://` references); the caller then falls back to
+     * {@link resolveAssetBytes}. The path is for reading only, and it is an
+     * asset-store path, not a workspace file.
+     */
+    async localPath(uri) {
+        const trimmed = uri.trim();
+        if (!trimmed || parsePackageAssetUri(trimmed)) {
+            return null;
+        }
+        const adapters = this.assetAdapters();
+        const tryLocalPath = async (adapter, storageUri) => {
+            try {
+                return await adapter.localPath(storageUri);
+            }
+            catch {
+                // An adapter that cannot answer is treated as having no local file.
+                return null;
+            }
+        };
+        if (trimmed.includes("://") && !trimmed.startsWith("asset://")) {
+            for (const adapter of adapters) {
+                const direct = await tryLocalPath(adapter, trimmed);
+                if (direct) {
+                    return direct;
+                }
             }
         }
-        let bytes = null;
-        if (this.storage) {
-            for (const uri of uriCandidates) {
+        const idCandidates = this.parseAssetIdCandidates(trimmed);
+        for (const adapter of adapters) {
+            for (const candidate of idCandidates) {
+                for (const key of this.assetKeysFor(candidate)) {
+                    const found = await tryLocalPath(adapter, adapter.uriForKey(key));
+                    if (found) {
+                        return found;
+                    }
+                }
+            }
+            const bareId = idCandidates[idCandidates.length - 1];
+            if (!bareId) {
+                continue;
+            }
+            for (const prefix of this.assetListingPrefixes(bareId)) {
                 try {
-                    const retrieved = await this.storage.retrieve(uri);
-                    if (retrieved) {
-                        bytes = retrieved;
-                        break;
+                    const listing = await adapter.list(prefix);
+                    const match = findListedAsset(listing.entries, bareId);
+                    const found = match ? await tryLocalPath(adapter, match.uri) : null;
+                    if (found) {
+                        return found;
+                    }
+                }
+                catch {
+                    // A listing that fails leaves the next, wider prefix to try.
+                }
+            }
+        }
+        return null;
+    }
+    /**
+     * Resolve an `asset://<id>[.ext]` reference (or bare id / storage URI) to its
+     * raw bytes.
+     *
+     * Server-uploaded assets are stored under the key `<id>.<ext>` and served at
+     * `/api/storage/<id>.<ext>`; runtime-materialized refs live under `assets/`.
+     * Resolution order: the in-process storage adapter (file/s3/supabase/memory),
+     * a prefix listing that tolerates extension mismatches, then an HTTP download
+     * from the server's `/api/storage` route. Returns the bytes plus an `attempts`
+     * trail for callers that build detailed errors; `null` bytes means unresolved.
+     */
+    async resolveAssetBytes(assetId, options) {
+        let idCandidates = this.parseAssetIdCandidates(assetId);
+        const trimmed = assetId.trim();
+        const attempts = [];
+        const adapters = this.assetAdapters();
+        const tryStorageUri = async (adapter, uri) => {
+            try {
+                const retrieved = await adapter.retrieve(uri);
+                if (retrieved) {
+                    return retrieved;
+                }
+                attempts.push(`storage miss: ${uri}`);
+            }
+            catch (error) {
+                attempts.push(`storage error: ${uri} (${error instanceof Error ? error.message : String(error)})`);
+            }
+            return null;
+        };
+        // Constant package assets (`package://<pkg>/<path>`) ship with the install
+        // — they have stable URIs and don't live in per-user storage. Resolve from
+        // the bundled package-assets dir when configured, else over HTTP from the
+        // server's package-asset route.
+        const packageRef = parsePackageAssetUri(trimmed);
+        if (packageRef) {
+            const root = this.environment.NODETOOL_PACKAGE_ASSETS_DIR ??
+                safeProcessEnv().NODETOOL_PACKAGE_ASSETS_DIR;
+            if (root) {
+                const segments = `${packageRef.packageName}/${packageRef.path}`
+                    .split("/")
+                    .filter((s) => s && s !== ".");
+                if (!segments.some((s) => s === "..")) {
+                    const filePath = resolve(join(root, ...segments));
+                    const within = !relative(resolve(root), filePath).startsWith("..");
+                    if (within) {
+                        try {
+                            const bytes = (await readFile(filePath));
+                            attempts.push(`package asset: ${filePath}`);
+                            return { bytes, attempts };
+                        }
+                        catch (error) {
+                            attempts.push(`package asset miss: ${filePath} (${error instanceof Error ? error.message : String(error)})`);
+                        }
                     }
-                    resolutionAttempts.push(`storage miss: ${uri}`);
+                }
+            }
+            const httpPath = packageAssetHttpPath(trimmed);
+            if (httpPath) {
+                let pkgBaseUrl = this.environment.NODETOOL_API_URL ??
+                    safeProcessEnv().NODETOOL_API_URL ??
+                    "http://localhost:7777";
+                while (pkgBaseUrl.endsWith("/")) {
+                    pkgBaseUrl = pkgBaseUrl.slice(0, -1);
+                }
+                const url = `${pkgBaseUrl}${httpPath}`;
+                try {
+                    const bytes = await this.downloadFile(url, {
+                        retry: { maxRetries: 1, backoffMs: 200 }
+                    });
+                    attempts.push(`downloaded: ${url}`);
+                    return { bytes, attempts };
                 }
                 catch (error) {
-                    resolutionAttempts.push(`storage error: ${uri} (${error instanceof Error ? error.message : String(error)})`);
+                    attempts.push(`package asset http miss: ${url} (${error instanceof Error ? error.message : String(error)})`);
                 }
             }
+            return { bytes: null, attempts };
         }
-        if (!bytes) {
-            let baseUrl = (this.environment.NODETOOL_API_URL ??
-                process.env.NODETOOL_API_URL ??
-                "http://localhost:7777");
-            while (baseUrl.endsWith("/")) {
-                baseUrl = baseUrl.slice(0, -1);
+        // A concrete storage URI / http URL handed in directly.
+        if (trimmed.includes("://") && !trimmed.startsWith("asset://")) {
+            for (const adapter of adapters) {
+                const direct = await tryStorageUri(adapter, trimmed);
+                if (direct) {
+                    return { bytes: direct, attempts };
+                }
             }
-            for (const candidate of idCandidates) {
+            if (/^https?:\/\//.test(trimmed)) {
                 try {
-                    const metaResponse = await this.httpGet(`${baseUrl}/api/assets/${encodeURIComponent(candidate)}`);
-                    const metadata = (await metaResponse.json());
-                    const getUrl = metadata.get_url;
-                    const uri = metadata.uri;
-                    if (typeof getUrl === "string" && getUrl) {
-                        const downloadUrl = getUrl.startsWith("/")
-                            ? `${baseUrl}${getUrl}`
-                            : getUrl;
-                        bytes = await this.downloadFile(downloadUrl, {
-                            retry: { maxRetries: 1, backoffMs: 200 }
-                        });
-                        resolutionAttempts.push(`downloaded: ${downloadUrl}`);
-                        break;
+                    const bytes = await this.downloadFile(trimmed, {
+                        retry: { maxRetries: 1, backoffMs: 200 }
+                    });
+                    attempts.push(`downloaded: ${trimmed}`);
+                    return { bytes, attempts };
+                }
+                catch (error) {
+                    attempts.push(`http error: ${trimmed} (${error instanceof Error ? error.message : String(error)})`);
+                }
+            }
+        }
+        // An asset row names the stored file exactly (`<owner>/<id>.<ext>`), so a
+        // reference that resolves to one is read by key and never by listing.
+        let assetRowFound = false;
+        if (this.hasModelInterface("getAssetInfo")) {
+            let asset = null;
+            const ownerPrefix = `${this.userId}/`;
+            const rowIdCandidates = new Set(idCandidates);
+            for (const candidate of idCandidates) {
+                if (candidate.startsWith(ownerPrefix)) {
+                    rowIdCandidates.add(candidate.slice(ownerPrefix.length));
+                }
+            }
+            for (const candidate of rowIdCandidates) {
+                asset = await this.getAssetInfo(candidate);
+                if (asset) {
+                    break;
+                }
+            }
+            if (asset) {
+                assetRowFound = true;
+                idCandidates = assetFileNameCandidates(asset.id, asset.content_type);
+            }
+            else if (options?.requireOwnedAsset) {
+                attempts.push(`asset unavailable or not owned: ${trimmed}`);
+                return { bytes: null, attempts };
+            }
+        }
+        for (const adapter of adapters) {
+            for (const candidate of idCandidates) {
+                for (const key of this.assetKeysFor(candidate)) {
+                    const bytes = await tryStorageUri(adapter, adapter.uriForKey(key));
+                    if (bytes) {
+                        return { bytes, attempts };
                     }
-                    if (typeof uri === "string" && this.storage) {
-                        const retrieved = await this.storage.retrieve(uri);
-                        if (retrieved) {
-                            bytes = retrieved;
-                            resolutionAttempts.push(`storage hit via metadata: ${uri}`);
-                            break;
+                }
+            }
+            // Extension-tolerant fallback: locate the stored file whose name starts
+            // with the id, since the URN extension may differ from the one on disk
+            // (e.g. jpeg vs jpg). Only reached when the exact-key lookups all miss
+            // and no asset row named the file.
+            const bareId = idCandidates[idCandidates.length - 1];
+            if (bareId && !assetRowFound) {
+                for (const prefix of this.assetListingPrefixes(bareId)) {
+                    try {
+                        const listing = await adapter.list(prefix);
+                        const match = findListedAsset(listing.entries, bareId);
+                        if (match) {
+                            const bytes = await tryStorageUri(adapter, match.uri);
+                            if (bytes) {
+                                return { bytes, attempts };
+                            }
                         }
-                        resolutionAttempts.push(`storage miss via metadata: ${uri}`);
+                    }
+                    catch (error) {
+                        attempts.push(`storage list error (${error instanceof Error ? error.message : String(error)})`);
                     }
                 }
-                catch (error) {
-                    resolutionAttempts.push(`api lookup error for ${candidate}: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+        // HTTP fallback: the server streams bytes at `/api/storage/<key>`.
+        let baseUrl = this.environment.NODETOOL_API_URL ??
+            safeProcessEnv().NODETOOL_API_URL ??
+            "http://localhost:7777";
+        while (baseUrl.endsWith("/")) {
+            baseUrl = baseUrl.slice(0, -1);
+        }
+        for (const candidate of idCandidates) {
+            if (!candidate.includes(".")) {
+                continue; // the storage route is keyed by filename (`<id>.<ext>`)
+            }
+            const url = `${baseUrl}/api/storage/${encodeURIComponent(candidate)}`;
+            try {
+                const bytes = await this.downloadFile(url, {
+                    retry: { maxRetries: 1, backoffMs: 200 }
+                });
+                attempts.push(`downloaded: ${url}`);
+                return { bytes, attempts };
+            }
+            catch (error) {
+                attempts.push(`http miss: ${url} (${error instanceof Error ? error.message : String(error)})`);
+            }
+        }
+        // Last resort: ask the asset API for metadata and follow its `get_url`.
+        // Handles bare ids (no extension, so the storage route can't be addressed
+        // directly) and backends that expose a single-asset metadata endpoint.
+        for (const candidate of idCandidates) {
+            try {
+                const metaResponse = await this.httpGet(`${baseUrl}/api/assets/${encodeURIComponent(candidate)}`);
+                const metadata = (await metaResponse.json());
+                const getUrl = metadata.get_url;
+                if (isNonEmptyString(getUrl)) {
+                    const downloadUrl = getUrl.startsWith("/")
+                        ? `${baseUrl}${getUrl}`
+                        : getUrl;
+                    const bytes = await this.downloadFile(downloadUrl, {
+                        retry: { maxRetries: 1, backoffMs: 200 }
+                    });
+                    attempts.push(`downloaded: ${downloadUrl}`);
+                    return { bytes, attempts };
                 }
+                const uri = metadata.uri;
+                if (isString(uri)) {
+                    for (const adapter of adapters) {
+                        const bytes = await tryStorageUri(adapter, uri);
+                        if (bytes) {
+                            return { bytes, attempts };
+                        }
+                    }
+                }
+            }
+            catch (error) {
+                attempts.push(`api lookup error for ${candidate}: ${error instanceof Error ? error.message : String(error)}`);
             }
         }
+        return { bytes: null, attempts };
+    }
+    async assetToSandbox(assetId, path) {
+        const outputPath = this.resolveSandboxFilePath(path);
+        const { bytes, attempts } = await this.resolveAssetBytes(assetId);
         if (!bytes) {
-            const details = resolutionAttempts.length > 0
-                ? ` Attempts: ${resolutionAttempts.join("; ")}`
-                : "";
+            const details = attempts.length > 0 ? ` Attempts: ${attempts.join("; ")}` : "";
             throw new Error(`Unable to resolve asset '${assetId}' to sandbox bytes.${details}`);
         }
         await mkdir(dirname(outputPath), { recursive: true });
         await writeFile(outputPath, bytes);
         return outputPath;
     }
-    async asset_to_sandbox(asset_id, path) {
-        return this.assetToSandbox(asset_id, path);
-    }
     async sandboxToAsset(path) {
         const filePath = this.resolveSandboxFilePath(path);
-        const bytes = await readFile(filePath);
+        const bytes = (await readFile(filePath));
         const contentType = ProcessingContext.guessMimeFromPath(filePath);
+        // SAFETY: the host's asset persistence answers with its own asset record;
+        // both reads below re-check the field before using it.
         const created = (await this.createAsset({
             name: basename(filePath),
             contentType,
             content: bytes
         }));
         const type = ProcessingContext.assetTypeForMime(contentType);
-        const assetId = typeof created.id === "string" ? created.id : null;
+        const assetId = isString(created.id) ? created.id : null;
         const uri = assetId !== null
             ? `asset://${assetId}`
-            : typeof created.uri === "string"
+            : isString(created.uri)
                 ? created.uri
                 : pathToFileURL(filePath).toString();
         return {
@@ -988,9 +1780,6 @@ export class ProcessingContext {
             asset_id: assetId
         };
     }
-    async sandbox_to_asset(path) {
-        return this.sandboxToAsset(path);
-    }
     async createMessage(req) {
         if (!req.thread_id) {
             throw new Error("Thread ID is required");
@@ -998,9 +1787,6 @@ export class ProcessingContext {
         const fn = this.requireModelInterface("createMessage");
         return fn({ userId: this.userId, req });
     }
-    async create_message(req) {
-        return this.createMessage(req);
-    }
     async getThreadMessages(threadId, limit = 10, startKey = null, reverse = false) {
         const fn = this.requireModelInterface("getMessages");
         return fn({
@@ -1011,9 +1797,10 @@ export class ProcessingContext {
             reverse
         });
     }
-    async get_messages(thread_id, limit = 10, start_key = null, reverse = false) {
-        return this.getThreadMessages(thread_id, limit, start_key, reverse);
-    }
+    // The four wrappers below and `normalizeOutputValue` are HOLDOUTs
+    // (anti-slop/no-unknown-returns): they rewrite an arbitrary workflow value —
+    // any node output, at any nesting depth — and NodeTool has no named union
+    // for that value domain.
     async assetsToDataUri(value) {
         return this.normalizeOutputValue(value, "data_uri");
     }
@@ -1029,8 +1816,8 @@ export class ProcessingContext {
     // -----------------------------------------------------------------------
     // Provider prediction pipeline
     // -----------------------------------------------------------------------
-    emitPrediction(status, req, id, data, error, startedAt) {
-        this.emit({
+    emitPrediction(status, req, id, data, error, startedAt, extra) {
+        const message = {
             type: "prediction",
             id,
             user_id: this.userId,
@@ -1038,20 +1825,233 @@ export class ProcessingContext {
             workflow_id: req.workflowId ?? this.workflowId ?? null,
             provider: req.provider,
             model: req.model,
+            capability: req.capability,
             status,
-            params: req.params ?? {},
+            // Redacted: bytes and data URLs become their length. The row stores
+            // this bag and every listener receives it.
+            params: redactGenerationParams(req.params),
             data: data ?? null,
             error: error ?? null,
-            duration: startedAt ? Date.now() - startedAt : null
-        });
+            duration: startedAt ? Date.now() - startedAt : null,
+            origin: extra?.origin ?? this.generationOrigin(req),
+            receipt: extra?.receipt ?? null
+        };
+        // Only a terminal message names assets; `running` has none to name.
+        if (extra?.asset_ids)
+            message.asset_ids = extra.asset_ids;
+        this.emit(message);
     }
     /**
-     * Resolve /api/storage/ URIs in message content to data URIs so providers
-     * can fetch them without needing a base URL.
+     * Who asked, defaulted from the context: a chat turn names its thread, a
+     * run names its job and node. A capability passes `surface` and its
+     * `tool_call_id` explicitly, the one id the context does not hold.
+     */
+    generationOrigin(req, override) {
+        const base = this.threadId
+            ? {
+                surface: "chat",
+                thread_id: this.threadId,
+                job_id: this.jobId || null,
+                node_id: req.nodeId ?? null
+            }
+            : {
+                surface: "workflow",
+                job_id: this.jobId || null,
+                node_id: req.nodeId ?? null
+            };
+        if (!override)
+            return base;
+        const merged = { ...base };
+        if (override.surface !== undefined)
+            merged.surface = override.surface;
+        if (override.thread_id !== undefined)
+            merged.thread_id = override.thread_id;
+        if (override.tool_call_id !== undefined)
+            merged.tool_call_id = override.tool_call_id;
+        if (override.request_id !== undefined)
+            merged.request_id = override.request_id;
+        if (override.job_id !== undefined)
+            merged.job_id = override.job_id;
+        if (override.node_id !== undefined)
+            merged.node_id = override.node_id;
+        return merged;
+    }
+    /**
+     * Retrieve raw bytes for a media URI referenced in message content. Handles
+     * the `asset://<id>` reference scheme (via {@link resolveAssetBytes}) as well
+     * as opaque storage URIs (memory/file/s3) via the storage adapter.
+     */
+    async retrieveMediaBytes(uri) {
+        // `/api/storage/<key>` (and its slash-less `api/storage/<key>` form) is the
+        // browser-facing route, not a storage-adapter uri — the InMemory/S3 adapters
+        // only accept `memory://`/`s3://`, so route it through resolveAssetBytes
+        // (which parses the key) like `asset://`.
+        if (uri.startsWith("asset://") ||
+            uri.startsWith("/api/storage/") ||
+            uri.startsWith("api/storage/")) {
+            const { bytes } = await this.resolveAssetBytes(uri);
+            return bytes;
+        }
+        for (const adapter of [this.assetStorage, this.storage]) {
+            if (!adapter)
+                continue;
+            const bytes = await adapter.retrieve(uri);
+            if (bytes)
+                return bytes;
+        }
+        return null;
+    }
+    /**
+     * Resolve non-data, non-http media URIs in message content to data URIs so
+     * providers can consume them directly. Covers `/api/storage/` and other
+     * storage URIs as well as the `asset://<id>` reference scheme (assets
+     * mentioned inline in a prompt). Text parts that contain `asset://<id>.<ext>`
+     * image / audio tokens are first split into proper blocks via
+     * {@link expandAssetReferences} so the same provider path handles chat
+     * surfaces (where the user typed / dropped a reference) and workflow node
+     * surfaces (where the agent node builds the message). Text document mentions
+     * (`asset://doc.md`, `.txt`, `.csv`, …) are inlined as their decoded
+     * contents in place of the token.
      */
     async resolveMessageMediaUris(messages) {
-        if (!this.storage)
-            return messages;
+        const IMAGE_MIME = {
+            png: "image/png",
+            jpg: "image/jpeg",
+            jpeg: "image/jpeg",
+            gif: "image/gif",
+            webp: "image/webp"
+        };
+        const AUDIO_MIME = {
+            mp3: "audio/mpeg",
+            wav: "audio/wav",
+            ogg: "audio/ogg",
+            m4a: "audio/mp4",
+            flac: "audio/flac"
+        };
+        const VIDEO_MIME = {
+            mp4: "video/mp4",
+            m4v: "video/mp4",
+            webm: "video/webm",
+            mov: "video/quicktime",
+            avi: "video/x-msvideo"
+        };
+        // Strict, anchored sanitizer for the URIs that may flow into the asset /
+        // storage retrieval path. Accept asset references, the browser-facing
+        // storage route, and URIs from configured storage adapters. External URLs
+        // and unrecognized schemes stay out of the storage adapter. `:` is allowed
+        // for named owner ids such as `projects/personal:<user_id>/assets/…`.
+        const RESOLVABLE_URI_RE = /^(?:asset:\/\/|\/?api\/storage\/|(?:memory|file|s3|supabase):\/\/)[A-Za-z0-9._~/%:-]+$/;
+        const isResolvableUri = (uri) => RESOLVABLE_URI_RE.test(uri);
+        // An `asset://` reference that cannot be dereferenced must not reach the
+        // provider: providers `fetch` a non-data URI, and the SSRF guard then
+        // rejects `asset://…` with "Refusing to fetch unsafe URL", which fails the
+        // whole turn on a message the user cannot fix. Replace the block with a
+        // note the model can act on instead — a stale attachment in the history
+        // must not break every later turn in the thread.
+        const unresolvedNote = (kind, uri) => ({
+            type: "text",
+            text: `[attached ${kind} could not be ${kind === "image" ? "shown" : "loaded"}: ${uri}]`
+        });
+        // A resolved block reaches the provider as a `data:` URI, which the model
+        // cannot pass to a tool. Emit the stored handle beside it so "make it like
+        // this" can become `edit_image({input_file: "asset://…"})` — only for the
+        // URIs `isResolvableUri` admits, never for a `data:` URI the caller already
+        // inlined.
+        const attachedNote = (kind, uri) => ({
+            type: "text",
+            text: `[attached ${kind} ${uri}]`
+        });
+        const resolvePart = async (part, 
+        // Parts split out of a text block already carry the literal token next
+        // to them (see `expandAssetReferences`), so a note there would repeat it.
+        fromText = false) => {
+            if (part.type === "image_url" &&
+                part.image.uri &&
+                isResolvableUri(part.image.uri)) {
+                const bytes = await this.retrieveMediaBytes(part.image.uri);
+                if (bytes) {
+                    const ext = part.image.uri.split(".").pop()?.toLowerCase() ?? "png";
+                    const mimeType = IMAGE_MIME[ext] ?? part.image.mimeType ?? "image/png";
+                    const b64 = Buffer.from(bytes).toString("base64");
+                    const block = {
+                        type: "image_url",
+                        image: { uri: `data:${mimeType};base64,${b64}`, mimeType }
+                    };
+                    return fromText
+                        ? [block]
+                        : [block, attachedNote("image", part.image.uri)];
+                }
+                return [unresolvedNote("image", part.image.uri)];
+            }
+            if (part.type === "audio" &&
+                part.audio.uri &&
+                isResolvableUri(part.audio.uri)) {
+                const bytes = await this.retrieveMediaBytes(part.audio.uri);
+                if (bytes) {
+                    const ext = part.audio.uri.split(".").pop()?.toLowerCase() ?? "mp3";
+                    const mimeType = AUDIO_MIME[ext] ?? part.audio.mimeType ?? "audio/mpeg";
+                    const b64 = Buffer.from(bytes).toString("base64");
+                    const block = {
+                        type: "audio",
+                        audio: { uri: `data:${mimeType};base64,${b64}`, mimeType }
+                    };
+                    return fromText
+                        ? [block]
+                        : [block, attachedNote("audio", part.audio.uri)];
+                }
+                return [unresolvedNote("audio", part.audio.uri)];
+            }
+            if (part.type === "video" &&
+                part.video.uri &&
+                isResolvableUri(part.video.uri)) {
+                const bytes = await this.retrieveMediaBytes(part.video.uri);
+                if (bytes) {
+                    const ext = part.video.uri.split(".").pop()?.toLowerCase() ?? "mp4";
+                    const mimeType = VIDEO_MIME[ext] ?? part.video.mimeType ?? "video/mp4";
+                    const b64 = Buffer.from(bytes).toString("base64");
+                    const block = {
+                        type: "video",
+                        video: { uri: `data:${mimeType};base64,${b64}`, mimeType }
+                    };
+                    return fromText
+                        ? [block]
+                        : [block, attachedNote("video", part.video.uri)];
+                }
+                return [unresolvedNote("video", part.video.uri)];
+            }
+            if (part.type === "text") {
+                // Entity mentions resolve first: each `entity://<id>` becomes the
+                // entity's name inline, a "Consistency references" line carrying its
+                // descriptor, and an `asset://` token for its reference image — which
+                // the asset pass below then turns into a real image block. Resolving
+                // here, per turn, is what makes a later rename or re-description
+                // reach every message that already mentions the entity.
+                const text = await expandEntityRefs(part.text, this, true);
+                if (!text.includes("asset://")) {
+                    return text === part.text ? [part] : [{ type: "text", text }];
+                }
+                // First split out image / audio mentions into their own blocks; what
+                // stays as text is then run through the document inliner so any
+                // .md/.txt/.csv mentions become their decoded contents. The image and
+                // audio blocks fall through to the URI-resolution branches above on a
+                // second pass so the provider receives data URIs.
+                const expanded = expandAssetReferences(text);
+                const out = [];
+                for (const sub of expanded) {
+                    if (sub.type === "text") {
+                        const inlined = await inlineTextAssetRefs(sub.text, this);
+                        if (inlined)
+                            out.push({ type: "text", text: inlined });
+                    }
+                    else {
+                        const resolved = await resolvePart(sub, true);
+                        out.push(...resolved);
+                    }
+                }
+                return out;
+            }
+            return [part];
+        };
         const resolved = [];
         for (const msg of messages) {
             if (!Array.isArray(msg.content)) {
@@ -1060,64 +2060,88 @@ export class ProcessingContext {
             }
             const parts = [];
             for (const part of msg.content) {
-                if (part.type === "image_url" &&
-                    part.image.uri &&
-                    !part.image.uri.startsWith("data:") &&
-                    !part.image.uri.startsWith("http")) {
-                    const bytes = await this.storage.retrieve(part.image.uri);
-                    if (bytes) {
-                        const ext = part.image.uri.split(".").pop()?.toLowerCase() ?? "png";
-                        const mime = {
-                            png: "image/png",
-                            jpg: "image/jpeg",
-                            jpeg: "image/jpeg",
-                            gif: "image/gif",
-                            webp: "image/webp"
-                        };
-                        const mimeType = mime[ext] ?? part.image.mimeType ?? "image/png";
-                        const b64 = Buffer.from(bytes).toString("base64");
-                        parts.push({
-                            type: "image_url",
-                            image: { uri: `data:${mimeType};base64,${b64}`, mimeType }
-                        });
-                        continue;
-                    }
+                parts.push(...(await resolvePart(part)));
+            }
+            resolved.push({ ...msg, content: parts });
+        }
+        return resolved;
+    }
+    async resolveRequiredImageEvidence(messages, required = []) {
+        const evidence = new Map();
+        const resolve = async (ref) => {
+            const identity = ref.uri?.startsWith("data:")
+                ? "inline image"
+                : ref.uri ?? ref.asset_id ?? "inline image";
+            const cached = ref.uri ? evidence.get(ref.uri) : undefined;
+            if (cached) {
+                return cached;
+            }
+            try {
+                const bytes = await loadMediaRefBytes(ref, this);
+                if (!bytes?.length) {
+                    throw new Error("no image bytes");
                 }
-                if (part.type === "audio" &&
-                    part.audio.uri &&
-                    !part.audio.uri.startsWith("data:") &&
-                    !part.audio.uri.startsWith("http")) {
-                    const bytes = await this.storage.retrieve(part.audio.uri);
-                    if (bytes) {
-                        const ext = part.audio.uri.split(".").pop()?.toLowerCase() ?? "mp3";
-                        const mime = {
-                            mp3: "audio/mpeg",
-                            wav: "audio/wav",
-                            ogg: "audio/ogg",
-                            m4a: "audio/mp4",
-                            flac: "audio/flac"
-                        };
-                        const mimeType = mime[ext] ?? part.audio.mimeType ?? "audio/mpeg";
-                        const b64 = Buffer.from(bytes).toString("base64");
-                        parts.push({
-                            type: "audio",
-                            audio: { uri: `data:${mimeType};base64,${b64}`, mimeType }
-                        });
-                        continue;
+                const mimeType = sniffImageMime(bytes);
+                if (!mimeType ||
+                    !["image/png", "image/jpeg", "image/webp", "image/gif"].includes(mimeType)) {
+                    throw new Error("unsupported image format");
+                }
+                await validateImageEvidence(bytes);
+                const block = {
+                    type: "image_url",
+                    image: {
+                        uri: `data:${mimeType};base64,${Buffer.from(bytes).toString("base64")}`,
+                        mimeType
                     }
+                };
+                if (ref.uri) {
+                    evidence.set(ref.uri, block);
                 }
-                parts.push(part);
+                return block;
             }
-            resolved.push({ ...msg, content: parts });
+            catch (error) {
+                throw new Error(`Required image evidence unavailable: ${identity} (${error instanceof Error ? error.message : String(error)})`);
+            }
+        };
+        for (const uri of required) {
+            await resolve({ type: "image", uri });
         }
-        return resolved;
+        const result = [];
+        for (const message of messages) {
+            if (!Array.isArray(message.content)) {
+                result.push(message);
+                continue;
+            }
+            const content = [];
+            let imageIndex = 0;
+            for (const part of message.content) {
+                if (part.type === "image_url") {
+                    imageIndex++;
+                    content.push(await resolve(part.image), {
+                        type: "text",
+                        text: `[required image ${part.image.uri && !part.image.uri.startsWith("data:")
+                            ? part.image.uri
+                            : `inline image ${imageIndex}`}]`
+                    });
+                }
+                else {
+                    content.push(part);
+                }
+            }
+            result.push({ ...message, content });
+        }
+        return result;
     }
     async dispatchCapability(provider, req) {
         const params = req.params ?? {};
         switch (req.capability) {
             case "generate_message":
                 return provider.generateMessageTraced({
-                    messages: await this.resolveMessageMediaUris(params.messages ?? []),
+                    messages: params.strict_image_evidence === true
+                        ? await this.resolveRequiredImageEvidence(params.messages ?? [], Array.isArray(params.required_images)
+                            ? params.required_images.filter(isString)
+                            : [])
+                        : await this.resolveMessageMediaUris(params.messages ?? []),
                     model: req.model,
                     tools: params.tools,
                     toolChoice: params.tool_choice,
@@ -1129,7 +2153,9 @@ export class ProcessingContext {
                 });
             case "text_to_image":
                 return provider.textToImage({
+                    signal: params.signal,
                     prompt: String(params.prompt ?? ""),
+                    entities: await coerceEntityList(params, this),
                     model: { id: req.model, name: req.model, provider: req.provider },
                     width: params.width,
                     height: params.height,
@@ -1139,9 +2165,25 @@ export class ProcessingContext {
                     quality: params.quality
                 });
             case "image_to_image":
-                return provider.imageToImage(params.image, {
+                return provider.imageToImage(coerceImageList(params), {
+                    signal: params.signal,
+                    prompt: String(params.prompt ?? ""),
+                    entities: await coerceEntityList(params, this),
+                    model: { id: req.model, name: req.model, provider: req.provider },
+                    negativePrompt: params.negative_prompt,
+                    targetWidth: params.target_width,
+                    targetHeight: params.target_height,
+                    aspectRatio: params.aspect_ratio,
+                    resolution: params.resolution,
+                    strength: params.strength,
+                    quality: params.quality
+                });
+            case "inpainting":
+                return provider.inpaint(coerceImageList(params), {
                     prompt: String(params.prompt ?? ""),
+                    entities: await coerceEntityList(params, this),
                     model: { id: req.model, name: req.model, provider: req.provider },
+                    mask: params.mask,
                     negativePrompt: params.negative_prompt,
                     targetWidth: params.target_width,
                     targetHeight: params.target_height,
@@ -1152,23 +2194,267 @@ export class ProcessingContext {
                 });
             case "text_to_video":
                 return provider.textToVideo({
+                    signal: params.signal,
                     prompt: String(params.prompt ?? ""),
+                    entities: await coerceEntityList(params, this),
                     model: { id: req.model, name: req.model, provider: req.provider },
                     negativePrompt: params.negative_prompt,
                     numFrames: params.num_frames,
                     durationSeconds: params.duration_seconds,
                     aspectRatio: params.aspect_ratio,
-                    resolution: params.resolution
+                    resolution: params.resolution,
+                    timeoutSeconds: params.timeout_seconds
                 });
             case "image_to_video":
-                return provider.imageToVideo(params.image, {
+                return provider.imageToVideo(firstNonEmptyByteList(coerceImageList(params)), {
+                    signal: params.signal,
                     prompt: params.prompt,
+                    entities: await coerceEntityList(params, this),
                     model: { id: req.model, name: req.model, provider: req.provider },
                     negativePrompt: params.negative_prompt,
                     numFrames: params.num_frames,
                     durationSeconds: params.duration_seconds,
                     aspectRatio: params.aspect_ratio,
-                    resolution: params.resolution
+                    resolution: params.resolution,
+                    timeoutSeconds: params.timeout_seconds
+                });
+            case "reference_to_video": {
+                const images = coerceByteList(params.reference_images);
+                const videos = coerceByteList(params.reference_videos);
+                if (images.length === 0 && videos.length === 0) {
+                    throw new Error("reference_to_video requires at least one reference image or video");
+                }
+                return provider.referenceToVideo({ images, videos }, {
+                    model: { id: req.model, name: req.model, provider: req.provider },
+                    prompt: isString(params.prompt) ? params.prompt : "",
+                    entities: await coerceEntityList(params, this),
+                    useReferenceVideoAudio: isBoolean(params.use_reference_video_audio)
+                        ? params.use_reference_video_audio
+                        : undefined,
+                    negativePrompt: isString(params.negative_prompt)
+                        ? params.negative_prompt
+                        : undefined,
+                    numFrames: isNumber(params.num_frames)
+                        ? params.num_frames
+                        : undefined,
+                    durationSeconds: isNumber(params.duration_seconds)
+                        ? params.duration_seconds
+                        : undefined,
+                    aspectRatio: isString(params.aspect_ratio)
+                        ? params.aspect_ratio
+                        : undefined,
+                    resolution: isString(params.resolution)
+                        ? params.resolution
+                        : undefined,
+                    timeoutSeconds: isNumber(params.timeout_seconds)
+                        ? params.timeout_seconds
+                        : undefined,
+                    signal: isAbortSignal(params.signal) ? params.signal : undefined
+                });
+            }
+            case "outpaint_image":
+                return provider.outpaintImage(coerceImageList(params), {
+                    signal: params.signal,
+                    prompt: params.prompt,
+                    entities: await coerceEntityList(params, this),
+                    model: { id: req.model, name: req.model, provider: req.provider },
+                    negativePrompt: params.negative_prompt,
+                    padding: coerceOutpaintPadding(params.padding),
+                    aspectRatio: params.aspect_ratio,
+                    seed: params.seed
+                });
+            case "upscale_image":
+                return provider.upscaleImage(params.image, {
+                    model: { id: req.model, name: req.model, provider: req.provider },
+                    scale: params.scale,
+                    prompt: params.prompt,
+                    creativity: params.creativity,
+                    seed: params.seed
+                });
+            case "remove_background":
+                return provider.removeBackground(params.image, {
+                    model: { id: req.model, name: req.model, provider: req.provider }
+                });
+            case "relight_image":
+                return provider.relightImage(params.image, {
+                    model: { id: req.model, name: req.model, provider: req.provider },
+                    prompt: params.prompt,
+                    negativePrompt: params.negative_prompt,
+                    seed: params.seed
+                });
+            case "segment_image":
+                return provider.segmentImage(params.image, {
+                    signal: params.signal,
+                    model: { id: req.model, name: req.model, provider: req.provider },
+                    prompt: params.prompt,
+                    points: params.points,
+                    box: params.box,
+                    maxMasks: params.max_masks,
+                    minConfidence: params.min_confidence
+                });
+            case "vectorize_image":
+                return provider.vectorizeImage(params.image, {
+                    model: { id: req.model, name: req.model, provider: req.provider }
+                });
+            case "estimate_depth":
+                return provider.estimateDepth(params.image, {
+                    model: { id: req.model, name: req.model, provider: req.provider },
+                    signal: isAbortSignal(params.signal) ? params.signal : this.signal
+                });
+            case "rerank":
+                return provider.rerank({
+                    model: req.model,
+                    query: isString(params.query) ? params.query : "",
+                    // Every entry stays, so result indices point into the caller's list.
+                    documents: Array.isArray(params.documents)
+                        ? params.documents.map((doc) => (isString(doc) ? doc : String(doc)))
+                        : [],
+                    topK: isNumber(params.top_k) ? params.top_k : undefined,
+                    signal: isAbortSignal(params.signal) ? params.signal : this.signal
+                });
+            case "track_object": {
+                const request = objectTrackingRequestSchema.parse(params);
+                if (!provider.getCapabilities().includes("track_object")) {
+                    throw new Error("The selected provider does not support object tracking.");
+                }
+                const signal = params.signal instanceof AbortSignal ? params.signal : this.signal;
+                signal.throwIfAborted();
+                const video = await loadMediaRefBytes({ type: "video", asset_id: request.sourceAssetId }, this);
+                if (!video?.byteLength) {
+                    throw new Error("The tracking source video could not be loaded.");
+                }
+                signal.throwIfAborted();
+                const output = await provider.trackObject(video, {
+                    ...request,
+                    model: req.model,
+                    signal
+                });
+                signal.throwIfAborted();
+                return parseObjectTrackingResult(output, request);
+            }
+            case "video_to_video": {
+                const signal = isAbortSignal(params.signal)
+                    ? params.signal
+                    : this.signal;
+                const referenceImages = coerceByteList(params.reference_images ?? params.referenceImages);
+                const referenceAssetIds = coerceStringList(params.reference_asset_ids ?? params.referenceAssetIds);
+                signal.throwIfAborted();
+                return provider.videoToVideo(params.video, {
+                    model: { id: req.model, name: req.model, provider: req.provider },
+                    prompt: params.prompt,
+                    referenceImages: referenceImages.length > 0 ? referenceImages : undefined,
+                    referenceAssetIds: referenceAssetIds.length > 0 ? referenceAssetIds : undefined,
+                    signal,
+                    entities: await coerceEntityList(params, this),
+                    negativePrompt: params.negative_prompt,
+                    strength: params.strength,
+                    durationSeconds: params.duration_seconds,
+                    resolution: params.resolution,
+                    seed: params.seed
+                });
+            }
+            case "video_to_audio": {
+                const source = isRecord(params.source)
+                    ? {
+                        assetId: params.source.assetId ?? params.source.asset_id,
+                        durationSeconds: params.source.durationSeconds ?? params.source.duration_seconds,
+                        startSeconds: params.source.startSeconds ?? params.source.start_seconds,
+                        endSeconds: params.source.endSeconds ?? params.source.end_seconds
+                    }
+                    : params.source;
+                const request = VideoToAudioRequest.parse({
+                    task: VIDEO_TO_AUDIO_TASK,
+                    model: {
+                        id: req.model,
+                        provider: req.provider,
+                        supportedTasks: [VIDEO_TO_AUDIO_TASK]
+                    },
+                    source,
+                    sceneContext: params.sceneContext ?? params.scene_context
+                });
+                const video = params.video instanceof Uint8Array
+                    ? params.video
+                    : await loadMediaRefBytes({ type: "video", asset_id: request.source.assetId }, this);
+                if (!video?.byteLength) {
+                    throw new Error("video_to_audio requires nonempty source video bytes");
+                }
+                return requestVideoToAudio(provider, video, request, {
+                    signal: params.signal
+                });
+            }
+            case "extend_video": {
+                if ((params.mode !== "start" && params.mode !== "end") ||
+                    typeof params.duration_seconds !== "number" ||
+                    !Number.isFinite(params.duration_seconds) ||
+                    params.duration_seconds <= 0) {
+                    throw new Error("extend_video requires start/end mode and positive duration_seconds");
+                }
+                return provider.extendVideo(params.video, {
+                    model: { id: req.model, name: req.model, provider: req.provider },
+                    prompt: typeof params.prompt === "string" ? params.prompt : "",
+                    mode: params.mode,
+                    durationSeconds: params.duration_seconds
+                });
+            }
+            case "upscale_video":
+                return provider.upscaleVideo(params.video, {
+                    signal: params.signal,
+                    model: { id: req.model, name: req.model, provider: req.provider },
+                    scale: params.scale,
+                    targetResolution: params.target_resolution,
+                    prompt: params.prompt,
+                    creativity: params.creativity,
+                    seed: params.seed,
+                    timeoutSeconds: params.timeout_seconds
+                });
+            case "interpolate_video":
+                return provider.interpolateVideo(params.video, {
+                    signal: params.signal,
+                    model: { id: req.model, name: req.model, provider: req.provider },
+                    targetFps: params.target_fps,
+                    factor: params.factor,
+                    seed: params.seed,
+                    timeoutSeconds: params.timeout_seconds
+                });
+            case "outpaint_video":
+                return provider.outpaintVideo(params.video, {
+                    signal: params.signal,
+                    model: { id: req.model, name: req.model, provider: req.provider },
+                    prompt: params.prompt,
+                    entities: await coerceEntityList(params, this),
+                    negativePrompt: params.negative_prompt,
+                    padding: coerceOutpaintPadding(params.padding),
+                    expandRatio: params.expand_ratio,
+                    aspectRatio: params.aspect_ratio,
+                    resolution: params.resolution,
+                    seed: params.seed,
+                    timeoutSeconds: params.timeout_seconds
+                });
+            case "lip_sync":
+                return provider.lipSync(params.video, {
+                    model: { id: req.model, name: req.model, provider: req.provider },
+                    audio: params.audio,
+                    seed: params.seed
+                });
+            case "text_to_music":
+                return provider.textToMusic({
+                    prompt: String(params.prompt ?? ""),
+                    model: { id: req.model, name: req.model, provider: req.provider },
+                    lyrics: params.lyrics,
+                    durationSeconds: params.duration_seconds,
+                    seed: params.seed,
+                    audioFormat: params.audioFormat,
+                    timeoutSeconds: params.timeout_seconds
+                });
+            case "audio_to_audio":
+                return provider.audioToAudio(params.audio, {
+                    model: { id: req.model, name: req.model, provider: req.provider },
+                    prompt: params.prompt,
+                    voice: params.voice,
+                    strength: params.strength,
+                    seed: params.seed,
+                    audioFormat: params.audioFormat,
+                    timeoutSeconds: params.timeout_seconds
                 });
             case "automatic_speech_recognition":
                 return provider.automaticSpeechRecognition({
@@ -1184,30 +2470,605 @@ export class ProcessingContext {
                     model: req.model,
                     dimensions: params.dimensions
                 });
+            case "text_to_3d":
+                return provider.textTo3D({
+                    model: model3dOf(params, req),
+                    prompt: String(params.prompt ?? ""),
+                    negativePrompt: params.negative_prompt ?? null,
+                    artStyle: params.art_style ?? null,
+                    outputFormat: params.output_format,
+                    seed: params.seed ?? null,
+                    timeoutSeconds: params.timeout_seconds ?? null,
+                    enableTextures: params.enable_textures
+                });
+            case "image_to_3d":
+                return provider.imageTo3D(coerceImageList(params)[0] ?? new Uint8Array(), {
+                    model: model3dOf(params, req),
+                    prompt: params.prompt ?? null,
+                    outputFormat: params.output_format,
+                    seed: params.seed ?? null,
+                    timeoutSeconds: params.timeout_seconds ?? null
+                });
             default:
                 throw new Error(`Capability '${req.capability}' requires streaming API`);
         }
     }
+    /**
+     * HOLDOUT (anti-slop/no-unknown-returns): the honest return type is
+     * {@link ProviderPredictionResult} (see {@link dispatchCapability}), but the
+     * node and capability call sites assert their own capability's result off it
+     * (`as Uint8Array`, `as number[][]`, …), and those assertions do not compile
+     * against the union. Typing it means editing every one of them. `text-nodes`
+     * is done — it parses each result with a predicate instead.
+     */
     async runProviderPrediction(req) {
-        const id = randomUUID();
+        return (await this.runGeneration(req)).output;
+    }
+    /**
+     * Run one generation: open the record, call the provider inside a receipt
+     * scope, persist what came back, close the record. Every terminal state is
+     * a message — `completed`, `failed`, `cancelled` — and the tracker turns
+     * those into the row. Design: docs/media-generation-tracking-design.md § 5.
+     */
+    async runGeneration(req) {
+        return this.runGenerationWith(req, (provider, signal) => {
+            if (!provider) {
+                throw new Error("Provider generation requires a provider.");
+            }
+            const dispatchReq = {
+                ...req,
+                params: { ...(req.params ?? {}), signal }
+            };
+            return this.retryContentFilterRefusal(req, () => this.dispatchCapability(provider, dispatchReq));
+        });
+    }
+    /**
+     * The generation envelope around an arbitrary provider call: the same
+     * record, receipt scope, persistence and terminal messages as
+     * {@link runGeneration}, for a caller whose call shape the capability
+     * switch has no case for — N images in one request, streamed PCM wrapped
+     * into a WAV. `call` receives the provider and the generation's abort
+     * signal; what it returns is the output, and its media buffers are what
+     * `persist` saves.
+     */
+    async runGenerationWith(req, call, opts) {
+        const id = req.id ?? randomUUID();
+        return withSpan("generation", { "generation.id": id, "generation.provider": req.provider, "generation.kind": req.capability }, async () => {
+            const startedAt = Date.now();
+            const origin = this.generationOrigin(req, req.origin);
+            const controller = new AbortController();
+            const signals = [controller.signal, this.signal];
+            if (req.signal)
+                signals.push(req.signal);
+            const signal = AbortSignal.any(signals);
+            const accept = opts?.onGenerationAccepted ??
+                this._generationLifecycle?.onGenerationAccepted;
+            const terminal = opts?.onGenerationTerminal ??
+                this._generationLifecycle?.onGenerationTerminal;
+            let durableAccepted = false;
+            let terminalAttempted = false;
+            try {
+                const accepted = await accept?.({ generationId: id, request: req });
+                if (accepted?.skipProvider) {
+                    throw new GenerationAlreadyAcceptedError(accepted.existingGenerationId ?? id);
+                }
+                durableAccepted = accepted?.durable === true;
+                generationRegistry.register(id, {
+                    userId: this.userId,
+                    abort: () => controller.abort(new Error("Generation cancelled"))
+                });
+                this.emitPrediction("running", req, id, null, undefined, startedAt, {
+                    origin
+                });
+                const provider = opts?.withoutProvider
+                    ? null
+                    : await this.getProvider(req.provider);
+                const { value: output, receipt: recorded, providerResult } = await runWithGenerationReceipt(() => call(provider, signal), {
+                    providerRequestOptions: accepted ?? undefined,
+                    onProviderRequestAccepted: opts?.onProviderRequestAccepted ??
+                        this._generationLifecycle?.onProviderRequestAccepted,
+                    onProviderRequestBound: opts?.onProviderRequestBound ??
+                        this._generationLifecycle?.onProviderRequestBound
+                });
+                const encoded = encodedAudioOf(output);
+                const persistedAssets = req.persist
+                    ? await this.persistGenerationBytes(id, req, encoded ? [encoded.data] : mediaBuffers(output), encoded?.mimeType)
+                    : [];
+                const assets = persistedAssets.filter((asset) => asset !== null);
+                let delivery;
+                if (opts?.finalizeOutput) {
+                    try {
+                        delivery = await opts.finalizeOutput(output, assets);
+                    }
+                    catch (error) {
+                        delivery = {
+                            status: "failed",
+                            error: error instanceof Error ? error.message : String(error)
+                        };
+                    }
+                }
+                const deliveryFields = {};
+                if (delivery) {
+                    deliveryFields.delivery = delivery;
+                }
+                const late = opts?.receiptAfterPersist?.() ?? null;
+                const receipt = late || recorded ? { ...(recorded ?? {}), ...(late ?? {}) } : null;
+                const assetIds = assets
+                    .map((asset) => asset.asset_id)
+                    .filter((assetId) => typeof assetId === "string");
+                const durableAssetIds = persistedAssets.map((asset) => asset?.asset_id ?? null);
+                try {
+                    terminalAttempted = true;
+                    await terminal?.({
+                        generationId: id,
+                        request: req,
+                        status: "completed",
+                        output: providerResult ?? output,
+                        receipt,
+                        assetIds: durableAssetIds,
+                        ...deliveryFields
+                    });
+                }
+                catch (terminalError) {
+                    this.emit({
+                        type: "log_update",
+                        node_id: req.nodeId ?? "",
+                        node_name: req.nodeId ?? "",
+                        workflow_id: req.workflowId ?? this.workflowId ?? null,
+                        severity: "warning",
+                        content: `Generation ${id} completed but durable finalization will be recovered: ${terminalError instanceof Error ? terminalError.message : String(terminalError)}`
+                    });
+                }
+                this.emitPrediction("completed", req, id, delivery ? { delivery } : generationResultData(req.capability, output), undefined, startedAt, { origin, asset_ids: assetIds, receipt });
+                generationRegistry.settle(id, {
+                    status: "completed",
+                    asset_ids: assetIds,
+                    receipt,
+                    ...deliveryFields
+                });
+                return {
+                    id,
+                    output,
+                    assets,
+                    receipt,
+                    duration_ms: Date.now() - startedAt,
+                    ...deliveryFields
+                };
+            }
+            catch (error) {
+                const cause = error instanceof GenerationScopeError ? error.cause : error;
+                const receipt = error instanceof GenerationScopeError ? error.receipt : null;
+                const providerResult = error instanceof GenerationScopeError
+                    ? error.providerResult
+                    : undefined;
+                const message = cause instanceof Error ? cause.message : String(cause);
+                if (cause instanceof GenerationAlreadyAcceptedError) {
+                    throw cause;
+                }
+                const status = signal.aborted
+                    ? durableAccepted
+                        ? "running"
+                        : "cancelled"
+                    : durableAccepted && !isAuthoritativeProviderTerminalError(cause)
+                        ? "running"
+                        : "failed";
+                if (durableAccepted && !terminalAttempted) {
+                    try {
+                        terminalAttempted = true;
+                        await terminal?.({
+                            generationId: id,
+                            request: req,
+                            status: isAuthoritativeProviderTerminalError(cause)
+                                ? "failed"
+                                : "recovering",
+                            output: providerResult,
+                            error: message,
+                            receipt,
+                            assetIds: []
+                        });
+                    }
+                    catch {
+                        // The provider observation remains authoritative. The durable row
+                        // can be finalized by the recovery worker.
+                    }
+                }
+                if (this.appRunContext && !durableAccepted && !terminalAttempted) {
+                    try {
+                        terminalAttempted = true;
+                        await terminal?.({
+                            generationId: id,
+                            request: req,
+                            status: signal.aborted ? "cancelled" : "failed",
+                            error: message,
+                            receipt,
+                            assetIds: []
+                        });
+                    }
+                    catch {
+                        // Preserve the provider failure; the live ledger can retry its write.
+                    }
+                }
+                this.emitPrediction(status, req, id, null, message, startedAt, {
+                    origin,
+                    receipt
+                });
+                generationRegistry.settle(id, {
+                    status,
+                    error: message,
+                    asset_ids: [],
+                    receipt
+                });
+                throw cause;
+            }
+        });
+    }
+    /**
+     * Save a generation's media output as assets, stamping the generation id
+     * on each. Bytes only: a segmentation result, a transcript or an embedding
+     * is a result and stays on the message.
+     */
+    async persistGenerationBytes(id, req, buffers, mimeOverride) {
+        if (!this.hasModelInterface("createAsset")) {
+            return buffers.map(() => null);
+        }
+        const assets = [];
+        // The prompt and settings ride on the asset, not only on the ledger row:
+        // the row has its own retention and lives in another table, while the
+        // asset is what somebody opens weeks later to make a variant.
+        const provenance = buildAssetGenerationMetadata({
+            prompt: req.params?.prompt,
+            provider: req.provider,
+            model: req.model,
+            capability: req.capability,
+            params: req.params
+        });
+        const metadata = { generation_id: id, ...provenance };
+        for (const [index, bytes] of buffers.entries()) {
+            const mime = req.persist?.mime ??
+                mimeOverride ??
+                generationMime(req.capability, bytes);
+            const ext = extForGenerationMime(mime);
+            const name = buffers.length === 1 || !req.persist?.name
+                ? (req.persist?.name ?? `${req.capability}-${startedName(id)}.${ext}`)
+                : req.persist.name.replace(/(\.[a-z0-9]+)?$/i, `-${index + 1}$1`);
+            try {
+                const created = await this.createAsset({
+                    name,
+                    contentType: mime,
+                    content: bytes,
+                    parentId: req.persist?.parentId ?? null,
+                    nodeId: req.nodeId ?? null,
+                    metadata: { ...metadata }
+                });
+                const assetId = isRecord(created) && typeof created.id === "string"
+                    ? created.id
+                    : null;
+                if (!assetId) {
+                    assets.push(null);
+                    continue;
+                }
+                assets.push({
+                    type: assetRefType(mime),
+                    uri: `asset://${assetId}.${ext}`,
+                    asset_id: assetId,
+                    metadata: { ...metadata }
+                });
+            }
+            catch (error) {
+                assets.push(null);
+                // The generation happened and was billed; a failed save must not turn
+                // it into a failed generation. The caller still gets the bytes.
+                this.emit({
+                    type: "log_update",
+                    node_id: req.nodeId ?? "",
+                    node_name: req.nodeId ?? "",
+                    workflow_id: req.workflowId ?? this.workflowId ?? null,
+                    severity: "warning",
+                    content: `Generated ${mime} could not be saved as an asset: ${error instanceof Error ? error.message : String(error)}`
+                });
+            }
+        }
+        return assets;
+    }
+    /**
+     * Run a prediction, retrying a content-filter refusal a bounded number of
+     * times. The filter is non-deterministic — Veo refused one shot of a
+     * five-shot trailer on an ordinary cinematic prompt and passed the same
+     * prompt on retry — and a refused take is not charged, so the cheap answer to
+     * a refusal is to ask again before failing the node that asked.
+     *
+     * A refusal that survives the retries is rethrown as-is, so the kernel can
+     * still drop the item rather than the run.
+     */
+    async retryContentFilterRefusal(req, attemptFn) {
+        for (let attempt = 1;; attempt++) {
+            try {
+                return await attemptFn();
+            }
+            catch (error) {
+                if (!isContentFilterRefusal(error) ||
+                    attempt > CONTENT_FILTER_MAX_RETRIES) {
+                    throw error;
+                }
+                const message = error instanceof Error ? error.message : String(error);
+                this.emit({
+                    type: "log_update",
+                    node_id: req.nodeId ?? "",
+                    node_name: req.nodeId ?? "",
+                    workflow_id: req.workflowId ?? this.workflowId ?? null,
+                    severity: "warning",
+                    content: `${req.provider}/${req.model} content-filtered this request (attempt ${attempt} of ${CONTENT_FILTER_MAX_RETRIES + 1}); retrying. ${message}`
+                });
+                await waitForRetry(contentFilterRetryDelayMs(attempt), this.signal);
+            }
+        }
+    }
+    /**
+     * Whether a provider streams raw PCM for text-to-speech. When false, the
+     * caller should use {@link textToSpeechEncoded} (the provider returns an
+     * encoded audio file rather than samples).
+     */
+    async providerSupportsStreamingTTS(providerId) {
+        const provider = await this.getProvider(providerId);
+        return provider.supportsStreamingTextToSpeech();
+    }
+    /**
+     * Whether a provider's chat API accepts a `video` content part. Lets a
+     * caller refuse before paying for a prediction that the provider would
+     * reject while resolving the message, which is where the video bytes have
+     * already been fetched and inlined.
+     */
+    async providerSupportsVideoInput(providerId) {
+        const provider = await this.getProvider(providerId);
+        return provider.supportsVideoInput;
+    }
+    /**
+     * Generate speech as an encoded audio file (mp3/wav/…). Returns null when the
+     * provider doesn't implement the encoded path. Used for providers (FAL, KIE,
+     * ElevenLabs) that return audio files instead of streaming PCM.
+     */
+    async textToSpeechEncoded(req) {
+        return this.runEncodedGeneration(req, async (provider) => {
+            const params = req.params ?? {};
+            return provider.textToSpeechEncoded({
+                text: String(params.text ?? ""),
+                model: req.model,
+                voice: params.voice,
+                speed: params.speed,
+                referenceAudio: params.reference_audio,
+                referenceText: params.reference_text,
+                language: params.language,
+                instructions: params.instructions,
+                audioFormat: params.audioFormat
+            });
+        });
+    }
+    /**
+     * The generation lifecycle for the encoded-audio paths: same id on every
+     * message, origin on `running`, the receipt on the terminal message,
+     * `cancelled` on abort. These return an encoded result rather than bytes,
+     * so the caller persists.
+     */
+    async runEncodedGeneration(req, call) {
+        const id = req.id ?? randomUUID();
         const startedAt = Date.now();
-        this.emitPrediction("running", req, id, null, undefined, startedAt);
+        const origin = this.generationOrigin(req, req.origin);
+        const controller = new AbortController();
+        const signals = [controller.signal, this.signal];
+        if (req.signal)
+            signals.push(req.signal);
+        const signal = AbortSignal.any(signals);
+        const accept = this._generationLifecycle?.onGenerationAccepted;
+        const terminal = this._generationLifecycle?.onGenerationTerminal;
+        let durableAccepted = false;
+        let terminalAttempted = false;
+        let accepted;
         try {
+            accepted = await accept?.({ generationId: id, request: req });
+            if (accepted?.skipProvider) {
+                throw new GenerationAlreadyAcceptedError(accepted.existingGenerationId ?? id);
+            }
+            durableAccepted = accepted?.durable === true;
+            generationRegistry.register(id, {
+                userId: this.userId,
+                abort: () => controller.abort(new Error("Generation cancelled"))
+            });
+            this.emitPrediction("running", req, id, null, undefined, startedAt, {
+                origin
+            });
             const provider = await this.getProvider(req.provider);
-            const output = await this.dispatchCapability(provider, req);
-            this.emitPrediction("completed", req, id, output, undefined, startedAt);
-            return output;
+            const { value, receipt, providerResult } = await runWithGenerationReceipt(() => call(provider, signal), {
+                providerRequestOptions: accepted ?? undefined,
+                onProviderRequestAccepted: this._generationLifecycle?.onProviderRequestAccepted,
+                onProviderRequestBound: this._generationLifecycle?.onProviderRequestBound
+            });
+            const encoded = encodedAudioOf(value);
+            const persistedAssets = req.persist && encoded
+                ? await this.persistGenerationBytes(id, req, [encoded.data], encoded.mimeType)
+                : [];
+            const assets = persistedAssets.filter((asset) => asset !== null);
+            const assetIds = assets
+                .map((asset) => asset.asset_id)
+                .filter((assetId) => typeof assetId === "string");
+            const durableAssetIds = persistedAssets.map((asset) => asset?.asset_id ?? null);
+            try {
+                terminalAttempted = true;
+                await terminal?.({
+                    generationId: id,
+                    request: req,
+                    status: "completed",
+                    output: providerResult ?? value,
+                    receipt,
+                    assetIds: durableAssetIds
+                });
+            }
+            catch {
+                // Provider success remains authoritative even when durable finalization
+                // needs a later recovery attempt.
+            }
+            this.emitPrediction("completed", req, id, null, undefined, startedAt, {
+                origin,
+                asset_ids: assetIds,
+                receipt
+            });
+            generationRegistry.settle(id, {
+                status: "completed",
+                asset_ids: assetIds,
+                receipt
+            });
+            return value;
         }
         catch (error) {
-            const message = error instanceof Error ? error.message : String(error);
-            this.emitPrediction("failed", req, id, null, message, startedAt);
-            throw error;
+            const cause = error instanceof GenerationScopeError ? error.cause : error;
+            const receipt = error instanceof GenerationScopeError ? error.receipt : null;
+            const providerResult = error instanceof GenerationScopeError
+                ? error.providerResult
+                : undefined;
+            const message = cause instanceof Error ? cause.message : String(cause);
+            if (cause instanceof GenerationAlreadyAcceptedError) {
+                throw cause;
+            }
+            const status = signal.aborted
+                ? durableAccepted
+                    ? "running"
+                    : "cancelled"
+                : durableAccepted && !isAuthoritativeProviderTerminalError(cause)
+                    ? "running"
+                    : "failed";
+            if (durableAccepted && !terminalAttempted) {
+                try {
+                    terminalAttempted = true;
+                    await terminal?.({
+                        generationId: id,
+                        request: req,
+                        status: isAuthoritativeProviderTerminalError(cause)
+                            ? "failed"
+                            : "recovering",
+                        output: providerResult,
+                        error: message,
+                        receipt,
+                        assetIds: []
+                    });
+                }
+                catch {
+                    // Keep the provider outcome visible while durable finalization is
+                    // retried by the recovery worker.
+                }
+            }
+            if (this.appRunContext && !durableAccepted && !terminalAttempted) {
+                try {
+                    terminalAttempted = true;
+                    await terminal?.({
+                        generationId: id,
+                        request: req,
+                        status: signal.aborted ? "cancelled" : "failed",
+                        error: message,
+                        receipt,
+                        assetIds: []
+                    });
+                }
+                catch {
+                    // Preserve the provider failure; the live ledger can retry its write.
+                }
+            }
+            this.emitPrediction(status, req, id, null, message, startedAt, {
+                origin,
+                receipt
+            });
+            generationRegistry.settle(id, {
+                status,
+                error: message,
+                asset_ids: [],
+                receipt
+            });
+            throw cause;
         }
     }
+    /**
+     * Generate music as an encoded audio file (mp3/wav/flac). Mirrors
+     * {@link textToSpeechEncoded} for the `text_to_music` capability — the
+     * provider returns a fully-encoded audio file rather than streaming PCM.
+     */
+    async textToMusic(req) {
+        return this.runEncodedGeneration(req, async (provider) => {
+            const params = req.params ?? {};
+            return provider.textToMusic({
+                prompt: String(params.prompt ?? ""),
+                model: { id: req.model, name: req.model, provider: req.provider },
+                lyrics: params.lyrics,
+                durationSeconds: params.duration_seconds,
+                seed: params.seed,
+                audioFormat: params.audioFormat,
+                timeoutSeconds: params.timeout_seconds
+            });
+        });
+    }
+    /**
+     * Rewrite a recording into another one. Mirrors {@link textToMusic} for the
+     * `audio_to_audio` capability: the provider hands back an encoded file, and
+     * the source bytes ride in `params.audio`.
+     */
+    async audioToAudio(req) {
+        return this.runEncodedGeneration(req, async (provider) => {
+            const params = req.params ?? {};
+            const audio = params.audio;
+            if (!(audio instanceof Uint8Array) || audio.length === 0) {
+                throw new Error("audio_to_audio needs source audio bytes");
+            }
+            return provider.audioToAudio(audio, {
+                model: { id: req.model, name: req.model, provider: req.provider },
+                prompt: params.prompt,
+                voice: params.voice,
+                strength: params.strength,
+                seed: params.seed,
+                audioFormat: params.audioFormat,
+                timeoutSeconds: params.timeout_seconds
+            });
+        });
+    }
+    /**
+     * Generate an audio result conditioned on a captured video window and scene
+     * context. The encoded-audio lifecycle persists the result without touching
+     * the source video's soundtrack or timeline placement.
+     */
+    async videoToAudio(req) {
+        return this.runEncodedGeneration(req, async (provider, signal) => {
+            const params = req.params ?? {};
+            const source = isRecord(params.source)
+                ? {
+                    assetId: params.source.assetId ?? params.source.asset_id,
+                    durationSeconds: params.source.durationSeconds ?? params.source.duration_seconds,
+                    startSeconds: params.source.startSeconds ?? params.source.start_seconds,
+                    endSeconds: params.source.endSeconds ?? params.source.end_seconds
+                }
+                : params.source;
+            const request = VideoToAudioRequest.parse({
+                task: VIDEO_TO_AUDIO_TASK,
+                model: {
+                    id: req.model,
+                    provider: req.provider,
+                    supportedTasks: [VIDEO_TO_AUDIO_TASK]
+                },
+                source,
+                sceneContext: params.sceneContext ?? params.scene_context
+            });
+            const video = params.video instanceof Uint8Array
+                ? params.video
+                : await loadMediaRefBytes({ type: "video", asset_id: request.source.assetId }, this);
+            if (!video?.byteLength) {
+                throw new Error("video_to_audio requires nonempty source video bytes");
+            }
+            return requestVideoToAudio(provider, video, request, { signal });
+        });
+    }
     async *streamProviderPrediction(req) {
-        const id = randomUUID();
+        const id = req.id ?? randomUUID();
         const startedAt = Date.now();
-        this.emitPrediction("running", req, id, null, undefined, startedAt);
+        const origin = this.generationOrigin(req, req.origin);
+        this.emitPrediction("running", req, id, null, undefined, startedAt, {
+            origin
+        });
+        let terminalStatusEmitted = false;
         try {
             const provider = await this.getProvider(req.provider);
             const params = req.params ?? {};
@@ -1232,7 +3093,11 @@ export class ProcessingContext {
                     text: String(params.text ?? ""),
                     model: req.model,
                     voice: params.voice,
-                    speed: params.speed
+                    speed: params.speed,
+                    referenceAudio: params.reference_audio,
+                    referenceText: params.reference_text,
+                    language: params.language,
+                    instructions: params.instructions
                 })) {
                     yield item;
                 }
@@ -1240,13 +3105,29 @@ export class ProcessingContext {
             else {
                 throw new Error(`Capability '${req.capability}' is not streamable`);
             }
-            this.emitPrediction("completed", req, id, null, undefined, startedAt);
+            this.emitPrediction("completed", req, id, null, undefined, startedAt, {
+                origin,
+                asset_ids: []
+            });
+            terminalStatusEmitted = true;
         }
         catch (error) {
             const message = error instanceof Error ? error.message : String(error);
-            this.emitPrediction("failed", req, id, null, message, startedAt);
+            const status = this.signal.aborted || req.signal?.aborted ? "cancelled" : "failed";
+            this.emitPrediction(status, req, id, null, message, startedAt, {
+                origin
+            });
+            terminalStatusEmitted = true;
             throw error;
         }
+        finally {
+            if (!terminalStatusEmitted) {
+                this.emitPrediction("completed", req, id, null, undefined, startedAt, {
+                    origin,
+                    asset_ids: []
+                });
+            }
+        }
     }
     // -----------------------------------------------------------------------
     // Output normalization
@@ -1257,6 +3138,8 @@ export class ProcessingContext {
      *
      * Port of sanitize_memory_uris_for_client() from types.py.
      */
+    // HOLDOUT (anti-slop/no-unknown-returns): same value domain as
+    // `normalizeOutputValue` — an arbitrary node output, rewritten in place.
     static sanitizeForClient(value) {
         if (value === null || value === undefined)
             return value;
@@ -1266,11 +3149,11 @@ export class ProcessingContext {
         if (Array.isArray(value)) {
             return value.map((v) => ProcessingContext.sanitizeForClient(v));
         }
-        if (typeof value !== "object")
+        if (!isRecord(value))
             return value;
         const obj = value;
         const uri = obj.uri;
-        const isAssetLike = "type" in obj && typeof uri === "string";
+        const isAssetLike = "type" in obj && isString(uri);
         if (isAssetLike && uri.startsWith("memory://")) {
             const sanitized = { ...obj };
             if (sanitized.data !== undefined && sanitized.data !== null) {
@@ -1320,13 +3203,22 @@ export class ProcessingContext {
         const v = value;
         return "type" in v && ("uri" in v || "data" in v || "asset_id" in v);
     }
-    static guessAssetMime(asset) {
-        const explicit = asset.mime_type ?? asset.content_type;
-        if (typeof explicit === "string" && explicit)
-            return explicit;
+    /**
+     * `mimeType` comes first because it is the field `ImageRef` declares — this
+     * used to read only `mime_type`, which nothing sets, so a node's sniffed
+     * `image/webp` was discarded and every provider's WebP stored as PNG.
+     * `image/unknown` is `image-nodes` reporting its own sniff found nothing, so
+     * it counts as undeclared here rather than as a type to forward.
+     */
+    static guessAssetMime(asset, bytes) {
+        const declared = asset.mimeType ?? asset.mime_type ?? asset.content_type;
+        if (isNonEmptyString(declared) && declared !== "image/unknown") {
+            return declared;
+        }
         const type = String(asset.type ?? "").toLowerCase();
-        if (type.includes("image"))
-            return "image/png";
+        if (type.includes("image")) {
+            return (bytes && sniffImageMime(bytes)) ?? "image/png";
+        }
         if (type.includes("audio"))
             return "audio/wav";
         if (type.includes("video"))
@@ -1338,10 +3230,10 @@ export class ProcessingContext {
         return "application/octet-stream";
     }
     static extForMime(mime) {
+        const imageExt = extForImageMime(mime);
+        if (imageExt)
+            return imageExt;
         const map = {
-            "image/png": "png",
-            "image/jpeg": "jpg",
-            "image/webp": "webp",
             "audio/wav": "wav",
             "audio/mpeg": "mp3",
             "video/mp4": "mp4",
@@ -1359,33 +3251,87 @@ export class ProcessingContext {
         if (Array.isArray(data) && data.every((v) => Number.isInteger(v))) {
             return new Uint8Array(data);
         }
-        if (typeof data === "string") {
+        if (isString(data)) {
             return Uint8Array.from(Buffer.from(data, "base64"));
         }
         return null;
     }
+    static isClientFetchableResolvedAssetUri(sourceUri, resolvedUri) {
+        return (resolvedUri.startsWith("/api/storage/") ||
+            resolvedUri.startsWith("api/storage/") ||
+            (/^(memory|file|s3|supabase):\/\//.test(sourceUri) &&
+                resolvedUri !== sourceUri &&
+                /^https?:\/\//.test(resolvedUri)));
+    }
     async getAssetBytes(asset) {
         const decoded = ProcessingContext.decodeAssetData(asset.data);
         if (decoded)
             return decoded;
         const uri = asset.uri;
-        if (typeof uri !== "string" || !this.storage)
-            return null;
-        return this.storage.retrieve(uri);
+        if (isString(uri) && this.storage) {
+            const stored = await this.storage.retrieve(uri);
+            if (stored)
+                return stored;
+        }
+        if (isString(uri) &&
+            (uri.startsWith("asset://") ||
+                uri.startsWith("/api/storage/") ||
+                uri.startsWith("api/storage/"))) {
+            const { bytes } = await this.resolveAssetBytes(uri);
+            if (bytes)
+                return bytes;
+        }
+        // No usable uri but an asset_id is present: resolve directly by id.
+        // resolveAssetBytes has its own HTTP fallback, so this works even without a
+        // storage adapter (which the early `!this.storage` return used to preclude).
+        const assetId = asset.asset_id;
+        if (isNonEmptyString(assetId)) {
+            const { bytes } = await this.resolveAssetBytes(`asset://${assetId}`);
+            if (bytes)
+                return bytes;
+        }
+        return null;
     }
-    async materializeAsset(asset, mode) {
-        if (mode === "python" || mode === "raw") {
-            return asset;
+    async materializeAsset(rawAsset, mode) {
+        if (mode === "native" || mode === "raw") {
+            // In-process consumers handle the raw asset as-is (incl. raw RGBA).
+            return rawAsset;
+        }
+        // A fetchable reference with no inline bytes is already materialized for
+        // an HTTP client. Reuse it instead of downloading the asset into this
+        // process and writing an identical second temp object. This is especially
+        // important for SDK pass-through workflows: their large input was already
+        // uploaded once and should not be copied again on output.
+        if (mode === "temp_url") {
+            const uri = isString(rawAsset.uri) ? rawAsset.uri : "";
+            const hasInlineBytes = ProcessingContext.decodeAssetData(rawAsset.data) !== null;
+            const isStorageRoute = uri.startsWith("/api/storage/") || uri.startsWith("api/storage/");
+            const isAdapterUri = /^(file|s3|supabase):\/\//.test(uri);
+            if (uri && !hasInlineBytes && (isStorageRoute || isAdapterUri)) {
+                const resolvedUri = this._tempUrlResolver
+                    ? await this._tempUrlResolver(uri)
+                    : uri;
+                if (ProcessingContext.isClientFetchableResolvedAssetUri(uri, resolvedUri)) {
+                    return {
+                        ...rawAsset,
+                        uri: resolvedUri,
+                        data: undefined
+                    };
+                }
+            }
         }
+        // Raw in-flight RGBA → encode to PNG up front so every downstream mode
+        // treats it as an ordinary image (correct mime, extension, and bytes).
+        const asset = (await encodeRawImageRef(rawAsset));
         const bytes = await this.getAssetBytes(asset);
         if (!bytes)
             return asset;
-        const mime = ProcessingContext.guessAssetMime(asset);
+        const mime = ProcessingContext.guessAssetMime(asset, bytes);
         if (mode === "data_uri") {
-            const encoded = Buffer.from(bytes).toString("base64");
+            const base64 = Buffer.from(bytes).toString("base64");
             return {
                 ...asset,
-                uri: `data:${mime};base64,${encoded}`
+                uri: `data:${mime};base64,${base64}`
             };
         }
         if (mode === "storage_url") {
@@ -1404,12 +3350,9 @@ export class ProcessingContext {
                 return asset;
             const key = `temp/${randomUUID()}.${ProcessingContext.extForMime(mime)}`;
             const storedUri = await this.storage.store(key, bytes, mime);
-            const resolvedUri = this._tempUrlResolver
-                ? await this._tempUrlResolver(storedUri)
-                : storedUri;
             return {
                 ...asset,
-                uri: resolvedUri,
+                uri: await this.resolveTempUrl(storedUri),
                 data: undefined
             };
         }
@@ -1417,6 +3360,10 @@ export class ProcessingContext {
             if (!this.workspaceDir) {
                 throw new Error("workspace_dir is required for workspace asset output");
             }
+            // Imported here rather than at module scope: this module also loads in
+            // browser / Edge runtimes, and `@nodetool-ai/storage` reaches `node:fs`.
+            // Only this branch, which already requires a workspace directory, needs it.
+            const { FileStorageAdapter } = await import("@nodetool-ai/storage");
             const workspaceAssets = new FileStorageAdapter(resolveWorkspacePath(this.workspaceDir, "assets"));
             const key = `${randomUUID()}.${ProcessingContext.extForMime(mime)}`;
             const uri = await workspaceAssets.store(key, bytes, mime);
@@ -1432,6 +3379,9 @@ export class ProcessingContext {
      * Recursively normalize workflow outputs, materializing asset-like values
      * according to the selected output mode.
      */
+    // HOLDOUT (anti-slop/no-unknown-returns): the input and the result are an
+    // arbitrary workflow value; naming that domain is a bigger change than a
+    // typing pass.
     async normalizeOutputValue(value, mode = this.assetOutputMode) {
         if (value === null || value === undefined)
             return value;
@@ -1442,9 +3392,27 @@ export class ProcessingContext {
             return Promise.all(value.map((item) => this.normalizeOutputValue(item, mode)));
         }
         if (ProcessingContext.isAssetLike(value)) {
-            return this.materializeAsset(value, mode);
+            let byMode = this._normalizedOutputAssets.get(value);
+            if (!byMode) {
+                byMode = new Map();
+                this._normalizedOutputAssets.set(value, byMode);
+            }
+            let normalized = byMode.get(mode);
+            if (!normalized) {
+                normalized = this.materializeAsset(value, mode);
+                byMode.set(mode, normalized);
+            }
+            try {
+                return await normalized;
+            }
+            catch (error) {
+                // A transient storage failure must remain retryable.
+                if (byMode.get(mode) === normalized)
+                    byMode.delete(mode);
+                throw error;
+            }
         }
-        if (typeof value === "object") {
+        if (isRecord(value)) {
             const entries = Object.entries(value);
             const normalized = await Promise.all(entries.map(async ([k, v]) => [k, await this.normalizeOutputValue(v, mode)]));
             return Object.fromEntries(normalized);
@@ -1452,4 +3420,155 @@ export class ProcessingContext {
         return value;
     }
 }
+/**
+ * The media resolver to hand `BaseProvider.generateLoop`, or undefined when
+ * this context cannot dereference one.
+ *
+ * `view_image` answers with an `asset://` reference and the loop turns it into
+ * pixels for the one request that needs them, so every host that drives a tool
+ * loop passes this. A partial context — a test double, a host object built
+ * from a subset of the interface — has no method to call, and the loop then
+ * sends the reference through untouched rather than throwing mid-turn.
+ */
+export function mediaResolverFor(context) {
+    if (!context || !isCallable(context.resolveMessageMediaUris))
+        return undefined;
+    return (messages) => context.resolveMessageMediaUris(messages);
+}
+// ---------------------------------------------------------------------------
+// Generation seam helpers
+// ---------------------------------------------------------------------------
+/**
+ * The 3D model a request names: the full `Model3D` the node resolved (with
+ * its supported tasks and formats) when it passed one, else the minimal ref.
+ */
+function model3dOf(params, req) {
+    const given = params.model;
+    if (isRecord(given) &&
+        typeof given.id === "string" &&
+        typeof given.provider === "string") {
+        return given;
+    }
+    return {
+        id: req.model,
+        name: req.model,
+        provider: req.provider
+    };
+}
+/** The media buffers a capability result carries, if any. */
+function mediaBuffers(output) {
+    if (output instanceof Uint8Array)
+        return [output];
+    if (Array.isArray(output) &&
+        output.length > 0 &&
+        output.every((item) => item instanceof Uint8Array)) {
+        return output;
+    }
+    return [];
+}
+/** An encoded-audio result (`{data, mimeType}`), or null for anything else. */
+function encodedAudioOf(value) {
+    if (!isRecord(value))
+        return null;
+    const data = value.data;
+    if (!(data instanceof Uint8Array) || data.length === 0)
+        return null;
+    const mimeType = value.mimeType;
+    return {
+        data,
+        mimeType: typeof mimeType === "string" ? mimeType : undefined
+    };
+}
+/** What a `completed` prediction message carries as `data`: never bytes. */
+function generationResultData(capability, output) {
+    if (output instanceof Uint8Array)
+        return null;
+    if (encodedAudioOf(output))
+        return null;
+    if (Array.isArray(output)) {
+        if (output.every((item) => item instanceof Uint8Array)) {
+            return { count: output.length };
+        }
+        if (capability === "segment_image") {
+            return output.map((item) => {
+                if (!isRecord(item))
+                    return item;
+                const { mask: _mask, ...rest } = item;
+                return rest;
+            });
+        }
+        if (capability === "generate_embedding") {
+            const first = output[0];
+            return {
+                count: output.length,
+                dimensions: Array.isArray(first) ? first.length : null
+            };
+        }
+        return { count: output.length };
+    }
+    return output ?? null;
+}
+const VIDEO_CAPABILITIES = new Set([
+    "text_to_video",
+    "image_to_video",
+    "reference_to_video",
+    "video_to_video",
+    "extend_video",
+    "lip_sync"
+]);
+const AUDIO_CAPABILITIES = new Set([
+    "text_to_speech",
+    "text_to_music",
+    "audio_to_audio",
+    "video_to_audio"
+]);
+const MODEL3D_CAPABILITIES = new Set([
+    "text_to_3d",
+    "image_to_3d"
+]);
+/** The MIME a generation's bytes carry when the caller stated none. */
+function generationMime(capability, bytes) {
+    if (VIDEO_CAPABILITIES.has(capability))
+        return "video/mp4";
+    if (AUDIO_CAPABILITIES.has(capability))
+        return "audio/mpeg";
+    if (MODEL3D_CAPABILITIES.has(capability))
+        return "model/gltf-binary";
+    if (capability === "vectorize_image")
+        return "image/svg+xml";
+    return sniffImageMime(bytes) ?? "image/png";
+}
+const GENERATION_MIME_EXT = {
+    "video/mp4": "mp4",
+    "video/webm": "webm",
+    "audio/mpeg": "mp3",
+    "audio/mp3": "mp3",
+    "audio/wav": "wav",
+    "audio/x-wav": "wav",
+    "audio/flac": "flac",
+    "audio/ogg": "ogg",
+    "model/gltf-binary": "glb",
+    "model/gltf+json": "gltf",
+    "image/svg+xml": "svg"
+};
+function extForGenerationMime(mime) {
+    if (mime.startsWith("image/") && mime !== "image/svg+xml") {
+        return extForImageMime(mime) ?? "bin";
+    }
+    return GENERATION_MIME_EXT[mime] ?? "bin";
+}
+function assetRefType(mime) {
+    if (mime.startsWith("image/"))
+        return "image";
+    if (mime.startsWith("video/"))
+        return "video";
+    if (mime.startsWith("audio/"))
+        return "audio";
+    return "asset";
+}
+/** A short, sortable name fragment for an unnamed generation asset. */
+function startedName(id) {
+    const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+    return `${stamp}-${id.slice(0, 8)}`;
+}
 //# sourceMappingURL=context.js.map