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

package/dist/context.d.ts

@@ -9,13 +9,40 @@
  *   - Output normalization (sanitize memory URIs, etc.).
  *   - Asset handling with pluggable storage adapters.
  */
-import type { AssetRef, ProcessingMessage } from "@nodetool-ai/protocol";
+import type { AssetRef, Entity, EntityKind, EntitySource, GenerationOrigin, GenerationReceipt, ProcessingMessage, ProviderCost } from "@nodetool-ai/protocol";
+import { AgentMemory } from "./agent-memory.js";
+import { VariableChannel } from "./variable-channel.js";
+import { type GenerationProviderRequestOptions, type GenerationReceiptScopeOptions } from "./generation-receipt.js";
+import type { StorageAdapter } from "@nodetool-ai/storage";
+import type { Workspace } from "./workspace.js";
+/**
+ * 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 declare const ACTIVE_MODEL_CONTEXT_KEY = "active_agent_model";
+/** The value stored under {@link ACTIVE_MODEL_CONTEXT_KEY}. */
+export interface ActiveModelSelection {
+    provider: string;
+    model: string;
+}
 import type { BaseProvider } from "./providers/base-provider.js";
-import type { ProviderStreamItem } from "./providers/types.js";
+import type { EncodedAudioResult, Message, ProviderStreamItem } from "./providers/types.js";
 import type { NodeExecutor } from "./node-executor.js";
+import { type SandboxModuleCatalog } from "./sandbox-module-catalog.js";
+export type { SandboxModuleCatalog } from "./sandbox-module-catalog.js";
+/**
+ * A key/value cache for node results.
+ *
+ * One instance holds the results of many different nodes, so the value type
+ * belongs to the key, not to the cache: each caller names the type it stored
+ * under that key.
+ */
 export interface CacheAdapter {
-    get(key: string): Promise<unknown | undefined>;
-    set(key: string, value: unknown, ttlSeconds?: number): Promise<void>;
+    get<TValue>(key: string): Promise<TValue | undefined>;
+    set<TValue>(key: string, value: TValue, ttlSeconds?: number): Promise<void>;
     has(key: string): Promise<boolean>;
     delete(key: string): Promise<void>;
 }
@@ -24,21 +51,50 @@ export interface CacheAdapter {
  */
 export declare class MemoryCache implements CacheAdapter {
     private _store;
-    get(key: string): Promise<unknown | undefined>;
-    set(key: string, value: unknown, ttlSeconds?: number): Promise<void>;
+    get<TValue>(key: string): Promise<TValue | undefined>;
+    set<TValue>(key: string, value: TValue, ttlSeconds?: number): Promise<void>;
     has(key: string): Promise<boolean>;
     delete(key: string): Promise<void>;
 }
-export interface StorageAdapter {
-    /** Store an asset and return a URI. */
-    store(key: string, data: Uint8Array, contentType?: string): Promise<string>;
-    /** Retrieve an asset by URI. */
-    retrieve(uri: string): Promise<Uint8Array | null>;
-    /** Check if an asset exists. */
-    exists(uri: string): Promise<boolean>;
-}
-export type AssetOutputMode = "python" | "data_uri" | "temp_url" | "storage_url" | "workspace" | "raw";
-export type ProviderCapability = "generate_message" | "generate_messages" | "text_to_image" | "image_to_image" | "text_to_video" | "image_to_video" | "text_to_speech" | "automatic_speech_recognition" | "generate_embedding";
+/**
+ * The storage contract lives in `@nodetool-ai/storage`; it is re-exported here
+ * so `@nodetool-ai/runtime/context` — the browser/Edge entry point — keeps
+ * naming it without pulling that package's Node-only implementations in.
+ */
+export type { StorageAdapter, StorageEntry, StorageListResult, StorageStat } from "@nodetool-ai/storage";
+/**
+ * Controls how asset-like values (ImageRef / AudioRef / VideoRef) are
+ * materialized when {@link ProcessingContext.normalizeOutputValue} runs.
+ *
+ * Pick the mode by where the consumer lives:
+ * - `native`: in-process JS/TS code that knows how to handle the live
+ *   object as-is (DSL, tests, kernel-internal handoffs). Inline `data`
+ *   bytes stay attached.
+ * - `data_uri`: anything that renders a `data:image/png;base64,...` URI
+ *   inline (markdown, simple HTML).
+ * - `temp_url`: HTTP-fetching client over a short-lived URL — bytes are
+ *   uploaded to the temp storage adapter and `data` is dropped.
+ * - `storage_url`: same as `temp_url` but persistent storage.
+ * - `workspace`: write the bytes to a file inside `workspaceDir` and
+ *   return that file URI.
+ * - `raw`: keep bytes embedded in the asset's `data` field.
+ *
+ * NOTE: this used to be called `"python"` (mirroring the Python enum,
+ * where it accurately meant "Python-native object"). The rename to
+ * `"native"` makes the contract language-agnostic and matches what the
+ * mode actually does in the TS runtime.
+ */
+export type AssetOutputMode = "native" | "data_uri" | "temp_url" | "storage_url" | "workspace" | "raw";
+export type ProviderCapability = "generate_message" | "generate_messages" | "text_to_image" | "image_to_image" | "inpainting" | "outpaint_image" | "upscale_image" | "remove_background" | "relight_image" | "segment_image" | "vectorize_image" | "text_to_video" | "image_to_video" | "reference_to_video" | "video_to_video" | "extend_video" | "upscale_video" | "interpolate_video" | "outpaint_video" | "lip_sync" | "text_to_speech" | "text_to_music" | "audio_to_audio" | "video_to_audio" | "automatic_speech_recognition" | "generate_embedding" | "text_to_3d" | "image_to_3d" | "render_model3d"
+/** A timeline 3D clip rendered to video through Blender (design §D6). */
+ | "bake_model3d_clip"
+/**
+ * Subject/object tracking through a clip's source (P0 AI Video, Phase 2):
+ * an initial box plus a direction in, samples of the subject's position out
+ * — the async half of the `track_object` capability
+ * (`timeline-track-object.ts`).
+ */
+ | "track_object";
 export type ProviderPredictionRequest = {
     provider: string;
     capability: ProviderCapability;
@@ -47,6 +103,89 @@ export type ProviderPredictionRequest = {
     workflowId?: string | null;
     params?: Record<string, unknown>;
 };
+/**
+ * A generation: one provider call that produces media, tracked from before
+ * the call to its terminal state (docs/media-generation-tracking-design.md).
+ */
+export interface GenerationRequest extends ProviderPredictionRequest {
+    /**
+     * The generation id, when the caller minted it. A background caller needs
+     * the id before the call settles; everyone else lets the seam mint one.
+     */
+    id?: string;
+    /** Who asked. Fields left unset default from the context (§5.1). */
+    origin?: Partial<GenerationOrigin>;
+    /**
+     * Save the result as an asset before `completed` is emitted, so the row and
+     * the asset name each other. Needs the `createAsset` model interface; a host
+     * without one gets the bytes back and `assets: []`.
+     */
+    persist?: {
+        name?: string;
+        mime?: string;
+        parentId?: string | null;
+    };
+    /** Caller-side cancellation, chained with `cancel_generation`'s. */
+    signal?: AbortSignal;
+    /** Optional destination attachment intent retained for durable recovery. */
+    destination?: {
+        document_id?: string | null;
+        target_type: string;
+        target_id: string;
+        selected?: boolean;
+    };
+}
+export interface GenerationResult<T = ProviderPredictionResult> {
+    /** The row id and the message id: one identity end to end. */
+    id: string;
+    output: T;
+    /** Assets the seam persisted; empty when `persist` was unset or unavailable. */
+    assets: AssetRef[];
+    receipt: GenerationReceipt | null;
+    duration_ms: number;
+}
+/** Raised by a durable host when an idempotent request is already owned. */
+export declare class GenerationAlreadyAcceptedError extends Error {
+    readonly generationId: string;
+    constructor(generationId: string);
+}
+export interface GenerationRunOptions {
+    /** A receipt known only after persistence finishes. */
+    receiptAfterPersist?: () => Partial<GenerationReceipt> | null;
+    /** A host-local generation, such as a Blender render, has no provider. */
+    withoutProvider?: true;
+    /**
+     * Durable host acceptance. When provided, this completes before the first
+     * provider call, including the paid queue POST. Without it the run is
+     * explicitly ephemeral and only the in-memory receipt is available.
+     */
+    onGenerationAccepted?: (input: {
+        readonly generationId: string;
+        readonly request: GenerationRequest;
+    }) => void | GenerationProviderRequestOptions | Promise<void | GenerationProviderRequestOptions>;
+    /** Persist the terminal provider outcome after the live result is decoded. */
+    onGenerationTerminal?: (input: {
+        readonly generationId: string;
+        readonly request: GenerationRequest;
+        readonly status: "completed" | "failed" | "cancelled" | "recovering";
+        readonly output?: unknown;
+        readonly error?: string;
+        readonly receipt: GenerationReceipt | null;
+        /** Positional media asset ids. Null preserves a failed save's index. */
+        readonly assetIds: readonly (string | null)[];
+    }) => void | Promise<void>;
+    /** Awaitable host hooks at the provider queue acceptance/binding boundary. */
+    onProviderRequestAccepted?: GenerationReceiptScopeOptions["onProviderRequestAccepted"];
+    onProviderRequestBound?: GenerationReceiptScopeOptions["onProviderRequestBound"];
+}
+/** Host-owned durable lifecycle callbacks injected into a context. */
+export type GenerationLifecycleHooks = Pick<GenerationRunOptions, "onGenerationAccepted" | "onProviderRequestAccepted" | "onProviderRequestBound" | "onGenerationTerminal">;
+/**
+ * What a provider prediction answers with: the result of whichever capability
+ * the request selected, as {@link ProcessingContext.dispatchCapability} routes
+ * it.
+ */
+export type ProviderPredictionResult = Awaited<ReturnType<BaseProvider["generateMessageTraced" | "textToImage" | "imageToImage" | "inpaint" | "outpaintImage" | "textToVideo" | "imageToVideo" | "referenceToVideo" | "upscaleImage" | "removeBackground" | "relightImage" | "segmentImage" | "vectorizeImage" | "videoToVideo" | "trackObject" | "extendVideo" | "upscaleVideo" | "interpolateVideo" | "outpaintVideo" | "lipSync" | "textToMusic" | "audioToAudio" | "videoToAudio" | "automaticSpeechRecognition" | "generateEmbedding" | "textTo3D" | "imageTo3D"]>>;
 export type HttpRetryOptions = {
     maxRetries?: number;
     backoffMs?: number;
@@ -75,22 +214,116 @@ export interface AssetCreateParamsLike {
     userId: string;
     workflowId: string | null;
     jobId: string;
+    projectId?: string | null;
     name: string;
     contentType: string;
     content: Uint8Array;
     parentId?: string | null;
     nodeId?: string | null;
+    /** Stored on the asset row; the generation seam stamps `generation_id`. */
+    metadata?: Record<string, unknown> | null;
+}
+/** A non-folder asset surfaced when listing a folder's contents. */
+export interface FolderAssetEntry {
+    id: string;
+    content_type: string;
+    name: string;
+}
+/** An asset's identity + metadata, as surfaced by {@link ProcessingContext.getAssetInfo}. */
+export interface AssetInfoEntry {
+    id: string;
+    content_type: string;
+    name: string;
+    metadata: Record<string, unknown> | null;
+}
+/**
+ * An executable tool the run's owner injects into the context for agent nodes
+ * to pick up by name. Structurally satisfied by the agent system's `Tool` base
+ * class, which lives in a package `runtime` cannot depend on.
+ */
+export interface InjectedTool {
+    name: string;
+    description?: string;
+    inputSchema?: Record<string, unknown>;
+    /**
+     * HOLDOUT (anti-slop/no-unknown-returns): this contract is satisfied
+     * structurally by `Tool` in `@nodetool-ai/agents`, whose `process` returns
+     * `Promise<unknown>`; narrowing here would stop every tool from fitting.
+     */
+    process: (context: ProcessingContext, params: Record<string, unknown>) => Promise<unknown>;
+    /**
+     * Preferred entry point when present: strips reserved fields and coerces
+     * params against the tool's schema before dispatching to `process`.
+     */
+    execute?: (context: ProcessingContext, params: Record<string, unknown>, options?: {
+        toolCallId?: string;
+    }) => Promise<unknown>;
+}
+/**
+ * A record the host's persistence layer answers with.
+ *
+ * The row and response types live in `@nodetool-ai/models`, which sits above
+ * `runtime`, so the port names the field every caller reads — the record's
+ * identity — and each caller re-reads the document fields it knows how to
+ * interpret.
+ */
+export interface PersistedRecordLike {
+    id: string;
 }
 export interface ProcessingContextModelInterfaces {
+    /** Read a non-secret setting owned by the current user. */
+    getSetting?: (args: {
+        userId: string;
+        key: string;
+    }) => Promise<string | null>;
     getJob?: (args: {
         userId: string;
         jobId: string;
-    }) => Promise<unknown | null>;
+    }) => Promise<PersistedRecordLike | null>;
+    /**
+     * HOLDOUT (anti-slop/no-unknown-returns): narrowing this to the created
+     * record's shape breaks the `as Record<string, unknown>` assertions on the
+     * result in `image-nodes` and `audio-nodes` — an interface without an index
+     * signature is not comparable to that type. Typing it honestly means editing
+     * those call sites too.
+     */
     createAsset?: (args: AssetCreateParamsLike) => Promise<unknown>;
+    /**
+     * Replace an existing asset's bytes in place, keeping its id. Returns `null`
+     * when the asset does not exist or is not owned by the user.
+     *
+     * An editing loop needs this: creating a new asset per save would give the
+     * caller a different id after every edit, and the handles it already handed
+     * out would point at a stale version.
+     */
+    updateAssetBytes?: (args: {
+        userId: string;
+        assetId: string;
+        content: Uint8Array;
+        contentType?: string;
+        name?: string;
+    }) => Promise<AssetInfoEntry | null>;
+    /**
+     * Recursively list the non-folder assets contained in `folderId`. Returns
+     * `null` when the id is not a folder (or does not exist) so callers can tell
+     * "not a folder" apart from "empty folder" (`[]`).
+     */
+    listFolderAssets?: (args: {
+        userId: string;
+        folderId: string;
+    }) => Promise<FolderAssetEntry[] | null>;
+    /**
+     * Look up one owned asset's identity + metadata (no bytes). Returns `null`
+     * when the asset does not exist or is not owned by the user.
+     */
+    getAssetInfo?: (args: {
+        userId: string;
+        assetId: string;
+    }) => Promise<AssetInfoEntry | null>;
     createMessage?: (args: {
         userId: string;
         req: MessageCreateRequestLike;
-    }) => Promise<unknown>;
+    }) => Promise<PersistedRecordLike>;
     getMessages?: (args: {
         userId: string;
         threadId: string;
@@ -98,65 +331,162 @@ export interface ProcessingContextModelInterfaces {
         startKey?: string | null;
         reverse?: boolean;
     }) => Promise<ThreadMessagesResultLike>;
+    /** Load a persisted sketch (image document) by id; null when missing or not owned. */
+    getImageDocument?: (args: {
+        userId: string;
+        id: string;
+    }) => Promise<PersistedRecordLike | null>;
+    /** Create a persisted sketch (image document); returns the created document response. */
+    createImageDocument?: (args: {
+        userId: string;
+        name: string;
+        projectId?: string;
+        width: number;
+        height: number;
+        document: unknown;
+    }) => Promise<PersistedRecordLike>;
+    /** Load a persisted timeline sequence by id; null when missing or not owned. */
+    getTimelineSequence?: (args: {
+        userId: string;
+        id: string;
+    }) => Promise<PersistedRecordLike | null>;
+    /** Create a persisted timeline sequence from a full sequence document. */
+    createTimelineSequence?: (args: {
+        userId: string;
+        sequence: unknown;
+    }) => Promise<PersistedRecordLike>;
+    /** Replace a persisted timeline sequence's document; null when missing or not owned. */
+    updateTimelineSequence?: (args: {
+        userId: string;
+        id: string;
+        sequence: unknown;
+    }) => Promise<PersistedRecordLike | null>;
+    /** Load a persisted script by id; null when missing or not owned. */
+    getScript?: (args: {
+        userId: string;
+        id: string;
+    }) => Promise<PersistedRecordLike | null>;
+    /** Create a persisted script from a name + document. */
+    createScript?: (args: {
+        userId: string;
+        name?: string;
+        projectId?: string;
+        document: unknown;
+    }) => Promise<PersistedRecordLike>;
+    /** Replace a persisted script's document (and optional timeline link); null when missing or not owned. */
+    updateScript?: (args: {
+        userId: string;
+        id: string;
+        document?: unknown;
+        timelineId?: string | null;
+        baseUpdatedAt?: string;
+    }) => Promise<PersistedRecordLike | null>;
+    /** Load a persisted storyboard by id; null when missing or not owned. */
+    getStoryboard?: (args: {
+        userId: string;
+        id: string;
+    }) => Promise<PersistedRecordLike | null>;
+    /** The caller's storyboards, optionally narrowed by project. */
+    listStoryboards?: (args: {
+        userId: string;
+        projectId?: string;
+        limit?: number;
+    }) => Promise<PersistedRecordLike[]>;
+    /**
+     * The copy a previous run derived from `templateId` for that `recastKey`;
+     * null when there is none. Scoped rather than listed, because a listing is
+     * windowed and a batch bigger than the window would keep re-deriving — and
+     * re-rendering — copies it already has.
+     */
+    findRecastStoryboard?: (args: {
+        userId: string;
+        projectId?: string;
+        templateId: string;
+        recastKey: string;
+    }) => Promise<PersistedRecordLike | null>;
+    /** Create a persisted storyboard from a name + document. */
+    createStoryboard?: (args: {
+        userId: string;
+        name?: string;
+        projectId?: string;
+        document: unknown;
+    }) => Promise<PersistedRecordLike>;
+    /** Replace a persisted storyboard's document (and optional timeline link); null when missing or not owned. */
+    updateStoryboard?: (args: {
+        userId: string;
+        id: string;
+        document?: unknown;
+        timelineId?: string | null;
+        baseUpdatedAt?: string;
+    }) => Promise<PersistedRecordLike | null>;
+    /** The caller's entity library, optionally narrowed by project, kind, tags or name. */
+    listEntities?: (args: {
+        userId: string;
+        projectId?: string;
+        kind?: EntityKind;
+        tags?: string[];
+        nameContains?: string;
+        limit?: number;
+    }) => Promise<Entity[]>;
+    /** Read one owned entity by id; null when missing, not owned, or not tagged. */
+    getEntity?: (args: {
+        userId: string;
+        id: string;
+    }) => Promise<Entity | null>;
+    /**
+     * Create or update one entity, identified by `source.key` when given and by
+     * (project, kind, name) otherwise. A re-run of the same graph therefore
+     * updates the entity it made last time instead of growing the library.
+     */
+    upsertEntity?: (args: EntityUpsertArgs) => Promise<EntityUpsertResult>;
+}
+/** The arguments {@link ProcessingContextModelInterfaces.upsertEntity} takes. */
+export interface EntityUpsertArgs {
+    userId: string;
+    projectId?: string;
+    kind: EntityKind;
+    name: string;
+    descriptor: string;
+    /** The image asset the entity shows; also the row a new entity is tagged on. */
+    imageAssetId: string;
+    description?: string;
+    tags?: string[];
+    voiceId?: string | null;
+    /** Stored verbatim on the marker, so a re-run finds its own row. */
+    source?: EntitySource;
 }
 /**
- * In-memory storage adapter useful for tests and single-process ephemeral runs.
+ * What an upsert did. The host owns the match rule (`source.key`, then
+ * project/kind/name), so it is the only place that can say whether the row is
+ * new — a caller re-deriving that from a probe duplicates the rule and drifts
+ * from it the moment the host's changes.
  */
-export declare class InMemoryStorageAdapter implements StorageAdapter {
-    private _store;
-    store(key: string, data: Uint8Array, _contentType?: string): Promise<string>;
-    retrieve(uri: string): Promise<Uint8Array | null>;
-    exists(uri: string): Promise<boolean>;
+export interface EntityUpsertResult {
+    entity: Entity;
+    created: boolean;
 }
 /**
- * File-system storage adapter rooted to a single base directory.
+ * The arguments one model interface takes, minus the `userId` every
+ * {@link ProcessingContext} forwarder binds from the run. Derived so the shape
+ * is declared once, on the interface.
  */
-export declare class FileStorageAdapter implements StorageAdapter {
-    readonly rootDir: string;
-    constructor(rootDir: string);
-    private resolvePathFromKey;
-    private resolvePathFromUri;
-    store(key: string, data: Uint8Array, _contentType?: string): Promise<string>;
-    retrieve(uri: string): Promise<Uint8Array | null>;
-    exists(uri: string): Promise<boolean>;
-}
-export interface S3Client {
-    putObject(input: {
-        bucket: string;
-        key: string;
-        body: Uint8Array;
-        contentType?: string;
-    }): Promise<void>;
-    getObject(input: {
-        bucket: string;
-        key: string;
-    }): Promise<Uint8Array | null>;
-    headObject(input: {
-        bucket: string;
-        key: string;
-    }): Promise<boolean>;
-}
+type ModelInterfaceArgs<K extends keyof ProcessingContextModelInterfaces> = Omit<Parameters<NonNullable<ProcessingContextModelInterfaces[K]>>[0], "userId">;
 /**
- * S3-backed storage adapter with injected client operations.
+ * Install the model interfaces every context in this process falls back to.
  *
- * This avoids hard-coupling runtime to any specific SDK while providing
- * predictable URI behavior (`s3://bucket/key`).
+ * 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 declare class S3StorageAdapter implements StorageAdapter {
-    readonly bucket: string;
-    readonly prefix: string | null;
-    readonly client: S3Client;
-    constructor(opts: {
-        bucket: string;
-        client: S3Client;
-        prefix?: string;
-    });
-    private keyForStore;
-    private parseUri;
-    store(key: string, data: Uint8Array, contentType?: string): Promise<string>;
-    retrieve(uri: string): Promise<Uint8Array | null>;
-    exists(uri: string): Promise<boolean>;
-}
+export declare function setDefaultModelInterfaces(interfaces: ProcessingContextModelInterfaces | null): void;
+/** The process-wide default, or null when no host installed one. */
+export declare function getDefaultModelInterfaces(): ProcessingContextModelInterfaces | null;
+export declare function normalizeStorageKey(key: string): string;
 /**
  * Resolve paths relative to a configured workspace root.
  *
@@ -167,29 +497,137 @@ export declare class S3StorageAdapter implements StorageAdapter {
  * - relative paths
  */
 export declare function resolveWorkspacePath(workspaceDir: string | null | undefined, path: string): string;
+/**
+ * Build the run's workspace from whatever the host supplied.
+ *
+ * Hosts are migrating from `workspaceDir` (a real folder) and `workspaceStorage`
+ * (a bare adapter) to `workspace`. Accepting all three keeps the call sites
+ * working while they move, and means a consumer only ever reads
+ * `context.workspace`. Constructed lazily through a setter the storage module
+ * installs, so `context.ts` does not import the implementation and stays
+ * loadable off Node.
+ */
+type WorkspaceFactory = (opts: {
+    workspace?: Workspace | null;
+    workspaceDir?: string | null;
+    workspaceStorage?: StorageAdapter | null;
+}) => Workspace | null;
+/** Installed once by `storage-workspace.ts`; see {@link ProcessingContext.workspace}. */
+export declare function setWorkspaceFactory(factory: WorkspaceFactory): void;
 export declare class ProcessingContext {
     readonly jobId: string;
     readonly workflowId: string | null;
+    /** Chat thread id, when this context is serving a chat-driven agent run. */
+    readonly threadId: string | null;
     readonly userId: string;
     readonly workspaceDir: string | null;
     readonly assetOutputMode: AssetOutputMode;
+    /**
+     * Whether Output nodes should turn transient media into durable Asset rows.
+     * Hosts can disable this for explicitly temporary SDK executions.
+     */
+    readonly persistOutputAssets: boolean;
     readonly environment: Record<string, string>;
+    /** Bearer token for authenticated calls back to the owning NodeTool API. */
+    readonly authToken: string | null;
+    /** Read-only sandbox module catalog supplied by the execution host. */
+    readonly sandboxModuleCatalog: SandboxModuleCatalog | null;
+    /**
+     * 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: AbortSignal;
+    /**
+     * 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: {
+        node_id: string;
+        payload: unknown;
+        input_id: string;
+    } | null;
     /** Message queue: all emitted processing messages. */
     private _messages;
+    /** Whether emit() feeds the pull queue (see constructor option). */
+    private _retainMessageQueue;
     /** Latest node status by node id. */
     private _nodeStatuses;
     /** Latest edge status by edge id. */
     private _edgeStatuses;
-    /** Optional message listener (for real-time streaming). */
-    private _onMessage;
+    /** Message listeners (for real-time streaming). */
+    private _messageListeners;
+    /**
+     * 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.
+     */
+    private readonly _normalizedOutputAssets;
     /** Cache adapter. */
     readonly cache: CacheAdapter;
     /** Storage adapter (optional, for asset handling). */
     readonly storage: StorageAdapter | null;
+    /**
+     * 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}.
+     */
+    readonly assetStorage: StorageAdapter | null;
+    /**
+     * 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.
+     */
+    readonly workspaceStorage: StorageAdapter | null;
+    /**
+     * 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.
+     */
+    readonly workspace: Workspace | null;
+    /** Project captured when this run started. */
+    readonly projectId: string | null;
+    /**
+     * 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}).
+     */
+    readonly memory: AgentMemory;
     /** Variables shared across node execution. */
     private _variables;
+    /** Named async channels backing Set/Get Variable (see {@link getChannel}). */
+    private _channels;
+    /** Remaining Set Variable writers per channel; channel closes at zero. */
+    private _channelWriters;
     /** Optional async secret resolver. */
     private _secretResolver;
+    /** Every secret value the resolver handed out this run (see {@link ProcessingContext.getResolvedSecretValues}). */
+    private _resolvedSecrets;
     /** Fetch function used by HTTP helpers. */
     private _fetch;
     /** Optional temporary URL resolver for stored assets. */
@@ -200,10 +638,21 @@ export declare class ProcessingContext {
     private _modelInterfaces;
     /** Provider cache keyed by provider id. */
     private _providers;
+    private _providerPromises;
     /** In-context memory URI cache (memory:// key-value objects). */
     private _memory;
     /** Optional control event dispatcher (set by workflow runner). */
     private _sendControlEvent;
+    /**
+     * 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.
+     */
+    private _injectedTools;
+    /** Provider charge (USD) reported by the current node execution (e.g. FAL/KIE generation). */
+    private _providerCost;
     /** Optional executor resolver for sub-workflow execution. */
     private _resolveExecutor;
     /** Optional node type resolver for sub-workflow graph hydration. */
@@ -212,25 +661,116 @@ export declare class ProcessingContext {
     private _totalCost;
     /** Per-operation cost entries. */
     private _operationCosts;
+    private readonly _generationLifecycle;
     constructor(opts: {
         jobId: string;
         workflowId?: string | null;
+        projectId?: string | null;
+        threadId?: string | null;
         userId?: string;
         workspaceDir?: string | null;
         assetOutputMode?: AssetOutputMode;
+        persistOutputAssets?: boolean;
         cache?: CacheAdapter;
         storage?: StorageAdapter | null;
+        assetStorage?: StorageAdapter | null;
+        workspaceStorage?: StorageAdapter | null;
+        /**
+         * The run's workspace. Preferred over `workspaceDir`/`workspaceStorage`,
+         * which are kept for hosts that still hand over a directory or a bare
+         * adapter — either one is wrapped into a Workspace here so every consumer
+         * sees the same interface whatever the host passed.
+         */
+        workspace?: Workspace | null;
         onMessage?: (msg: ProcessingMessage) => void;
         variables?: Record<string, unknown>;
         environment?: Record<string, string>;
+        authToken?: string | null;
+        sandboxModuleCatalog?: SandboxModuleCatalog | null;
         secretResolver?: (key: string, userId: string) => Promise<string | null | undefined> | string | null | undefined;
         fetchFn?: (input: string, init?: RequestInit) => Promise<Response>;
         tempUrlResolver?: (uri: string) => Promise<string> | string;
         modelInterfaces?: ProcessingContextModelInterfaces;
+        /**
+         * Wake-up payload for a trigger-driven run. Usually left unset at
+         * construction and assigned later by the kernel (see {@link triggerEvent});
+         * accepted here too so tests and single-node harnesses can construct a
+         * context with it directly.
+         */
+        triggerEvent?: {
+            node_id: string;
+            payload: unknown;
+            input_id: string;
+        } | null;
+        /**
+         * Keep emitted messages in the pull queue (popMessage/waitMessage).
+         * Consumers that stream via message listeners instead (the browser/
+         * workflow-runner path) should pass false — with nothing draining the
+         * queue, an infinite realtime stream otherwise retains every chunk
+         * payload for the lifetime of the run. Default true (server paths pull
+         * from the queue).
+         */
+        retainMessageQueue?: boolean;
+        /** Optional durable lifecycle owned by the host. */
+        generationLifecycle?: GenerationLifecycleHooks;
     });
-    copy(): ProcessingContext;
+    /**
+     * 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?: {
+        shareMemory?: boolean;
+        inheritMessageListeners?: boolean;
+    }): ProcessingContext;
     setProviderResolver(resolver: (providerId: string) => Promise<BaseProvider> | BaseProvider): void;
+    /**
+     * 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(): boolean;
     setModelInterfaces(modelInterfaces: ProcessingContextModelInterfaces): void;
+    /**
+     * 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.
+     */
+    private modelInterfaces;
+    /**
+     * 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: keyof ProcessingContextModelInterfaces): boolean;
+    /** Read a user setting, falling back to this run's environment. */
+    getSetting(key: string): Promise<string | null>;
     /**
      * Set the control event dispatcher (called by the workflow runner).
      * This allows agent nodes to dispatch control events to controlled nodes
@@ -242,6 +782,15 @@ export declare class ProcessingContext {
      * Returns null if no control event dispatcher is configured.
      */
     sendControlEvent(targetNodeId: string, properties: Record<string, unknown>): Promise<Record<string, unknown> | null>;
+    /**
+     * 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: InjectedTool[]): void;
+    /** Injected tool matching `name`, or null when the caller supplied none. */
+    getInjectedTool(name: string): InjectedTool | null;
     setResolveExecutor(fn: (node: {
         id: string;
         type: string;
@@ -256,59 +805,118 @@ export declare class ProcessingContext {
         nodeType: string;
         propertyTypes?: Record<string, string>;
         outputs?: Record<string, string>;
-        isDynamic?: boolean;
+        supportsDynamicInputs?: boolean;
         descriptorDefaults?: Record<string, unknown>;
     } | null>): void;
     get resolveNodeType(): ((nodeType: string) => Promise<{
         nodeType: string;
         propertyTypes?: Record<string, string>;
         outputs?: Record<string, string>;
-        isDynamic?: boolean;
+        supportsDynamicInputs?: boolean;
         descriptorDefaults?: Record<string, unknown>;
     } | null>) | null;
-    /**
-     * Check if control event dispatch is available.
-     */
     get hasControlEventSupport(): boolean;
     registerProvider(providerId: string, provider: BaseProvider): void;
     getProvider(providerId: string): Promise<BaseProvider>;
-    get_provider(providerId: string): Promise<BaseProvider>;
+    /**
+     * Check whether a registered provider has all required credentials
+     * resolvable through this context (DB/keychain/env).
+     */
+    isProviderConfigured(providerId: string): Promise<boolean>;
     setSecretResolver(resolver: (key: string, userId: string) => Promise<string | null | undefined> | string | null | undefined): void;
     setTempUrlResolver(resolver: (uri: string) => Promise<string> | string): void;
+    /**
+     * 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.
+     */
+    resolveTempUrl(uri: string): Promise<string>;
+    /**
+     * 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(): boolean;
     getSecret(key: string): Promise<string | 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(): ReadonlySet<string>;
     getSecretRequired(key: string): Promise<string>;
-    get_secret(key: string): Promise<string | null>;
-    get_secret_required(key: string): Promise<string>;
     get<T = unknown>(key: string, defaultValue?: T): T;
     set(key: string, value: unknown): void;
+    /** Whether a shared variable with this name has been set. */
+    hasVariable(key: string): boolean;
+    /**
+     * 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(): {
+        [x: string]: unknown;
+    };
+    /**
+     * 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: string, count: number): void;
+    /**
+     * 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<T = unknown>(name: string): VariableChannel<T>;
+    /**
+     * 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: string): void;
+    /** Close every channel — a teardown backstop so no reader is left waiting. */
+    closeAllChannels(): void;
+    /** Whether any Set Variable node was registered as writing to `name`. */
+    hasChannelWriters(name: string): boolean;
     storeStepResult(key: string, value: unknown): Promise<string>;
     loadStepResult<T = unknown>(key: string, defaultValue?: T): Promise<T>;
-    private workspacePathFor;
-    private persistVariableIfNeeded;
     generateNodeCacheKey(nodeType: string, nodeProps: unknown): string;
-    getCachedResult(nodeType: string, nodeProps: unknown): Promise<unknown>;
-    cacheResult(nodeType: string, nodeProps: unknown, result: unknown, ttlSeconds?: number): Promise<void>;
+    getCachedResult<TResult>(nodeType: string, nodeProps: unknown): Promise<TResult | undefined>;
+    cacheResult<TResult>(nodeType: string, nodeProps: unknown, result: TResult, ttlSeconds?: number): Promise<void>;
+    addMessageListener(listener: (msg: ProcessingMessage) => void): () => void;
     /**
      * 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: ProcessingMessage): void;
     postMessage(msg: ProcessingMessage): void;
-    post_message(msg: ProcessingMessage): void;
-    /** Get all emitted messages. */
+    /** Record actual provider charge for the current node run (attached to completed NodeUpdate). */
+    setProviderCost(provider: string, amount: number, unit: string, details?: Pick<ProviderCost, "model" | "billing_unit" | "quantity" | "unit_price" | "currency" | "provider_request_id" | "input_tokens" | "output_tokens" | "cached_tokens">): void;
+    getProviderCost(): ProviderCost | null;
+    clearProviderCost(): void;
     getMessages(): ReadonlyArray<ProcessingMessage>;
     hasMessages(): boolean;
     popMessage(): ProcessingMessage | undefined;
-    private _messageResolve;
+    private _messageWaiters;
     /** Notify that a new message has been pushed. */
     private _notifyMessage;
     popMessageAsync(): Promise<ProcessingMessage>;
-    pop_message_async(): Promise<ProcessingMessage>;
     getNodeStatuses(): Readonly<Record<string, ProcessingMessage>>;
     getEdgeStatuses(): Readonly<Record<string, ProcessingMessage>>;
-    /** Clear the message queue. */
     clearMessages(): void;
-    clear_messages(): void;
     trackOperationCost(operation: string, cost: number, metadata?: Record<string, unknown>): void;
     addToTotalCost(cost: number): void;
     resetTotalCost(): void;
@@ -319,65 +927,265 @@ export declare class ProcessingContext {
         total: number;
         byPrefix: Record<string, number>;
     };
-    private httpRequestWithRetries;
+    /**
+     * Issue an HTTP request with the retry/backoff policy every node shares.
+     * `httpGet` is the GET shorthand; other verbs go through this directly.
+     */
+    httpRequestWithRetries(method: string, url: string, opts?: HttpRequestOptions): Promise<Response>;
     httpGet(url: string, opts?: HttpRequestOptions): Promise<Response>;
-    httpPost(url: string, opts?: HttpRequestOptions): Promise<Response>;
-    httpPatch(url: string, opts?: HttpRequestOptions): Promise<Response>;
-    httpPut(url: string, opts?: HttpRequestOptions): Promise<Response>;
-    httpDelete(url: string, opts?: HttpRequestOptions): Promise<Response>;
-    httpHead(url: string, opts?: HttpRequestOptions): Promise<Response>;
     downloadFile(url: string, opts?: HttpRequestOptions): Promise<Uint8Array>;
-    downloadText(url: string, opts?: HttpRequestOptions): Promise<string>;
-    http_get(url: string, opts?: HttpRequestOptions): Promise<Response>;
-    http_post(url: string, opts?: HttpRequestOptions): Promise<Response>;
-    http_patch(url: string, opts?: HttpRequestOptions): Promise<Response>;
-    http_put(url: string, opts?: HttpRequestOptions): Promise<Response>;
-    http_delete(url: string, opts?: HttpRequestOptions): Promise<Response>;
-    http_head(url: string, opts?: HttpRequestOptions): Promise<Response>;
     private requireModelInterface;
-    getJob(jobId: string): Promise<unknown | null>;
-    get_job(jobId: string): Promise<unknown | null>;
-    createAsset(args: {
-        name: string;
-        contentType: string;
-        content?: Uint8Array | null;
-        parentId?: string | null;
-        instructions?: Uint8Array | null;
-        nodeId?: string | null;
-    }): Promise<unknown>;
-    create_asset(args: {
-        name: string;
-        contentType: string;
+    getJob(jobId: string): Promise<PersistedRecordLike | null>;
+    /**
+     * 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`.
+     */
+    createAsset(args: Omit<ModelInterfaceArgs<"createAsset">, "workflowId" | "jobId" | "content"> & {
         content?: Uint8Array | null;
-        parentId?: string | null;
+        /** Legacy name for `content`; used when `content` is absent. */
         instructions?: Uint8Array | null;
-        nodeId?: string | null;
     }): Promise<unknown>;
+    /**
+     * Replace an owned asset's bytes, keeping its id. Null when the asset is
+     * missing or belongs to someone else.
+     */
+    updateAssetBytes(args: ModelInterfaceArgs<"updateAssetBytes">): Promise<AssetInfoEntry | null>;
+    /** Load a persisted sketch (image document) owned by the current user. */
+    getImageDocument(id: string): Promise<PersistedRecordLike | null>;
+    /** Create a persisted sketch (image document) owned by the current user. */
+    createImageDocument(args: ModelInterfaceArgs<"createImageDocument">): Promise<PersistedRecordLike>;
+    /** Load a persisted timeline sequence owned by the current user. */
+    getTimelineSequence(id: string): Promise<PersistedRecordLike | null>;
+    /** Create a persisted timeline sequence owned by the current user. */
+    createTimelineSequence(sequence: unknown): Promise<PersistedRecordLike>;
+    /** Replace a persisted timeline sequence's document. */
+    updateTimelineSequence(id: string, sequence: unknown): Promise<PersistedRecordLike | null>;
+    /** Load a persisted script owned by the current user. */
+    getScript(id: string): Promise<PersistedRecordLike | null>;
+    /** Create a persisted script owned by the current user. */
+    createScript(args: ModelInterfaceArgs<"createScript">): Promise<PersistedRecordLike>;
+    /** Replace a persisted script's document (and optional timeline link). */
+    updateScript(id: string, args: Omit<ModelInterfaceArgs<"updateScript">, "id">): Promise<PersistedRecordLike | null>;
+    /** Load a persisted storyboard owned by the current user. */
+    getStoryboard(id: string): Promise<PersistedRecordLike | null>;
+    /** The current user's storyboards, narrowed by the given filters. */
+    listStoryboards(args?: ModelInterfaceArgs<"listStoryboards">): Promise<PersistedRecordLike[]>;
+    /** The copy this user derived from a template for one recast mapping. */
+    findRecastStoryboard(args: ModelInterfaceArgs<"findRecastStoryboard">): Promise<PersistedRecordLike | null>;
+    /** Create a persisted storyboard owned by the current user. */
+    createStoryboard(args: ModelInterfaceArgs<"createStoryboard">): Promise<PersistedRecordLike>;
+    /** Replace a persisted storyboard's document (and optional timeline link). */
+    updateStoryboard(id: string, args: Omit<ModelInterfaceArgs<"updateStoryboard">, "id">): Promise<PersistedRecordLike | null>;
+    /** The current user's entity library, narrowed by the given filters. */
+    listEntities(args?: ModelInterfaceArgs<"listEntities">): Promise<Entity[]>;
+    /** Read one entity owned by the current user. */
+    getEntity(id: string): Promise<Entity | null>;
+    /** Create or update one entity in the current user's library. */
+    upsertEntity(args: ModelInterfaceArgs<"upsertEntity">): Promise<EntityUpsertResult>;
+    /**
+     * 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.
+     */
+    listFolderAssets(folderId: string): Promise<FolderAssetEntry[] | null>;
+    /**
+     * 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.
+     */
+    getAssetInfo(assetId: string): Promise<AssetInfoEntry | null>;
     private resolveSandboxFilePath;
     private static guessMimeFromPath;
     private static assetTypeForMime;
     private parseAssetIdCandidates;
+    /**
+     * 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.
+     */
+    private assetAdapters;
+    /**
+     * 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.
+     */
+    private assetKeysFor;
+    /**
+     * 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.
+     */
+    private assetListingPrefixes;
+    /**
+     * 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.
+     */
+    localPath(uri: string): Promise<string | 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.
+     */
+    resolveAssetBytes(assetId: string): Promise<{
+        bytes: Uint8Array | null;
+        attempts: string[];
+    }>;
     assetToSandbox(assetId: string, path: string): Promise<string>;
-    asset_to_sandbox(asset_id: string, path: string): Promise<string>;
     sandboxToAsset(path: string): Promise<AssetRef>;
-    sandbox_to_asset(path: string): Promise<AssetRef>;
-    createMessage(req: MessageCreateRequestLike): Promise<unknown>;
-    create_message(req: MessageCreateRequestLike): Promise<unknown>;
+    createMessage(req: MessageCreateRequestLike): Promise<PersistedRecordLike>;
     getThreadMessages(threadId: string, limit?: number, startKey?: string | null, reverse?: boolean): Promise<ThreadMessagesResultLike>;
-    get_messages(thread_id: string, limit?: number, start_key?: string | null, reverse?: boolean): Promise<ThreadMessagesResultLike>;
     assetsToDataUri(value: unknown): Promise<unknown>;
     assetsToStorageUrl(value: unknown): Promise<unknown>;
     assetsToWorkspaceFiles(value: unknown): Promise<unknown>;
     uploadAssetsToTemp(value: unknown): Promise<unknown>;
     private emitPrediction;
     /**
-     * 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.
+     */
+    private generationOrigin;
+    /**
+     * 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.
      */
-    private resolveMessageMediaUris;
+    private retrieveMediaBytes;
+    /**
+     * 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.
+     */
+    resolveMessageMediaUris(messages: Message[]): Promise<Message[]>;
     private dispatchCapability;
+    /**
+     * 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.
+     */
     runProviderPrediction(req: ProviderPredictionRequest): Promise<unknown>;
-    streamProviderPrediction(req: ProviderPredictionRequest): AsyncGenerator<ProviderStreamItem | unknown>;
+    /**
+     * 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.
+     */
+    runGeneration(req: GenerationRequest): Promise<GenerationResult>;
+    /**
+     * 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.
+     */
+    runGenerationWith<T>(req: GenerationRequest, call: (provider: BaseProvider | null, signal: AbortSignal) => Promise<T>, opts?: GenerationRunOptions): Promise<GenerationResult<T>>;
+    /**
+     * 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.
+     */
+    private persistGenerationBytes;
+    /**
+     * 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.
+     */
+    private retryContentFilterRefusal;
+    /**
+     * 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).
+     */
+    providerSupportsStreamingTTS(providerId: string): Promise<boolean>;
+    /**
+     * 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.
+     */
+    providerSupportsVideoInput(providerId: string): Promise<boolean>;
+    /**
+     * 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.
+     */
+    textToSpeechEncoded(req: GenerationRequest): Promise<EncodedAudioResult | null>;
+    /**
+     * 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.
+     */
+    private runEncodedGeneration;
+    /**
+     * 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.
+     */
+    textToMusic(req: GenerationRequest): Promise<EncodedAudioResult>;
+    /**
+     * 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`.
+     */
+    audioToAudio(req: GenerationRequest): Promise<EncodedAudioResult>;
+    /**
+     * 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.
+     */
+    videoToAudio(req: GenerationRequest): Promise<EncodedAudioResult>;
+    streamProviderPrediction(req: GenerationRequest): AsyncGenerator<ProviderStreamItem | unknown>;
     /**
      * Sanitize memory URIs from output values before sending to client.
      * Replaces internal memory:// URIs with safe placeholders.
@@ -391,9 +1199,17 @@ export declare class ProcessingContext {
      */
     resolveWorkspacePath(path: string): string;
     private static isAssetLike;
+    /**
+     * `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.
+     */
     private static guessAssetMime;
     private static extForMime;
     private static decodeAssetData;
+    private static isClientFetchableResolvedAssetUri;
     private getAssetBytes;
     private materializeAsset;
     /**
@@ -402,4 +1218,15 @@ export declare class ProcessingContext {
      */
     normalizeOutputValue(value: unknown, mode?: AssetOutputMode): Promise<unknown>;
 }
+/**
+ * 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 declare function mediaResolverFor(context: Pick<ProcessingContext, "resolveMessageMediaUris"> | undefined | null): ((messages: Message[]) => Promise<Message[]>) | undefined;
 //# sourceMappingURL=context.d.ts.map