@mongodb-js/agent-engine-runner-shared 0.11.3

package/dist/secure_wrapper.js

@@ -0,0 +1,1249 @@
+/**
+ * SecureToolWrapper — routes all tool calls through OE for logging and policy enforcement.
+ *
+ * Provides:
+ *   SecureToolWrapper: wraps tool execution calls to route through OE
+ *   createSecureToolFunction: wraps a tool function with runtime context lookup
+ *   requestOeApproval / reportOeResult: low-level OE HTTP helpers (exported for SecureLLMProxy)
+ *   PolicyDeniedException / ToolExecutionError / LLMInvocationError: exception classes
+ */
+import { isDeepStrictEqual } from "node:util";
+import { getLogger } from "./logger.js";
+import { ownerDelivered } from "./owner_callback.js";
+import { SuspendPayloadSchema, ToolExecuteResponseSchema, coerceTokenUsage, } from "./models.js";
+import { classifyToolAPIError, requestCredentialValues, ToolAPIErrorSchema, } from "./tool_api_error.js";
+import { getRequestTimeout, getToolReadTimeout, logToolRequest, logToolResult, logCachedResult, logPolicyBlocked, OE_RETRYABLE_MAX_ATTEMPTS, } from "./utils.js";
+import { getCurrentExecutionId, getCurrentOeOwnerUrl, getCurrentUserId, getCurrentWrapper, getRequestedSuspend, runWithCallAbortSignal, runWithCustomerOrigin, reportOeOwnerUrlFailure, runWithSuspendRequestContext, withExecutionSignal, } from "./context.js";
+import { getSuspendHandler } from "./hooks.js";
+import { fetchPlatform, getFetchOptionsForLongCall, getFetchOptionsWithTLS, } from "./tls_client.js";
+import { discardResponseBody, retryAfterWaitMs, waitForRetry, } from "./server/http_retry.js";
+import { SpanStatusCode } from "@opentelemetry/api";
+import { getCurrentTraceContext, getTracer } from "./tracing/setup.js";
+import { runWithToolMemoryReadOwnership } from "./tool_memory_ownership.js";
+import { ActivityKind, DurableActivityDeniedError, DurableActivityInterrupted, ReplayedActivityFailedError, WorkflowClient, activityRequiresReconstruction, allocateActivityOrdinal, currentAttemptContext, runSerialActivity, toolActivityKey, } from "./workflow/index.js";
+import { semanticInputFromJson, valueToJson } from "./workflow/activity.js";
+const logger = getLogger("agent_engine_runner_shared.secure_wrapper");
+const DURABLE_TOOL_RESULT_JSON_ERROR = "durable workflow values must be JSON-safe";
+function isObject(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+/**
+ * Extract token usage from an LLM response's `response_metadata`.
+ *
+ * Handles provider-variant key names:
+ *   - OpenAI:   `response_metadata.usage.{prompt_tokens, completion_tokens, total_tokens}`
+ *   - Anthropic: `response_metadata.usage.{input_tokens, output_tokens}`
+ *   - Some providers: `response_metadata.token_usage.{...}`
+ *
+ * Returns an object with keys `prompt_tokens`, `completion_tokens`,
+ * `total_tokens`, `model`. All values may be `null` if unavailable.
+ *
+ * Mirrors Python's `agent_engine_runner_shared.secure_wrapper.extract_usage` 1:1.
+ */
+export function extractUsage(response, fallbackModel = null) {
+    const result = {
+        prompt_tokens: null,
+        completion_tokens: null,
+        total_tokens: null,
+        model: fallbackModel,
+    };
+    const respObj = isObject(response) ? response : {};
+    const rm = isObject(respObj["response_metadata"])
+        ? respObj["response_metadata"]
+        : {};
+    // Coerce each key independently so an empty or malformed `usage`
+    // still falls through to `token_usage`.
+    let usageTu = coerceTokenUsage(rm["usage"]);
+    if (usageTu === undefined) {
+        usageTu = coerceTokenUsage(rm["token_usage"]);
+    }
+    if (usageTu === undefined) {
+        usageTu = coerceTokenUsage(respObj["usage_metadata"]);
+    }
+    if (usageTu === undefined) {
+        usageTu = coerceTokenUsage(respObj["usage"]);
+    }
+    if (usageTu !== undefined) {
+        const prompt = usageTu.promptTokens ?? usageTu.inputTokens;
+        const completion = usageTu.completionTokens ?? usageTu.outputTokens;
+        const total = usageTu.totalTokens;
+        if (prompt != null)
+            result.prompt_tokens = prompt;
+        if (completion != null)
+            result.completion_tokens = completion;
+        if (total != null) {
+            result.total_tokens = total;
+        }
+        else if (result.prompt_tokens !== null &&
+            result.completion_tokens !== null) {
+            result.total_tokens = result.prompt_tokens + result.completion_tokens;
+        }
+        if (usageTu.model)
+            result.model = usageTu.model;
+    }
+    // Python: `rm.get("model_name") or rm.get("model") or fallback_model`
+    const modelName = rm["model_name"] ||
+        rm["model"] ||
+        result.model ||
+        fallbackModel;
+    result.model = modelName ?? null;
+    return result;
+}
+/**
+ * Extract token usage from a tool-pod usage dict into `reportOeResult` kwargs.
+ *
+ * Uses `!= null` checks instead of truthy `||` so a valid `0` token count is
+ * not treated as missing. Computes `total_tokens` when the provider omits it.
+ *
+ * Mirrors Python's `_extract_pod_usage`. Python keeps the leading underscore
+ * as a "private" convention and leaves the function unexported. TS exports
+ * this (TS `noUnusedLocals` flags unused module-level functions, and the
+ * leading-underscore identifier convention doesn't translate cleanly to TS).
+ *
+ * @internal — call sites are expected to live inside the agent-engine-runner-shared
+ * package or downstream framework SDKs; not part of the stable public API.
+ */
+export function extractPodUsage(usage, fallbackModel = null) {
+    if (!usage || Object.keys(usage).length === 0) {
+        return {
+            prompt_tokens: null,
+            completion_tokens: null,
+            total_tokens: null,
+            model: fallbackModel,
+        };
+    }
+    // Note: prefers `input_tokens` over `prompt_tokens` (Anthropic-first),
+    // which is the opposite of `extractUsage`. Matches Python verbatim.
+    let prompt = usage["input_tokens"];
+    if (prompt == null)
+        prompt = usage["prompt_tokens"];
+    let completion = usage["output_tokens"];
+    if (completion == null)
+        completion = usage["completion_tokens"];
+    let total = usage["total_tokens"];
+    if (total == null && prompt != null && completion != null) {
+        total = prompt + completion;
+    }
+    let model = usage["model"];
+    if (!model)
+        model = fallbackModel;
+    return {
+        prompt_tokens: prompt ?? null,
+        completion_tokens: completion ?? null,
+        total_tokens: total ?? null,
+        model: model ?? null,
+    };
+}
+// =============================================================================
+// Exceptions
+// =============================================================================
+export class PolicyDeniedException extends Error {
+    reason;
+    /** Guardrail policy identity when the denial came from a guardrail policy. */
+    guardrailMeta;
+    constructor(reason, guardrailMeta = null, options) {
+        super(`Policy denied: ${reason}`, options);
+        this.name = "PolicyDeniedException";
+        this.reason = reason;
+        this.guardrailMeta = guardrailMeta;
+    }
+}
+class OERetryAfterError extends Error {
+    waitMs;
+    constructor(waitMs, options) {
+        super(`OE retry after ${waitMs}ms`, options);
+        this.name = "OERetryAfterError";
+        this.waitMs = waitMs;
+    }
+}
+/** Raised when tool execution fails. */
+export class ToolExecutionError extends Error {
+    error;
+    constructor(error, options) {
+        super(`Tool execution error: ${error}`, options);
+        this.name = "ToolExecutionError";
+        this.error = error;
+    }
+}
+const TERMINAL_EXECUTION_REASONS = {
+    "execution already error": "This execution already ended in error; later tool calls are rejected.",
+    "execution already completed": "This execution already completed; later tool calls are rejected.",
+    "execution already cancelled": "This execution was cancelled; later tool calls are rejected.",
+};
+export class TerminalExecutionError extends ToolExecutionError {
+    constructor(error, options) {
+        super(error, options);
+        this.name = "TerminalExecutionError";
+    }
+}
+export function raiseForOeRejection(reason, guardrailMeta = null) {
+    const text = reason ?? "Policy denied";
+    if (Object.hasOwn(TERMINAL_EXECUTION_REASONS, text)) {
+        throw new TerminalExecutionError(TERMINAL_EXECUTION_REASONS[text]);
+    }
+    throw new PolicyDeniedException(text, guardrailMeta);
+}
+/**
+ * Raised when a tool call outlives its deadline.
+ *
+ * Distinct from PolicyDeniedException on purpose. A timeout means the call was
+ * permitted and ran — it just ran too long — so reporting it as a denial sends
+ * the developer to debug governance instead of their tool.
+ */
+export class ToolCallTimeoutError extends ToolExecutionError {
+    toolName;
+    timeoutSeconds;
+    elapsedSeconds;
+    constructor(toolName, timeoutSeconds, elapsedSeconds, options) {
+        const message = `Tool '${toolName}' timed out after ${elapsedSeconds.toFixed(1)}s ` +
+            `(deadline ${timeoutSeconds.toFixed(0)}s). It can be given longer via ` +
+            `RUNNER_TOOL_READ_TIMEOUT, or interrupted while running.`;
+        super(message, options);
+        this.name = "ToolCallTimeoutError";
+        this.message = message;
+        this.toolName = toolName;
+        this.timeoutSeconds = timeoutSeconds;
+        this.elapsedSeconds = elapsedSeconds;
+    }
+}
+/**
+ * Whether an error is this call outliving a deadline, as opposed to a transport
+ * failure. Covers the caller's AbortSignal.timeout and Undici's own
+ * headers/body budgets, which surface as a TypeError carrying a code.
+ */
+function isCallDeadlineError(exc) {
+    if (exc.name === "TimeoutError")
+        return true;
+    const code = exc.cause?.code;
+    return code === "UND_ERR_HEADERS_TIMEOUT" || code === "UND_ERR_BODY_TIMEOUT";
+}
+class DurableToolActivityFailedError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = "DurableToolActivityFailedError";
+    }
+}
+const DURABLE_TOOL_FAILURE_PREFIX = "__agentic_durable_tool_failure_v1__:";
+const DURABLE_TOOL_FAILURE_FALLBACK = "durable activity failed";
+function toolErrorMessage(error) {
+    const message = error instanceof ToolExecutionError
+        ? error.error
+        : error instanceof Error
+            ? error.message
+            : String(error);
+    return message || DURABLE_TOOL_FAILURE_FALLBACK;
+}
+function encodeDurableToolFailure(error) {
+    const payload = {
+        kind: "execution",
+        message: toolErrorMessage(error),
+    };
+    if (error instanceof ToolCallTimeoutError) {
+        payload["kind"] = "timeout";
+        payload["tool_name"] = error.toolName;
+        payload["timeout_seconds"] = error.timeoutSeconds;
+        payload["elapsed_seconds"] = error.elapsedSeconds;
+    }
+    else if (error instanceof ExternalAPICallError) {
+        payload["kind"] = "external_api";
+        payload["tool_api_error"] = error.tool_api_error;
+    }
+    return `${DURABLE_TOOL_FAILURE_PREFIX}${JSON.stringify(payload)}`;
+}
+function decodeDurableToolFailure(message, cause) {
+    if (!message.startsWith(DURABLE_TOOL_FAILURE_PREFIX)) {
+        return new ToolExecutionError(message || DURABLE_TOOL_FAILURE_FALLBACK, {
+            cause,
+        });
+    }
+    let payload;
+    try {
+        payload = JSON.parse(message.slice(DURABLE_TOOL_FAILURE_PREFIX.length));
+    }
+    catch {
+        return new ToolExecutionError(message, { cause });
+    }
+    if (!isObject(payload))
+        return new ToolExecutionError(message, { cause });
+    const failureMessage = typeof payload["message"] === "string" && payload["message"]
+        ? payload["message"]
+        : DURABLE_TOOL_FAILURE_FALLBACK;
+    const kind = payload["kind"];
+    if (kind === "external_api") {
+        const parsed = ToolAPIErrorSchema.safeParse(payload["tool_api_error"]);
+        if (!parsed.success) {
+            return new ToolExecutionError(failureMessage, { cause });
+        }
+        return new ExternalAPICallError(failureMessage, parsed.data, { cause });
+    }
+    if (kind !== "timeout") {
+        return new ToolExecutionError(failureMessage, { cause });
+    }
+    const toolName = payload["tool_name"];
+    const timeoutSeconds = payload["timeout_seconds"];
+    const elapsedSeconds = payload["elapsed_seconds"];
+    if (typeof toolName !== "string" ||
+        typeof timeoutSeconds !== "number" ||
+        !Number.isFinite(timeoutSeconds) ||
+        typeof elapsedSeconds !== "number" ||
+        !Number.isFinite(elapsedSeconds)) {
+        return new ToolExecutionError(failureMessage, { cause });
+    }
+    return new ToolCallTimeoutError(toolName, timeoutSeconds, elapsedSeconds, {
+        cause,
+    });
+}
+export class ExternalAPICallError extends ToolExecutionError {
+    tool_api_error;
+    constructor(error, toolApiError, options) {
+        super(error, options);
+        this.name = "ExternalAPICallError";
+        this.tool_api_error = toolApiError;
+    }
+}
+export class LLMInvocationError extends Error {
+    error;
+    /** Invoke-owner attribution. Only `"llm"` means the provider failed. */
+    source;
+    /**
+     * Machine-readable classification the tool pod stamped on the failure
+     * (e.g. a provider credential rejection), when it did. Travels to the
+     * OE/UI on the ERROR chunk metadata instead of the generic invocation
+     * code so consumers can classify without string-matching prose.
+     */
+    error_code;
+    constructor(error, options) {
+        super(`LLM invocation error: ${error}`, options);
+        this.name = "LLMInvocationError";
+        this.error = error;
+        this.source = options?.source;
+        this.error_code = options?.error_code;
+    }
+}
+/**
+ * Request approval from OE before executing a tool/LLM call.
+ * Any HTTP or network error becomes PolicyDeniedException — fail-safe.
+ */
+export async function requestOeApproval(args) {
+    try {
+        return await requestOeApprovalRaw(args);
+    }
+    catch (exc) {
+        if (exc instanceof OERetryAfterError) {
+            throw new PolicyDeniedException("OE unreachable; blocking for safety", null, { cause: exc });
+        }
+        throw exc;
+    }
+}
+async function requestOeApprovalRaw(args) {
+    const { oeUrl, executionId, toolName, arguments: toolArgs, step, kind, isLocal = true, redactFields, providerType, scopes, metadata, toolCallId, customHeaders, timeoutMs, } = args;
+    const { traceId, spanId } = getCurrentTraceContext();
+    const body = {
+        execution_id: executionId,
+        tool_name: toolName,
+        arguments: toolArgs,
+        step_number: step,
+        tool_call_id: toolCallId ?? null,
+        kind: kind ?? null,
+        is_local: isLocal,
+        redact_fields: redactFields ?? [],
+        provider_type: providerType ?? null,
+        scopes: scopes ?? [],
+        metadata: metadata ?? {},
+        custom_headers: customHeaders,
+        trace_id: traceId ?? undefined,
+        span_id: spanId ?? undefined,
+    };
+    let resp;
+    // The OE keeps /tool/execute open until the tool returns, so this deadline
+    // bounds the tool's own runtime. Callers with a different profile (the LLM
+    // proxy) pass their own timeoutMs.
+    const deadlineMs = timeoutMs ?? getToolReadTimeout() * 1000;
+    const startedAt = Date.now();
+    try {
+        // Undici's own headers/body budgets have to be raised to the call deadline
+        // too, or they cap it independently of the AbortSignal. The connect budget
+        // stays short so an unreachable OE still fails fast.
+        const tlsOptions = getFetchOptionsForLongCall(oeUrl, deadlineMs);
+        resp = await fetchPlatform(`${oeUrl.replace(/\/$/, "")}/tool/execute`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify(body),
+            // Combine the per-call read deadline with the execution-wide abort signal
+            // so an AER execution timeout cancels this in-flight OE call (Python gets
+            // this from asyncio.wait_for cancelling the inner coroutine).
+            signal: withExecutionSignal(AbortSignal.timeout(deadlineMs)),
+            ...tlsOptions,
+        });
+        if (!resp.ok) {
+            const status = resp.status;
+            const statusText = resp.statusText;
+            const retryAfter = resp.headers?.get?.("Retry-After") ?? null;
+            await discardResponseBody(resp);
+            if (status === 503) {
+                const waitMs = retryAfterWaitMs(retryAfter);
+                if (waitMs !== null) {
+                    throw new OERetryAfterError(waitMs);
+                }
+            }
+            throw new Error(`HTTP ${status}: ${statusText}`);
+        }
+    }
+    catch (exc) {
+        if (exc instanceof OERetryAfterError) {
+            throw exc;
+        }
+        // AbortSignal.any propagates the reason of whichever signal fired, so a
+        // TimeoutError is this call's own deadline; an AbortError is the execution
+        // being torn down (cancel/interrupt), which is not a timeout. Undici raises
+        // its own headers/body deadline as a TypeError with a code rather than a
+        // TimeoutError, so match that too — it is still the call outliving a
+        // deadline, and reporting it as an unreachable OE is what this replaces.
+        if (exc instanceof Error && isCallDeadlineError(exc)) {
+            const elapsedSeconds = (Date.now() - startedAt) / 1000;
+            logger.error({ step, toolName, elapsedSeconds }, `Step ${step}: Tool '${toolName}' timed out`);
+            throw new ToolCallTimeoutError(toolName, deadlineMs / 1000, elapsedSeconds, { cause: exc });
+        }
+        logger.error({ step, err: String(exc) }, `Step ${step}: Failed to request OE approval`);
+        throw new PolicyDeniedException("OE unreachable; blocking for safety", null, {
+            cause: exc,
+        });
+    }
+    // Reading the body is part of the fail-safe contract: a 200 with a
+    // non-JSON/truncated body (e.g. a proxy error page) must still block rather
+    // than surface a raw SyntaxError that bypasses the policy-denied path.
+    let data;
+    try {
+        data = await resp.json();
+    }
+    catch (exc) {
+        logger.error({ step, err: String(exc) }, `Step ${step}: Failed to read OE approval response`);
+        throw new PolicyDeniedException("OE response unreadable; blocking for safety", null, { cause: exc });
+    }
+    // A schema mismatch is a programming/contract bug, not a network error, so
+    // let the ZodError propagate rather than masking it as a policy denial.
+    return ToolExecuteResponseSchema.parse(data);
+}
+/**
+ * Repeat the same /tool/execute while OE says the failure is retryable.
+ * Reservation-loss returns status=error with retryable=true after releasing
+ * the step stamp. Retrying the same step here keeps durable activity from
+ * recording FAILED on a call that can still succeed.
+ */
+export async function requestOeApprovalRetryable(args) {
+    // Started as the active span before the first requestOeApproval call, so
+    // its trace_id/span_id — read via getCurrentTraceContext() inside
+    // requestOeApproval — reflect this span, not whatever was active before it.
+    // Without a span here, a retried call (OE-side reservation loss) is
+    // invisible: the surrounding tool-node span just looks slower, with no
+    // record of how many attempts happened or how long each took.
+    return getTracer().startActiveSpan("secure_wrapper.request_oe_approval", async (span) => {
+        let attemptCount = 0;
+        try {
+            let response;
+            for (let attempt = 0; attempt < OE_RETRYABLE_MAX_ATTEMPTS; attempt++) {
+                try {
+                    response = await requestOeApprovalRaw(args);
+                }
+                catch (err) {
+                    if (!(err instanceof OERetryAfterError)) {
+                        throw err;
+                    }
+                    attemptCount = attempt + 1;
+                    if (attempt >= OE_RETRYABLE_MAX_ATTEMPTS - 1) {
+                        throw new PolicyDeniedException("OE unreachable; blocking for safety", null, { cause: err });
+                    }
+                    const waited = await waitForRetry(err.waitMs, withExecutionSignal(new AbortController().signal));
+                    if (!waited) {
+                        throw new PolicyDeniedException("OE unreachable; blocking for safety", null, { cause: err });
+                    }
+                    continue;
+                }
+                attemptCount = attempt + 1;
+                if (response.status !== "error" || !response.retryable) {
+                    break;
+                }
+            }
+            if (response === undefined) {
+                throw new PolicyDeniedException("OE unreachable; blocking for safety");
+            }
+            return response;
+        }
+        catch (err) {
+            span.recordException(err);
+            span.setStatus({ code: SpanStatusCode.ERROR });
+            throw err;
+        }
+        finally {
+            span.setAttribute("attempt_count", attemptCount);
+            span.end();
+        }
+    });
+}
+/**
+ * Report an execution result and require OE to acknowledge settlement.
+ *
+ * Started as the active span before getCurrentTraceContext() is read below,
+ * so the trace_id/span_id put on the wire reflect this span. Without a span
+ * here, a slow-to-ack OE (or a retried settlement) is invisible: the
+ * surrounding tool-node span just looks slower, with no record of how many
+ * attempts happened.
+ */
+export async function reportOeResult(args) {
+    return getTracer().startActiveSpan("secure_wrapper.report_oe_result", async (span) => {
+        let attemptCount = 0;
+        try {
+            await reportOeResultAttempts(args, (count) => {
+                attemptCount = count;
+            });
+        }
+        catch (err) {
+            span.recordException(err);
+            span.setStatus({ code: SpanStatusCode.ERROR });
+            throw err;
+        }
+        finally {
+            span.setAttribute("attempt_count", attemptCount);
+            span.end();
+        }
+    });
+}
+async function reportOeResultAttempts(args, onAttempt) {
+    const { oeUrl, executionId, toolName, step, status, result, error, durationMs, podName, promptTokens, completionTokens, totalTokens, model, kind, metadata, toolCallId, ownerUrl, onOwnerFailure, toolApiError, } = args;
+    const { traceId, spanId } = getCurrentTraceContext();
+    const body = {
+        execution_id: executionId,
+        step_number: step,
+        tool_name: toolName,
+        tool_call_id: toolCallId ?? undefined,
+        status,
+        result,
+        error: error ?? undefined,
+        duration_ms: durationMs,
+        pod_name: podName ?? undefined,
+        prompt_tokens: promptTokens ?? undefined,
+        completion_tokens: completionTokens ?? undefined,
+        total_tokens: totalTokens ?? undefined,
+        model: model ?? undefined,
+        kind: kind ?? undefined,
+        metadata: metadata ?? {},
+        trace_id: traceId ?? undefined,
+        span_id: spanId ?? undefined,
+        tool_api_error: toolApiError ?? undefined,
+    };
+    const serializedBody = JSON.stringify(body);
+    const serviceUrl = `${oeUrl.replace(/\/$/, "")}/tool/result`;
+    // Owner pre-attempt per the shared owner-callback policy (owner_callback.ts):
+    // a single best-effort POST that does not consume the service retry budget.
+    const ownerResultUrl = ownerUrl
+        ? `${ownerUrl.replace(/\/$/, "")}/tool/result`
+        : null;
+    const attemptOffset = ownerResultUrl === null ? 0 : 1;
+    if (ownerResultUrl !== null)
+        onAttempt(1);
+    if (ownerResultUrl !== null &&
+        (await ownerDelivered(ownerResultUrl, () => ({
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: serializedBody,
+            signal: AbortSignal.timeout(getRequestTimeout() * 1000),
+            ...getFetchOptionsWithTLS(ownerResultUrl),
+        }), (msg) => logger.warn(`/tool/result ${msg} URL ${serviceUrl}`)))) {
+        return;
+    }
+    if (ownerResultUrl !== null) {
+        onOwnerFailure?.();
+    }
+    const tlsOptions = getFetchOptionsWithTLS(serviceUrl);
+    let lastError;
+    for (let attempt = 0; attempt < 3; attempt += 1) {
+        let retryWaitMs = null;
+        onAttempt(attemptOffset + attempt + 1);
+        let response;
+        try {
+            response = await fetchPlatform(serviceUrl, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: serializedBody,
+                signal: AbortSignal.timeout(getRequestTimeout() * 1000),
+                ...tlsOptions,
+            });
+        }
+        catch (error) {
+            lastError = error;
+        }
+        if (response !== undefined) {
+            const ok = response.ok;
+            const responseStatus = response.status;
+            const retryAfter = response.headers?.get?.("Retry-After") ?? null;
+            await discardResponseBody(response);
+            if (ok)
+                return;
+            const error = new ToolExecutionError(`OE rejected result settlement with HTTP ${responseStatus}`);
+            if (responseStatus >= 400 && responseStatus < 500) {
+                throw error;
+            }
+            lastError = error;
+            if (responseStatus === 503) {
+                retryWaitMs = retryAfterWaitMs(retryAfter);
+            }
+        }
+        if (attempt < 2) {
+            await new Promise((resolve) => setTimeout(resolve, retryWaitMs ?? 100 * 2 ** attempt));
+        }
+    }
+    throw new ToolExecutionError(`OE did not acknowledge tool result settlement: ${String(lastError)}`);
+}
+// =============================================================================
+// Interrupt marker
+// =============================================================================
+// Marker key for an OE-triggered call interruption, kept out of the plain
+// shape a real tool result could return, and namespaced to avoid collision
+// with a tool's own artifact keys.
+//
+import { CALL_INTERRUPTED_ARTIFACT_KEY } from "./call_interrupted.js";
+import { CALL_INTERRUPT_REASON } from "./server/drain.js";
+// Re-exported so existing `secure_wrapper.js` importers keep working; the
+// canonical owner is `./call_interrupted.js` (see its comment).
+export { CALL_INTERRUPTED_ARTIFACT_KEY };
+export const INTERRUPTED_CALL_CONTENT = "This call was stopped before completing.";
+// Identity-checked sentinel distinguishing an OE-triggered interrupt from any
+// real tool return value. Never shape-checked — a tool cannot return this by accident.
+class CallInterrupted {
+}
+const CALL_INTERRUPTED = new CallInterrupted();
+/**
+ * Race a tool body against its per-call abort signal. Node has no preemptive
+ * cancel: the abort stops the wait so the graph continues, while the body's
+ * detached promise runs out — its late settlement is swallowed by the race's
+ * own handlers.
+ */
+function raceWithCallAbort(task, signal) {
+    if (signal.aborted) {
+        return Promise.reject(callAbortError());
+    }
+    return new Promise((resolve, reject) => {
+        const onAbort = () => reject(callAbortError());
+        signal.addEventListener("abort", onAbort, { once: true });
+        task.then((value) => {
+            signal.removeEventListener("abort", onAbort);
+            resolve(value);
+        }, (error) => {
+            signal.removeEventListener("abort", onAbort);
+            reject(error instanceof Error ? error : new Error(String(error)));
+        });
+    });
+}
+/** The race's rejection shape: AbortError, so error paths read it as interrupted. */
+function callAbortError() {
+    const error = new Error(INTERRUPTED_CALL_CONTENT);
+    error.name = "AbortError";
+    return error;
+}
+/** A whole-run drain latched before the tool body started. */
+function drainAbortError() {
+    const error = new Error("execution is draining");
+    error.name = "AbortError";
+    return error;
+}
+const INTERRUPTED_WIRE_MARKER = Object.freeze({
+    [CALL_INTERRUPTED_ARTIFACT_KEY]: true,
+});
+function isLocalTool(options) {
+    return ((options.isLocal ?? true) &&
+        !options.providerType &&
+        (options.scopes?.length ?? 0) === 0);
+}
+function buildToolActivityInput(args, options) {
+    const input = {
+        arguments: args,
+        is_local: isLocalTool(options),
+    };
+    if (options.metadata !== undefined)
+        input.metadata = options.metadata;
+    if (options.providerType != null) {
+        input.provider_type = options.providerType;
+    }
+    if (options.scopes !== undefined && options.scopes.length > 0) {
+        input.scopes = [...options.scopes].sort();
+    }
+    if (options.toolCallId)
+        input.tool_call_id = options.toolCallId;
+    return input;
+}
+function encodeToolActivityResult(value) {
+    let encoded;
+    if (value === CALL_INTERRUPTED) {
+        encoded = INTERRUPTED_WIRE_MARKER;
+    }
+    else if (typeof value !== "object" ||
+        value === null ||
+        Array.isArray(value) ||
+        !(CALL_INTERRUPTED_ARTIFACT_KEY in value)) {
+        encoded = value;
+    }
+    else {
+        const result = { ...value };
+        delete result[CALL_INTERRUPTED_ARTIFACT_KEY];
+        encoded = result;
+    }
+    assertDurableToolResultJsonSafe(encoded);
+    return encoded;
+}
+function assertDurableToolResultJsonSafe(value) {
+    let roundTripped;
+    try {
+        roundTripped = valueToJson(semanticInputFromJson(value));
+    }
+    catch {
+        throw new TypeError(DURABLE_TOOL_RESULT_JSON_ERROR);
+    }
+    if (!isDeepStrictEqual(value, roundTripped)) {
+        throw new TypeError(DURABLE_TOOL_RESULT_JSON_ERROR);
+    }
+}
+function decodeToolActivityResult(value, rawOnInterrupt) {
+    const isInterrupt = typeof value === "object" &&
+        value !== null &&
+        !Array.isArray(value) &&
+        Object.keys(value).length === 1 &&
+        value[CALL_INTERRUPTED_ARTIFACT_KEY] === true;
+    if (!isInterrupt)
+        return value;
+    return rawOnInterrupt ? CALL_INTERRUPTED : { interrupted: true };
+}
+export class OperationalStepAllocator {
+    n = 0;
+    next() {
+        this.n += 1;
+        return this.n;
+    }
+    observeAtLeast(n) {
+        if (n <= 0)
+            return;
+        if (n > this.n)
+            this.n = n;
+    }
+    current() {
+        return this.n;
+    }
+}
+export class SecureToolWrapper {
+    oeUrl;
+    executionId;
+    customHeaders;
+    /**
+     * Validated replica-specific OE owner base URL, or null. Forwarded
+     * to `reportOeResult` for the in-process (local-callback) tool-result path so
+     * settlement prefers the owning OE replica.
+     */
+    oeOwnerUrl;
+    ownerUrlFailed = false;
+    /** Shared with SecureLLMProxy for this execution (single-AER assumption). */
+    operationalSteps;
+    durableMemory = null;
+    /**
+     * Per-execution drain registry, enabling the per-call abort (POST
+     * /interrupt/call) for tools this wrapper runs locally; null leaves local
+     * calls unaddressable, as before.
+     */
+    drainRegistry;
+    constructor(oeUrl, executionId, customHeaders, oeOwnerUrl, drainRegistry) {
+        this.oeUrl = oeUrl.replace(/\/$/, "");
+        this.executionId = executionId;
+        this.customHeaders = customHeaders ?? {};
+        this.oeOwnerUrl = oeOwnerUrl ?? null;
+        this.drainRegistry = drainRegistry ?? null;
+        this.operationalSteps = new OperationalStepAllocator();
+    }
+    currentOeOwnerUrl() {
+        if (this.ownerUrlFailed)
+            return null;
+        if (getCurrentExecutionId() === this.executionId) {
+            return getCurrentOeOwnerUrl();
+        }
+        return this.oeOwnerUrl;
+    }
+    reportOeOwnerFailure() {
+        this.ownerUrlFailed = true;
+        if (getCurrentExecutionId() === this.executionId) {
+            reportOeOwnerUrlFailure();
+        }
+    }
+    /** Current operational-step watermark for compatibility readers. */
+    get stepCounter() {
+        return this.operationalSteps.current();
+    }
+    /** Allocate the next operational step_number for this execution. */
+    nextOperationalStep() {
+        return this.operationalSteps.next();
+    }
+    /** Raise the allocator watermark (e.g. from OE latest_step_number). */
+    observeOperationalStep(n) {
+        this.operationalSteps.observeAtLeast(n);
+    }
+    async close() {
+        // no-op — available for future cleanup
+    }
+    /**
+     * Execute a tool call through OE.
+     *
+     * Flow:
+     *   1. POST /tool/execute — OE approves or denies
+     *   2. OE returns a final outcome or routes the call back in process
+     *   3. Wrapper logs the outcome and converts suspend payloads back into framework interrupts
+     */
+    async executeTool(toolName, args, options = {}) {
+        const step = this.nextOperationalStep();
+        // The tool's redact_fields policy must reach the debug argument dump —
+        // it ships to the centralized log sink even at debug level.
+        logToolRequest(toolName, args, step, "TOOL", options.redactFields ?? []);
+        if (currentAttemptContext() === null) {
+            return this.executeToolNative(toolName, args, step, options);
+        }
+        return this.executeToolDurably(toolName, args, step, options);
+    }
+    async executeToolDurably(toolName, args, step, options) {
+        const { toolCallId, rawOnInterrupt = false } = options;
+        const durableMemory = this.durableMemory;
+        const activityKey = toolCallId ? toolActivityKey(toolCallId) : undefined;
+        const activityOrdinal = allocateActivityOrdinal(activityKey);
+        try {
+            const result = await runSerialActivity({
+                client: new WorkflowClient(this.oeUrl),
+                kind: ActivityKind.TOOL,
+                name: toolName,
+                activityOrdinal,
+                semanticInput: buildToolActivityInput(args, options),
+                execute: (context) => this.executeToolActivity(toolName, args, step, options, context.activityId),
+                onActivityResolved: durableMemory === null
+                    ? undefined
+                    : (client, context, value) => durableMemory.synchronizeTool(client, context, value, getCurrentUserId(), toolCallId, toolName),
+                exclusive: activityKey === undefined,
+            });
+            return decodeToolActivityResult(result, rawOnInterrupt);
+        }
+        catch (error) {
+            if (error instanceof DurableActivityDeniedError) {
+                if (error.cause instanceof PolicyDeniedException)
+                    throw error.cause;
+                throw new PolicyDeniedException(error.message, null, {
+                    cause: error,
+                });
+            }
+            if (error instanceof ReplayedActivityFailedError) {
+                throw decodeDurableToolFailure(error.message, error);
+            }
+            if (error instanceof DurableToolActivityFailedError) {
+                throw decodeDurableToolFailure(error.message, error);
+            }
+            throw error;
+        }
+    }
+    async executeToolActivity(toolName, args, step, options, activityId) {
+        try {
+            if (isLocalTool(options) &&
+                options.localExecutor !== undefined &&
+                activityRequiresReconstruction(activityId)) {
+                // OE already resolved this exact admitted activity. Re-enter its
+                // captured callback so LangGraph can reconstruct interrupt().
+                return encodeToolActivityResult(await options.localExecutor());
+            }
+            const result = await this.executeToolNative(toolName, args, step, { ...options, rawOnInterrupt: true }, "reject");
+            return encodeToolActivityResult(result);
+        }
+        catch (error) {
+            if (error instanceof PolicyDeniedException) {
+                throw new DurableActivityDeniedError(error.reason, { cause: error });
+            }
+            if (options.isFrameworkControlFlow?.(error) === true) {
+                throw new DurableActivityInterrupted(error);
+            }
+            throw new DurableToolActivityFailedError(encodeDurableToolFailure(error), {
+                cause: error,
+            });
+        }
+    }
+    async executeToolNative(toolName, args, step, options, interruptMode = "framework") {
+        const { metadata, providerType, scopes, toolCallId, rawOnInterrupt = false, isLocal = true, localExecutor, isFrameworkControlFlow, } = options;
+        const effectiveIsLocal = isLocalTool({
+            isLocal,
+            providerType,
+            scopes,
+        });
+        const effectiveLocalExecutor = effectiveIsLocal ? localExecutor : undefined;
+        const response = await requestOeApprovalRetryable({
+            oeUrl: this.oeUrl,
+            executionId: this.executionId,
+            toolName,
+            arguments: args,
+            step,
+            isLocal: effectiveIsLocal,
+            redactFields: options.redactFields,
+            providerType,
+            scopes,
+            toolCallId,
+            metadata,
+            customHeaders: this.customHeaders,
+        });
+        if (response.elicitation) {
+            if (interruptMode === "reject") {
+                throw new ToolExecutionError("durable Tool activities support terminal outcomes only; " +
+                    "the framework adapter must own authorization interrupts");
+            }
+            const interrupt = getSuspendHandler();
+            if (interrupt == null) {
+                throw new Error("No suspend handler registered. Ensure the framework SDK calls registerSuspendHandler() before run().");
+            }
+            interrupt({
+                suspend_reason: "authorization_required",
+                suspend_context: {
+                    authorization_url: response.elicitation.authorization_url,
+                    elicitation_id: response.elicitation.elicitation_id,
+                    message: response.elicitation.message,
+                    created: response.elicitation.created,
+                },
+            });
+            throw new Error("authorization_required interrupt must halt execution; suspend handler should throw (e.g. LangGraph GraphInterrupt).");
+        }
+        if (!response.proceed) {
+            const reason = response.reason ?? "Policy denied";
+            if (!Object.hasOwn(TERMINAL_EXECUTION_REASONS, reason)) {
+                logPolicyBlocked(toolName, step, reason);
+            }
+            raiseForOeRejection(reason, response.guardrail_meta ?? null);
+        }
+        if (response.latest_step_number != null) {
+            this.observeOperationalStep(response.latest_step_number);
+        }
+        if (response.from_cache) {
+            logCachedResult(toolName, step);
+        }
+        if (response.route_to === "callback") {
+            if (!effectiveIsLocal) {
+                throw new ToolExecutionError("OE returned a local callback route for a tool declared as remote");
+            }
+            if (effectiveLocalExecutor == null) {
+                // Registered-tool adapters always install this executor. Merely
+                // running in AER is not enough for a low-level caller: the wrapper
+                // still needs the original framework tool object to invoke.
+                throw new ToolExecutionError("Local callback route is missing its registered tool executor");
+            }
+            const startedAt = performance.now();
+            // Register the call with the drain registry so POST /interrupt/call can
+            // address it. A controller exists only for tools that declared
+            // call-interrupt support: Node has no preemptive cancel, so the abort
+            // stops the wait, fires the signal the opted-in body honors, and lets
+            // the graph continue. A tool without the declaration answers
+            // not_cancellable and its outcome flows honestly.
+            const registry = this.drainRegistry;
+            const supportsCallInterrupt = options.supportsCallInterrupt === true;
+            let callController;
+            let preAborted = false;
+            if (registry != null) {
+                callController = supportsCallInterrupt
+                    ? new AbortController()
+                    : undefined;
+                try {
+                    preAborted = registry.beginWork(this.executionId, callController, step);
+                }
+                catch {
+                    // A whole-run drain latched between the OE approval and this
+                    // dispatch: the run is terminal, so the tool must not start.
+                    throw drainAbortError();
+                }
+            }
+            let localResult;
+            let suspendMarker = null;
+            try {
+                await runWithSuspendRequestContext(async () => {
+                    if (preAborted) {
+                        // The Stop landed in the OE-approval → in-graph-dispatch handoff:
+                        // skip the body and settle interrupted.
+                        throw callAbortError();
+                    }
+                    localResult = await runWithCustomerOrigin(() => {
+                        const controller = callController;
+                        if (controller === undefined) {
+                            return Promise.resolve().then(() => effectiveLocalExecutor());
+                        }
+                        // The body must be scheduled inside the signal's scope:
+                        // AsyncLocalStorage context is captured when the promise chain is
+                        // created, so a chain built outside would run signal-blind.
+                        return runWithCallAbortSignal(controller.signal, () => raceWithCallAbort(Promise.resolve().then(() => effectiveLocalExecutor()), controller.signal));
+                    });
+                    suspendMarker = getRequestedSuspend();
+                });
+            }
+            catch (error) {
+                // Snapshot the stop decision before the settlement awaits below: a
+                // Stop landing mid-report must not repaint an already-classified
+                // genuine error (or a drain abort) as a stopped call.
+                const stoppedByCallInterrupt = preAborted ||
+                    (callController !== undefined &&
+                        callController.signal.reason === CALL_INTERRUPT_REASON);
+                // Close interruptibility ahead of the report: a Stop landing
+                // mid-report reads already_settled, not a stop the durable record
+                // will contradict. No await runs between the snapshot and this claim,
+                // so no abort can slip between them.
+                registry?.claimSettlement(this.executionId, step);
+                const interrupted = isFrameworkControlFlow?.(error) === true ||
+                    (error instanceof Error && error.name === "AbortError");
+                const propagatedError = error;
+                const durationMs = performance.now() - startedAt;
+                const status = interrupted ? "interrupted" : "error";
+                const classified = status === "error"
+                    ? await classifyToolAPIError(propagatedError, undefined, requestCredentialValues())
+                    : undefined;
+                const errorText = classified
+                    ? classified.message
+                    : propagatedError instanceof Error
+                        ? `${propagatedError.name}: ${propagatedError.message}`
+                        : String(propagatedError);
+                logToolResult(toolName, step, status, null, errorText, durationMs);
+                try {
+                    await reportOeResult({
+                        oeUrl: this.oeUrl,
+                        ownerUrl: this.currentOeOwnerUrl(),
+                        onOwnerFailure: () => this.reportOeOwnerFailure(),
+                        executionId: this.executionId,
+                        toolName,
+                        step,
+                        toolCallId,
+                        status,
+                        result: null,
+                        error: errorText,
+                        durationMs,
+                        metadata,
+                        toolApiError: classified?.toolApiError,
+                    });
+                }
+                catch (settlementError) {
+                    throw new AggregateError([propagatedError, settlementError], "In-process tool result settlement failed", { cause: settlementError });
+                }
+                if (stoppedByCallInterrupt) {
+                    // This call was deliberately stopped: the graph continues with the
+                    // stopped-call result instead of unwinding.
+                    return rawOnInterrupt ? CALL_INTERRUPTED : { interrupted: true };
+                }
+                throw propagatedError;
+            }
+            finally {
+                if (registry != null) {
+                    registry.endWork(this.executionId, callController, step);
+                }
+            }
+            const durationMs = performance.now() - startedAt;
+            if (suspendMarker !== null && interruptMode === "reject") {
+                const error = new ToolExecutionError("durable Tool activities support terminal outcomes only; " +
+                    "the framework adapter must own suspension and resume");
+                logToolResult(toolName, step, "error", null, error.message, durationMs);
+                await reportOeResult({
+                    oeUrl: this.oeUrl,
+                    ownerUrl: this.currentOeOwnerUrl(),
+                    onOwnerFailure: () => this.reportOeOwnerFailure(),
+                    executionId: this.executionId,
+                    toolName,
+                    step,
+                    toolCallId,
+                    status: "error",
+                    result: null,
+                    error: error.message,
+                    durationMs,
+                    metadata,
+                });
+                throw error;
+            }
+            const status = suspendMarker === null ? "success" : "suspend";
+            const reportedResult = suspendMarker === null ? localResult : JSON.stringify(suspendMarker);
+            logToolResult(toolName, step, status, reportedResult, null, durationMs);
+            await reportOeResult({
+                oeUrl: this.oeUrl,
+                ownerUrl: this.currentOeOwnerUrl(),
+                onOwnerFailure: () => this.reportOeOwnerFailure(),
+                executionId: this.executionId,
+                toolName,
+                step,
+                toolCallId,
+                status,
+                result: reportedResult,
+                error: null,
+                durationMs,
+                metadata,
+            });
+            if (suspendMarker !== null) {
+                // suspendPayloadToJson records this out of band, so relayed tool output
+                // cannot forge a wait.
+                return this.handleSuspend(reportedResult);
+            }
+            return localResult;
+        }
+        if (response.route_to != null) {
+            throw new ToolExecutionError(`Unexpected OE tool route: ${response.route_to}`);
+        }
+        const status = response.status ?? "error";
+        const result = response.result;
+        const error = response.error;
+        const durationMs = response.duration_ms ?? 0;
+        logToolResult(toolName, step, status, result, error ?? null, durationMs);
+        if (status === "interrupted") {
+            // Only the LangGraph tool-wrapping path requests the raw sentinel and
+            // coerces it immediately; every other caller keeps the plain dict.
+            return rawOnInterrupt ? CALL_INTERRUPTED : { interrupted: true };
+        }
+        if (status === "error") {
+            if (response.tool_api_error) {
+                throw new ExternalAPICallError(error ?? "Unknown error", response.tool_api_error);
+            }
+            throw new ToolExecutionError(error ?? "Unknown error");
+        }
+        // Suspend is honored only from the OE-confirmed status channel, whose
+        // provenance is the tool author's suspendPayloadToJson call — never from
+        // sniffing result content, which a relayed untrusted payload controls.
+        // A successful result is returned verbatim.
+        if (status === "suspend") {
+            if (interruptMode === "reject") {
+                throw new ToolExecutionError("durable Tool activities support terminal outcomes only; " +
+                    "the framework adapter must own suspension and resume");
+            }
+            return this.handleSuspend(result);
+        }
+        if (status !== "success") {
+            throw new ToolExecutionError(`Unexpected OE tool status: ${status}`);
+        }
+        return result;
+    }
+    /** Fire the framework HITL interrupt for an OE-confirmed suspend. */
+    handleSuspend(result) {
+        let parsed = result;
+        if (typeof result === "string") {
+            try {
+                parsed = JSON.parse(result);
+            }
+            catch {
+                /* not JSON, keep as-is */
+            }
+        }
+        if (typeof parsed !== "object" ||
+            parsed === null ||
+            Array.isArray(parsed)) {
+            throw new ToolExecutionError("OE reported suspend but the result is not a suspend payload");
+        }
+        const interrupt = getSuspendHandler();
+        if (interrupt == null) {
+            throw new Error("No suspend handler registered. Ensure the framework SDK calls registerSuspendHandler() before run().");
+        }
+        const payload = SuspendPayloadSchema.parse(parsed);
+        const humanDecision = interrupt(payload);
+        if (typeof humanDecision !== "object" ||
+            humanDecision === null ||
+            Array.isArray(humanDecision)) {
+            throw new TypeError(`Expected object from HITL interrupt, got ${typeof humanDecision}`);
+        }
+        return JSON.stringify(humanDecision);
+    }
+}
+function isTwoElementArray(value) {
+    return Array.isArray(value) && value.length === 2;
+}
+/**
+ * Shapes a tool result for LangChain's content_and_artifact wire format.
+ * `toolDeclaredFormat` (the tool's own original format, independent of the
+ * forced wire-level `responseFormat`) decides whether a real result gets
+ * shape-matched into (content, artifact) — otherwise it's never split.
+ */
+function coerceContentAndArtifact(result, responseFormat, toolDeclaredFormat = "content") {
+    if (result === CALL_INTERRUPTED) {
+        if (responseFormat === "content_and_artifact") {
+            return [
+                INTERRUPTED_CALL_CONTENT,
+                { [CALL_INTERRUPTED_ARTIFACT_KEY]: true },
+            ];
+        }
+        return { interrupted: true };
+    }
+    if (responseFormat !== "content_and_artifact")
+        return result;
+    if (toolDeclaredFormat === "content_and_artifact" &&
+        isTwoElementArray(result)) {
+        const [content, artifact] = result;
+        // Only the interrupted branch above may set this key — a tool's own
+        // artifact must never be able to forge it.
+        if (typeof artifact === "object" &&
+            artifact !== null &&
+            CALL_INTERRUPTED_ARTIFACT_KEY in artifact) {
+            const stripped = { ...artifact };
+            delete stripped[CALL_INTERRUPTED_ARTIFACT_KEY];
+            return [content, stripped];
+        }
+        return result;
+    }
+    return [result, null];
+}
+/**
+ * Create a wrapped tool function that routes through SecureToolWrapper.
+ *
+ * The wrapper is looked up from AsyncLocalStorage context at call time,
+ * so the tool can be built before execution context exists.
+ *
+ * The registered tool must expose an `invoke` method for both approved local
+ * execution and the direct-execution debugging path. Direct execution is
+ * UNSAFE and only for debugging.
+ */
+export function createSecureToolFunction(originalTool, toolName, allowDirect = false, options = {}) {
+    const { metadata, providerType, scopes, responseFormat = "content", toolDeclaredFormat, redactFields, isLocal = true, isFrameworkControlFlow, supportsCallInterrupt = false, } = options;
+    const effectiveToolFormat = toolDeclaredFormat ?? responseFormat;
+    return async (kwargs = {}, config) => {
+        // When a tool is invoked with a ToolCall, LangChain JS exposes it on
+        // config.toolCall (toolCall.id is the stable id) and also mirrors the id
+        // onto config.configurable.tool_call_id. Prefer config.toolCall.id — that is
+        // the documented shape ToolNode produces — and fall back to configurable.
+        // Forward it to OE for the execution-log join key.
+        const rawToolCallId = config?.toolCall?.id ?? config?.configurable?.tool_call_id;
+        const toolCallId = typeof rawToolCallId === "string" ? rawToolCallId : undefined;
+        const wrapper = getCurrentWrapper();
+        if (wrapper == null) {
+            if (!allowDirect) {
+                throw new Error(`SecureToolWrapper missing for tool ${toolName}; ` +
+                    "execution not allowed (RUNNER_ALLOW_DIRECT_TOOL_EXECUTION=false)");
+            }
+            logger.warn(`No wrapper for tool ${toolName}, executing directly (UNSAFE)`);
+            const tool = originalTool;
+            return coerceContentAndArtifact(await tool.invoke(kwargs), responseFormat, effectiveToolFormat);
+        }
+        // Capture the registered tool object and this invocation's arguments. OE
+        // approves first; invoking this closure afterward keeps execution on the
+        // framework's original stack with its live native context.
+        const localExecutor = isLocal
+            ? () => runWithToolMemoryReadOwnership(() => {
+                const tool = originalTool;
+                return tool.invoke(kwargs);
+            })
+            : undefined;
+        try {
+            const result = await wrapper.executeTool(toolName, kwargs, {
+                metadata,
+                providerType,
+                scopes,
+                toolCallId,
+                rawOnInterrupt: true,
+                redactFields,
+                isLocal,
+                localExecutor,
+                isFrameworkControlFlow,
+                // Absent unless declared: a present-but-false key would read as a
+                // declared capability to exact-shape consumers.
+                ...(supportsCallInterrupt && { supportsCallInterrupt }),
+            });
+            return coerceContentAndArtifact(result, responseFormat, effectiveToolFormat);
+        }
+        catch (exc) {
+            // Both branches re-throw; the only distinction is that a
+            // ToolExecutionError is logged as it propagates to the graph.
+            if (exc instanceof ToolExecutionError) {
+                logger.info({ tool_name: toolName, error: exc.error }, `Propagating tool execution error to graph for ${toolName}: ${exc.error}`);
+            }
+            throw exc;
+        }
+    };
+}