@agent-native/core 0.149.1 → 0.149.3

package/dist/agent/production-agent.js

@@ -13,7 +13,7 @@ import { extractMcpToolResultImages } from "../mcp-client/index.js";
 import { isMcpToolAllowedForRequest } from "../mcp-client/visibility.js";
 import { shouldInferSentimentForTurn } from "../observability/sentiment.js";
 import { completeRun as completeProgressRun, startRun as startProgressRun, updateRunProgress, } from "../progress/registry.js";
-import { getFrontmatterValue, parseFrontmatter, } from "../resources/metadata.js";
+import { isRuntimeVisibleScope, parseSkillFrontmatter, } from "../server/agent-chat/skill-frontmatter.js";
 import { canUseDeployCredentialFallbackForRequest, getProviderCredentialAuthFailure, readDeployCredentialEnv, } from "../server/credential-provider.js";
 import { readBody } from "../server/h3-helpers.js";
 import { getRequestRunContext, ensureRequestRunContext, getRequestContext, getRequestOrgId, getRequestUserEmail, runWithRequestContext, } from "../server/request-context.js";
@@ -39,6 +39,7 @@ import { ProcessorChain, TripWire, toolCallsFromContent, } from "./processors.js
 import { startRun, subscribeToRun, getActiveRunForThread, getActiveRunForThreadAsync, getRun, abortRun, abortRunDurably, abortTurnDurably, tryClaimRunSlot, isHostedRuntime, resolveRunSoftTimeoutMs, resolveRunToolTimeoutCeilingMs, } from "./run-manager.js";
 import { writeLedgerEntry, readLedgerEntry, clearLedgerForThread, insertRun, insertRunEvent, isTurnAborted, markRunAborted, updateRunHeartbeat, updateRunStatusIfRunning, setRunError, setRunTerminalReason, claimBackgroundRun, readBackgroundRunClaim, recordRunDiagnostic, countRunsForTurn, RUN_DIAG_STAGE, UNCLAIMED_BACKGROUND_RUN_GRACE_MS, } from "./run-store.js";
 import { buildCurrentTimeUserContext } from "./runtime-context.js";
+import { consumeAgentToolApproval, createAgentToolApproval, } from "./tool-approval-store.js";
 import { findCompletedJournalEntry, } from "./tool-call-journal.js";
 import { redactSensitiveFields, sanitizeToolErrorText, sanitizeToolErrorValue, } from "./tool-error-redaction.js";
 import { describeToolResultImages, extractAgentImagesFromActionResult, } from "./tool-result-images.js";
@@ -688,7 +689,7 @@ const VISIBLE_RETRY_THRESHOLD_MS = 10_000;
  */
 const FOREGROUND_FIRST_MODEL_EVENT_TIMEOUT_MS = 25_000;
 // Raised from 1 -> 2 now that each retry actually adapts (raises the token
-// ceiling and steps reasoning effort down a tier) instead of re-issuing the
+// ceiling and steps effort down a tier) instead of re-issuing the
 // exact same doomed request twice.
 const EMPTY_FINAL_RESPONSE_RETRY_LIMIT = 2;
 const MAIN_CHAT_INTERNAL_CONTINUATION_LIMIT = 6;
@@ -1198,9 +1199,9 @@ function escapeReferenceAttribute(value) {
     return value.replace(/&/g, "&").replace(/"/g, """);
 }
 function isRuntimeVisibleSkillContent(content) {
-    const frontmatter = parseFrontmatter(content);
-    const scope = getFrontmatterValue(frontmatter, "scope")?.trim().toLowerCase();
-    return scope !== "dev";
+    // Route through the shared normalizer so an unrecognized `scope:` stays
+    // invisible here too. A local `!== "dev"` check silently readmits it.
+    return isRuntimeVisibleScope(parseSkillFrontmatter(content).scope);
 }
 export async function resolveSkillReferenceContent(ref) {
     if (!ref.path && !ref.name)
@@ -2120,6 +2121,8 @@ export async function executeAgentToolCall(options) {
             threadId: options.threadId,
             turnId: options.turnId,
             approvedToolCalls: options.approvedToolCalls,
+            onApprovalRequired: options.onApprovalRequired,
+            consumeApproval: options.consumeApproval,
         });
     }
     catch (error) {
@@ -2307,6 +2310,51 @@ function stableStringify(value) {
 export function toolCallCacheKey(toolName, input) {
     return `${toolName}:${stableStringify(normalizeToolCallInputForHistory(input))}`;
 }
+export function findApprovedStructuredToolCall(history, approvedToolCalls) {
+    if (!Array.isArray(history) || !approvedToolCalls?.length)
+        return undefined;
+    const approved = new Set(approvedToolCalls);
+    const calls = new Map();
+    let match;
+    for (const message of history) {
+        if (message.role === "assistant") {
+            for (const part of message.content) {
+                if (part.type !== "tool-call")
+                    continue;
+                const callId = typeof part.id === "string"
+                    ? part.id
+                    : typeof part.toolCallId === "string"
+                        ? part.toolCallId
+                        : "";
+                const name = typeof part.name === "string"
+                    ? part.name
+                    : typeof part.toolName === "string"
+                        ? part.toolName
+                        : "";
+                if (!callId || !name)
+                    continue;
+                calls.set(callId, { name, input: part.input ?? part.args ?? {} });
+            }
+            continue;
+        }
+        for (const part of message.content) {
+            if (part.type !== "tool-result")
+                continue;
+            const call = calls.get(part.toolCallId);
+            if (!call || !approved.has(toolCallCacheKey(call.name, call.input))) {
+                continue;
+            }
+            const result = part.content.toLowerCase();
+            if (!result.includes("did not execute") &&
+                !result.includes("awaiting human approval") &&
+                !result.includes("waiting for your approval")) {
+                continue;
+            }
+            match = { ...call, callId: part.toolCallId };
+        }
+    }
+    return match;
+}
 const INTERRUPTED_TOOL_LEDGER_POLL_MS = process.env.NODE_ENV === "test" ? 0 : 2_000;
 async function waitForInterruptedToolLedgerEntry(opts) {
     const pollMs = INTERRUPTED_TOOL_LEDGER_POLL_MS;
@@ -3965,7 +4013,16 @@ export async function runAgentLoop(opts) {
             const approvalKey = toolCallCacheKey(toolCall.name, toolCall.input);
             // Consume a grant on its first exact match. A second identical call in
             // the same continuation must request its own human approval.
-            const wasApproved = approvedToolCallKeys.delete(approvalKey);
+            const approvalBinding = {
+                toolName: toolCall.name,
+                input: toolCall.input,
+                callId: toolCall.id,
+                approvalKey,
+            };
+            const requestedApproval = approvedToolCallKeys.delete(approvalKey);
+            const wasApproved = requestedApproval && opts.consumeApproval
+                ? await opts.consumeApproval(approvalBinding)
+                : requestedApproval;
             if (actionEntry.needsApproval && !wasApproved) {
                 let mustApprove = false;
                 try {
@@ -3989,6 +4046,7 @@ export async function runAgentLoop(opts) {
                     mustApprove = true;
                 }
                 if (mustApprove) {
+                    await opts.onApprovalRequired?.(approvalBinding);
                     send({
                         type: "tool_start",
                         id: toolCall.id,
@@ -4231,370 +4289,401 @@ export async function runAgentLoop(opts) {
                 tool: toolCall.name,
                 input: toolCall.input,
             });
-            const toolCallSchemaError = toolCallErrors.get(toolCall.id);
-            if (toolCallSchemaError && !toolInputNormalized) {
-                const result = finalizeToolErrorResult(toolInputSchemaErrorResult(toolCall.name, toolCallSchemaError.input, toolCallSchemaError.error, actionEntry?.tool.parameters));
-                send({
-                    type: "tool_done",
-                    id: toolCall.id,
-                    tool: toolCall.name,
-                    input: toolCall.input,
-                    result,
-                    isError: true,
-                    completedSideEffect: false,
-                });
-                recordToolResult(result, true);
-                return {
-                    type: "tool-result",
-                    toolCallId: toolCall.id,
-                    toolName: toolCall.name,
-                    toolInput: wireToolInput,
-                    content: result,
-                    isError: true,
-                };
-            }
-            const rawToolInputError = validateRawToolInput(actionEntry, toolCall.input);
-            if (rawToolInputError) {
-                const result = finalizeToolErrorResult(toolInputSchemaErrorResult(toolCall.name, toolCall.input, rawToolInputError, actionEntry.tool.parameters));
-                send({
-                    type: "tool_done",
-                    id: toolCall.id,
-                    tool: toolCall.name,
-                    input: toolCall.input,
-                    result,
-                    isError: true,
-                    completedSideEffect: false,
-                });
-                recordToolResult(result, true);
-                return {
-                    type: "tool-result",
-                    toolCallId: toolCall.id,
-                    toolName: toolCall.name,
-                    toolInput: wireToolInput,
-                    content: result,
-                    isError: true,
-                };
-            }
-            // dedupe: false opts a read-only tool out of the guard entirely — the
-            // cacheKey stays null so it never gets skipped-as-duplicate and never
-            // populates the cache (see the success handler below, which also
-            // leaves dedupe:false results uncached and un-cleared).
-            const cacheKey = actionEntry.readOnly === true && actionEntry.dedupe !== false
-                ? toolCallCacheKey(toolCall.name, toolCall.input)
-                : null;
-            if (cacheKey && readOnlyToolResultCache.has(cacheKey)) {
-                const previousResult = readOnlyToolResultCache.get(cacheKey) ?? "";
-                // `contextMessages` (not `messages`) is what the model actually sees
-                // this iteration — context-xray eviction/summarization and
-                // observational-memory trimming can drop the earlier result from
-                // view even though it's still cached here. Only strike-count the
-                // repeat when the model could have looked back and found it itself.
-                const visible = isCachedToolResultVisibleInContext(contextMessages, toolCall, previousResult);
+            let toolDoneEmitted = false;
+            const emitToolDone = (event) => {
+                send(event);
+                toolDoneEmitted = true;
+            };
+            // Every tool_start must have exactly one matching tool_done. Keeping the
+            // whole post-start path inside this finally block turns unexpected
+            // synchronous failures in validation, cache handling, or future branches
+            // into an explicit tool error instead of leaving run-manager's in-flight
+            // counter latched forever.
+            try {
+                const toolCallSchemaError = toolCallErrors.get(toolCall.id);
+                if (toolCallSchemaError && !toolInputNormalized) {
+                    const result = finalizeToolErrorResult(toolInputSchemaErrorResult(toolCall.name, toolCallSchemaError.input, toolCallSchemaError.error, actionEntry?.tool.parameters));
+                    emitToolDone({
+                        type: "tool_done",
+                        id: toolCall.id,
+                        tool: toolCall.name,
+                        input: toolCall.input,
+                        result,
+                        isError: true,
+                        completedSideEffect: false,
+                    });
+                    recordToolResult(result, true);
+                    return {
+                        type: "tool-result",
+                        toolCallId: toolCall.id,
+                        toolName: toolCall.name,
+                        toolInput: wireToolInput,
+                        content: result,
+                        isError: true,
+                    };
+                }
+                const rawToolInputError = validateRawToolInput(actionEntry, toolCall.input);
+                if (rawToolInputError) {
+                    const result = finalizeToolErrorResult(toolInputSchemaErrorResult(toolCall.name, toolCall.input, rawToolInputError, actionEntry.tool.parameters));
+                    emitToolDone({
+                        type: "tool_done",
+                        id: toolCall.id,
+                        tool: toolCall.name,
+                        input: toolCall.input,
+                        result,
+                        isError: true,
+                        completedSideEffect: false,
+                    });
+                    recordToolResult(result, true);
+                    return {
+                        type: "tool-result",
+                        toolCallId: toolCall.id,
+                        toolName: toolCall.name,
+                        toolInput: wireToolInput,
+                        content: result,
+                        isError: true,
+                    };
+                }
+                // dedupe: false opts a read-only tool out of the guard entirely — the
+                // cacheKey stays null so it never gets skipped-as-duplicate and never
+                // populates the cache (see the success handler below, which also
+                // leaves dedupe:false results uncached and un-cleared).
+                const cacheKey = actionEntry.readOnly === true && actionEntry.dedupe !== false
+                    ? toolCallCacheKey(toolCall.name, toolCall.input)
+                    : null;
+                if (cacheKey && readOnlyToolResultCache.has(cacheKey)) {
+                    const previousResult = readOnlyToolResultCache.get(cacheKey) ?? "";
+                    // `contextMessages` (not `messages`) is what the model actually sees
+                    // this iteration — context-xray eviction/summarization and
+                    // observational-memory trimming can drop the earlier result from
+                    // view even though it's still cached here. Only strike-count the
+                    // repeat when the model could have looked back and found it itself.
+                    const visible = isCachedToolResultVisibleInContext(contextMessages, toolCall, previousResult);
+                    let result;
+                    if (visible) {
+                        const repeats = (duplicateReadOnlyToolCalls.get(cacheKey) ?? 0) + 1;
+                        duplicateReadOnlyToolCalls.set(cacheKey, repeats);
+                        result = visibleDuplicateReadOnlyToolResult(toolCall.name);
+                        if (repeats >= 3) {
+                            requestedActionStop ??= {
+                                message: "I stopped because the agent kept asking for the same read-only context it already had. Please send the request again if you want me to retry from a fresh turn.",
+                                errorCode: "duplicate_read_only_tool",
+                            };
+                        }
+                    }
+                    else {
+                        // The earlier result was trimmed out of the model's visible
+                        // context — this isn't a repetitive loop, the model legitimately
+                        // can't see the answer anymore. Re-serve it in full and don't
+                        // count a strike.
+                        duplicateReadOnlyToolCalls.set(cacheKey, 0);
+                        result = resurfacedDuplicateReadOnlyToolResult(toolCall.name, previousResult);
+                    }
+                    emitToolDone({
+                        type: "tool_done",
+                        id: toolCall.id,
+                        tool: toolCall.name,
+                        input: toolCall.input,
+                        result,
+                        completedSideEffect: false,
+                    });
+                    recordToolResult(result, false);
+                    return {
+                        type: "tool-result",
+                        toolCallId: toolCall.id,
+                        toolName: toolCall.name,
+                        toolInput: wireToolInput,
+                        content: result,
+                    };
+                }
+                if (opts.executionMode === "plan" &&
+                    !isPlanModeToolCallAllowed(toolCall.name, toolCall.input, actionEntry)) {
+                    const result = planModeBlockedMessage(toolCall.name);
+                    emitToolDone({
+                        type: "tool_done",
+                        id: toolCall.id,
+                        tool: toolCall.name,
+                        input: toolCall.input,
+                        result,
+                        isError: true,
+                        completedSideEffect: false,
+                    });
+                    recordToolResult(result, true);
+                    return {
+                        type: "tool-result",
+                        toolCallId: toolCall.id,
+                        toolName: toolCall.name,
+                        toolInput: wireToolInput,
+                        content: result,
+                        isError: true,
+                    };
+                }
                 let result;
-                if (visible) {
-                    const repeats = (duplicateReadOnlyToolCalls.get(cacheKey) ?? 0) + 1;
-                    duplicateReadOnlyToolCalls.set(cacheKey, repeats);
-                    result = visibleDuplicateReadOnlyToolResult(toolCall.name);
-                    if (repeats >= 3) {
+                let isError = false;
+                let mcpApp;
+                let toolResultImages;
+                try {
+                    // The run may have been aborted while we waited above for an
+                    // interrupted tool's ledger result (the wait can poll for minutes).
+                    // Re-check before invoking the action: starting it now would spawn a
+                    // fresh zombie execution — a duplicate side effect / double charge —
+                    // which the ledger-recovery path exists to prevent. The Promise.race
+                    // "Run aborted" leg below only rejects AFTER the action is invoked, so
+                    // it cannot guard this. Throw here instead, handled like any abort.
+                    if (signal.aborted) {
+                        throw new Error("Run aborted");
+                    }
+                    const timeoutSignal = AbortSignal.timeout(toolTimeoutMs);
+                    const actionUserEmail = opts.ownerEmail ?? getRequestUserEmail();
+                    const actionOrgId = opts.orgId ?? getRequestOrgId() ?? null;
+                    const actionContext = {
+                        send,
+                        userEmail: actionUserEmail ?? undefined,
+                        orgId: actionOrgId,
+                        appId: opts.appId,
+                        caller: opts.actionCaller ?? "tool",
+                        automation: opts.automation,
+                        networkProtocol: opts.networkProtocol,
+                        networkId: opts.networkId,
+                        networkPeer: opts.networkPeer,
+                        delegationDepth: opts.delegationDepth,
+                        visitedApps: opts.visitedApps,
+                        attachments: opts.attachments,
+                        signal,
+                        // Audit attribution: the action name + the agent thread/turn that
+                        // triggered this call, so a mutation can be traced to its run.
+                        actionName: toolCall.name,
+                        ...(wasApproved ? { approvedToolCallKey: approvalKey } : {}),
+                        ...(opts.threadId ? { threadId: opts.threadId } : {}),
+                        ...(opts.runId ? { runId: opts.runId } : {}),
+                        ...(opts.turnId ? { turnId: opts.turnId } : {}),
+                    };
+                    const requestContext = getRequestContext();
+                    const invokeAction = () => actionEntry.run(toolCall.input, actionContext);
+                    // Keep a reference to the action promise so we can attach a zombie-
+                    // detection continuation AFTER Promise.race abandons it on run abort.
+                    // The promise itself is not awaited here — Promise.race owns the await.
+                    const actionPromise = Promise.resolve(runWithRequestContext({
+                        ...(requestContext ?? {}),
+                        ...(actionUserEmail ? { userEmail: actionUserEmail } : {}),
+                        ...(actionOrgId ? { orgId: actionOrgId } : {}),
+                        ...(requestContext?.run ? { run: requestContext.run } : {}),
+                    }, invokeAction));
+                    // When the run is aborted (soft-timeout / user cancel) while this tool
+                    // call is in flight, Promise.race below will throw "Run aborted" and the
+                    // action's promise becomes a zombie — it keeps running but its result is
+                    // never returned to the loop. If the zombie eventually resolves, write
+                    // the result to the durable ledger keyed by (threadId, toolKey) so the
+                    // next continuation chunk can recover it instead of re-executing the
+                    // side effect.
+                    if (opts.threadId && !actionEntry.readOnly) {
+                        const ledgerThreadId = opts.threadId;
+                        const ledgerToolKey = toolCallCacheKey(toolCall.name, toolCall.input);
+                        actionPromise
+                            .then((zombieRaw) => {
+                            const zombieMcp = isMcpActionResult(zombieRaw)
+                                ? zombieRaw
+                                : null;
+                            if (zombieMcp &&
+                                zombieMcp.raw &&
+                                typeof zombieMcp.raw === "object" &&
+                                zombieMcp.raw.isError === true) {
+                                return;
+                            }
+                            const zombieText = zombieMcp ? zombieMcp.text : zombieRaw;
+                            const zombieStr = typeof zombieText === "string"
+                                ? zombieText
+                                : JSON.stringify(zombieText, null, 2);
+                            void writeLedgerEntry(ledgerThreadId, ledgerToolKey, zombieStr);
+                        })
+                            .catch(() => {
+                            // Action errored in the zombie — no result to ledger.
+                        });
+                    }
+                    const raw = await Promise.race([
+                        actionPromise,
+                        new Promise((_, reject) => {
+                            timeoutSignal.addEventListener("abort", () => reject(new Error(`Tool call timed out after ${toolTimeoutMs / 1000} seconds`)));
+                        }),
+                        // Stop waiting on the tool when the run itself is aborted (e.g. the
+                        // run-manager soft timeout, or a user cancel). Without this leg the
+                        // loop blocks on an in-flight tool for up to TOOL_TIMEOUT_MS after
+                        // the run signal has already fired.
+                        new Promise((_, reject) => {
+                            if (signal.aborted) {
+                                reject(new Error("Run aborted"));
+                                return;
+                            }
+                            signal.addEventListener("abort", () => reject(new Error("Run aborted")), { once: true });
+                        }),
+                    ]);
+                    const mcpResult = isMcpActionResult(raw) ? raw : null;
+                    const rawForAgent = mcpResult ? mcpResult.text : raw;
+                    if (mcpResult &&
+                        mcpResult.raw &&
+                        typeof mcpResult.raw === "object" &&
+                        mcpResult.raw.isError === true) {
+                        isError = true;
+                    }
+                    mcpApp = mcpResult?.mcpApp;
+                    // Demo mode is browser-local presentation state. The agent and MCP
+                    // layers always receive the real, access-scoped tool result.
+                    let resultForAgent = rawForAgent;
+                    // Vision images for the model: MCP tools return standard `image`
+                    // content parts; first-party actions opt in via the well-known
+                    // `_agentImages` result field (stripped from the JSON the model
+                    // reads). The images array
+                    // never touches the ledger — only the compact text notes appended
+                    // below are persisted.
+                    let imageNotes = [];
+                    if (mcpResult) {
+                        const mcpImages = extractMcpToolResultImages(mcpResult.raw);
+                        if (mcpImages.length > 0)
+                            toolResultImages = mcpImages;
+                    }
+                    else {
+                        const extracted = extractAgentImagesFromActionResult(resultForAgent);
+                        resultForAgent = extracted.value;
+                        imageNotes = extracted.notes;
+                        if (extracted.images.length > 0) {
+                            toolResultImages = extracted.images;
+                        }
+                    }
+                    if (toolResultImages) {
+                        imageNotes = [
+                            ...describeToolResultImages(toolResultImages),
+                            ...imageNotes,
+                        ];
+                    }
+                    let resultStr = typeof resultForAgent === "string"
+                        ? resultForAgent
+                        : JSON.stringify(resultForAgent, null, 2);
+                    if (resultStr.length > toolMaxResultChars) {
+                        const truncated = resultStr.slice(0, toolMaxResultChars);
+                        resultStr = `${truncated}\n\n...[truncated — full result was ${resultStr.length.toLocaleString()} chars; only first ${toolMaxResultChars.toLocaleString()} shown]`;
+                    }
+                    // Image notes go after truncation so they always survive into the
+                    // persisted result string (the durable record that an image existed).
+                    if (imageNotes.length > 0) {
+                        resultStr = `${resultStr}\n\n${imageNotes.join("\n")}`;
+                    }
+                    result = resultStr;
+                    if (toolCall.name === TOOL_SEARCH_ACTION_NAME && !isError) {
+                        const added = expandActiveTools(extractToolSearchResultNames(rawForAgent));
+                        if (added.length > 0) {
+                            result += `\n\nLoaded matching tool schemas for next step: ${added.join(", ")}`;
+                        }
+                    }
+                }
+                catch (err) {
+                    if (isAgentActionStopError(err)) {
+                        const message = sanitizeToolErrorValue(err.message) ||
+                            `Stopped after ${toolCall.name} failed.`;
+                        result = sanitizeToolErrorValue(err.toolResult || message);
                         requestedActionStop ??= {
-                            message: "I stopped because the agent kept asking for the same read-only context it already had. Please send the request again if you want me to retry from a fresh turn.",
-                            errorCode: "duplicate_read_only_tool",
+                            message,
+                            ...(err.errorCode ? { errorCode: err.errorCode } : {}),
                         };
                     }
+                    else {
+                        const message = sanitizeToolErrorValue(err);
+                        result = `Error running ${toolCall.name}: ${message}${rateLimitRecoveryHint(message)}`;
+                    }
+                    isError = true;
                 }
-                else {
-                    // The earlier result was trimmed out of the model's visible
-                    // context — this isn't a repetitive loop, the model legitimately
-                    // can't see the answer anymore. Re-serve it in full and don't
-                    // count a strike.
-                    duplicateReadOnlyToolCalls.set(cacheKey, 0);
-                    result = resurfacedDuplicateReadOnlyToolResult(toolCall.name, previousResult);
+                if (isError) {
+                    result = finalizeToolErrorResult(result);
                 }
-                send({
-                    type: "tool_done",
-                    id: toolCall.id,
-                    tool: toolCall.name,
-                    input: toolCall.input,
-                    result,
-                    completedSideEffect: false,
-                });
-                recordToolResult(result, false);
-                return {
-                    type: "tool-result",
-                    toolCallId: toolCall.id,
-                    toolName: toolCall.name,
-                    toolInput: wireToolInput,
-                    content: result,
-                };
-            }
-            if (opts.executionMode === "plan" &&
-                !isPlanModeToolCallAllowed(toolCall.name, toolCall.input, actionEntry)) {
-                const result = planModeBlockedMessage(toolCall.name);
-                send({
+                // Side-channel warnings raised anywhere inside the action's call stack
+                // (see `action-warnings.ts`). Drained here rather than in the success
+                // branch so an action that warns and then throws still surfaces it, and
+                // so nothing stays pending to bleed into a later tool's result.
+                const agentWarnings = drainAgentWarnings();
+                if (agentWarnings.length > 0) {
+                    result = `${result}\n\n${formatAgentWarningsForToolResult(agentWarnings)}`;
+                }
+                // Auto-refresh the UI after a successful mutating tool call. Any call
+                // that isn't read-only — by its own per-call Plan-mode effect, else the
+                // action's readOnly flag — is assumed to mutate. The client's useDbSync
+                // listener sees a change event with source:"action" and invalidates
+                // ["action"] queries so list-* / get-* refetch. This makes refresh after
+                // agent writes reliable without the model needing to remember to call
+                // `refresh-screen` itself.
+                if (!isError) {
+                    try {
+                        const { actionCallIsReadOnly, notifyActionChangeInBackground } = await import("../server/action-change.js");
+                        if (!actionCallIsReadOnly(actionEntry, toolCall.input, false)) {
+                            const owner = opts.ownerEmail ?? getRequestUserEmail() ?? undefined;
+                            const orgId = opts.orgId ?? getRequestOrgId() ?? undefined;
+                            notifyActionChangeInBackground({
+                                actionName: toolCall.name,
+                                ...(owner ? { owner } : {}),
+                                ...(orgId ? { orgId } : {}),
+                            });
+                        }
+                    }
+                    catch (error) {
+                        // poll module may be unavailable in non-server contexts — keep the
+                        // tool result, but make the failed background refresh observable.
+                        console.warn("Could not notify the action-change poller after a tool call", error);
+                    }
+                }
+                emitToolDone({
                     type: "tool_done",
                     id: toolCall.id,
                     tool: toolCall.name,
                     input: toolCall.input,
                     result,
-                    isError: true,
-                    completedSideEffect: false,
+                    ...(isError ? { isError: true } : {}),
+                    ...(isError
+                        ? { completedSideEffect: false }
+                        : actionEntry.readOnly !== true
+                            ? { completedSideEffect: true }
+                            : {}),
+                    ...(mcpApp ? { mcpApp } : {}),
+                    ...(actionEntry.chatUI ? { chatUI: actionEntry.chatUI } : {}),
                 });
-                recordToolResult(result, true);
+                recordToolResult(result, isError);
+                if (!isError) {
+                    if (cacheKey) {
+                        readOnlyToolResultCache.set(cacheKey, result);
+                    }
+                    else if (actionEntry.readOnly !== true) {
+                        // A genuine write invalidates all cached reads. A dedupe:false
+                        // read-only tool also has a null cacheKey (see above) but must NOT
+                        // clear the cache — it isn't a write and other tools' cached reads
+                        // are still valid.
+                        readOnlyToolResultCache.clear();
+                        duplicateReadOnlyToolCalls.clear();
+                    }
+                }
                 return {
                     type: "tool-result",
                     toolCallId: toolCall.id,
                     toolName: toolCall.name,
                     toolInput: wireToolInput,
                     content: result,
-                    isError: true,
+                    ...(isError ? { isError } : {}),
+                    ...(!isError && toolResultImages && toolResultImages.length > 0
+                        ? { images: toolResultImages }
+                        : {}),
                 };
             }
-            let result;
-            let isError = false;
-            let mcpApp;
-            let toolResultImages;
-            try {
-                // The run may have been aborted while we waited above for an
-                // interrupted tool's ledger result (the wait can poll for minutes).
-                // Re-check before invoking the action: starting it now would spawn a
-                // fresh zombie execution — a duplicate side effect / double charge —
-                // which the ledger-recovery path exists to prevent. The Promise.race
-                // "Run aborted" leg below only rejects AFTER the action is invoked, so
-                // it cannot guard this. Throw here instead, handled like any abort.
-                if (signal.aborted) {
-                    throw new Error("Run aborted");
-                }
-                const timeoutSignal = AbortSignal.timeout(toolTimeoutMs);
-                const actionUserEmail = opts.ownerEmail ?? getRequestUserEmail();
-                const actionOrgId = opts.orgId ?? getRequestOrgId() ?? null;
-                const actionContext = {
-                    send,
-                    userEmail: actionUserEmail ?? undefined,
-                    orgId: actionOrgId,
-                    appId: opts.appId,
-                    caller: opts.actionCaller ?? "tool",
-                    automation: opts.automation,
-                    networkProtocol: opts.networkProtocol,
-                    networkId: opts.networkId,
-                    networkPeer: opts.networkPeer,
-                    delegationDepth: opts.delegationDepth,
-                    visitedApps: opts.visitedApps,
-                    attachments: opts.attachments,
-                    signal,
-                    // Audit attribution: the action name + the agent thread/turn that
-                    // triggered this call, so a mutation can be traced to its run.
-                    actionName: toolCall.name,
-                    ...(wasApproved ? { approvedToolCallKey: approvalKey } : {}),
-                    ...(opts.threadId ? { threadId: opts.threadId } : {}),
-                    ...(opts.runId ? { runId: opts.runId } : {}),
-                    ...(opts.turnId ? { turnId: opts.turnId } : {}),
-                };
-                const requestContext = getRequestContext();
-                const invokeAction = () => actionEntry.run(toolCall.input, actionContext);
-                // Keep a reference to the action promise so we can attach a zombie-
-                // detection continuation AFTER Promise.race abandons it on run abort.
-                // The promise itself is not awaited here — Promise.race owns the await.
-                const actionPromise = Promise.resolve(runWithRequestContext({
-                    ...(requestContext ?? {}),
-                    ...(actionUserEmail ? { userEmail: actionUserEmail } : {}),
-                    ...(actionOrgId ? { orgId: actionOrgId } : {}),
-                    ...(requestContext?.run ? { run: requestContext.run } : {}),
-                }, invokeAction));
-                // When the run is aborted (soft-timeout / user cancel) while this tool
-                // call is in flight, Promise.race below will throw "Run aborted" and the
-                // action's promise becomes a zombie — it keeps running but its result is
-                // never returned to the loop. If the zombie eventually resolves, write
-                // the result to the durable ledger keyed by (threadId, toolKey) so the
-                // next continuation chunk can recover it instead of re-executing the
-                // side effect.
-                if (opts.threadId && !actionEntry.readOnly) {
-                    const ledgerThreadId = opts.threadId;
-                    const ledgerToolKey = toolCallCacheKey(toolCall.name, toolCall.input);
-                    actionPromise
-                        .then((zombieRaw) => {
-                        const zombieMcp = isMcpActionResult(zombieRaw) ? zombieRaw : null;
-                        if (zombieMcp &&
-                            zombieMcp.raw &&
-                            typeof zombieMcp.raw === "object" &&
-                            zombieMcp.raw.isError === true) {
-                            return;
-                        }
-                        const zombieText = zombieMcp ? zombieMcp.text : zombieRaw;
-                        const zombieStr = typeof zombieText === "string"
-                            ? zombieText
-                            : JSON.stringify(zombieText, null, 2);
-                        void writeLedgerEntry(ledgerThreadId, ledgerToolKey, zombieStr);
-                    })
-                        .catch(() => {
-                        // Action errored in the zombie — no result to ledger.
+            finally {
+                if (!toolDoneEmitted) {
+                    const result = `Error running ${toolCall.name}: tool execution ended before returning a result.`;
+                    emitToolDone({
+                        type: "tool_done",
+                        id: toolCall.id,
+                        tool: toolCall.name,
+                        input: toolCall.input,
+                        result,
+                        isError: true,
+                        completedSideEffect: false,
                     });
-                }
-                const raw = await Promise.race([
-                    actionPromise,
-                    new Promise((_, reject) => {
-                        timeoutSignal.addEventListener("abort", () => reject(new Error(`Tool call timed out after ${toolTimeoutMs / 1000} seconds`)));
-                    }),
-                    // Stop waiting on the tool when the run itself is aborted (e.g. the
-                    // run-manager soft timeout, or a user cancel). Without this leg the
-                    // loop blocks on an in-flight tool for up to TOOL_TIMEOUT_MS after
-                    // the run signal has already fired.
-                    new Promise((_, reject) => {
-                        if (signal.aborted) {
-                            reject(new Error("Run aborted"));
-                            return;
-                        }
-                        signal.addEventListener("abort", () => reject(new Error("Run aborted")), { once: true });
-                    }),
-                ]);
-                const mcpResult = isMcpActionResult(raw) ? raw : null;
-                const rawForAgent = mcpResult ? mcpResult.text : raw;
-                if (mcpResult &&
-                    mcpResult.raw &&
-                    typeof mcpResult.raw === "object" &&
-                    mcpResult.raw.isError === true) {
-                    isError = true;
-                }
-                mcpApp = mcpResult?.mcpApp;
-                // Demo mode is browser-local presentation state. The agent and MCP
-                // layers always receive the real, access-scoped tool result.
-                let resultForAgent = rawForAgent;
-                // Vision images for the model: MCP tools return standard `image`
-                // content parts; first-party actions opt in via the well-known
-                // `_agentImages` result field (stripped from the JSON the model
-                // reads). The images array
-                // never touches the ledger — only the compact text notes appended
-                // below are persisted.
-                let imageNotes = [];
-                if (mcpResult) {
-                    const mcpImages = extractMcpToolResultImages(mcpResult.raw);
-                    if (mcpImages.length > 0)
-                        toolResultImages = mcpImages;
-                }
-                else {
-                    const extracted = extractAgentImagesFromActionResult(resultForAgent);
-                    resultForAgent = extracted.value;
-                    imageNotes = extracted.notes;
-                    if (extracted.images.length > 0) {
-                        toolResultImages = extracted.images;
-                    }
-                }
-                if (toolResultImages) {
-                    imageNotes = [
-                        ...describeToolResultImages(toolResultImages),
-                        ...imageNotes,
-                    ];
-                }
-                let resultStr = typeof resultForAgent === "string"
-                    ? resultForAgent
-                    : JSON.stringify(resultForAgent, null, 2);
-                if (resultStr.length > toolMaxResultChars) {
-                    const truncated = resultStr.slice(0, toolMaxResultChars);
-                    resultStr = `${truncated}\n\n...[truncated — full result was ${resultStr.length.toLocaleString()} chars; only first ${toolMaxResultChars.toLocaleString()} shown]`;
-                }
-                // Image notes go after truncation so they always survive into the
-                // persisted result string (the durable record that an image existed).
-                if (imageNotes.length > 0) {
-                    resultStr = `${resultStr}\n\n${imageNotes.join("\n")}`;
-                }
-                result = resultStr;
-                if (toolCall.name === TOOL_SEARCH_ACTION_NAME && !isError) {
-                    const added = expandActiveTools(extractToolSearchResultNames(rawForAgent));
-                    if (added.length > 0) {
-                        result += `\n\nLoaded matching tool schemas for next step: ${added.join(", ")}`;
-                    }
-                }
-            }
-            catch (err) {
-                if (isAgentActionStopError(err)) {
-                    const message = sanitizeToolErrorValue(err.message) ||
-                        `Stopped after ${toolCall.name} failed.`;
-                    result = sanitizeToolErrorValue(err.toolResult || message);
-                    requestedActionStop ??= {
-                        message,
-                        ...(err.errorCode ? { errorCode: err.errorCode } : {}),
-                    };
-                }
-                else {
-                    const message = sanitizeToolErrorValue(err);
-                    result = `Error running ${toolCall.name}: ${message}${rateLimitRecoveryHint(message)}`;
-                }
-                isError = true;
-            }
-            if (isError) {
-                result = finalizeToolErrorResult(result);
-            }
-            // Side-channel warnings raised anywhere inside the action's call stack
-            // (see `action-warnings.ts`). Drained here rather than in the success
-            // branch so an action that warns and then throws still surfaces it, and
-            // so nothing stays pending to bleed into a later tool's result.
-            const agentWarnings = drainAgentWarnings();
-            if (agentWarnings.length > 0) {
-                result = `${result}\n\n${formatAgentWarningsForToolResult(agentWarnings)}`;
-            }
-            // Auto-refresh the UI after a successful mutating tool call. Any call
-            // that isn't read-only — by its own per-call Plan-mode effect, else the
-            // action's readOnly flag — is assumed to mutate. The client's useDbSync
-            // listener sees a change event with source:"action" and invalidates
-            // ["action"] queries so list-* / get-* refetch. This makes refresh after
-            // agent writes reliable without the model needing to remember to call
-            // `refresh-screen` itself.
-            if (!isError) {
-                try {
-                    const { actionCallIsReadOnly, notifyActionChangeInBackground } = await import("../server/action-change.js");
-                    if (!actionCallIsReadOnly(actionEntry, toolCall.input, false)) {
-                        const owner = opts.ownerEmail ?? getRequestUserEmail() ?? undefined;
-                        const orgId = opts.orgId ?? getRequestOrgId() ?? undefined;
-                        notifyActionChangeInBackground({
-                            actionName: toolCall.name,
-                            ...(owner ? { owner } : {}),
-                            ...(orgId ? { orgId } : {}),
-                        });
-                    }
-                }
-                catch {
-                    // poll module may be unavailable in non-server contexts — ignore
-                }
-            }
-            send({
-                type: "tool_done",
-                id: toolCall.id,
-                tool: toolCall.name,
-                input: toolCall.input,
-                result,
-                ...(isError ? { isError: true } : {}),
-                ...(isError
-                    ? { completedSideEffect: false }
-                    : actionEntry.readOnly !== true
-                        ? { completedSideEffect: true }
-                        : {}),
-                ...(mcpApp ? { mcpApp } : {}),
-                ...(actionEntry.chatUI ? { chatUI: actionEntry.chatUI } : {}),
-            });
-            recordToolResult(result, isError);
-            if (!isError) {
-                if (cacheKey) {
-                    readOnlyToolResultCache.set(cacheKey, result);
-                }
-                else if (actionEntry.readOnly !== true) {
-                    // A genuine write invalidates all cached reads. A dedupe:false
-                    // read-only tool also has a null cacheKey (see above) but must NOT
-                    // clear the cache — it isn't a write and other tools' cached reads
-                    // are still valid.
-                    readOnlyToolResultCache.clear();
-                    duplicateReadOnlyToolCalls.clear();
+                    recordToolResult(result, true);
                 }
             }
-            return {
-                type: "tool-result",
-                toolCallId: toolCall.id,
-                toolName: toolCall.name,
-                toolInput: wireToolInput,
-                content: result,
-                ...(isError ? { isError } : {}),
-                ...(!isError && toolResultImages && toolResultImages.length > 0
-                    ? { images: toolResultImages }
-                    : {}),
-            };
         };
         const getParallelBatchKind = (toolCall) => {
             const entry = actions[toolCall.name];
@@ -6433,6 +6522,12 @@ export function createProductionAgentHandler(options) {
             ...historyMessages,
             { role: "user", content: userContent },
         ];
+        const requestedApprovedToolCalls = Array.isArray(body.approvedToolCalls) && body.approvedToolCalls.length > 0
+            ? body.approvedToolCalls
+                .filter((key) => typeof key === "string")
+                .slice(0, 200)
+            : undefined;
+        const exactApprovedToolCall = findApprovedStructuredToolCall(structuredHistory, requestedApprovedToolCalls);
         const firstRequestPayloadDetail = buildFirstRequestPayloadDetail({
             isFirstRequest: history.length === 0,
             systemPrompt: requestSystemPrompt,
@@ -6486,6 +6581,38 @@ export function createProductionAgentHandler(options) {
             : typeof requestTurnId === "string" && requestTurnId.trim()
                 ? requestTurnId.trim()
                 : runId;
+        const approvalStoreBinding = (binding) => {
+            if (!ownerEmail) {
+                throw new Error("Cannot create or consume an approval without an authenticated owner");
+            }
+            return {
+                ownerEmail,
+                orgId: getRequestOrgId() ?? null,
+                threadId: effectiveThreadId,
+                turnId: effectiveTurnId,
+                toolName: binding.toolName,
+                callId: binding.callId,
+                approvalKey: binding.approvalKey,
+            };
+        };
+        const approvalHooks = {
+            onApprovalRequired: async (binding) => {
+                await createAgentToolApproval(approvalStoreBinding(binding));
+            },
+            consumeApproval: async (binding) => {
+                if (!ownerEmail)
+                    return false;
+                return consumeAgentToolApproval(approvalStoreBinding(binding));
+            },
+        };
+        const exactApprovedToolEntry = exactApprovedToolCall
+            ? requestActions[exactApprovedToolCall.name]
+            : undefined;
+        const approvedToolCallsForExecution = exactApprovedToolCall && exactApprovedToolEntry?.needsApproval
+            ? [
+                toolCallCacheKey(exactApprovedToolCall.name, exactApprovedToolCall.input),
+            ]
+            : undefined;
         if (isBackgroundWorker &&
             (await isTurnAborted(effectiveThreadId, effectiveTurnId))) {
             await markRunAborted(runId, "user").catch(() => { });
@@ -7236,15 +7363,13 @@ export function createProductionAgentHandler(options) {
                     ? { threadId: effectiveThreadId, turnId: effectiveTurnId }
                     : {}),
                 // Human-in-the-loop approval grants for this turn (sanitized — the
-                // request is untrusted; accept only a bounded list of string keys).
-                ...(Array.isArray(body.approvedToolCalls) &&
-                    body.approvedToolCalls.length
-                    ? {
-                        approvedToolCalls: body.approvedToolCalls
-                            .filter((k) => typeof k === "string")
-                            .slice(0, 200),
-                    }
+                // request is untrusted; only the exact structured call is passed to
+                // the loop, where the durable grant is consumed atomically.
+                ...(approvedToolCallsForExecution
+                    ? { approvedToolCalls: approvedToolCallsForExecution }
                     : {}),
+                onApprovalRequired: approvalHooks.onApprovalRequired,
+                consumeApproval: approvalHooks.consumeApproval,
                 // A worker PROVEN to be running inside the real 15-min Netlify
                 // `-background` function (`runsInBackgroundFunction`) has minutes of
                 // budget left on THIS invocation. Let it catch a recoverable
@@ -7269,6 +7394,31 @@ export function createProductionAgentHandler(options) {
             send({ type: "activity", label: "Contacting model" });
             let instrumented = false;
             try {
+                if (exactApprovedToolCall &&
+                    approvedToolCallsForExecution &&
+                    requestActions[exactApprovedToolCall.name]) {
+                    send({
+                        type: "activity",
+                        label: `Running approved ${exactApprovedToolCall.name} action`,
+                        tool: exactApprovedToolCall.name,
+                    });
+                    await executeAgentToolCall({
+                        actions: requestActions,
+                        name: exactApprovedToolCall.name,
+                        input: exactApprovedToolCall.input,
+                        callId: exactApprovedToolCall.callId,
+                        signal: agentLoopOpts.signal,
+                        ownerEmail,
+                        orgId: getRequestOrgId() ?? null,
+                        threadId: effectiveThreadId,
+                        turnId: effectiveTurnId,
+                        approvedToolCalls: approvedToolCallsForExecution,
+                        onApprovalRequired: approvalHooks.onApprovalRequired,
+                        consumeApproval: approvalHooks.consumeApproval,
+                        send,
+                    });
+                    return;
+                }
                 try {
                     const { getObservabilityConfig, instrumentAgentLoop } = await import("../observability/traces.js");
                     const obsConfig = await getObservabilityConfig();