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

package/dist/session/chat-turn.js

@@ -0,0 +1,3612 @@
+import { registerChatRunTrace, registerWorkflowRunTrace, withRegisteredRunTrace, settleRegisteredRunTrace } from "@nodetool-ai/execution";
+import { getRunTraceScope, suppressRunTraceContent } from "@nodetool-ai/runtime";
+import { TRACE_RESTRICTED_CAPABILITY_MODULES } from "@nodetool-ai/protocol";
+import { trace, SpanStatusCode } from "@opentelemetry/api";
+import { settleRunTrace, registerRunTraceParent, registerRunTraceParents, threadHasTraceContentTools } from "@nodetool-ai/models";
+import { capabilityModuleOf, listCapabilitySpecs } from "@nodetool-ai/agents";
+import { createLogger } from "@nodetool-ai/config";
+import { randomUUID } from "node:crypto";
+import { SUPERSEDED_TOOL_RESULT, repairOrphanedToolCalls } from "../chat-tool-call-repair.js";
+import { attachChatPredictionForwarder } from "../chat-prediction-forwarder.js";
+import { isGoogleWorkspaceEnabled } from "@nodetool-ai/config";
+import { isFunctionValue, isNonEmptyString, isNumber, isObjectLike, isRecord, isString } from "../lib/wire-values.js";
+import { storeAssetWithThumbnail } from "../lib/thumbnail.js";
+import { createGenerationRun, generateSpeechBytes, generateMusicBytes } from "./media-generation.js";
+import { attachRunCostLedger, linkGenerationAssets, ExecutionSession, isExecutionPreflightError, toRawGraphInput } from "@nodetool-ai/execution";
+import { Asset, COMPACTION_EVENT_TYPE, compactionMessageContent, isCompactionMessage, Job, Message, Prediction, Project, Skill, Thread, Memory, Workflow } from "@nodetool-ai/models";
+import { WORKFLOW_DOCUMENT_TOOL_NAMES } from "@nodetool-ai/node-sdk";
+import { ACTIVE_MODEL_CONTEXT_KEY, DIRECT_TOOL_NAMES, RUN_BUDGET_CONTEXT_KEY, createRunBudget, detectImageMime, IMAGE_MIME_TO_EXT, expandEntitiesForGeneration, getProcessSandboxModuleCatalog, estimatePromptTokens, isToolCall, isProviderSessionUpdate, isProviderMessageEvent, isProviderStop, httpStatusFromError, groqRequestFailureMessage, mediaResolverFor, providerFailureDetail, resolveContextWindow } from "@nodetool-ai/runtime";
+import { isModelSelection, PROVIDER_IDS, NO_MODEL_SELECTED_MESSAGE, noMediaModelSelectedMessage } from "@nodetool-ai/protocol";
+import { Tool, compactAssetUris, compactResourceIds } from "@nodetool-ai/agents";
+import { createChatCodeActSession, createSandboxClock, sandboxPackagesForChat, CODEACT_RESIDENT_TOOL_NAMES, EXECUTE_CODE_TOOL_NAME } from "@nodetool-ai/agents";
+import { availableBuiltinToolNames, GOOGLE_WORKSPACE_TOOL_NAMES, APIFY_TOOL_NAMES, SERPAPI_TOOL_NAMES, capabilityForName, capabilityProviderTool, getAllMcpCapabilitySpecs, toolFromCapability, capabilityFromTool, createCapabilityRun, contextSecretAvailability, BackgroundSubtaskRegistry, PERMISSION_GATE_CONTEXT_KEY, GAME_ASSET_NODE_RUNNER_CONTEXT_KEY, extractInjectableImages, registerTemporaryImageHandle } from "@nodetool-ai/agents";
+import { mcpToolHostDeps } from "../mcp-tool-deps.js";
+import { externalMcpToolsFor } from "../external-mcp.js";
+import { formatSkillCatalogForPrompt, mergeSystemSkills, formatMemoriesForPrompt } from "@nodetool-ai/agents";
+import { RunNodeTool } from "../agent/run-node-tool.js";
+import { extractEmbeddedImage } from "./asset-autosave.js";
+import { buildChatAgentSystemPrompt, focusedUiToolNames, normalizeToolCallName, RESIDENT_TOOL_NAMES, unroutableToolMessage } from "./chat-prompt.js";
+import { createRuntimeContext } from "./model-interfaces.js";
+import { getSetting } from "../settings-registry.js";
+import { appendContextToLastUser, createWorkflowResponseContent, dbMessageToProviderMessage, extractTextContent, historySinceCompaction, invokedSkillsSection, toolResultDisplayText } from "./chat-history.js";
+import { chooseCompactionCut, compactionThreshold, COMPACTION_SUMMARY_MAX_TOKENS, holdsTranscriptServerSide, readCompactionSettings, summarizeForCompaction } from "./chat-compaction.js";
+import { createRelayActivityWaiter, DEFAULT_RUN_JOB_EXECUTION_OPTIONS } from "./job-execution.js";
+function restrictedTraceToolNames() {
+    const modules = new Set(TRACE_RESTRICTED_CAPABILITY_MODULES);
+    return listCapabilitySpecs().filter((spec) => modules.has(capabilityModuleOf(spec.name) ?? "")).map((spec) => spec.name);
+}
+function seedStoredToolProvenance(messages) {
+    for (const message of messages) {
+        const names = message.name ? [message.name] : [];
+        if (isCompactionMessage(message)) {
+            names.push(...(message.tools ?? []));
+        }
+        for (const call of message.tool_calls ?? []) {
+            if (!isRecord(call)) {
+                continue;
+            }
+            if (isString(call.name)) {
+                names.push(call.name);
+            }
+            if (isRecord(call.function) && isString(call.function.name)) {
+                names.push(call.function.name);
+            }
+        }
+        for (const name of names) {
+            const moduleName = capabilityModuleOf(name);
+            if (moduleName === "email" || moduleName === "google" || moduleName === "browser") {
+                suppressRunTraceContent();
+            }
+        }
+    }
+}
+const log = createLogger("nodetool.websocket.runner");
+/** Providers whose credential is an account sign-in, not an API key. */
+const SIGN_IN_PROVIDER_LABELS = {
+    [PROVIDER_IDS.CODEX]: "Codex",
+    [PROVIDER_IDS.CLAUDE_AGENT_SDK]: "Claude"
+};
+const GENERIC_CHAT_ERROR = "Something went wrong while processing your request. Please try again.";
+/**
+ * Keep implementation details out of the client error envelope. Provider
+ * messages remain useful when they are short and user-facing, but database
+ * diagnostics and query arguments can contain schema details or secrets.
+ */
+function safeClientErrorText(error) {
+    const text = error instanceof Error ? error.message : String(error);
+    if (text.length > 500 ||
+        /\b(?:select|insert|update|delete)\b[\s\S]*\b(?:from|where|into|set)\b/i.test(text) ||
+        /(?:sqlite|sqlstate|drizzle|query\s+(?:failed|parameter)|bind\s+parameter|database\s+error|stack\s+trace|\bparams?\s*[:=]|\bparameters?\s*[:=]|\b(?:api[_ -]?key|authorization|bearer)\s*[:=]|https?:\/\/\S*\?\S*=)/i.test(text)) {
+        return GENERIC_CHAT_ERROR;
+    }
+    return text || GENERIC_CHAT_ERROR;
+}
+/**
+ * Gemini wraps JSON failures in a plain Error (`Gemini API error 429: …`), so
+ * the shared status helper cannot see the status when the wrapper says
+ * `API error` instead of `HTTP`. Parse only that known wrapper and retain a
+ * bounded, user-actionable classification rather than forwarding the JSON.
+ */
+function geminiFailureSummary(error, providerId) {
+    if (providerId.toLowerCase() !== "gemini") {
+        return null;
+    }
+    const text = error instanceof Error ? error.message : "";
+    const wrapper = text.match(/^Gemini API error(?:\s+(\d{3}))?:\s*([\s\S]+)$/i);
+    if (!wrapper) {
+        return null;
+    }
+    const wrapperStatus = Number(wrapper[1]);
+    let status = wrapperStatus >= 100 && wrapperStatus <= 599 ? wrapperStatus : null;
+    let message = wrapper[2].trim();
+    try {
+        const parsed = JSON.parse(wrapper[2]);
+        if (isObjectLike(parsed)) {
+            const root = parsed;
+            const nested = isObjectLike(root.error) ? root.error : root;
+            if (isObjectLike(nested)) {
+                const code = nested.code;
+                if (status === null &&
+                    isNumber(code) &&
+                    Number.isInteger(code) &&
+                    code >= 100 &&
+                    code <= 599) {
+                    status = code;
+                }
+                if (isString(nested.message)) {
+                    message = nested.message;
+                }
+            }
+        }
+    }
+    catch {
+        // The provider sometimes returns plain text after the same wrapper.
+    }
+    const lower = message.toLowerCase();
+    let kind = null;
+    if (/quota|resource_exhausted|rate limit|billing|credit|limit exceeded|daily limit/.test(lower)) {
+        kind = "quota";
+    }
+    else if (/no longer available|model[^.]{0,80}(?:not found|unavailable|unsupported|does not exist)|(?:not found|unavailable|unsupported)[^.]{0,80}model/.test(lower)) {
+        kind = "model";
+    }
+    else if (/tool|function call|function calling|function_declaration/.test(lower) &&
+        /not support|unsupported|invalid|disable|not enabled/.test(lower)) {
+        kind = "tools";
+    }
+    const safeMessage = safeClientErrorText(message);
+    return {
+        status,
+        kind,
+        message: safeMessage === GENERIC_CHAT_ERROR ? null : safeMessage
+    };
+}
+function providerFailureMessage(error, providerId, model) {
+    const gemini = geminiFailureSummary(error, providerId);
+    const groq = groqRequestFailureMessage(error);
+    const status = httpStatusFromError(error) ?? gemini?.status ?? null;
+    const statusCode = status ?? undefined;
+    const rawMessage = groq ?? gemini?.message ?? safeClientErrorText(error);
+    const body = isObjectLike(error) ? (error.body ?? error.response) : undefined;
+    const bodyError = isObjectLike(body) && isObjectLike(body.error) ? body.error : body;
+    const bodyText = isObjectLike(bodyError) && isString(bodyError.message)
+        ? safeClientErrorText(bodyError.message)
+        : null;
+    const bodyMessage = bodyText === GENERIC_CHAT_ERROR ? null : bodyText;
+    if (providerId.toLowerCase() === "openai" &&
+        /\borganization must be verified\b/i.test(bodyMessage ?? rawMessage)) {
+        return {
+            errorType: status === null ? "error" : "http_status_error",
+            message: "This model requires a verified OpenAI organization. Verify your provider organization or choose a model your account can access.",
+            statusCode
+        };
+    }
+    const detail = providerFailureDetail(error);
+    if (detail?.code === "context_exceeded") {
+        const target = model ? `${providerId}/${model}` : providerId;
+        return {
+            errorType: "error",
+            message: `The ${target} request is too large for the model context window. Shorten the conversation or remove some attachments and try again.`,
+            statusCode
+        };
+    }
+    if (detail?.code === "provider_auth") {
+        const signIn = SIGN_IN_PROVIDER_LABELS[detail.provider];
+        const remedy = signIn ? `Sign in to ${signIn} again` : "Check the API key";
+        return {
+            errorType: "error",
+            message: `Authentication failed: ${detail.provider} rejected the configured credentials. ${remedy} in Settings → Models & Providers.`,
+            statusCode
+        };
+    }
+    if (status === null) {
+        return { errorType: "error", message: rawMessage, statusCode };
+    }
+    const modelName = model || "requested";
+    let message;
+    if (gemini?.kind === "quota") {
+        message = `Account quota exhausted for ${providerId}/${model}. Check your ${providerId} quota or billing and try again later.`;
+    }
+    else if (gemini?.kind === "model") {
+        message = `Model ${modelName} is unavailable on ${providerId}. Choose another model or check that your account has access to it.`;
+    }
+    else if (gemini?.kind === "tools") {
+        message = `Model ${modelName} does not support the requested tools on ${providerId}. Choose a model with tool support or disable tools.`;
+    }
+    else if (status === 400) {
+        message = `Bad request: ${groq ?? bodyMessage ?? rawMessage}`;
+    }
+    else if (status === 401) {
+        message = "Authentication failed: Invalid API key or token";
+    }
+    else if (status === 402) {
+        message = `Account billing or credit limit reached for ${providerId}. Check your ${providerId} plan or billing.`;
+    }
+    else if (status === 403) {
+        message =
+            "Access forbidden: You don't have permission for this resource. Check the provider key's model and account access.";
+    }
+    else if (status === 404) {
+        message = `Model ${modelName} was not found or is unavailable on ${providerId}. Choose another model or check account access.`;
+    }
+    else if (status === 413) {
+        const bodyDetail = bodyMessage ?? rawMessage;
+        message =
+            groq ??
+                (bodyDetail === GENERIC_CHAT_ERROR
+                    ? "Request is too large for the provider. Shorten the conversation or remove some attachments and try again."
+                    : `Request is too large for the provider (${bodyDetail}). Shorten the conversation or remove some attachments and try again.`);
+    }
+    else if (status === 429) {
+        message =
+            groq ??
+                "Rate limited: Too many requests or insufficient provider quota. Check your provider plan and try again later.";
+    }
+    else if (status >= 500) {
+        message =
+            groq ??
+                bodyMessage ??
+                `Server error (${status}): The service is temporarily unavailable`;
+    }
+    else {
+        message = `HTTP error (${status}): ${rawMessage}`;
+    }
+    return { errorType: "http_status_error", message, statusCode };
+}
+/**
+ * How many of a user's newest memories the turn reads to build its block. The
+ * read doubles as the "how many live in other threads" count, so it is capped:
+ * the number is a nudge toward `memory_search`, not an audit.
+ */
+const MEMORY_SCAN_LIMIT = 400;
+/** How many of this thread's memories are pasted into the block. */
+const MEMORY_BLOCK_LIMIT = 100;
+/**
+ * How many recent messages to scan when probing for a resumable session before
+ * deciding whether the full thread needs loading. Large enough to clear the
+ * occasional errored turn between sessioned assistant replies, tiny next to a
+ * full thread load.
+ */
+const SESSION_PROBE_WINDOW = 50;
+/**
+ * Output-token worst case assumed when reserving a chat turn. The chat loop
+ * sends no `maxTokens`, so nothing bounds the answer from this side; the
+ * reservation charges the same ceiling the Agent node defaults to, which is
+ * what makes the dollar cap hold instead of being noticed after the money is
+ * spent.
+ */
+const CHAT_TURN_MAX_OUTPUT_TOKENS = 16_384;
+/** Documented defaults for the five `NODETOOL_AGENT_*` budget settings. */
+const AGENT_BUDGET_DEFAULTS = {
+    costCapUsd: 5,
+    deadlineMs: 1_800_000,
+    maxConcurrency: 8,
+    maxTurns: 200,
+    unpricedTokenCeiling: 400_000
+};
+/**
+ * Read one budget setting. The store is best-effort — the same rule the rest
+ * of the runner follows for settings: an unreachable database falls back to
+ * the documented default rather than failing the turn.
+ */
+async function readBudgetSetting(key) {
+    try {
+        return await getSetting(key);
+    }
+    catch {
+        // Settings store unavailable — the caller's default stands.
+        return null;
+    }
+}
+async function budgetSettingNumber(key, fallback) {
+    const raw = await readBudgetSetting(key);
+    if (raw === null)
+        return fallback;
+    const parsed = Number(raw);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+}
+/**
+ * The run's USD ceiling, or `null` for no ceiling at all.
+ *
+ * `Number("")` is 0 and a cap of 0 refuses every turn rather than lifting the
+ * ceiling, so a blank or non-positive value means *no cap* — which is what a
+ * local-only install wants. An absent setting takes the documented $5 default;
+ * `getSetting` cannot tell an empty stored value from an unset one (it falls
+ * through both), so "no cap" is expressed by storing a non-positive number.
+ */
+async function budgetCostCapUsd() {
+    const raw = await readBudgetSetting("NODETOOL_AGENT_TURN_COST_CAP_USD");
+    // `getSetting` answers null for both an unset and an empty stored value, so
+    // clearing the field restores the default rather than removing the cap.
+    // Removing it is `0`, which is why a non-positive number means "no cap"
+    // instead of a cap nothing could ever pass.
+    if (raw === null)
+        return AGENT_BUDGET_DEFAULTS.costCapUsd;
+    const parsed = Number(raw.trim());
+    if (!Number.isFinite(parsed) || parsed <= 0)
+        return null;
+    return parsed;
+}
+/**
+ * The one budget a chat turn shares downward (invariant I-2): the capability
+ * runs, the sub-agent runtime, the provider loop, and — through the context
+ * key — an Agent node started by `run_node` and any JS script the turn runs.
+ * Every one of them reserves against the same cap instead of opening its own.
+ */
+async function createChatTurnBudget() {
+    const [capUsd, deadlineMs, maxConcurrency, maxTurns, unpricedTokenCeiling] = await Promise.all([
+        budgetCostCapUsd(),
+        budgetSettingNumber("NODETOOL_AGENT_TURN_DEADLINE_MS", AGENT_BUDGET_DEFAULTS.deadlineMs),
+        budgetSettingNumber("NODETOOL_AGENT_MAX_CONCURRENCY", AGENT_BUDGET_DEFAULTS.maxConcurrency),
+        budgetSettingNumber("NODETOOL_AGENT_MAX_TURNS", AGENT_BUDGET_DEFAULTS.maxTurns),
+        budgetSettingNumber("NODETOOL_AGENT_UNPRICED_TOKEN_CEILING", AGENT_BUDGET_DEFAULTS.unpricedTokenCeiling)
+    ]);
+    return createRunBudget({
+        capUsd,
+        maxOutputTokens: CHAT_TURN_MAX_OUTPUT_TOKENS,
+        unpricedTokenCeiling,
+        deadlineMs,
+        maxConcurrency,
+        maxTurns
+    });
+}
+/**
+ * Find the continuation token to resume this thread with: the `provider_session`
+ * of the most recent assistant message, but only if it was produced by the same
+ * `provider` and `model` as the incoming request (a session is bound to both).
+ * Returns null when there is nothing to resume, so the provider starts fresh.
+ */
+function lastMatchingProviderSession(dbMessages, providerId, model) {
+    for (let i = dbMessages.length - 1; i >= 0; i--) {
+        const m = dbMessages[i];
+        if (m.role !== "assistant")
+            continue;
+        const session = m.provider_session;
+        if (!session)
+            continue;
+        return session.providerId === providerId && session.model === model
+            ? session
+            : null;
+    }
+    return null;
+}
+/**
+ * One connection's chat turns: the turn counter and abort controller, the
+ * per-thread permission state, the capability run, and the three message
+ * shapes a `chat_message` frame can take — an agent turn, a workflow run, or
+ * a media generation.
+ *
+ * It reaches the connection only through {@link ClientSession}. Everything
+ * else another region owns arrives in {@link ChatTurnDeps}.
+ */
+export class ChatTurnHandler {
+    session;
+    deps;
+    chatRequestSeq = 0;
+    /**
+     * Aborts the in-flight chat/inference turn. The seq counter above only filters
+     * stale output at yield boundaries — it cannot interrupt a provider that is
+     * blocked awaiting a response, nor tell one that owns a subprocess (the Claude
+     * Agent provider) to stop working. This signal does, and is threaded into
+     * every provider call the turn makes.
+     */
+    chatAbort = null;
+    /**
+     * Per-thread set of tool names the user approved for the rest of the chat
+     * via "Allow for this chat". Persists across messages within a thread.
+     */
+    chatSessionAllow = new Map();
+    /**
+     * Live permission mode for an in-flight turn. `set_permission_mode` writes
+     * here so switching to Auto mid-turn applies to the next gated call.
+     */
+    chatTurnPermissionMode = new Map();
+    /**
+     * The capability run for the chat turn this connection is executing — the
+     * gate, the context, and everything a capability needs that only exists per
+     * turn. Built beside the toolbelt; the sandbox still calls the belt, and PR
+     * 11 is what switches the guest onto `run.invoke`.
+     */
+    chatCapabilityRun = null;
+    /**
+     * Input window per `provider/model`, resolved once per connection and again
+     * whenever a turn selects a model this connection has not used.
+     */
+    contextWindows = new Map();
+    /**
+     * The provider-reported size of each thread's last call, keyed by thread,
+     * with the `provider/model` it was measured on. The next turn's prompt is at
+     * least this large, and this counts what the local estimate cannot see.
+     */
+    measuredThreadTokens = new Map();
+    constructor(session, deps) {
+        this.session = session;
+        this.deps = deps;
+    }
+    /** The run built for the last chat turn — what PR 11 hands to the sandbox. */
+    getCapabilityRun() {
+        return this.chatCapabilityRun;
+    }
+    /**
+     * Open a chat/inference turn: cancel whatever was running and hand back the
+     * seq + signal the new turn runs under. A superseding message cancels the
+     * previous turn exactly as an explicit Stop does.
+     */
+    beginTurn() {
+        this.cancel();
+        this.chatRequestSeq += 1;
+        this.chatAbort = new AbortController();
+        return {
+            seq: this.chatRequestSeq,
+            signal: this.chatAbort.signal,
+            controller: this.chatAbort
+        };
+    }
+    /** Bump the turn counter without opening a new turn — what `stop` does. */
+    bumpRequestSeq() {
+        this.chatRequestSeq += 1;
+    }
+    /** The turn a caller's `requestSeq` is compared against. */
+    get currentRequestSeq() {
+        return this.chatRequestSeq;
+    }
+    /** Abort the in-flight turn, if any. Idempotent. */
+    cancel() {
+        this.chatAbort?.abort();
+        this.chatAbort = null;
+    }
+    /**
+     * Retire a turn that finished on its own. Clears the controller only when it
+     * is still the current one — a superseding turn has already installed its
+     * own, and clearing that would make a later Stop a no-op.
+     */
+    endTurn(controller) {
+        if (controller && this.chatAbort === controller)
+            this.chatAbort = null;
+    }
+    /** Resolve a client tool call this turn is waiting on. */
+    resolveToolResult(toolCallId, payload) {
+        this.deps.toolBridge.resolveResult(toolCallId, payload);
+    }
+    /**
+     * Apply a mid-turn permission-mode switch. Auto also releases every
+     * approval already waiting on this thread — the user just said yes to all
+     * of them.
+     */
+    setPermissionMode(threadId, mode) {
+        const liveMode = this.chatTurnPermissionMode.get(threadId);
+        if (liveMode) {
+            liveMode.value = mode;
+        }
+        if (mode === "auto") {
+            this.deps.approvalBridge.resolveScope(threadId, { decision: "allow" });
+        }
+    }
+    /**
+     * Which workflow decides where this conversation's files go.
+     *
+     * The workspace must not move between turns of one conversation: a file
+     * written in the previous message has to still be there in the next. The
+     * message's own `workflow_id` is not stable enough to key it on — the client
+     * attaches the id it has when it sends, so a turn sent before the thread list
+     * loaded carries none, resolves the default workspace instead of the
+     * workflow's, and the files the agent wrote a moment ago read as wiped. The
+     * thread's binding is the durable one, so it fills in whenever the message
+     * omits it.
+     */
+    async threadWorkspaceWorkflowId(userId, threadId, messageWorkflowId) {
+        if (messageWorkflowId)
+            return messageWorkflowId;
+        if (!threadId)
+            return null;
+        try {
+            const thread = await Thread.find(userId, threadId);
+            return isNonEmptyString(thread?.workflow_id) ? thread.workflow_id : null;
+        }
+        catch (err) {
+            this.session.logError("thread workspace lookup failed", err);
+            return null;
+        }
+    }
+    async ensureThreadExists(threadId, workflowId, projectId) {
+        const userId = this.session.requireUserId();
+        if (!threadId) {
+            if (projectId && projectId !== "default") {
+                await Project.requireOwned(userId, projectId);
+            }
+            const thread = await Thread.create({
+                user_id: userId,
+                workflow_id: workflowId ?? null,
+                project_id: projectId ?? "default",
+                title: ""
+            });
+            return thread.id;
+        }
+        const existing = await Thread.find(userId, threadId);
+        if (existing)
+            return existing.id;
+        const thread = await Thread.create({
+            id: threadId,
+            user_id: userId,
+            workflow_id: workflowId ?? null,
+            project_id: projectId ?? "default",
+            title: ""
+        });
+        return thread.id;
+    }
+    /**
+     * Save a message dict to the database.
+     * Mirrors Python's _save_message_to_db_async: pops id, type, user_id before create.
+     */
+    async saveMessageToDb(messageData) {
+        const data = { ...messageData };
+        delete data.id;
+        delete data.type;
+        const threadId = isString(data.thread_id) ? data.thread_id : "";
+        delete data.thread_id;
+        const userId = this.session.requireUserId();
+        delete data.user_id;
+        const message = await Message.create({ thread_id: threadId, user_id: userId, ...data });
+        const scope = getRunTraceScope();
+        if (scope) {
+            await registerRunTraceParent(userId, scope.runId, { kind: "message", id: message.id });
+        }
+        return message;
+    }
+    /**
+     * Persist raw image bytes carried on an assistant message (native providers
+     * that run a server-side image tool emit them inline) as real assets, and
+     * rewrite each such block to the wire shape `{ type: "image_url", image: {
+     * type: "image", asset_id, mimeType } }`. Blocks that already reference an
+     * asset (uri / asset_id, no raw data) and non-image blocks pass through
+     * untouched. Raw base64 is never persisted or sent.
+     */
+    async materializeAssistantImageContent(content, userId, workflowId, projectId = "default") {
+        const out = [];
+        for (const block of content) {
+            if (block.type !== "image_url") {
+                out.push({ ...block });
+                continue;
+            }
+            const image = block.image;
+            const rawData = image.data;
+            let bytes = null;
+            if (rawData instanceof Uint8Array) {
+                bytes = rawData;
+            }
+            else if (isString(rawData) && rawData) {
+                bytes = new Uint8Array(Buffer.from(rawData, "base64"));
+            }
+            if (!bytes) {
+                // Already an asset/uri reference (or empty) — leave as-is.
+                out.push({ ...block });
+                continue;
+            }
+            const mimeType = isString(image.mimeType) ? image.mimeType : "image/png";
+            const ext = IMAGE_MIME_TO_EXT[mimeType] ?? "png";
+            // Per-block isolation: a storage failure must not abort the whole turn —
+            // the image is already generated (and billed), and the assistant text
+            // plus any sibling images should still reach the user. Degrade the
+            // failed block to a text notice; never fall back to raw base64.
+            try {
+                const asset = new Asset({
+                    user_id: userId,
+                    workflow_id: workflowId ?? null,
+                    project_id: projectId,
+                    name: `image_${Date.now()}`,
+                    content_type: mimeType,
+                    // Home — see the chat media generation path.
+                    parent_id: userId
+                });
+                const fileName = `${asset.id}.${ext}`;
+                await storeAssetWithThumbnail(asset.user_id, asset.id, fileName, bytes, mimeType);
+                asset.size = bytes.length;
+                await asset.save();
+                // The DB / wire shape mirrors handleMediaGenerationMessage: an asset_id
+                // reference (never raw bytes). resolveContentUrls / resolveContentForProvider
+                // dereference asset_id on the way out and on the next turn.
+                out.push({
+                    type: "image_url",
+                    image: { type: "image", asset_id: asset.id, mimeType }
+                });
+            }
+            catch (err) {
+                log.error("Failed to store generated image as asset", {
+                    error: err instanceof Error ? err.message : String(err)
+                });
+                out.push({
+                    type: "text",
+                    text: "[a generated image could not be saved]"
+                });
+            }
+        }
+        return out;
+    }
+    /**
+     * Recursively process tool results, handling asset-like objects.
+     * Mirrors Python's RegularChatProcessor._process_tool_result().
+     *
+     * - Asset-like objects (have type + uri/data): materialized via storage
+     * - Date/datetime: converted to ISO string
+     * - Arrays/objects: recursed into
+     * - Primitives: returned as-is
+     */
+    // HOLDOUT (anti-slop/no-unknown-returns): a tool result is an arbitrary
+    // value — the same open domain `ProcessingContext.normalizeOutputValue`
+    // rewrites — and this walk answers in that domain.
+    async processToolResult(obj, ctx) {
+        if (obj === null || obj === undefined)
+            return obj;
+        // Asset-like objects: { type: "image"|"audio"|"video"|..., uri?: string, data?: ... }
+        if (isRecord(obj)) {
+            const record = obj;
+            // Check if it's an asset-like object (has type + uri or data)
+            if ("type" in record &&
+                ("uri" in record || "data" in record || "asset_id" in record)) {
+                // Use ProcessingContext's normalizeOutputValue to handle asset materialization
+                return ctx.normalizeOutputValue(record, "storage_url");
+            }
+            // Date objects
+            if (obj instanceof Date) {
+                return obj.toISOString();
+            }
+            // Regular objects — recurse into values
+            const result = {};
+            for (const [key, value] of Object.entries(record)) {
+                result[key] = await this.processToolResult(value, ctx);
+            }
+            return result;
+        }
+        // Arrays — recurse into items
+        if (Array.isArray(obj)) {
+            return Promise.all(obj.map((item) => this.processToolResult(item, ctx)));
+        }
+        // Uint8Array/Buffer — store as asset
+        if (obj instanceof Uint8Array) {
+            if (!ctx.storage)
+                return obj;
+            const key = `assets/${randomUUID()}.bin`;
+            const uri = await ctx.storage.store(key, obj);
+            return { type: "asset", uri };
+        }
+        // Primitives
+        return obj;
+    }
+    /**
+     * Persist image bytes to temp storage and return a handle `view_image` can
+     * resolve — a bare `<uuid>.<ext>` storage key. No DB asset row is created, so
+     * these captures never clutter the user's asset library; the bytes live only
+     * in the request's temp storage. Returns null if there is no storage adapter
+     * or the write fails.
+     */
+    async storeTempImageAsset(ctx, bytes, mimeType) {
+        if (!ctx.storage)
+            return null;
+        const ext = IMAGE_MIME_TO_EXT[mimeType] ?? "png";
+        const key = `${randomUUID()}.${ext}`;
+        try {
+            await ctx.storage.store(key, bytes, mimeType);
+            registerTemporaryImageHandle(ctx, key);
+            return key;
+        }
+        catch (err) {
+            log.error("Failed to store temp image asset", {
+                error: err instanceof Error ? err.message : String(err)
+            });
+            return null;
+        }
+    }
+    /**
+     * Replace embedded image pixels in a tool result — timeline `frames[]` or an
+     * `image_content` blob (e.g. `ui_3d_capture_view`) — with temp-asset handles.
+     * The model receives a handle and an instruction to call `view_image`, which
+     * is the single mechanism that pulls pixels into context. Keeps image bytes
+     * out of the standing chat history. Non-image results pass through untouched.
+     */
+    // HOLDOUT (anti-slop/no-unknown-returns): same open tool-result domain as
+    // `processToolResult`; non-image results pass through untouched.
+    async materializeToolResultImages(toolResult, ctx) {
+        if (!isRecord(toolResult)) {
+            return toolResult;
+        }
+        const record = toolResult;
+        const handleFor = async (payload) => {
+            if (!payload)
+                return null;
+            if ("uri" in payload)
+                return payload.uri;
+            return this.storeTempImageAsset(ctx, payload.bytes, payload.mimeType);
+        };
+        // Timeline frames → one image handle per frame.
+        if (Array.isArray(record.frames)) {
+            const handles = [];
+            let stored = 0;
+            for (const frame of record.frames) {
+                if (!isObjectLike(frame)) {
+                    handles.push(frame);
+                    continue;
+                }
+                const f = { ...frame };
+                const payload = extractEmbeddedImage({
+                    uri: f.dataUrl,
+                    mimeType: "image/jpeg"
+                });
+                delete f.dataUrl;
+                const id = await handleFor(payload);
+                if (id) {
+                    f.image_id = id;
+                    stored++;
+                }
+                handles.push(f);
+            }
+            const out = { ...record, frames: handles };
+            if (stored > 0) {
+                out.note = `Captured ${stored} timeline frame(s) as image assets. Call view_image({ image_id }) to inspect a frame.`;
+            }
+            return out;
+        }
+        // Single image_content blob → one image handle.
+        if (isObjectLike(record.image_content)) {
+            const payload = extractEmbeddedImage(record.image_content);
+            const id = await handleFor(payload);
+            const out = { ...record };
+            delete out.image_content;
+            if (id) {
+                out.image_id = id;
+                const base = isString(record.note) ? record.note : "Captured an image.";
+                out.note = `${base} Saved as image asset "${id}". Call view_image({ image_id: "${id}" }) to inspect it.`;
+            }
+            return out;
+        }
+        return toolResult;
+    }
+    /**
+     * Render the turn's memory block.
+     *
+     * Memory is user-scoped, but only **this thread's** memories are pasted in:
+     * the store grows for the life of the account, and a block that grew with it
+     * would eventually cost more than the turn. What the agent gets instead is
+     * this thread's notes in full plus a count of the ones saved elsewhere, so
+     * it knows to reach them with `memory_search` rather than assume the block
+     * is everything.
+     *
+     * Resource refs are used as stored (asset refs already carry the `asset://`
+     * uri captured at save time) — one indexed query, no per-asset lookups on
+     * the hot path. Best-effort: a DB hiccup returns an empty block rather than
+     * breaking the turn.
+     */
+    async buildMemoryBlock(userId, threadId) {
+        try {
+            // One read over the user's newest memories, split by thread here rather
+            // than issuing a second count query.
+            const recent = await Memory.list(userId, { limit: MEMORY_SCAN_LIMIT });
+            const mine = recent.filter((memory) => memory.thread_id === threadId);
+            const elsewhere = recent.length - mine.length;
+            if (mine.length === 0 && elsewhere === 0)
+                return "";
+            // Stored with full ids; shown with short ones, which every capability
+            // accepts back. Free text is only rewritten where the scheme types the
+            // id (`asset://…`), so a hash in a note stays intact.
+            const rendered = mine.slice(0, MEMORY_BLOCK_LIMIT).map((memory) => ({
+                kind: memory.kind,
+                title: memory.title,
+                content: compactAssetUris(memory.content),
+                resources: compactResourceIds(Array.isArray(memory.resources) ? memory.resources : [])
+            }));
+            return formatMemoriesForPrompt(rendered, elsewhere);
+        }
+        catch (err) {
+            log.warn("Failed to build memory block", {
+                threadId,
+                error: err instanceof Error ? err.message : String(err)
+            });
+            return "";
+        }
+    }
+    async buildGenerationBlock(userId, threadId) {
+        try {
+            const [rows, next] = await Prediction.listGenerations(userId, {
+                threadId,
+                limit: 50
+            });
+            if (rows.length === 0)
+                return "";
+            const generations = rows.map((row) => ({
+                generation_id: row.id,
+                status: row.status,
+                model: row.model,
+                capability: row.capability,
+                tool_call_id: row.tool_call_id,
+                asset_uris: (row.asset_ids ?? []).map((id) => `asset://${id}`)
+            }));
+            return [
+                "Saved generations for this conversation (database snapshot):",
+                JSON.stringify(generations),
+                "Reuse completed assets. A missing tool response does not mean the generation failed. " +
+                    "Use get_generation or await_generation to check pending work before starting another paid render. " +
+                    "An interrupted record does not prove that the provider cancelled its request.",
+                next
+                    ? "Older records are available through list_generations with this thread_id."
+                    : ""
+            ]
+                .filter(Boolean)
+                .join("\n");
+        }
+        catch (error) {
+            log.warn("Failed to load conversation generations", {
+                threadId,
+                error: error instanceof Error ? error.message : String(error)
+            });
+            return "Generation history is temporarily unavailable. Check list_generations before retrying earlier renders.";
+        }
+    }
+    /**
+     * The user's skills, read once per turn.
+     *
+     * Two halves with different lifetimes, which is why the caller splits them.
+     * The catalog (name + description) changes only when the skills table does,
+     * so it belongs in the system prompt where a provider's automatic prefix
+     * cache can keep it. The body of a skill the message invoked with `/<name>`
+     * changes per turn, so it rides at the tail with the other volatile context.
+     *
+     * Best-effort like the memory block: a DB hiccup costs the skills, not the
+     * turn.
+     */
+    async loadUserSkills(userId) {
+        let rows = [];
+        try {
+            rows = await Skill.listByUser(userId);
+        }
+        catch (err) {
+            log.warn("Failed to load user skills", {
+                error: err instanceof Error ? err.message : String(err)
+            });
+        }
+        // The shipped skills ride in the same catalog. They come off disk rather
+        // than the table, so a DB hiccup costs the user's own rows and not these.
+        return mergeSystemSkills(rows.map((row) => ({
+            name: row.name,
+            description: row.description,
+            content: row.content
+        })));
+    }
+    /**
+     * Round-trip a permission approval to the client and resolve with the
+     * user's decision. Emits a `tool_approval_request`, then waits for the
+     * matching `tool_approval_response` (resolved via {@link approvalBridge}).
+     * A cancelled wait (stop) is treated as a denial.
+     */
+    async requestToolApproval(threadId, request) {
+        const approvalId = `appr_${randomUUID()}`;
+        await this.session.send({
+            type: "tool_approval_request",
+            thread_id: threadId,
+            approval_id: approvalId,
+            tool_name: request.toolName,
+            category: request.category,
+            message: request.message,
+            description: request.description ?? "",
+            args: request.args
+        });
+        try {
+            // No timeout — the user may take a while; `stop` cancels this thread.
+            const response = await this.deps.approvalBridge.createWaiter(approvalId, 0, threadId);
+            const decision = response.decision;
+            if (decision === "allow" ||
+                decision === "allow_for_chat" ||
+                decision === "deny") {
+                return decision;
+            }
+            return "deny";
+        }
+        catch {
+            // Cancelled (generation stopped) — treat as a denial.
+            return "deny";
+        }
+    }
+    /**
+     * Open the bespoke secret dialog on the client and resolve with what the
+     * user did — never with what they typed.
+     *
+     * The value does not travel over this socket in either direction. The
+     * dialog writes it with the client's own `settings.secrets.upsert` call, so
+     * the credential never enters the chat transcript, the run's message log, or
+     * the model's context; this frame only asks, and the response only reports.
+     *
+     * A cancelled wait (the user pressed Stop) is a decline, which is the same
+     * fail-closed reading the approval prompts take.
+     */
+    async requestSecretEntry(threadId, request) {
+        const approvalId = `secret_${randomUUID()}`;
+        await this.session.send({
+            type: "secret_request",
+            thread_id: threadId,
+            approval_id: approvalId,
+            key: request.key,
+            description: request.description ?? null,
+            reason: request.reason ?? null,
+            help_url: request.helpUrl ?? null
+        });
+        try {
+            // No timeout — finding an API key takes as long as it takes; `stop`
+            // cancels this thread.
+            const response = await this.deps.approvalBridge.createWaiter(approvalId, 0, threadId);
+            return response.status === "saved" ? "saved" : "declined";
+        }
+        catch {
+            return "declined";
+        }
+    }
+    /**
+     * Execute a single node by type and return its output. Builds a one-node
+     * graph and runs it through a fresh `ExecutionSession` (@nodetool-ai/execution),
+     * then returns the
+     * node's completed result. Backs the `run_node` chat tool.
+     */
+    // HOLDOUT (anti-slop/no-unknown-returns): answers with the node's own output
+    // — an arbitrary workflow value — or an `{ error }` bag when the run failed.
+    async runSingleNode(nodeType, inputs, userId, projectId = null, 
+    /** The calling turn's gate, when a chat turn is what started this node. */
+    gate = null) {
+        const jobId = randomUUID();
+        const nodeId = "node_0";
+        const rawGraph = {
+            nodes: [{ id: nodeId, type: nodeType, data: inputs ?? {} }],
+            edges: []
+        };
+        let graph;
+        try {
+            graph = await this.deps.hydrateGraph(rawGraph);
+        }
+        catch (err) {
+            return {
+                error: `Failed to prepare node '${nodeType}': ${err instanceof Error ? err.message : String(err)}`
+            };
+        }
+        if (this.deps.beforeRunJob) {
+            try {
+                await this.deps.beforeRunJob(graph);
+            }
+            catch (err) {
+                return {
+                    error: `Node prerequisites failed: ${err instanceof Error ? err.message : String(err)}`
+                };
+            }
+        }
+        const context = createRuntimeContext({
+            jobId,
+            workflowId: null,
+            projectId,
+            userId,
+            workspace: this.session.workspaceResolver
+                ? await this.session.workspaceResolver(null, userId)
+                : null,
+            assetOutputMode: this.session.mode === "text" ? "data_uri" : "temp_url"
+        });
+        context.runTraceContext = getRunTraceScope() ?? null;
+        // This context is built here rather than copied from the turn, so the
+        // turn's gate has to be put on it by hand. The node's own loops read it
+        // with `gateFromContext`; a node run outside a chat turn carries none and
+        // gates headless.
+        if (gate)
+            context.set(PERMISSION_GATE_CONTEXT_KEY, gate);
+        context.setResolveExecutor((node) => this.session.resolveExecutor(node));
+        if (this.session.resolveNodeType) {
+            const resolverObj = isFunctionValue(this.session.resolveNodeType)
+                ? { resolveNodeType: this.session.resolveNodeType }
+                : this.session.resolveNodeType;
+            context.setResolveNodeType((type) => resolverObj.resolveNodeType(type));
+        }
+        // A node selecting a model this runtime cannot honour is refused before
+        // the kernel starts; the tool answers with the reason, like every other
+        // preparation failure here.
+        let session;
+        try {
+            session = await ExecutionSession.create({
+                graph: toRawGraphInput(graph),
+                resolveExecutor: (node) => this.session.resolveExecutor(node),
+                bridgeFactory: async () => null,
+                jobLifecycleBridge: this.session.pythonBridge ?? null,
+                jobId,
+                context,
+                params: {},
+                // A node run from a project's agent thread is that project's spend;
+                // the ledger this session attaches writes it. Null outside a project.
+                projectId: projectId ?? null,
+                validateNode: this.session.validateNode
+            });
+        }
+        catch (err) {
+            if (!isExecutionPreflightError(err))
+                throw err;
+            return { error: err.message };
+        }
+        const result = await session.result;
+        // Capture the node's completed result from the streamed updates.
+        let nodeResult;
+        while (context.hasMessages()) {
+            const msg = context.popMessage();
+            if (msg &&
+                msg.type === "node_update" &&
+                msg.node_id === nodeId &&
+                msg.status === "completed" &&
+                msg.result != null) {
+                nodeResult = msg.result;
+            }
+        }
+        if (result.status === "failed") {
+            return { error: result.error ?? `Node '${nodeType}' failed` };
+        }
+        if (nodeResult === undefined) {
+            // Fall back to the runner's collected outputs (e.g. Output nodes).
+            return result.outputs ?? { status: result.status };
+        }
+        return this.processToolResult(nodeResult, context);
+    }
+    /**
+     * Handle an incoming chat message.
+     *
+     * Mirrors Python's full 3-layer flow:
+     *   handle_chat_message → handle_message_impl → process_messages
+     *     → _run_processor + RegularChatProcessor.process()
+     *
+     * The processor sends messages to a queue. _run_processor reads them:
+     *   - type === "message" → persist to DB AND forward to client
+     *   - anything else → forward to client only
+     *
+     * RegularChatProcessor.process():
+     *   1. Prepend system prompt if first message isn't system role
+     *   2. while True: messages_to_send = chat_history + unprocessed_messages
+     *   3. Stream chunks (type: "chunk") — forwarded to client (not persisted)
+     *   4. On tool call: build assistant Message + tool result Message (type: "message")
+     *      → persisted to DB AND forwarded to client
+     *   5. If unprocessed_messages empty, break
+     *   6. Send done chunk + final assistant Message
+     */
+    async handleChatMessage(data, requestSeq, signal) {
+        const messageWorkflowId = isString(data.workflow_id)
+            ? data.workflow_id
+            : null;
+        const threadId = await this.ensureThreadExists(isString(data.thread_id) ? data.thread_id : undefined, messageWorkflowId, isString(data.project_id) ? data.project_id : undefined);
+        data.thread_id = threadId;
+        // Route this turn takes: a workflow chatbot and a media generation carry
+        // their own model selection (checked in their handlers), a plain chat turn
+        // is served by the language model the composer picked.
+        const workflowTargetHint = isString(data.workflow_target)
+            ? data.workflow_target
+            : null;
+        const mediaModeHint = isObjectLike(data.media_generation)
+            ? data.media_generation.mode
+            : null;
+        const isPlainChatTurn = workflowTargetHint !== "workflow" &&
+            (!isString(mediaModeHint) || mediaModeHint === "chat");
+        // A plain chat turn without a chosen model used to fall through to the
+        // built-in default and die deep in provider resolution ("No provider
+        // registered for \"empty\"") — after the user's message had been
+        // persisted. Reject it up front and say what to do instead.
+        if (isPlainChatTurn && !isModelSelection(data.provider, data.model)) {
+            await this.session.send({
+                type: "error",
+                message: NO_MODEL_SELECTED_MESSAGE,
+                thread_id: threadId
+            });
+            return;
+        }
+        // Apply defaults — matches Python's handle_chat_message
+        if (!data.model)
+            data.model = this.deps.defaults.model;
+        if (!data.provider)
+            data.provider = this.deps.defaults.provider;
+        const providerId = data.provider;
+        const model = data.model;
+        const workflowId = messageWorkflowId;
+        const userId = this.session.requireUserId();
+        log.debug("Chat message", { threadId, model, provider: providerId });
+        // Save user message to DB — matches Python's _save_message_to_db_async(data)
+        const turnMessage = await this.saveMessageToDb(data);
+        const rootContext = createRuntimeContext({ jobId: turnMessage.id, threadId, workflowId, userId, workspace: null });
+        await registerChatRunTrace(rootContext, { messageId: turnMessage.id, threadId });
+        return withRegisteredRunTrace(rootContext, "chat.turn", async () => {
+            try {
+                if (await threadHasTraceContentTools(userId, threadId, restrictedTraceToolNames())) {
+                    suppressRunTraceContent();
+                }
+                await this.handlePersistedChatTurn(data, turnMessage, rootContext, requestSeq, signal);
+                await settleRegisteredRunTrace(rootContext, signal?.aborted ? "cancelled" : "completed");
+            }
+            catch (error) {
+                await settleRegisteredRunTrace(rootContext, signal?.aborted ? "cancelled" : "failed", error instanceof Error ? error.message : String(error));
+                throw error;
+            }
+        });
+    }
+    async handlePersistedChatTurn(data, turnMessage, rootContext, requestSeq, signal) {
+        const threadId = String(data.thread_id);
+        const workflowId = isString(data.workflow_id) ? data.workflow_id : null;
+        const userId = this.session.requireUserId();
+        const providerId = String(data.provider);
+        const model = String(data.model);
+        if (requestSeq !== undefined && requestSeq !== this.chatRequestSeq)
+            return;
+        if (!this.session.resolveProvider) {
+            await settleRegisteredRunTrace(rootContext, "failed", "No provider resolver configured");
+            await this.session.send({
+                type: "error",
+                message: "No provider resolver configured",
+                thread_id: threadId
+            });
+            return;
+        }
+        // Route to the workflow processor ONLY when the client explicitly opts in
+        // via `workflow_target: "workflow"`. A bare `workflow_id` is context, not a
+        // routing signal: the editor binds the open workflow so `ui_*` tools target
+        // it, and that ambient id must not hijack the turn into running the
+        // workflow as a chatbot. Genuine workflow-chatbot runs set `workflow_target`
+        // (and carry `workflow_id`/`graph` for the processor to load/execute).
+        const workflowTarget = isString(data.workflow_target)
+            ? data.workflow_target
+            : null;
+        if (workflowTarget === "workflow") {
+            await this.handleWorkflowMessage(data, requestSeq, signal);
+            return;
+        }
+        // Route to media generation when the client requests a text-to-image or
+        // text-to-video turn. The composer attaches a `media_generation` field
+        // with mode + params; when mode is a media mode we invoke the provider's
+        // textToImage / textToVideo instead of a regular LLM round and return an
+        // assistant message containing MessageImageContent / MessageVideoContent.
+        const mediaGeneration = isObjectLike(data.media_generation)
+            ? data.media_generation
+            : null;
+        if (mediaGeneration &&
+            isString(mediaGeneration.mode) &&
+            mediaGeneration.mode !== "chat") {
+            await this.handleMediaGenerationMessage(data, mediaGeneration, requestSeq, signal);
+            return;
+        }
+        const provider = await this.session.resolveProvider(providerId, userId);
+        // Permission mode for this turn. Governs whether gated tool calls run,
+        // ask for approval, or are blocked. Defaults to "default".
+        const permissionMode = data.permission_mode === "plan" ||
+            data.permission_mode === "auto" ||
+            data.permission_mode === "default"
+            ? data.permission_mode
+            : "default";
+        // A surface can send a context-specific system-prompt addendum (e.g. the
+        // App Builder's build-an-app-UI guidance), layered after the base prompt.
+        const extraSystemPrompt = isString(data.system_prompt)
+            ? data.system_prompt
+            : null;
+        // Which documents the user has open, and which one has focus. The `ui_*`
+        // tools all require an explicit document id, so this is what makes them
+        // usable — see `formatUiContext`.
+        const uiContext = isObjectLike(data.ui_context)
+            ? data.ui_context
+            : null;
+        // History load. Session-based providers (e.g. claude_agent) keep the
+        // conversation upstream, so when a resumable session exists for this
+        // provider+model we do NOT reload the whole thread: we probe a bounded
+        // recent window, send only the turns since the session, and hand the
+        // provider a `loadFullHistory` thunk it calls only if it must prime context
+        // (resume failed / system prompt changed). Otherwise we load the full
+        // history and use the standard slice-based resume. The DB column is the
+        // source of truth; the provider also keeps an in-process cache.
+        // The action contract + tool catalog section, assigned once the codeact
+        // session exists (before the system message is materialized). Read lazily
+        // here because the resume `loadFullHistory` thunk and the prepend both run
+        // after tool resolution.
+        let codeactPromptSection = "";
+        // The user's skills, read once. The catalog goes into the system prompt
+        // below because it is stable — it changes only when the skills table does,
+        // so a provider's prefix cache keeps it across turns. The body of an
+        // invoked skill is volatile and rides at the tail instead.
+        const userSkills = await this.loadUserSkills(userId);
+        const skillCatalogSection = formatSkillCatalogForPrompt(userSkills);
+        const buildSystemContent = () => {
+            const base = buildChatAgentSystemPrompt(permissionMode, extraSystemPrompt, uiContext, workflowId);
+            const sections = [base];
+            if (codeactPromptSection)
+                sections.push(codeactPromptSection);
+            if (skillCatalogSection)
+                sections.push(skillCatalogSection);
+            return sections.join("\n\n");
+        };
+        const systemChatMessage = () => ({
+            role: "system",
+            content: buildSystemContent(),
+            toolCallId: null,
+            toolCalls: null,
+            threadId: null
+        });
+        const copiedMessageIds = new Set();
+        const convertDbMessages = (rows) => {
+            const out = [];
+            for (const m of rows) {
+                copiedMessageIds.add(m.id);
+                seedStoredToolProvenance([m]);
+                const pm = dbMessageToProviderMessage(m, this.session.userId);
+                if (pm)
+                    out.push(pm);
+            }
+            // A thread that took an interleave before this was fixed still holds a
+            // tool call with no result. Anthropic 400s on one, so loading such a
+            // thread under a different provider or model would fail every turn from
+            // here on. Patch the history we send; the stored rows are left alone.
+            return repairOrphanedToolCalls(out);
+        };
+        let chatHistory;
+        let priorSession = null;
+        // The provider calls this only on a priming fallback; null on the full path.
+        let loadFullHistory = null;
+        // Absolute checkpoint to persist on the assistant message when the fast path
+        // sent only a delta (so the stored value matches the full-load path); null
+        // when the provider's own checkpoint is already absolute.
+        let sessionCheckpointOverride = null;
+        {
+            const [recent] = await Message.paginate(threadId, {
+                reverse: true,
+                limit: SESSION_PROBE_WINDOW
+            });
+            seedStoredToolProvenance(recent);
+            const probeHasWholeThread = recent.length < SESSION_PROBE_WINDOW;
+            // `recent` is newest-first. Walk to the first boundary marker: an
+            // assistant carrying a session token, or a compaction record. Both claim
+            // to say where history starts, and whichever is newer wins — the walk
+            // meets it first, so the loop decides by stopping.
+            //
+            // A compaction newer than the session must win: the upstream transcript
+            // that session token resumes is the very history compaction just replaced,
+            // so resuming it would send back everything the cut removed (and the cut
+            // usually happened because that transcript no longer fits).
+            let probeSession = null;
+            let probeCompaction = null;
+            const sinceMarkerNewestFirst = [];
+            for (const m of recent) {
+                if (isCompactionMessage(m)) {
+                    probeCompaction = m;
+                    break;
+                }
+                if (m.role === "assistant" && m.provider_session) {
+                    const s = m.provider_session;
+                    if (s.providerId === providerId && s.model === model)
+                        probeSession = s;
+                    break;
+                }
+                sinceMarkerNewestFirst.push(m);
+            }
+            if (probeCompaction) {
+                // COMPACTED path: the summary row plus everything after it, already in
+                // hand from the probe. No session resumes across a compaction, so
+                // `priorSession` stays null and the provider rebuilds from these rows.
+                chatHistory = convertDbMessages([
+                    probeCompaction,
+                    ...sinceMarkerNewestFirst.reverse()
+                ]);
+            }
+            else if (probeSession) {
+                // RESUME fast path: the SDK already holds the prior turns, so send only
+                // the messages since the session — no full-thread load.
+                const newTurns = convertDbMessages(sinceMarkerNewestFirst.reverse());
+                chatHistory = newTurns;
+                // The single system message prepended below sits at index 0, so the new
+                // turns begin at index 1 (the provider's relative resume checkpoint).
+                priorSession = {
+                    providerId,
+                    model,
+                    token: probeSession.token,
+                    systemHash: probeSession.systemHash,
+                    checkpoint: 1
+                };
+                if (probeSession.traceContentSuppressed) {
+                    priorSession.traceContentSuppressed = true;
+                }
+                // Absolute position to persist: prior prefix + the prior assistant + the
+                // new turns — identical to what the full-load path would store.
+                sessionCheckpointOverride =
+                    probeSession.checkpoint + 1 + newTurns.length;
+                loadFullHistory = async () => {
+                    const [rows] = await Message.paginate(threadId, { limit: 1000 });
+                    const full = convertDbMessages(historySinceCompaction(rows));
+                    full.unshift(systemChatMessage());
+                    const scope = getRunTraceScope();
+                    if (scope) {
+                        await registerRunTraceParents(userId, scope.runId, [...copiedMessageIds].map((id) => ({ kind: "message", id })));
+                    }
+                    return full;
+                };
+            }
+            else if (probeHasWholeThread) {
+                // The whole thread fit in the probe window — reuse it, no second query.
+                const rows = historySinceCompaction([...recent].reverse());
+                chatHistory = convertDbMessages(rows);
+                priorSession = lastMatchingProviderSession(rows, providerId, model);
+            }
+            else {
+                // Long thread without a resumable session in the recent window: load it
+                // all (a far-back session still resumes via the slice path). A session
+                // older than the compaction cut is not one of them: searching only the
+                // compacted slice is what keeps the newest marker winning here too.
+                const [rows] = await Message.paginate(threadId, { limit: 1000 });
+                const kept = historySinceCompaction(rows);
+                chatHistory = convertDbMessages(kept);
+                priorSession = lastMatchingProviderSession(kept, providerId, model);
+            }
+        }
+        if (priorSession?.traceContentSuppressed) {
+            suppressRunTraceContent();
+        }
+        // Expose the read-only `run_search` fan-out primitive by default. A client
+        // can opt out by sending `enable_read_only_search: false`.
+        const enableReadOnlySearch = data.enable_read_only_search !== false;
+        // Assemble the fixed, always-on toolbelt. There is no per-message tool
+        // selection anymore — the agent reasons over the full toolbelt and the
+        // permission gate (below) governs execution.
+        // Google Workspace runs on the token from the user's Google sign-in, so it
+        // only exists on deployments that have a login. Local mode never sees it.
+        const googleWorkspace = isGoogleWorkspaceEnabled();
+        const chatProviders = await this.deps.configuredProviders(userId);
+        // The project this conversation belongs to, when it is a project's own
+        // agent thread. Documents the turn creates land in it rather than in the
+        // loose bucket, without the model having to pass `project_id` every time,
+        // and everything the turn spends is billed to it.
+        const chatProjectId = (await Project.findByThread(userId, threadId))?.id ?? undefined;
+        // The permission gate the belt is wrapped in below. Built before the belt
+        // because the Apify tools carry it into their own run: in discovery mode
+        // the actor policy asks this gate to approve an actor the install has not
+        // allowlisted, so the user sees that question in the same place as every
+        // other permission prompt. The session allow-set is shared per thread so
+        // "Allow for this chat" sticks.
+        const sessionAllow = this.chatSessionAllow.get(threadId) ?? new Set();
+        this.chatSessionAllow.set(threadId, sessionAllow);
+        // A gated call inside a code action parks the guest program until the user
+        // answers, and the gate stops the clock for exactly that long — the wait is
+        // the user's, not the program's, and charged to the action's wall clock it
+        // would kill the very program that asked.
+        const codeactClock = createSandboxClock();
+        const liveMode = { value: permissionMode };
+        this.chatTurnPermissionMode.set(threadId, liveMode);
+        const chatGate = {
+            get mode() {
+                return liveMode.value;
+            },
+            sessionAllow,
+            requestApproval: async (request) => this.requestToolApproval(threadId, request),
+            clock: codeactClock
+        };
+        // The single-node runner is a closure only this package can build, so
+        // `run_node` reaches a capability run as a host-supplied capability rather
+        // than out of the registry. It runs the node on a context of its own, so
+        // the turn's gate is handed over explicitly — without it an agent loop
+        // inside the node finds no gate and runs headless, and approving
+        // `run_node` becomes approval for whatever the node then calls.
+        const runNodeTool = new RunNodeTool((nodeType, inputs) => this.runSingleNode(nodeType, inputs, userId, chatProjectId, chatGate));
+        // The bounds this turn runs under, created once and shared by everything
+        // it starts (invariant I-2). A loop that made its own would hand every
+        // nested agent a fresh allowance, which is no ceiling at all.
+        const turnBudget = await createChatTurnBudget();
+        // The user's external MCP servers (Blender, Hugging Face, …). Their tools
+        // are plain belt tools named `mcp_<server>_<tool>`, so every loop reaches
+        // them the same way; a server that does not answer is skipped, not fatal.
+        let externalMcpTools = [];
+        try {
+            externalMcpTools = await externalMcpToolsFor(userId);
+        }
+        catch (err) {
+            log.warn("External MCP tools unavailable for this turn", {
+                error: err instanceof Error ? err.message : String(err)
+            });
+        }
+        const legacyCapabilities = [runNodeTool, ...externalMcpTools].map(capabilityFromTool);
+        const nativeSpecs = [
+            ...availableBuiltinToolNames().map((name) => capabilityForName(name).spec),
+            ...(googleWorkspace ? GOOGLE_WORKSPACE_TOOL_NAMES : []).map((name) => capabilityForName(name).spec),
+            ...[...APIFY_TOOL_NAMES, ...SERPAPI_TOOL_NAMES].map((name) => capabilityForName(name).spec),
+            ...getAllMcpCapabilitySpecs({ registry: this.session.nodeRegistry, providers: chatProviders }),
+            capabilityForName("list_collections").spec,
+            capabilityForName("query_collection").spec
+        ];
+        const specsByName = new Map();
+        for (const spec of [...nativeSpecs, ...legacyCapabilities.map((entry) => entry.spec)]) {
+            if (!specsByName.has(spec.name)) {
+                specsByName.set(spec.name, spec);
+            }
+        }
+        const baseSpecs = [...specsByName.values()];
+        const legacyByName = new Map(legacyCapabilities.map((entry) => [entry.spec.name, entry]));
+        // Delegated executors still consume Tool[]. Adapt only at that boundary.
+        // Each child context owns a separate run so its memory and depth are local.
+        const childRuns = new WeakMap();
+        const childRun = (context) => {
+            let run = childRuns.get(context);
+            if (!run) {
+                run = createCapabilityRun({
+                    context, gate: chatGate, nodeRegistry: this.session.nodeRegistry,
+                    providers: chatProviders, budget: turnBudget,
+                    availableSecrets: contextSecretAvailability(context),
+                    ...mcpToolHostDeps(), capabilities: legacyCapabilities
+                });
+                childRuns.set(context, run);
+            }
+            return run;
+        };
+        const baseTools = baseSpecs.map((spec) => {
+            const entry = legacyByName.get(spec.name)
+                ?? capabilityForName(spec.name);
+            return toolFromCapability(entry.spec, entry.impl, childRun);
+        });
+        // Inject the recursive-decomposition primitive (ungated — it spawns a
+        // child loop whose own tools are the gated `baseTools`). Child events
+        // stream back tagged with `parent_tool_call_id` so the UI can nest cards.
+        const serverTools = baseSpecs.slice();
+        // The same runtime the delegation tools take, kept for the capability run
+        // below: provider, model, the parent belt, and the event forwarder.
+        let subAgentRuntime;
+        {
+            const subtaskThreadId = threadId;
+            const subtaskWorkflowId = workflowId;
+            const forwardSubtaskMessage = async (msg) => {
+                const enriched = { ...msg };
+                if (enriched.thread_id == null)
+                    enriched.thread_id = subtaskThreadId;
+                if (enriched.workflow_id == null)
+                    enriched.workflow_id = subtaskWorkflowId;
+                try {
+                    await this.session.send(enriched);
+                    // Tool calls inside a subtask only arrive here as transient
+                    // tool_call_update events; the chat UI needs a persistent assistant
+                    // message with tool_calls to render a ToolCallCard. Emit a synthetic
+                    // one so child tool calls show up as cards nested below the parent
+                    // run_subtask card.
+                    await this.emitSyntheticToolCallCard(enriched);
+                }
+                catch (err) {
+                    log.warn("Failed to forward subtask event", {
+                        error: err instanceof Error ? err.message : String(err)
+                    });
+                }
+            };
+            subAgentRuntime = {
+                provider,
+                model,
+                parentTools: () => baseTools,
+                forwardMessage: forwardSubtaskMessage,
+                background: new BackgroundSubtaskRegistry(),
+                // Every delegated loop reserves against this turn's cap rather than
+                // opening one of its own.
+                budget: turnBudget
+            };
+            // All four delegation tools reach the belt as capabilities over this
+            // runtime. The class is still what runs — the `agents` module builds one
+            // per call — so the depth gate, the child's inherited belt (with a
+            // `run_subtask` of its own stitched in by `buildChildToolset`, since this
+            // snapshot deliberately predates the unshift), and the
+            // `parent_tool_call_id` / `subtask_depth` tagging are unchanged.
+            // `start_subtask` / `wait_subtasks` share the per-turn registry above:
+            // spawn returns immediately, and the parent collects on its own terms.
+            serverTools.unshift(capabilityForName("run_subtask").spec);
+            serverTools.unshift(capabilityForName("start_subtask").spec);
+            serverTools.unshift(capabilityForName("wait_subtasks").spec);
+            // Plan mode's own capability: `create_plan` runs the TaskPlanner over the
+            // objective and streams the plan into the thread, executing nothing. It
+            // is offered only here, because plan mode is the one place where a plan
+            // *is* the deliverable — everywhere else the agent does the work instead
+            // of describing it. The belt is a per-turn snapshot, so this reads the
+            // mode the turn started in — `liveMode` covers a mid-turn switch for the
+            // gate, not for which tools were offered.
+            if (permissionMode === "plan") {
+                serverTools.unshift(capabilityForName("create_plan").spec);
+            }
+            // The other half: `execute_plan` runs a plan the user has already seen,
+            // on the same ParallelTaskExecutor `Agent` uses. It is on the belt in
+            // every mode, gated — in plan mode the gate answers
+            // `blocked_in_plan_mode`, which tells the model to have the user switch
+            // out, where dropping it from the belt entirely would only say the tool
+            // does not exist. It is *offered* everywhere but plan mode, below.
+            serverTools.unshift(capabilityForName("execute_plan").spec);
+            // Read-only fan-out search (opt-in). Reuses the same runtime — the
+            // capability filters the parent belt to its read-only allowlist
+            // internally, so passing the full snapshot is correct.
+            if (enableReadOnlySearch) {
+                serverTools.unshift(capabilityForName("run_search").spec);
+            }
+        }
+        const serverToolMap = new Map(serverTools.map((t) => [t.name, t]));
+        const workflowDocumentToolNames = new Set(WORKFLOW_DOCUMENT_TOOL_NAMES);
+        log.info("Resolved server tools", {
+            permissionMode,
+            resolved: serverTools.map((t) => t.name)
+        });
+        const serverSchemas = serverTools.map((t) => capabilityProviderTool(t));
+        // Every client tool the connected UI registered is exposed. They used to be
+        // gated on an active workflow, which made the editor tools unreachable from
+        // plain chat; they are deferred behind `nodetool.searchTools()` anyway, and each one now
+        // takes an explicit document id, so the gate cost reach without buying
+        // safety. Which ids are valid comes from `ui_context` in the system prompt.
+        const clientToolNames = Object.keys(this.deps.clientTools());
+        const clientSchemas = [];
+        for (const [name, manifest] of Object.entries(this.deps.clientTools())) {
+            if (serverToolMap.has(name))
+                continue;
+            // The frontend manifest carries the JSON schema under `parameters`
+            // (FrontendToolRegistry.getManifest); accept `inputSchema` too for any
+            // client that uses the provider-tool field name.
+            const schema = typeof manifest.parameters === "object"
+                ? manifest.parameters
+                : typeof manifest.inputSchema === "object"
+                    ? manifest.inputSchema
+                    : undefined;
+            clientSchemas.push({
+                name,
+                description: isString(manifest.description)
+                    ? manifest.description
+                    : undefined,
+                inputSchema: schema
+            });
+        }
+        const allSchemas = [...serverSchemas, ...clientSchemas];
+        // A chat turn with tools always runs in CodeAct: the model acts by writing
+        // sandboxed JavaScript over the toolbelt (docs/codeact-design.md), and the
+        // session's in-sandbox `nodetool.searchTools()` is the discovery path. The session
+        // is created below, once the tool router and processing context exist.
+        const useCodeAct = allSchemas.length > 0;
+        // The tool list handed to the provider: `execute_code`, the direct tools
+        // (DIRECT_TOOL_NAMES) and `view_image`, pushed once the session exists.
+        const providerToolSchemas = [];
+        log.info("Provider tool schemas", {
+            permissionMode,
+            serverToolCount: serverTools.length,
+            clientToolCount: clientToolNames.length,
+            codeact: useCodeAct
+        });
+        // Create a processing context for tool execution
+        // A chat turn without a workflow still resolves a workspace — the user's
+        // default one. It used to fall back to the whole OS temp dir, which is
+        // neither bounded nor anywhere the user would look for what an agent wrote.
+        const chatWorkspace = this.session.workspaceResolver
+            ? await this.session.workspaceResolver(await this.threadWorkspaceWorkflowId(userId, threadId, workflowId), userId)
+            : null;
+        const ctx = createRuntimeContext({
+            jobId: randomUUID(),
+            workflowId,
+            threadId: threadId || null,
+            projectId: chatProjectId,
+            userId,
+            workspace: chatWorkspace,
+            authToken: this.deps.authToken()
+        });
+        ctx.runTraceContext = rootContext.runTraceContext;
+        ctx.set("chat_message_id", turnMessage.id);
+        if (ctx.runTraceContext) {
+            await registerRunTraceParents(userId, ctx.runTraceContext.runId, [...copiedMessageIds].map((id) => ({ kind: "message", id })));
+        }
+        const detachPredictions = attachChatPredictionForwarder((listener) => ctx.addMessageListener(listener), (msg) => this.session.sendDetached(msg), { threadId: threadId || null, workflowId });
+        // A chat turn that generates an image or a video spends real money without
+        // ever constructing an ExecutionSession, so the ledger is attached here
+        // too — otherwise the turn is invisible to `nodetool costs`.
+        const detachCostLedger = attachRunCostLedger(ctx, {
+            userId,
+            workflowId: workflowId ?? null,
+            // A project's own thread attributes its spend to that project, so
+            // `nodetool costs` can answer what a project cost.
+            projectId: chatProjectId ?? null,
+            resolveSecret: (key) => ctx.getSecret(key)
+        });
+        // Stamp the turn's own selection so a tool that launches another harness
+        // inherits this chat's provider/model when the call doesn't name one.
+        ctx.set(ACTIVE_MODEL_CONTEXT_KEY, {
+            provider: providerId,
+            model
+        });
+        // The channel every nested loop already carries: an Agent node started
+        // through `run_node`, a JS script, a sub-agent three levels down all read
+        // the budget off the context instead of creating one (`budgetFromContext`).
+        ctx.set(RUN_BUDGET_CONTEXT_KEY, turnBudget);
+        // The same channel carries the turn's permission gate, so a loop this
+        // package never constructs gates through the user's mode instead of
+        // building an ungated run of its own (`gateFromContext`, invariant I-1).
+        // The object is shared by reference: `chatGate.mode` reads `liveMode`, so
+        // a mid-turn `set_permission_mode` reaches a node that started before it.
+        ctx.set(PERMISSION_GATE_CONTEXT_KEY, chatGate);
+        // The capability run for this turn: the same gate the belt is wrapped in,
+        // this context, and the singletons the tool constructors take today. Every
+        // capability a host must supply itself goes in `capabilities` — `run_node`
+        // carries a closure only this package can build. The codeact session below
+        // mounts it, so an action can import
+        // `@nodetool-ai/sandbox-nodetool/<namespace>` and land on `run.invoke`.
+        this.chatCapabilityRun = createCapabilityRun({
+            context: ctx,
+            gate: chatGate,
+            projectId: chatProjectId,
+            availableSecrets: contextSecretAvailability(ctx),
+            nodeRegistry: this.session.nodeRegistry,
+            providers: chatProviders,
+            subAgent: subAgentRuntime,
+            budget: turnBudget,
+            secretPrompt: (request) => this.requestSecretEntry(threadId, request),
+            ...mcpToolHostDeps(),
+            capabilities: legacyCapabilities
+        });
+        const gameAssetRun = this.chatCapabilityRun;
+        const gameAssetNodeRunner = (args) => gameAssetRun.invoke("run_node", args);
+        ctx.set(GAME_ASSET_NODE_RUNNER_CONTEXT_KEY, gameAssetNodeRunner);
+        // CodeAct session for this turn. Created here so its prompt section is in
+        // place before the system message is materialized below. The tool router
+        // (`executeTool`, defined further down) is late-bound through a ref; it is
+        // assigned before the provider loop can run any action.
+        let codeactExecuteToolRef = null;
+        let codeactSession = null;
+        if (useCodeAct) {
+            // The core set (file, search, fetch, todo, delegation) and discovery
+            // (which providers, models and node types this install has) are also
+            // plain tool calls: one question with one answer, which routing through
+            // a sandbox action only delays. They stay on the belt so code can still
+            // compose them; the prompt documents the direct call.
+            // `create_plan` joins them in plan mode: the plan is that turn's whole
+            // deliverable, and a deliverable reached only by writing a sandbox action
+            // to import it is one the model routinely does not reach for.
+            // `execute_plan` is direct for the same reason, in every other mode:
+            // running the plan the user just approved is that turn's whole point.
+            const directNames = new Set(DIRECT_TOOL_NAMES);
+            if (permissionMode === "plan")
+                directNames.add("create_plan");
+            else
+                directNames.add("execute_plan");
+            const directSchemas = allSchemas.filter((s) => s.name !== "view_image" && directNames.has(s.name));
+            codeactSession = createChatCodeActSession({
+                includeProductKnowledge: false,
+                tools: allSchemas
+                    .filter((s) => s.name !== "view_image")
+                    .map((s) => ({
+                    name: s.name,
+                    description: s.description,
+                    inputSchema: s.inputSchema
+                })),
+                sandboxPackages: sandboxPackagesForChat({
+                    source: uiContext?.source,
+                    focusedType: uiContext?.focused?.type,
+                    catalog: getProcessSandboxModuleCatalog()
+                }),
+                directToolNames: directSchemas.map((s) => s.name),
+                executeTool: async (call) => {
+                    if (!codeactExecuteToolRef) {
+                        throw new Error("Tool router not ready");
+                    }
+                    return codeactExecuteToolRef({
+                        id: call.id,
+                        name: call.name,
+                        args: call.args
+                    });
+                },
+                residentToolNames: [
+                    ...CODEACT_RESIDENT_TOOL_NAMES,
+                    ...RESIDENT_TOOL_NAMES,
+                    ...focusedUiToolNames(uiContext, allSchemas.map((schema) => schema.name))
+                ],
+                context: ctx,
+                signal,
+                clock: codeactClock,
+                capabilityRun: this.chatCapabilityRun ?? undefined
+            });
+            providerToolSchemas.push(codeactSession.providerTool);
+            providerToolSchemas.push(...directSchemas);
+            // `view_image` stays a direct provider tool: it is the one channel that
+            // puts pixels into the model's context, and pixels cannot ride the
+            // sandbox's JSON observation envelope.
+            const viewImage = allSchemas.find((s) => s.name === "view_image");
+            if (viewImage)
+                providerToolSchemas.push(viewImage);
+            codeactPromptSection = codeactSession.systemPromptSection;
+            log.info("Chat turn running in codeact mode", {
+                threadId,
+                toolCount: allSchemas.length,
+                directToolCount: directSchemas.length
+            });
+        }
+        // Prepend system prompt if first message isn't system role — matches Python
+        if (chatHistory.length === 0 || chatHistory[0].role !== "system") {
+            chatHistory.unshift({
+                role: "system",
+                content: buildSystemContent(),
+                toolCallId: null,
+                toolCalls: null,
+                threadId: null
+            });
+        }
+        // The agent now discovers and queries collections itself via the
+        // list_collections / query_collection tools, so there is no client-driven
+        // RAG pre-query here.
+        const userContent = extractTextContent(data.content);
+        // Final assistant text. Updated as the provider emits assistant
+        // messages; the last one wins.
+        let content = "";
+        // The session token to persist onto the assistant message. Seeds from the
+        // prior turn's token (so a session-based provider resumes) and is refreshed
+        // whenever the provider emits a new ProviderSessionUpdate this turn.
+        let capturedSession = priorSession;
+        // What to persist onto the assistant message: the provider's token, but with
+        // the absolute checkpoint when the fast path sent only a delta (the
+        // provider's emitted checkpoint is relative to the trimmed view).
+        const sessionForPersist = () => {
+            if (!capturedSession) {
+                return null;
+            }
+            const contentSuppressed = getRunTraceScope()?.policy.contentSuppressed || priorSession?.traceContentSuppressed || capturedSession.traceContentSuppressed;
+            const persisted = { ...capturedSession };
+            if (sessionCheckpointOverride != null) {
+                persisted.checkpoint = sessionCheckpointOverride;
+            }
+            if (contentSuppressed) {
+                persisted.traceContentSuppressed = true;
+            }
+            return persisted;
+        };
+        // Cap on tool-calling rounds before the loop stops. Generous enough to
+        // build a multi-component app UI or run a long edit session in one turn —
+        // 10 was too low and cut off the app builder mid-build.
+        const MAX_TOOL_ROUNDS = 50;
+        // Items still read from a superseded turn, purely to catch tool results
+        // already in flight. A provider that honors the abort ends well inside it.
+        const MAX_SUPERSEDED_DRAIN_ITEMS = 200;
+        const useTools = providerToolSchemas.length > 0;
+        // The wire messages. The provider's generateLoop owns the tool-calling
+        // rounds and message assembly from here.
+        let messagesToSend = [...chatHistory];
+        // Everything turn-scoped, gathered in one place and appended once, after
+        // media resolution, to the last user message. None of it is persisted, so
+        // whatever is injected here is absent from the history a later turn sends
+        // — which is exactly why it must sit behind every byte a later turn will
+        // reuse. See `appendContextToLastUser`.
+        const volatileContext = [];
+        // Durable memories (memory_* tools), so the agent starts each turn aware
+        // of what it recorded — project facts, decisions, and the assets it
+        // generated for reuse. This thread's in full, the rest as a count it can
+        // search. Deterministic and always-on.
+        if (threadId) {
+            const memoryBlock = await this.buildMemoryBlock(userId, threadId);
+            if (memoryBlock)
+                volatileContext.push(memoryBlock);
+            const generationBlock = await this.buildGenerationBlock(userId, threadId);
+            if (generationBlock)
+                volatileContext.push(generationBlock);
+        }
+        // The bodies of any skills the message invoked with `/<name>`. The catalog
+        // half is stable and already sits in the system prompt.
+        const invokedSkills = invokedSkillsSection(userSkills, userContent);
+        if (invokedSkills)
+            volatileContext.push(invokedSkills);
+        // Expand any `asset://<id>.<ext>` references the composer or a prior turn
+        // attached and dereference the URIs to data the provider can consume.
+        // Image / audio mentions typed inline in a text part get split into proper
+        // blocks first (mirroring what the workflow agent node does in
+        // `buildUserMessage`), then every block with an `asset://` / storage URI is
+        // resolved to a data URI. Text-document mentions are inlined as their
+        // decoded contents. Without this step the provider would see literal
+        // `asset://…` text and never look at the referenced media.
+        //
+        // The volatile block is appended after resolution, so a memory's
+        // `asset://` reference stays a reference instead of being inlined as a
+        // data URI. Both steps are one closure because compaction rebuilds the
+        // wire messages from a shortened history and must reproduce them exactly.
+        const withTurnContext = async (base) => {
+            const resolved = await ctx.resolveMessageMediaUris(base);
+            return volatileContext.length > 0
+                ? appendContextToLastUser(resolved, volatileContext.join("\n\n"))
+                : resolved;
+        };
+        messagesToSend = await withTurnContext(messagesToSend);
+        // Run one tool call and return the result to feed back to the model. Owns
+        // server/client tool routing, side effects (client round-trips via the
+        // ToolBridge), and asset materialization; the provider's loop orchestrates.
+        // Image results (e.g. ui_3d_capture_view) return MessageContent blocks so
+        // vision providers can see them; everything else returns result text.
+        const executeTool = async (toolCall) => {
+            let toolResult;
+            const serverTool = serverToolMap.get(toolCall.name);
+            const preferClientDocumentTool = workflowDocumentToolNames.has(toolCall.name) &&
+                this.deps.clientTools()[toolCall.name] !== undefined;
+            if (preferClientDocumentTool) {
+                // The renderer owns live, potentially unsaved state. Use it when it is
+                // present; the server implementation remains the headless fallback.
+                await this.session.send({
+                    type: "tool_call",
+                    thread_id: threadId,
+                    tool_call_id: toolCall.id,
+                    name: toolCall.name,
+                    args: toolCall.args
+                });
+                const clientResult = await this.deps.toolBridge.createWaiter(toolCall.id, 300_000, threadId);
+                toolResult =
+                    clientResult.result ?? clientResult.content ?? clientResult;
+            }
+            else if (serverTool) {
+                try {
+                    const args = { ...Tool.stripMessage(toolCall.args) };
+                    if (serverTool.needsToolCallId) {
+                        args["_tool_call_id"] = toolCall.id;
+                    }
+                    if (!this.chatCapabilityRun) {
+                        throw new Error("Chat capability run is unavailable");
+                    }
+                    toolResult = await this.chatCapabilityRun.invoke(serverTool.name, args);
+                }
+                catch (err) {
+                    const errMsg = err instanceof Error ? err.message : String(err);
+                    log.error("Tool execution failed", {
+                        tool: toolCall.name,
+                        error: errMsg
+                    });
+                    toolResult = { error: errMsg };
+                }
+            }
+            else if (this.deps.clientTools()[toolCall.name]) {
+                // Client-side tool — round-trip through the UI via the ToolBridge.
+                await this.session.send({
+                    type: "tool_call",
+                    thread_id: threadId,
+                    tool_call_id: toolCall.id,
+                    name: toolCall.name,
+                    args: toolCall.args
+                });
+                const clientResult = await this.deps.toolBridge.createWaiter(toolCall.id, 300_000, threadId);
+                toolResult =
+                    clientResult.result ?? clientResult.content ?? clientResult;
+            }
+            else {
+                toolResult = { error: `Tool "${toolCall.name}" not available` };
+            }
+            // view_image is the ONE mechanism that puts pixels into the model's
+            // context: its image_content rides the tool message so the model sees the
+            // image this turn. (The chat loop builds tool messages inside
+            // provider.generateLoop, so the tool return value is the only hook.)
+            if (toolCall.name === "view_image") {
+                const injected = extractInjectableImages(toolResult);
+                if (injected) {
+                    return [{ type: "text", text: injected.text }, ...injected.images];
+                }
+            }
+            // Every other tool that produced pixels (timeline frames, 3D capture, …)
+            // gets them persisted as temp image assets; the model receives only a
+            // handle and calls view_image when it wants to look.
+            toolResult = await this.materializeToolResultImages(toolResult, ctx);
+            const processed = compactResourceIds(await this.processToolResult(toolResult, ctx));
+            return isString(processed) ? processed : JSON.stringify(processed);
+        };
+        // Late-bind the codeact bridge to the router above, and route
+        // `execute_code` calls into the sandbox session; everything else (only
+        // `view_image` is offered in codeact mode) keeps the normal path.
+        codeactExecuteToolRef = executeTool;
+        const session = codeactSession;
+        const beltToolNames = new Set(allSchemas.map((s) => s.name));
+        const effectiveExecuteTool = async (rawCall) => {
+            // A model that read the CodeAct prompt sometimes calls
+            // `tools.<name>` at the top level. Recover the plain name first, so the
+            // call reaches the tool instead of dying as "no such tool".
+            const name = normalizeToolCallName(rawCall.name);
+            const toolCall = name === rawCall.name ? rawCall : { ...rawCall, name };
+            if (!session)
+                return executeTool(toolCall);
+            if (name === EXECUTE_CODE_TOOL_NAME) {
+                return session.executeAction(toolCall.args);
+            }
+            // A belt tool named directly still runs: the router is the same gate the
+            // sandbox bridge goes through, so answering the call is strictly better
+            // than refusing it and spending a round on the correction.
+            if (beltToolNames.has(name))
+                return executeTool(toolCall);
+            // Answer, do not throw: the model can only correct course if the
+            // recovery instructions arrive as this call's tool result.
+            return JSON.stringify({ error: unroutableToolMessage(name) });
+        };
+        // Tool name by call id, so persisted tool messages keep their name (the
+        // provider Message carries only the id).
+        const toolNames = new Map();
+        // Calls announced by an assistant message that have not been answered by a
+        // tool message yet. Whatever is still here when the turn tears down never
+        // got its result row, and the `finally` below writes a stand-in so the
+        // transcript stays well-formed.
+        const openToolCalls = new Set();
+        // Set when a newer turn supersedes this one. The loop then stops feeding
+        // the client and only rescues the results still coming.
+        let superseded = false;
+        let drainedItems = 0;
+        let terminalDoneSent = false;
+        const sendTerminalDone = async () => {
+            if (terminalDoneSent)
+                return;
+            terminalDoneSent = true;
+            await this.session.send({
+                type: "chunk",
+                content: "",
+                done: true,
+                thread_id: threadId
+            });
+        };
+        /**
+         * Write one message this turn produced. `echo` is false for a superseded
+         * turn: the row still belongs in the thread, but the client has moved on
+         * and replaying it there would interleave a dead turn into a live one.
+         */
+        const persistTurnMessage = async (m, echo) => {
+            if (m.role === "assistant") {
+                // Content may be a plain string or a MessageContent[] carrying
+                // native-image blocks. Raw image bytes are turned into real assets
+                // here so base64 never lands in the DB or on the wire.
+                let persistedContent = m.content ?? null;
+                if (isString(m.content)) {
+                    if (echo)
+                        content = m.content;
+                }
+                else if (Array.isArray(m.content)) {
+                    const materialized = await this.materializeAssistantImageContent(m.content, userId, workflowId, chatProjectId ?? "default");
+                    persistedContent = materialized;
+                    if (echo) {
+                        content = materialized
+                            .filter((c) => c.type === "text" && isString(c.text))
+                            .map((c) => c.text)
+                            .join("");
+                    }
+                }
+                const toolCalls = Array.isArray(m.toolCalls)
+                    ? m.toolCalls.map((tc) => ({
+                        id: tc.id,
+                        name: tc.name,
+                        args: tc.args,
+                        result: null,
+                        // Gemini 3 rejects a history that replays a function call
+                        // without the signature it issued, so it rides into the DB.
+                        thought_signature: tc.thought_signature ?? null
+                    }))
+                    : null;
+                for (const tc of toolCalls ?? []) {
+                    if (!isString(tc.id))
+                        continue;
+                    openToolCalls.add(tc.id);
+                    toolNames.set(tc.id, tc.name);
+                }
+                const assistantMsgData = {
+                    type: "message",
+                    role: "assistant",
+                    content: persistedContent
+                };
+                if (toolCalls) {
+                    assistantMsgData.tool_calls = toolCalls;
+                }
+                assistantMsgData.thread_id = threadId;
+                assistantMsgData.workflow_id = workflowId;
+                assistantMsgData.provider = providerId;
+                assistantMsgData.model = model;
+                assistantMsgData.provider_session = sessionForPersist();
+                await this.saveMessageToDb(assistantMsgData);
+                if (echo)
+                    await this.session.send(assistantMsgData);
+                return;
+            }
+            if (m.role !== "tool")
+                return;
+            // Image tool results carry MessageContent blocks; persist/echo only
+            // their note text so chat history stays light (the base64 rode the
+            // in-flight provider message, never the DB).
+            const toolContent = Array.isArray(m.content)
+                ? toolResultDisplayText(m.content)
+                : isString(m.content)
+                    ? m.content
+                    : "";
+            if (isString(m.toolCallId))
+                openToolCalls.delete(m.toolCallId);
+            const toolMsgData = {
+                type: "message",
+                role: "tool",
+                tool_call_id: m.toolCallId ?? null,
+                name: m.toolCallId ? (toolNames.get(m.toolCallId) ?? null) : null,
+                content: toolContent,
+                thread_id: threadId,
+                workflow_id: workflowId,
+                provider: providerId,
+                model
+            };
+            await this.saveMessageToDb(toolMsgData);
+            if (echo)
+                await this.session.send(toolMsgData);
+        };
+        // The Claude Agent provider runs the SDK's own loop, which resolves skills
+        // through its native `Skill` tool (progressive disclosure) rather than the
+        // always-on catalog every other provider reads from the system prompt. Hand
+        // it the user's DB skills so that loop can list and load them; it
+        // materializes them into an isolated local plugin (no `settingSources`
+        // leakage). Other providers get skills via the system-prompt catalog above
+        // and ignore this field.
+        const skillsForProvider = provider.provider === PROVIDER_IDS.CLAUDE_AGENT_SDK
+            ? userSkills.map((skill) => ({
+                name: skill.name,
+                description: skill.description,
+                content: skill.content
+            }))
+            : undefined;
+        // ── Compaction (D5) ──────────────────────────────────────────────────
+        // A long thread eventually stops fitting, and from then on every turn dies
+        // on a provider error the user cannot act on. Compaction replaces the
+        // turns before the last few with one summary row and sends that instead.
+        // The rows stay in the database for the UI and `nodetool.threads.*`; only
+        // the provider's view is cut.
+        const compaction = await readCompactionSettings();
+        const modelKey = `${providerId}/${model}`;
+        let contextWindow = this.contextWindows.get(modelKey);
+        if (!contextWindow && compaction.thresholdTokens === null) {
+            contextWindow = resolveContextWindow(provider, model);
+            this.contextWindows.set(modelKey, contextWindow);
+        }
+        const compactionThresholdTokens = compactionThreshold(compaction, contextWindow ? (await contextWindow).tokens : 0);
+        /** Spent by the reactive trigger below; bounds the turn to one retry. */
+        let compactionRetryUsed = false;
+        /** Tell the user what was compacted, or why it was not. */
+        const compactionLog = async (content, severity) => {
+            await this.session.send({
+                type: "log_update",
+                node_id: "",
+                node_name: "compaction",
+                content,
+                severity,
+                thread_id: threadId
+            });
+        };
+        /**
+         * Which model writes the summary: `NODETOOL_COMPACTION_MODEL` when set,
+         * otherwise the one the turn is already running on. The setting takes the
+         * `provider/model` form the supervisor's does, and a bare id names a model
+         * on this turn's provider.
+         */
+        const summarizerModel = async () => {
+            const configured = compaction.model;
+            if (configured === null)
+                return { provider, model };
+            const slash = configured.indexOf("/");
+            if (slash <= 0)
+                return { provider, model: configured };
+            const otherId = configured.slice(0, slash);
+            const otherModel = configured.slice(slash + 1);
+            if (otherId === providerId)
+                return { provider, model: otherModel };
+            const resolved = await this.session.resolveProvider?.(otherId, userId);
+            if (!resolved) {
+                throw new Error(`No provider registered for "${otherId}"`);
+            }
+            return { provider: resolved, model: otherModel };
+        };
+        /**
+         * Summarize this thread up to the cut, persist the record, and rebuild the
+         * wire messages from what survives. Answers whether it compacted.
+         *
+         * Everything that can go wrong here leaves the turn running against the
+         * history it already had: a thread too short to cut, a summarizer that
+         * failed, a summarizer with nothing to say. This is the one place A4 does
+         * not fail closed (I-4), because the alternative to a missing summary is a
+         * turn that cannot run at all.
+         */
+        const compactThread = async (reason) => {
+            const [rows] = await Message.paginate(threadId, { limit: 1000 });
+            const cut = chooseCompactionCut(historySinceCompaction(rows), compaction.keepUserTurns, {
+                // Leave room for the summary, turn context and subsequent replies.
+                maxTokens: compactionThresholdTokens * 0.75 -
+                    COMPACTION_SUMMARY_MAX_TOKENS -
+                    estimatePromptTokens([systemChatMessage()]) -
+                    estimatePromptTokens([
+                        { role: "user", content: volatileContext.join("\n\n") }
+                    ]),
+                countTokens: (row) => estimatePromptTokens(convertDbMessages([row]))
+            });
+            if (!cut)
+                return false;
+            let summary;
+            try {
+                const summarizer = await summarizerModel();
+                summary = await summarizeForCompaction({
+                    provider: summarizer.provider,
+                    model: summarizer.model,
+                    // The stored rows, not the wire messages: an `asset://` uri is still
+                    // a uri here rather than the data it resolves to, which is what lets
+                    // the summary carry the reference forward.
+                    messages: convertDbMessages(cut.summarize),
+                    signal
+                });
+            }
+            catch (err) {
+                const detail = err instanceof Error ? err.message : String(err);
+                log.warn("Compaction summary failed", { threadId, error: detail });
+                await compactionLog(`Could not summarize this conversation (${detail}). Sending it in full.`, "warning");
+                return false;
+            }
+            if (summary === null) {
+                await compactionLog("The summary of this conversation came back empty. Sending it in full.", "warning");
+                return false;
+            }
+            // The record belongs at the cut, not at the end of the thread: history
+            // assembly starts from the newest one, so a record written after the kept
+            // turns would drop them from the next turn's view. Rows are ordered by
+            // `created_at`, so it takes the millisecond before the first survivor.
+            const boundary = Date.parse(cut.keep[0].created_at);
+            const record = await Message.create({
+                thread_id: threadId,
+                user_id: userId,
+                role: "user",
+                execution_event_type: COMPACTION_EVENT_TYPE,
+                content: compactionMessageContent(summary),
+                tools: getRunTraceScope()?.policy.contentSuppressed ? restrictedTraceToolNames() : null,
+                created_at: Number.isFinite(boundary)
+                    ? new Date(boundary - 1).toISOString()
+                    : cut.keep[0].created_at
+            });
+            messagesToSend = await withTurnContext([
+                systemChatMessage(),
+                ...convertDbMessages([record, ...cut.keep])
+            ]);
+            // The upstream transcript a session token resumes is the history the cut
+            // just replaced, so nothing resumes across a compaction.
+            capturedSession = null;
+            this.measuredThreadTokens.delete(threadId);
+            loadFullHistory = null;
+            sessionCheckpointOverride = null;
+            await this.session.send({
+                type: "message",
+                role: "user",
+                execution_event_type: COMPACTION_EVENT_TYPE,
+                content: record.content,
+                thread_id: threadId,
+                workflow_id: workflowId
+            });
+            log.info("Compacted chat history", {
+                threadId,
+                summarized: cut.summarize.length,
+                kept: cut.keep.length
+            });
+            await compactionLog(`Summarized the earlier part of this conversation because ${reason}.`, "info");
+            return true;
+        };
+        // Trigger 1, proactive: the prompt reached the threshold, 90% of the
+        // model's input window unless `NODETOOL_CHAT_COMPACTION_TOKENS` sets it.
+        // The size is the larger of two numbers. The provider-reported size of
+        // this thread's last call counts the system prompt and tool definitions.
+        // `estimatePromptTokens` counts the messages added since, scoring each
+        // attached image, audio, video or document at a fixed per-modality figure
+        // so a resolved `data:` uri never reaches the tokenizer.
+        //
+        // A provider holding the conversation upstream is sent only the turns since
+        // its session token, so this number would describe a fraction of what it
+        // actually has. Those get trigger 2 alone: the provider itself says when
+        // the transcript stopped fitting.
+        if (!holdsTranscriptServerSide(providerId, capturedSession !== null)) {
+            const measured = this.measuredThreadTokens.get(threadId);
+            const promptTokens = Math.max(estimatePromptTokens(messagesToSend), measured?.modelKey === modelKey ? measured.tokens : 0);
+            if (promptTokens >= compactionThresholdTokens) {
+                await compactThread(`it reached about ${promptTokens} tokens, at or over the ` +
+                    `${compactionThresholdTokens}-token limit`);
+            }
+        }
+        /**
+         * One pass of the provider's tool-calling loop over the current
+         * `messagesToSend`. A function rather than a statement so the reactive
+         * compaction below can run it a second time against a shortened history.
+         */
+        const streamTurn = async () => {
+            for await (const item of provider.generateLoop({
+                messages: messagesToSend,
+                model,
+                tools: useTools ? providerToolSchemas : undefined,
+                threadId,
+                providerSession: capturedSession,
+                loadFullHistory: loadFullHistory ?? undefined,
+                executeTool: useTools ? effectiveExecuteTool : undefined,
+                maxIterations: MAX_TOOL_ROUNDS,
+                turnBudget,
+                sequentialTools: session ? true : undefined,
+                workspaceDir: chatWorkspace?.localDir ?? undefined,
+                skills: skillsForProvider,
+                resolveMedia: mediaResolverFor(ctx),
+                signal
+            })) {
+                // A newer turn has taken over. Stop driving the client, but do NOT
+                // drop what this turn already produced: the provider checks its abort
+                // signal before dispatching a tool, never during one, so a call in
+                // flight runs to completion and its result is arriving right now.
+                // Discarding it left the model blind to a side effect it had already
+                // caused, and it silently redid the work.
+                if (!superseded &&
+                    requestSeq !== undefined &&
+                    requestSeq !== this.chatRequestSeq) {
+                    superseded = true;
+                }
+                if (superseded) {
+                    if (isProviderMessageEvent(item)) {
+                        await persistTurnMessage(item.message, false);
+                    }
+                    // Nothing left outstanding: the rest of this turn is work the user
+                    // has already moved on from.
+                    if (openToolCalls.size === 0)
+                        break;
+                    // The turn's signal is already aborted, so a provider that honors it
+                    // ends within a few items. One that does not must never hold this
+                    // handler open — stop reading and let the `finally` stand in for
+                    // whatever is still missing.
+                    if (++drainedItems > MAX_SUPERSEDED_DRAIN_ITEMS) {
+                        log.warn("Superseded turn kept producing; stopped draining", {
+                            threadId,
+                            openToolCalls: openToolCalls.size
+                        });
+                        break;
+                    }
+                    continue;
+                }
+                if (isProviderStop(item)) {
+                    // A limit ended the turn, not the model finishing its answer. Said
+                    // nowhere, the two are indistinguishable to the user (invariant
+                    // I-3), so the reason is persisted as an ordinary assistant message:
+                    // it belongs in the transcript the next turn reads, and it is
+                    // per-turn text that must never reach the system prompt (I-7).
+                    //
+                    // `aborted` is the user pressing Stop or a newer message superseding
+                    // this one. They already know why it stopped, and a notice there
+                    // would scold them for using the control. The other three are limits
+                    // nobody asked for in the moment: the dollar cap, the wall clock,
+                    // and the tool-round ceiling all leave the turn unfinished mid-work.
+                    if (item.reason !== "aborted") {
+                        // The budget names the ceiling it hit ("turn budget of $5
+                        // reached"); the round cap is not a budget stop, and reading a
+                        // budget a sub-agent exhausted earlier would name the wrong limit.
+                        const detail = item.reason === "iterations"
+                            ? item.detail
+                            : (turnBudget.exhausted?.detail ?? item.detail);
+                        await persistTurnMessage({ role: "assistant", content: `Stopped: ${detail}` }, true);
+                    }
+                    else if (signal?.reason === "shutdown") {
+                        // …except a shutdown, which nobody asked for either. The reply
+                        // stops mid-sentence and, said nowhere, reads as the model
+                        // finishing; the note says the server went away, and is what the
+                        // next turn reads when the client retries on the machine that
+                        // stayed.
+                        await persistTurnMessage({ role: "assistant", content: "Stopped: server restarting" }, true);
+                    }
+                    continue;
+                }
+                if (isProviderSessionUpdate(item)) {
+                    // Internal continuity token — capture for persistence, never wired.
+                    capturedSession = item.session;
+                    continue;
+                }
+                if (isProviderMessageEvent(item)) {
+                    await persistTurnMessage(item.message, true);
+                    continue;
+                }
+                if (isToolCall(item)) {
+                    // Informational: the loop executes it through executeTool.
+                    toolNames.set(item.id, item.name);
+                    log.info("Tool call", { tool: item.name, args: item.args });
+                    continue;
+                }
+                // `isChunk` from the runtime additionally requires string content, so
+                // it drops the native-`Float32Array` audio chunks the client decodes.
+                // `type === "chunk"` is Chunk's alone in this union, so test that.
+                if (item.type === "chunk") {
+                    // The provider loop emits a terminal chunk for its completion, and
+                    // this handler emits the turn terminal below. Keep one envelope
+                    // terminal even when a provider double emits its own `done` item.
+                    if (!item.thread_id)
+                        item.thread_id = threadId;
+                    await this.session.send(item.done === true ? { ...item, done: false } : { ...item });
+                }
+            }
+        };
+        try {
+            // At most two passes. The second happens only when the first ended with
+            // the provider's own context-exceeded signal and compaction answered it
+            // by shortening the history. A second such failure is surfaced: the
+            // shortened transcript did not fit either, and compacting again would
+            // buy another summarizer call to learn the same thing.
+            //
+            // A provider rejects an oversized request before it generates anything,
+            // so the retry re-reads a turn that produced no messages of its own.
+            for (;;) {
+                try {
+                    await streamTurn();
+                    const lastCallTokens = provider.lastCallTokens;
+                    if (typeof lastCallTokens === "number") {
+                        this.measuredThreadTokens.set(threadId, {
+                            modelKey,
+                            tokens: lastCallTokens
+                        });
+                    }
+                    break;
+                }
+                catch (err) {
+                    if (compactionRetryUsed ||
+                        providerFailureDetail(err)?.code !== "context_exceeded") {
+                        throw err;
+                    }
+                    compactionRetryUsed = true;
+                    const compacted = await compactThread("the provider refused the request: this conversation no longer fits its context window");
+                    if (!compacted)
+                        throw err;
+                    log.info("Retrying the turn against the compacted history", {
+                        threadId
+                    });
+                }
+            }
+            // A superseded turn is done once its outstanding results are saved. The
+            // completion chunk and the memory pass belong to the turn the user is
+            // actually watching, which has its own.
+            if (superseded)
+                return;
+            // Log provider call for cost tracking — matches Python's _log_provider_call()
+            await this._logProviderCall(userId, provider, providerId, model, workflowId, chatProjectId ?? null);
+            // What the run spent, where the user can see it. A number only the
+            // server log carries is a number nobody reads; `unpricedTurns` rides
+            // along when there were any, so the total reads as the lower bound it
+            // is rather than as the whole bill (invariant I-4).
+            const spentUsd = turnBudget.turns.spentUsd;
+            const unpricedTurns = turnBudget.turns.unpricedTurns;
+            await this.session.send({
+                type: "log_update",
+                node_id: "",
+                node_name: "budget",
+                content: unpricedTurns > 0
+                    ? `Run spent at least $${spentUsd.toFixed(4)} (${unpricedTurns} turn(s) on a model with no catalog price)`
+                    : `Run spent $${spentUsd.toFixed(4)}`,
+                severity: "info",
+                thread_id: threadId
+            });
+            // Signal completion — matches Python's done chunk.
+            await sendTerminalDone();
+            log.debug("Chat complete", {
+                threadId,
+                chars: content.length,
+                // What the whole run — this loop plus every sub-agent and node it
+                // started — reserved and committed against the shared budget.
+                spentUsd: turnBudget.turns.spentUsd,
+                stoppedBy: turnBudget.exhausted?.kind ?? null
+            });
+        }
+        catch (err) {
+            // Stop and supersede are expected control flow. Their provider errors
+            // must not become durable assistant failures or a second terminal frame.
+            if (signal?.aborted === true ||
+                (requestSeq !== undefined && requestSeq !== this.chatRequestSeq)) {
+                return;
+            }
+            const errMsg = err instanceof Error ? err.message : String(err);
+            await settleRegisteredRunTrace(rootContext, "failed", errMsg);
+            log.error("Chat processing error", { threadId, error: errMsg });
+            let errorType = "error";
+            let statusCode;
+            let formattedMsg = safeClientErrorText(err);
+            // Connection errors (ECONNREFUSED, ENOTFOUND, etc.)
+            if (errMsg.includes("ECONNREFUSED") ||
+                errMsg.includes("ENOTFOUND") ||
+                errMsg.includes("fetch failed") ||
+                errMsg.includes("nodename nor servname")) {
+                errorType = "connection_error";
+                if (errMsg.includes("ENOTFOUND") ||
+                    errMsg.includes("nodename nor servname")) {
+                    formattedMsg =
+                        "Connection error: Unable to resolve hostname. Please check your network connection and API endpoint configuration.";
+                }
+                else {
+                    formattedMsg = `Connection error: ${safeClientErrorText(err)}`;
+                }
+            }
+            else {
+                const providerFailure = providerFailureMessage(err, providerId, model);
+                errorType = providerFailure.errorType;
+                statusCode = providerFailure.statusCode;
+                formattedMsg = providerFailure.message;
+            }
+            const errorMessage = {
+                type: "error",
+                message: formattedMsg,
+                error_type: errorType
+            };
+            if (statusCode !== undefined) {
+                errorMessage.status_code = statusCode;
+            }
+            errorMessage.thread_id = threadId;
+            errorMessage.workflow_id = workflowId;
+            await this.session.send(errorMessage);
+            // Signal completion even on error — matches Python
+            await sendTerminalDone();
+            const errorMsgData = {
+                type: "message",
+                role: "assistant",
+                content: errorType === "connection_error"
+                    ? `I encountered a connection error: ${formattedMsg}. Please check your network connection and try again.`
+                    : errorType === "http_status_error"
+                        ? `I encountered an API error (HTTP ${statusCode}): ${formattedMsg}`
+                        : `I encountered an error: ${formattedMsg}`,
+                thread_id: threadId,
+                workflow_id: workflowId,
+                provider: providerId,
+                model
+            };
+            await this.saveMessageToDb(errorMsgData);
+            await this.session.send(errorMsgData);
+        }
+        finally {
+            detachPredictions();
+            detachCostLedger();
+            try {
+                await chatWorkspace?.cleanupScratch?.();
+            }
+            catch (err) {
+                log.warn("Chat workspace scratch cleanup failed", {
+                    threadId,
+                    error: err instanceof Error ? err.message : String(err)
+                });
+            }
+            // Whatever is still outstanding never got a result row. Leaving the gap
+            // makes the thread malformed — Anthropic rejects a `tool_use` with no
+            // `tool_result` — and leaves the model unaware the call was abandoned,
+            // which is what made it silently redo the work.
+            for (const toolCallId of openToolCalls) {
+                try {
+                    await this.saveMessageToDb({
+                        type: "message",
+                        role: "tool",
+                        tool_call_id: toolCallId,
+                        name: toolNames.get(toolCallId) ?? null,
+                        content: SUPERSEDED_TOOL_RESULT,
+                        thread_id: threadId,
+                        workflow_id: workflowId,
+                        provider: providerId,
+                        model
+                    });
+                }
+                catch (err) {
+                    // Best effort: a turn that already failed must not fail again here.
+                    this.session.logError("superseded tool result save failed", err);
+                }
+            }
+            openToolCalls.clear();
+        }
+    }
+    /**
+     * Log a provider call for cost tracking — mirrors Python's _log_provider_call().
+     * Best-effort: never throws, logs warnings on failure.
+     */
+    async _logProviderCall(userId, provider, providerId, model, workflowId, projectId) {
+        if (!providerId || !model) {
+            log.warn("Cannot log provider call: missing provider or model");
+            return;
+        }
+        try {
+            // A provider that could not price a call reports why. Its running total
+            // is then missing that spend, so a zero is written as null — the row
+            // reads unpriced in `nodetool costs` instead of summing as free, the
+            // same posture the cost ledger takes.
+            const unpricedReason = provider.unpricedReason;
+            const cost = provider.cost;
+            const unpriced = cost === 0 && unpricedReason != null;
+            await Prediction.create({
+                user_id: userId,
+                provider: providerId,
+                model,
+                cost: unpriced ? null : cost,
+                metadata: unpricedReason ? { unpriced_reason: unpricedReason } : null,
+                workflow_id: workflowId,
+                // Token spend from a project's agent thread is the project's; a turn
+                // outside a project records a null rather than a bucket name.
+                project_id: projectId,
+                status: "completed",
+                node_id: ""
+            });
+            log.debug("Logged provider call", { provider: providerId, model, cost });
+        }
+        catch (err) {
+            if (err instanceof TypeError || err instanceof ReferenceError) {
+                log.warn("Failed to log provider call due to invalid data", {
+                    error: err instanceof Error ? err.message : String(err)
+                });
+            }
+            else {
+                log.error("Unexpected error logging provider call", {
+                    error: err instanceof Error ? err.message : String(err)
+                });
+            }
+        }
+    }
+    /**
+     * Detect message input node names from a workflow graph.
+     * Mirrors Python's WorkflowMessageProcessor._detect_message_input_names().
+     *
+     * Scans graph nodes for types ending in .MessageInput / .MessageListInput
+     * and returns their data.name values.
+     */
+    detectMessageInputNames(graph) {
+        let messageName = null;
+        let messagesName = null;
+        for (const node of graph.nodes) {
+            const nodeType = isString(node.type) ? node.type : "";
+            const data = isObjectLike(node.data)
+                ? node.data
+                : {};
+            const nodeName = isString(data.name) ? data.name.trim() : "";
+            if (!nodeName)
+                continue;
+            if (messageName === null &&
+                (nodeType === "nodetool.input.MessageInput" ||
+                    nodeType.endsWith(".MessageInput"))) {
+                messageName = nodeName;
+            }
+            if (messagesName === null &&
+                (nodeType === "nodetool.input.MessageListInput" ||
+                    nodeType.endsWith(".MessageListInput"))) {
+                messagesName = nodeName;
+            }
+        }
+        return { messageName, messagesName };
+    }
+    /**
+     * Handle a chat_message with a `media_generation` payload by invoking the
+     * selected provider's textToImage / textToVideo API, storing the resulting
+     * asset(s), and returning them to the client as an assistant `Message`
+     * whose `content` is an array of `MessageImageContent` / `MessageVideoContent`
+     * blocks.
+     *
+     * The generated bytes are persisted via `ctx.storage.store()` so each
+     * output receives a stable URI the client can resolve as a server asset.
+     * The `media_generation` echo on the assistant message lets the UI render
+     * the generation header (model, variation count, resolution, etc.) in the
+     * conversation stream.
+     */
+    async handleMediaGenerationMessage(data, mediaGeneration, requestSeq, signal) {
+        const threadId = isString(data.thread_id) ? data.thread_id : "";
+        const workflowId = isString(data.workflow_id) ? data.workflow_id : null;
+        const userId = this.session.requireUserId();
+        const mode = String(mediaGeneration.mode ?? "");
+        // The media composer's own selection first; a client without a separate
+        // media picker (mobile) sends only the message-level one. The built-in
+        // chat default is not in the chain — a text model can never serve a
+        // generation, so falling back to it only buys an obscure provider error.
+        const providerId = String(mediaGeneration.provider ?? data.provider ?? "");
+        const modelId = String(mediaGeneration.model ?? data.model ?? "");
+        const prompt = extractTextContent(data.content);
+        /**
+         * Whether this turn has been cancelled. The media provider APIs take no
+         * AbortSignal, so an in-flight generation runs to completion regardless —
+         * but its result must not be stored as an asset or delivered to a user who
+         * pressed Stop. Checked after every provider call, before any write.
+         */
+        const cancelled = () => signal?.aborted === true ||
+            (requestSeq !== undefined && requestSeq !== this.chatRequestSeq);
+        let terminalDoneSent = false;
+        const sendTerminalDone = async () => {
+            if (terminalDoneSent)
+                return;
+            terminalDoneSent = true;
+            await this.session.send({
+                type: "chunk",
+                thread_id: threadId,
+                content: "",
+                done: true
+            });
+        };
+        log.info("Media generation", {
+            threadId,
+            mode,
+            provider: providerId,
+            model: modelId,
+            promptLen: prompt.length
+        });
+        if (!isModelSelection(providerId, modelId)) {
+            await this.session.send({
+                type: "error",
+                message: noMediaModelSelectedMessage(mode),
+                thread_id: threadId
+            });
+            return;
+        }
+        if (!prompt) {
+            await this.session.send({
+                type: "error",
+                message: "Please enter a prompt",
+                thread_id: threadId
+            });
+            return;
+        }
+        if (requestSeq !== undefined && requestSeq !== this.chatRequestSeq)
+            return;
+        let projectId = null;
+        try {
+            projectId = (await Project.findByThread(userId, threadId))?.id ?? null;
+            if (!this.session.resolveProvider) {
+                throw new Error("No provider resolver configured");
+            }
+            // Entity expansion and provider resolution are part of the guarded
+            // setup. A missing entity or provider must follow the same error path as
+            // a provider call and leave a durable assistant failure row.
+            const { prompt: expandedPrompt, referenceImages } = await expandEntitiesForGeneration(prompt, this.deps.entityRefResolver(userId));
+            const entityImageBytes = await this.deps.resolveEntityReferenceImages(userId, referenceImages);
+            const provider = await this.session.resolveProvider(providerId, userId);
+            provider.setMessageEmitter((msg) => {
+                this.session.sendDetached(msg);
+            });
+            const { generate, seamAssetId, storeAsset: storeMediaAsset } = createGenerationRun({
+                userId,
+                providerId,
+                modelId,
+                provider,
+                origin: {
+                    surface: "chat",
+                    thread_id: threadId || null,
+                    ...(isString(data.request_id)
+                        ? { request_id: data.request_id }
+                        : requestSeq !== undefined
+                            ? { request_id: `chat:${threadId}:${requestSeq}` }
+                            : {})
+                },
+                threadId,
+                workflowId: workflowId ?? null,
+                projectId,
+                assetNamePrefix: mode,
+                signal
+            });
+            if (mode === "image") {
+                const variations = Math.max(1, Math.min(Number(mediaGeneration.variations ?? 1), 8));
+                const width = isNumber(mediaGeneration.width)
+                    ? mediaGeneration.width
+                    : undefined;
+                const height = isNumber(mediaGeneration.height)
+                    ? mediaGeneration.height
+                    : undefined;
+                const imageModel = {
+                    id: modelId,
+                    name: modelId,
+                    provider: providerId
+                };
+                const params = {
+                    model: imageModel,
+                    prompt: expandedPrompt,
+                    width,
+                    height,
+                    signal
+                };
+                // Surface a progress chunk so the UI can show the request flight
+                await this.session.send({
+                    type: "chunk",
+                    thread_id: threadId,
+                    content: "",
+                    content_type: "text",
+                    content_metadata: { media_generation: mediaGeneration },
+                    done: false
+                });
+                if (requestSeq !== undefined && requestSeq !== this.chatRequestSeq)
+                    return;
+                // A mentioned entity carries a reference image: the generation becomes
+                // an edit against those images, mirroring the generate_media RPC.
+                const generated = entityImageBytes.length > 0
+                    ? await generate("image_to_image", {
+                        prompt: expandedPrompt,
+                        target_width: width ?? null,
+                        target_height: height ?? null,
+                        num_images: variations,
+                        images: entityImageBytes
+                    }, {}, (abort) => provider.imageToImages(entityImageBytes, {
+                        model: imageModel,
+                        prompt: expandedPrompt,
+                        targetWidth: width ?? null,
+                        targetHeight: height ?? null,
+                        signal: abort
+                    }, variations))
+                    : await generate("text_to_image", {
+                        prompt: expandedPrompt,
+                        width,
+                        height,
+                        num_images: variations
+                    }, {}, (abort) => provider.textToImages({ ...params, signal: abort }, variations));
+                if (cancelled())
+                    return;
+                const imageContents = [];
+                for (const [index, bytes] of generated.output.entries()) {
+                    // Per-variation: a cancel partway through must not keep persisting.
+                    if (cancelled())
+                        return;
+                    const mimeType = detectImageMime(bytes);
+                    const assetId = seamAssetId(generated, index) ??
+                        (await storeMediaAsset(bytes, mimeType, IMAGE_MIME_TO_EXT[mimeType] ?? "png"));
+                    imageContents.push({
+                        type: "image_url",
+                        image: { type: "image", asset_id: assetId, mimeType }
+                    });
+                }
+                const assistantMsgData = {
+                    type: "message",
+                    role: "assistant",
+                    content: imageContents,
+                    thread_id: threadId,
+                    workflow_id: workflowId,
+                    provider: providerId,
+                    model: modelId,
+                    media_generation: mediaGeneration
+                };
+                // Re-check: cancellation may have landed while the asset was persisting.
+                if (cancelled())
+                    return;
+                await this.saveMessageToDb(assistantMsgData);
+                await this.session.send(assistantMsgData);
+                await sendTerminalDone();
+                return;
+            }
+            if (mode === "video") {
+                const aspectRatio = isString(mediaGeneration.aspect_ratio)
+                    ? mediaGeneration.aspect_ratio
+                    : null;
+                const resolution = isString(mediaGeneration.resolution)
+                    ? mediaGeneration.resolution
+                    : null;
+                const duration = isNumber(mediaGeneration.duration)
+                    ? mediaGeneration.duration
+                    : null;
+                const videoModel = {
+                    id: modelId,
+                    name: modelId,
+                    provider: providerId
+                };
+                await this.session.send({
+                    type: "chunk",
+                    thread_id: threadId,
+                    content: "",
+                    content_type: "text",
+                    content_metadata: { media_generation: mediaGeneration },
+                    done: false
+                });
+                // If the user referenced/attached an image, they want it animated:
+                // route to image-to-video so the image actually reaches the provider.
+                // Many "video" models (e.g. fal-ai/stable-video) in fact require an
+                // image and reject a text-only request with an opaque 422.
+                const sourceBytes = await this.deps.resolveSourceImageBytes(data, mediaGeneration, userId);
+                const videoParams = {
+                    prompt: expandedPrompt,
+                    aspect_ratio: aspectRatio,
+                    resolution,
+                    duration_seconds: duration
+                };
+                const generated = sourceBytes && sourceBytes.length > 0
+                    ? await generate("image_to_video", { ...videoParams, images: [sourceBytes] }, { mime: "video/mp4" }, (abort) => provider.imageToVideo(sourceBytes, {
+                        model: videoModel,
+                        prompt: expandedPrompt,
+                        aspectRatio,
+                        resolution,
+                        durationSeconds: duration,
+                        numInferenceSteps: null,
+                        signal: abort
+                    }))
+                    : await generate("text_to_video", videoParams, { mime: "video/mp4" }, (abort) => provider.textToVideo({
+                        model: videoModel,
+                        prompt: expandedPrompt,
+                        aspectRatio,
+                        resolution,
+                        durationSeconds: duration,
+                        signal: abort
+                    }));
+                if (cancelled())
+                    return;
+                const assetId = seamAssetId(generated) ??
+                    (await storeMediaAsset(generated.output, "video/mp4", "mp4"));
+                const assistantMsgData = {
+                    type: "message",
+                    role: "assistant",
+                    content: [
+                        {
+                            type: "video",
+                            video: {
+                                type: "video",
+                                asset_id: assetId,
+                                format: "mp4",
+                                duration: duration
+                            }
+                        }
+                    ],
+                    thread_id: threadId,
+                    workflow_id: workflowId,
+                    provider: providerId,
+                    model: modelId,
+                    media_generation: mediaGeneration
+                };
+                // Re-check: cancellation may have landed while the asset was persisting.
+                if (cancelled())
+                    return;
+                await this.saveMessageToDb(assistantMsgData);
+                await this.session.send(assistantMsgData);
+                await sendTerminalDone();
+                return;
+            }
+            if (mode === "reference_to_video") {
+                // The whole set of attachments conditions one clip, so every image
+                // and video on the message reaches the provider — plus the reference
+                // images of any `@`-mentioned entity, which is the same kind of input
+                // arriving by a different route.
+                const references = await this.deps.resolveReferenceMediaBytes(data, mediaGeneration, userId);
+                const referenceImages = [...references.images, ...entityImageBytes];
+                const referenceVideos = references.videos;
+                if (referenceImages.length === 0 && referenceVideos.length === 0) {
+                    await this.session.send({
+                        type: "error",
+                        message: "Reference to video needs at least one reference — attach an image or a video first",
+                        thread_id: threadId
+                    });
+                    return;
+                }
+                const aspectRatio = isString(mediaGeneration.aspect_ratio)
+                    ? mediaGeneration.aspect_ratio
+                    : null;
+                const resolution = isString(mediaGeneration.resolution)
+                    ? mediaGeneration.resolution
+                    : null;
+                const duration = isNumber(mediaGeneration.duration)
+                    ? mediaGeneration.duration
+                    : null;
+                // Only some models take it, and a model that does not rejects the
+                // request rather than silently dropping the audio, so the flag is
+                // forwarded only when the composer set it.
+                const useReferenceVideoAudio = typeof mediaGeneration.use_reference_video_audio === "boolean"
+                    ? mediaGeneration.use_reference_video_audio
+                    : undefined;
+                const r2vModel = {
+                    id: modelId,
+                    name: modelId,
+                    provider: providerId
+                };
+                await this.session.send({
+                    type: "chunk",
+                    thread_id: threadId,
+                    content: "",
+                    content_type: "text",
+                    content_metadata: { media_generation: mediaGeneration },
+                    done: false
+                });
+                const generated = await generate("reference_to_video", {
+                    prompt: expandedPrompt,
+                    aspect_ratio: aspectRatio,
+                    resolution,
+                    duration_seconds: duration,
+                    reference_images: referenceImages,
+                    reference_videos: referenceVideos,
+                    use_reference_video_audio: useReferenceVideoAudio
+                }, { mime: "video/mp4" }, (abort) => provider.referenceToVideo({ images: referenceImages, videos: referenceVideos }, {
+                    model: r2vModel,
+                    prompt: expandedPrompt,
+                    aspectRatio,
+                    resolution,
+                    durationSeconds: duration,
+                    useReferenceVideoAudio,
+                    signal: abort
+                }));
+                if (cancelled())
+                    return;
+                const assetId = seamAssetId(generated) ??
+                    (await storeMediaAsset(generated.output, "video/mp4", "mp4"));
+                const assistantMsgData = {
+                    type: "message",
+                    role: "assistant",
+                    content: [
+                        {
+                            type: "video",
+                            video: {
+                                type: "video",
+                                asset_id: assetId,
+                                format: "mp4",
+                                duration
+                            }
+                        }
+                    ],
+                    thread_id: threadId,
+                    workflow_id: workflowId,
+                    provider: providerId,
+                    model: modelId,
+                    media_generation: mediaGeneration
+                };
+                // Re-check: cancellation may have landed while the asset was persisting.
+                if (cancelled())
+                    return;
+                await this.saveMessageToDb(assistantMsgData);
+                await this.session.send(assistantMsgData);
+                await sendTerminalDone();
+                return;
+            }
+            if (mode === "audio" || mode === "music") {
+                const voice = isString(mediaGeneration.voice)
+                    ? mediaGeneration.voice
+                    : undefined;
+                const speed = isNumber(mediaGeneration.speed)
+                    ? mediaGeneration.speed
+                    : 1.0;
+                const requestedFormatRaw = isString(mediaGeneration.audio_format)
+                    ? mediaGeneration.audio_format.toLowerCase()
+                    : null;
+                const supportedFormats = new Set([
+                    "mp3",
+                    "wav",
+                    "pcm",
+                    "opus",
+                    "flac",
+                    "aac"
+                ]);
+                const requestedFormat = requestedFormatRaw && supportedFormats.has(requestedFormatRaw)
+                    ? requestedFormatRaw
+                    : null;
+                await this.session.send({
+                    type: "chunk",
+                    thread_id: threadId,
+                    content: "",
+                    content_type: "text",
+                    content_metadata: { media_generation: mediaGeneration },
+                    done: false
+                });
+                const durationSeconds = isNumber(mediaGeneration.duration)
+                    ? mediaGeneration.duration
+                    : undefined;
+                const audioGenerationId = randomUUID();
+                let assetId;
+                let audioMimeType;
+                await generate(mode === "music" ? "text_to_music" : "text_to_speech", mode === "music"
+                    ? { prompt: expandedPrompt, duration_seconds: durationSeconds }
+                    : {
+                        text: expandedPrompt,
+                        voice,
+                        speed,
+                        audio_format: requestedFormat
+                    }, null, async () => {
+                    const speech = mode === "music"
+                        ? await generateMusicBytes(provider, {
+                            model: {
+                                id: modelId,
+                                name: modelId,
+                                provider: providerId
+                            },
+                            prompt: expandedPrompt,
+                            durationSeconds
+                        }, cancelled)
+                        : await generateSpeechBytes(provider, {
+                            text: expandedPrompt,
+                            model: modelId,
+                            voice,
+                            speed,
+                            audioFormat: requestedFormat
+                        }, cancelled);
+                    if (!speech)
+                        return null;
+                    assetId = await storeMediaAsset(speech.bytes, speech.mimeType, speech.ext);
+                    audioMimeType = speech.mimeType;
+                    return assetId;
+                }, audioGenerationId);
+                if (cancelled())
+                    return;
+                if (!assetId || !audioMimeType) {
+                    throw new Error("Provider returned no audio data");
+                }
+                await linkGenerationAssets([audioGenerationId], [assetId]);
+                const assistantMsgData = {
+                    type: "message",
+                    role: "assistant",
+                    content: [
+                        {
+                            type: "audio",
+                            audio: {
+                                type: "audio",
+                                asset_id: assetId,
+                                mimeType: audioMimeType
+                            }
+                        }
+                    ],
+                    thread_id: threadId,
+                    workflow_id: workflowId,
+                    provider: providerId,
+                    model: modelId,
+                    media_generation: mediaGeneration
+                };
+                // Re-check: cancellation may have landed while the asset was persisting.
+                if (cancelled())
+                    return;
+                await this.saveMessageToDb(assistantMsgData);
+                await this.session.send(assistantMsgData);
+                await sendTerminalDone();
+                return;
+            }
+            if (mode === "image_edit" || mode === "image_to_video") {
+                // Resolve the source image from either the message content (most
+                // common path: user dropped an image into the composer) or from the
+                // explicit `source_asset_id` echo on the media_generation payload.
+                const sourceBytes = await this.deps.resolveSourceImageBytes(data, mediaGeneration, userId);
+                // A zero-length buffer (e.g. a storage read that resolved but came
+                // back empty) is truthy — without the length check it sails past this
+                // guard, then silently drops out of `attachAssets`'s image field
+                // downstream, so fal gets a request with no image at all and rejects
+                // it with an opaque 422 instead of the friendly error below.
+                if (!sourceBytes || sourceBytes.length === 0) {
+                    await this.session.send({
+                        type: "error",
+                        message: "A source image is required — drop or attach an image first",
+                        thread_id: threadId
+                    });
+                    return;
+                }
+                await this.session.send({
+                    type: "chunk",
+                    thread_id: threadId,
+                    content: "",
+                    content_type: "text",
+                    content_metadata: { media_generation: mediaGeneration },
+                    done: false
+                });
+                if (mode === "image_edit") {
+                    const variations = Math.max(1, Math.min(Number(mediaGeneration.variations ?? 1), 8));
+                    const targetWidth = isNumber(mediaGeneration.width)
+                        ? mediaGeneration.width
+                        : undefined;
+                    const targetHeight = isNumber(mediaGeneration.height)
+                        ? mediaGeneration.height
+                        : undefined;
+                    const strength = isNumber(mediaGeneration.strength)
+                        ? mediaGeneration.strength
+                        : undefined;
+                    const numInferenceSteps = isNumber(mediaGeneration.num_inference_steps)
+                        ? mediaGeneration.num_inference_steps
+                        : undefined;
+                    const editModel = {
+                        id: modelId,
+                        name: modelId,
+                        provider: providerId
+                    };
+                    const params = {
+                        model: editModel,
+                        prompt: expandedPrompt,
+                        targetWidth: targetWidth ?? null,
+                        targetHeight: targetHeight ?? null,
+                        strength: strength ?? null,
+                        numInferenceSteps: numInferenceSteps ?? null,
+                        signal
+                    };
+                    if (requestSeq !== undefined && requestSeq !== this.chatRequestSeq)
+                        return;
+                    const generated = await generate("image_to_image", {
+                        prompt: expandedPrompt,
+                        target_width: targetWidth ?? null,
+                        target_height: targetHeight ?? null,
+                        strength: strength ?? null,
+                        num_inference_steps: numInferenceSteps ?? null,
+                        num_images: variations,
+                        images: [sourceBytes, ...entityImageBytes]
+                    }, {}, (abort) => provider.imageToImages([sourceBytes, ...entityImageBytes], { ...params, signal: abort }, variations));
+                    if (cancelled())
+                        return;
+                    const imageContents = [];
+                    for (const [index, bytes] of generated.output.entries()) {
+                        // Per-variation: a cancel partway through must not keep persisting.
+                        if (cancelled())
+                            return;
+                        const mimeType = detectImageMime(bytes);
+                        const assetId = seamAssetId(generated, index) ??
+                            (await storeMediaAsset(bytes, mimeType, IMAGE_MIME_TO_EXT[mimeType] ?? "png"));
+                        imageContents.push({
+                            type: "image_url",
+                            image: {
+                                type: "image",
+                                asset_id: assetId,
+                                mimeType
+                            }
+                        });
+                    }
+                    const assistantMsgData = {
+                        type: "message",
+                        role: "assistant",
+                        content: imageContents,
+                        thread_id: threadId,
+                        workflow_id: workflowId,
+                        provider: providerId,
+                        model: modelId,
+                        media_generation: mediaGeneration
+                    };
+                    // Re-check: cancellation may have landed while the asset was persisting.
+                    if (cancelled())
+                        return;
+                    await this.saveMessageToDb(assistantMsgData);
+                    await this.session.send(assistantMsgData);
+                    await sendTerminalDone();
+                    return;
+                }
+                // image_to_video
+                const aspectRatio = isString(mediaGeneration.aspect_ratio)
+                    ? mediaGeneration.aspect_ratio
+                    : null;
+                const resolution = isString(mediaGeneration.resolution)
+                    ? mediaGeneration.resolution
+                    : null;
+                const duration = isNumber(mediaGeneration.duration)
+                    ? mediaGeneration.duration
+                    : null;
+                const numInferenceSteps = isNumber(mediaGeneration.num_inference_steps)
+                    ? mediaGeneration.num_inference_steps
+                    : null;
+                const i2vModel = {
+                    id: modelId,
+                    name: modelId,
+                    provider: providerId
+                };
+                const params = {
+                    model: i2vModel,
+                    prompt: expandedPrompt,
+                    aspectRatio,
+                    resolution,
+                    durationSeconds: duration,
+                    numInferenceSteps,
+                    signal
+                };
+                const generated = await generate("image_to_video", {
+                    prompt: expandedPrompt,
+                    aspect_ratio: aspectRatio,
+                    resolution,
+                    duration_seconds: duration,
+                    num_inference_steps: numInferenceSteps,
+                    images: [sourceBytes]
+                }, { mime: "video/mp4" }, (abort) => provider.imageToVideo(sourceBytes, { ...params, signal: abort }));
+                if (cancelled())
+                    return;
+                const assetId = seamAssetId(generated) ??
+                    (await storeMediaAsset(generated.output, "video/mp4", "mp4"));
+                const assistantMsgData = {
+                    type: "message",
+                    role: "assistant",
+                    content: [
+                        {
+                            type: "video",
+                            video: {
+                                type: "video",
+                                asset_id: assetId,
+                                format: "mp4",
+                                duration
+                            }
+                        }
+                    ],
+                    thread_id: threadId,
+                    workflow_id: workflowId,
+                    provider: providerId,
+                    model: modelId,
+                    media_generation: mediaGeneration
+                };
+                // Re-check: cancellation may have landed while the asset was persisting.
+                if (cancelled())
+                    return;
+                await this.saveMessageToDb(assistantMsgData);
+                await this.session.send(assistantMsgData);
+                await sendTerminalDone();
+                return;
+            }
+            // Modes not yet implemented on the backend — fall back to an informative
+            // error so the client can render the unsupported state cleanly.
+            await this.session.send({
+                type: "error",
+                message: `Media generation mode "${mode}" is not yet supported`,
+                thread_id: threadId
+            });
+        }
+        catch (err) {
+            if (cancelled())
+                return;
+            const errMsg = err instanceof Error ? err.message : String(err);
+            const scope = getRunTraceScope();
+            if (scope) {
+                trace.getActiveSpan()?.setStatus({ code: SpanStatusCode.ERROR });
+                await settleRunTrace(userId, scope.runId, { status: "failed", error: scope.policy.contentSuppressed ? "Execution failed" : errMsg, secretValues: scope.secretValues, contentSuppressed: scope.policy.contentSuppressed });
+            }
+            log.error("Media generation error", { threadId, mode, error: errMsg });
+            const failure = providerFailureMessage(err, providerId, modelId);
+            const failureMessage = `Generation failed: ${failure.message}`;
+            const assistantMsgData = {
+                type: "message",
+                role: "assistant",
+                content: failureMessage,
+                thread_id: threadId,
+                workflow_id: workflowId,
+                provider: providerId,
+                model: modelId,
+                media_generation: mediaGeneration
+            };
+            try {
+                await this.saveMessageToDb(assistantMsgData);
+            }
+            catch (persistError) {
+                this.session.logError("media failure message save failed", persistError);
+            }
+            await this.session.send({
+                type: "error",
+                message: failureMessage,
+                thread_id: threadId
+            });
+            await this.session.send(assistantMsgData);
+            await sendTerminalDone();
+        }
+    }
+    /**
+     * Handle a chat message that targets a workflow.
+     *
+     * Mirrors Python's process_messages_for_workflow → WorkflowMessageProcessor/
+     * ChatWorkflowMessageProcessor flow:
+     *   1. Load workflow from DB
+     *   2. Detect message input node names from graph
+     *   3. Prepare params (serialized message + history)
+     *   4. Run workflow via ExecutionSession (@nodetool-ai/execution)
+     *   5. Stream events (job_update, node_update, output_update)
+     *   6. Collect output_update results
+     *   7. Send response message with typed content, then the terminal chunk
+     */
+    async handleWorkflowMessage(data, requestSeq, signal) {
+        const threadId = isString(data.thread_id) ? data.thread_id : "";
+        const workflowId = isString(data.workflow_id) ? data.workflow_id : null;
+        const providerId = isString(data.provider)
+            ? data.provider
+            : this.deps.defaults.provider;
+        const model = isString(data.model) ? data.model : this.deps.defaults.model;
+        const userId = this.session.requireUserId();
+        const chatProjectId = (await Project.findByThread(userId, threadId))?.id ?? undefined;
+        const jobId = randomUUID();
+        log.info("Workflow message", { threadId, workflowId, jobId });
+        // Assigned once the run's abort listener is registered; released in the
+        // finally so a completed workflow's listener can't cancel() a runner that
+        // already finished when a later Stop/disconnect fires the same signal.
+        let releaseAbortListener = null;
+        try {
+            if (!workflowId) {
+                throw new Error("workflow_id is required for workflow processing");
+            }
+            // Load workflow from DB
+            const workflow = await Workflow.find(userId, workflowId);
+            if (!workflow) {
+                throw new Error(`Workflow ${workflowId} not found`);
+            }
+            const rawGraph = workflow.graph;
+            // Detect message input names from raw graph (reads node.data) — matches Python
+            const { messageName, messagesName } = this.detectMessageInputNames(rawGraph);
+            const graph = await this.deps.hydrateGraph(rawGraph);
+            if (this.deps.beforeRunJob) {
+                await this.deps.beforeRunJob(graph);
+            }
+            const messageInputName = (isString(data.workflow_message_input_name)
+                ? data.workflow_message_input_name
+                : null) ??
+                messageName ??
+                "message";
+            const messagesInputName = (isString(data.workflow_messages_input_name)
+                ? data.workflow_messages_input_name
+                : null) ??
+                messagesName ??
+                "messages";
+            // Build chat history for params — matches Python
+            const [dbMessages] = await Message.paginate(threadId, { limit: 1000 });
+            const inheritedTrace = getRunTraceScope();
+            seedStoredToolProvenance(dbMessages);
+            if (inheritedTrace) {
+                await registerRunTraceParents(userId, inheritedTrace.runId, dbMessages.map((m) => ({ kind: "message", id: m.id })));
+            }
+            const chatHistorySerialized = dbMessages.map((m) => ({
+                role: m.role,
+                content: m.content,
+                created_at: m.created_at,
+                thread_id: m.thread_id
+            }));
+            // Serialize current message
+            const currentMessage = {
+                role: isString(data.role) ? data.role : "user",
+                content: data.content,
+                thread_id: threadId,
+                workflow_id: workflowId,
+                provider: providerId,
+                model
+            };
+            // Prepare params — matches Python's WorkflowMessageProcessor
+            const params = {
+                [messageInputName]: currentMessage,
+                [messagesInputName]: [...chatHistorySerialized, currentMessage]
+            };
+            if (isObjectLike(data.params)) {
+                Object.assign(params, data.params);
+            }
+            // If chat workflow, add legacy params — matches Python's ChatWorkflowMessageProcessor
+            if (workflow.run_mode === "chat") {
+                const legacyChatInput = chatHistorySerialized.map((m) => ({
+                    role: m.role,
+                    content: extractTextContent(m.content),
+                    created_at: m.created_at
+                }));
+                params["chat_input"] = legacyChatInput;
+                if (messagesInputName !== "messages") {
+                    params["messages"] = legacyChatInput;
+                }
+            }
+            // Create processing context
+            const workspace = this.session.workspaceResolver
+                ? await this.session.workspaceResolver(workflowId, userId)
+                : null;
+            const context = createRuntimeContext({
+                jobId,
+                workflowId,
+                projectId: chatProjectId,
+                userId,
+                workspace,
+                assetOutputMode: this.session.mode === "text" ? "data_uri" : "temp_url"
+            });
+            context.runTraceContext = getRunTraceScope() ?? null;
+            // Expose executor/node-type resolution for sub-workflow nodes
+            context.setResolveExecutor((node) => this.session.resolveExecutor(node));
+            if (this.session.resolveNodeType) {
+                const resolverObj = isFunctionValue(this.session.resolveNodeType)
+                    ? { resolveNodeType: this.session.resolveNodeType }
+                    : this.session.resolveNodeType;
+                context.setResolveNodeType((nodeType) => resolverObj.resolveNodeType(nodeType));
+            }
+            await Job.create({ id: jobId, workflow_id: workflowId, user_id: userId, status: "running", params, graph });
+            await registerWorkflowRunTrace(context, { jobId, workflowId });
+            // Create and run workflow (A5: via the ExecutionSession facade — see
+            // the identical note in `startJobInner`).
+            const session = await ExecutionSession.create({
+                graph: toRawGraphInput(graph),
+                resolveExecutor: (node) => this.session.resolveExecutor(node),
+                bridgeFactory: async () => null,
+                jobLifecycleBridge: this.session.pythonBridge ?? null,
+                jobId,
+                workflowId,
+                context,
+                params,
+                validateNode: this.session.validateNode
+            });
+            const active = {
+                jobId,
+                workflowId,
+                context,
+                session,
+                graph,
+                finished: false,
+                status: "running",
+                requireTerminalResult: false,
+                executionOptions: { ...DEFAULT_RUN_JOB_EXECUTION_OPTIONS },
+                timings: {
+                    acceptedAt: performance.now(),
+                    queueMs: 0,
+                    graphLoadedMs: 0,
+                    graphHydratedMs: 0,
+                    preRunMs: 0,
+                    persistenceMs: 0,
+                    kernelStartedAt: performance.now()
+                }
+            };
+            this.deps.jobs.registerJob(jobId, active);
+            // The run already started inside `ExecutionSession.create()` above.
+            const executePromise = session.result;
+            // Stream events, collect output_update results
+            const result = {};
+            await this.session.send({
+                type: "job_update",
+                status: "running",
+                job_id: jobId,
+                workflow_id: workflowId
+            });
+            let finalOutputs = {};
+            const executionSettled = executePromise
+                .then((r) => {
+                active.status = r.status;
+                active.error = r.error;
+                finalOutputs = r.outputs ?? {};
+            })
+                .catch((err) => {
+                active.status = "failed";
+                active.error = err instanceof Error ? err.message : String(err);
+            })
+                .finally(() => {
+                active.finished = true;
+            });
+            const waitForActivity = createRelayActivityWaiter(active.context, executionSettled, signal);
+            const nodeTypes = new Map();
+            const graphNodes = graph.nodes ?? [];
+            for (const n of graphNodes) {
+                if (n.id) {
+                    nodeTypes.set(String(n.id), isString(n.type) ? n.type : "");
+                }
+            }
+            // A chat Stop / superseding message bumps chatRequestSeq. Unlike the
+            // other chat handlers this one owns a workflow runner, so cancel it and
+            // stop streaming when our turn is no longer current — otherwise the run
+            // completes and delivers an assistant message after the user stopped.
+            const superseded = () => requestSeq !== undefined && requestSeq !== this.chatRequestSeq;
+            // Cancel the moment Stop fires rather than waiting for the streaming loop
+            // below to come back around — the run may be parked inside a long node.
+            const onAbort = () => {
+                try {
+                    active.session.cancel();
+                }
+                catch {
+                    // best-effort cancel
+                }
+            };
+            if (signal?.aborted) {
+                onAbort();
+            }
+            else if (signal) {
+                signal.addEventListener("abort", onAbort, { once: true });
+                releaseAbortListener = () => signal.removeEventListener("abort", onAbort);
+            }
+            while (!active.finished || active.context.hasMessages()) {
+                if (superseded()) {
+                    try {
+                        active.session.cancel();
+                    }
+                    catch {
+                        // best-effort cancel
+                    }
+                    active.status = "cancelled";
+                    try {
+                        const job = await Job.get(jobId);
+                        if (job && job.status !== "cancelled") {
+                            job.markCancelled();
+                            await job.save();
+                        }
+                    }
+                    catch (err) {
+                        this.session.logError("workflow chat cancellation persistence failed", err);
+                    }
+                    this.deps.jobs.dropJob(jobId);
+                    return;
+                }
+                while (active.context.hasMessages()) {
+                    const msg = active.context.popMessage();
+                    if (!msg)
+                        break;
+                    const outbound = { ...msg };
+                    outbound.job_id ??= jobId;
+                    outbound.workflow_id ??= workflowId;
+                    // Every message, not just node updates: a `prediction` is where
+                    // ledger-priced generation spend (Replicate, Gemini, OpenAI, …)
+                    // reports itself.
+                    this.deps.jobs.handleNodeProviderCost(active, outbound);
+                    if (outbound.type === "node_update" ||
+                        outbound.type === "output_update") {
+                        const nodeId = String(outbound.node_id ?? "");
+                        const nodeType = nodeTypes.get(nodeId) ?? "";
+                        // Capture output_update values for the response message
+                        if (outbound.type === "output_update") {
+                            if (nodeType.includes("Output")) {
+                                const nodeName = isString(outbound.node_name)
+                                    ? outbound.node_name
+                                    : nodeType;
+                                result[nodeName] = outbound.value;
+                            }
+                            else {
+                                continue; // Skip non-output node output_updates
+                            }
+                        }
+                    }
+                    await this.session.send(outbound);
+                }
+                if (!active.finished) {
+                    await waitForActivity();
+                }
+            }
+            // Collect any outputs from the runner result — only Output-type nodes
+            // The kernel considers all leaf nodes as "output nodes", but for the
+            // response message we only want nodes whose type includes "Output"
+            // (matching Python's WorkflowMessageProcessor behavior).
+            for (const [nodeType, values] of Object.entries(finalOutputs)) {
+                if (!nodeType.includes("Output"))
+                    continue;
+                if (!result[nodeType] && Array.isArray(values) && values.length > 0) {
+                    result[nodeType] = values.length === 1 ? values[0] : values;
+                }
+            }
+            // Send terminal job_update if not already sent
+            await this.session.send({
+                type: "job_update",
+                status: active.status,
+                job_id: jobId,
+                workflow_id: workflowId,
+                error: active.error,
+                result: { outputs: finalOutputs }
+            });
+            // Persist final job status
+            try {
+                const job = (await Job.get(jobId));
+                // Don't overwrite a cancelled row (DB-only tRPC cancel) when the
+                // in-flight run finishes — keep the cancellation authoritative.
+                if (job) {
+                    if (job.status !== "cancelled") {
+                        if (active.status === "completed")
+                            job.markCompleted();
+                        else if (active.status === "failed")
+                            job.markFailed(active.error ?? "Unknown error");
+                        else if (active.status === "cancelled")
+                            job.markCancelled();
+                    }
+                    job.cost = this.deps.jobs.runMeasuredCost(active);
+                    await job.save();
+                }
+            }
+            catch (error) {
+                this.session.logError("workflow job persistence (final) failed", error);
+            }
+            // Create response message from workflow outputs — matches Python's _create_response_message
+            const responseContent = createWorkflowResponseContent(result);
+            const responseMsg = {
+                type: "message",
+                role: "assistant",
+                content: responseContent,
+                thread_id: threadId,
+                workflow_id: workflowId,
+                provider: providerId,
+                model,
+                job_id: jobId
+            };
+            await this.saveMessageToDb(responseMsg);
+            await this.session.send(responseMsg);
+            // Signal completion — done chunk with job_id + workflow_id
+            await this.session.send({
+                type: "chunk",
+                content: "",
+                done: true,
+                job_id: jobId,
+                workflow_id: workflowId,
+                thread_id: threadId
+            });
+            log.debug("Workflow message complete", { threadId, workflowId, jobId });
+        }
+        catch (err) {
+            const errMsg = err instanceof Error ? err.message : String(err);
+            const scope = getRunTraceScope();
+            if (scope) {
+                trace.getActiveSpan()?.setStatus({ code: SpanStatusCode.ERROR });
+                await settleRunTrace(userId, scope.runId, { status: "failed", error: scope.policy.contentSuppressed ? "Execution failed" : errMsg, secretValues: scope.secretValues, contentSuppressed: scope.policy.contentSuppressed });
+            }
+            log.error("Workflow message error", {
+                threadId,
+                workflowId,
+                error: errMsg
+            });
+            await this.session.send({
+                type: "error",
+                message: `Error processing workflow: ${errMsg}`,
+                job_id: jobId,
+                workflow_id: workflowId,
+                thread_id: threadId
+            });
+            // Send done chunk even on error — matches Python
+            await this.session.send({
+                type: "chunk",
+                content: "",
+                done: true,
+                job_id: jobId,
+                workflow_id: workflowId,
+                thread_id: threadId
+            });
+        }
+        finally {
+            releaseAbortListener?.();
+            // Always release the concurrency slot and drain the queue, even if
+            // streaming/persist/sendMessage threw above. Otherwise a mid-stream
+            // socket-write failure would orphan the ActiveJob and permanently shrink
+            // the MAX_CONCURRENT_JOBS cap (run_job then queues forever).
+            this.deps.jobs.releaseJob(jobId);
+        }
+    }
+    /**
+     * If `event` is a tool_call_update, also emit a synthetic assistant message
+     * whose `tool_calls` array contains this call. The chat UI renders a
+     * persistent ToolCallCard from messages with tool_calls; tool_call_update
+     * by itself only drives transient "now running" state. We skip events that
+     * already carry `agent_execution_id` because those are routed to
+     * ExecutionTree via the agent_execution path.
+     */
+    async emitSyntheticToolCallCard(event) {
+        if (event["type"] !== "tool_call_update")
+            return;
+        const toolCallId = event["tool_call_id"];
+        const name = event["name"];
+        if (!isString(toolCallId) || !isString(name))
+            return;
+        if (!toolCallId || !name)
+            return;
+        const args = isObjectLike(event["args"])
+            ? event["args"]
+            : {};
+        const message = isString(event["message"]) ? event["message"] : null;
+        await this.session.send({
+            type: "message",
+            role: "assistant",
+            content: null,
+            tool_calls: [
+                {
+                    id: toolCallId,
+                    name,
+                    args,
+                    message,
+                    result: null
+                }
+            ],
+            parent_tool_call_id: event["parent_tool_call_id"] ?? null,
+            subtask_depth: event["subtask_depth"] ?? null,
+            thread_id: event["thread_id"] ?? null,
+            workflow_id: event["workflow_id"] ?? null
+        });
+    }
+}
+//# sourceMappingURL=chat-turn.js.map