@qduc/term2 0.22.1 → 0.24.0

package/dist/tools/system/run-code/run-code.js

@@ -1,76 +1,71 @@
-import { appendFileSync } from 'node:fs';
-import { lstat } from 'node:fs/promises';
-import { randomUUID } from 'node:crypto';
 import { z } from 'zod';
 import { relaxedNumber } from '../../utils.js';
-import { normalizeToolParameters } from '../../../lib/tool-invoke.js';
-import { SandboxedCodeHostImpl } from '../../../services/sandboxed-code-host/sandboxed-code-host.js';
-import { applyApprovalGrant } from '../../../services/approval/approval-grant-executor.js';
-import { isZodToolParameterSchema, } from '../../types.js';
 import { createBaseMessage, getCallIdFromItem, getOutputText, isSuccessOutput, normalizeToolArguments, } from '../../format-helpers.js';
-import { WORKFLOW_PROHIBITED_TOOLS } from '../../../services/agent-runtime/workflow/workflow-evaluator.js';
-import { renderCompactSignature, renderToolsHeader } from './tools-header.js';
-import { emitRunCodeCompletionTelemetry } from './run-code-telemetry.js';
-import { resolveWorkspacePath, resolveWorkspacePathPhysically } from '../../utils.js';
-import { resolveOutsideWorkspaceEdit } from '../../../services/approval/approval-descriptor.js';
-import { parseUpstreamApplyPatch } from '../../file/upstream-apply-patch.js';
-import { saveOutputArtifact, formatFullOutputSavedNote } from '../../../utils/shell/shell-output.js';
-export const TOOL_NAME_RUN_CODE = 'run_code';
-export const TOOL_NAME_DESCRIBE = 'describe';
+import { renderToolsHeader } from './tools-header.js';
+import { RUN_CODE_EXECUTION_RESULT } from './run-code-execution.js';
+import { formatFullOutputSavedNote, saveOutputArtifact } from '../../../utils/shell/shell-output.js';
+import { RUN_CODE_LIMITS, RUN_CODE_PROHIBITED_TOOLS, TOOL_NAME_RUN_CODE, createRunCodeRuntime, } from './run-code-runtime.js';
+export { RUN_CODE_EXECUTION_RESULT, getRunCodeExecutionResult } from './run-code-execution.js';
+export { RUN_CODE_LIMITS, RUN_CODE_PROHIBITED_TOOLS, TOOL_NAME_DESCRIBE, TOOL_NAME_RUN_CODE, isDirectlyCallable, } from './run-code-runtime.js';
 const DEFAULT_TIMEOUT_MS = 120_000;
 /** Node `setTimeout` wraps delays above `2**31-1` to ~1 ms. */
 const MAX_TIMEOUT_MS = 2_147_483_647;
 const MAX_OUTPUT_CHARS = 30_000;
-let nextBridgeRunId = 0;
-const createBridgeRunId = () => `run_code_bridge_${++nextBridgeRunId}`;
+const encodeInputKeysForValidation = (value) => {
+    if (Array.isArray(value))
+        return value.map(encodeInputKeysForValidation);
+    if (value === null || typeof value !== 'object')
+        return value;
+    const encoded = Object.create(null);
+    for (const [key, item] of Object.entries(value)) {
+        Object.defineProperty(encoded, `$${key}`, {
+            value: encodeInputKeysForValidation(item),
+            enumerable: true,
+            configurable: true,
+            writable: true,
+        });
+    }
+    return encoded;
+};
+const decodeValidatedInputKeys = (value) => {
+    const decode = (item) => {
+        if (Array.isArray(item))
+            return item.map(decode);
+        if (item === null || typeof item !== 'object')
+            return item;
+        const decoded = Object.create(null);
+        for (const [key, nested] of Object.entries(item)) {
+            Object.defineProperty(decoded, key.slice(1), {
+                value: decode(nested),
+                enumerable: true,
+                configurable: true,
+                writable: true,
+            });
+        }
+        return decoded;
+    };
+    return decode(value);
+};
+const runCodeInputsSchema = z
+    .preprocess(encodeInputKeysForValidation, z.record(z.string(), z.json()))
+    // Zod records omit `__proto__`; prefixing every key before validation and
+    // removing exactly one prefix afterward keeps all JSON object keys inert.
+    .overwrite(decodeValidatedInputKeys);
 /**
  * Script-shaped limits. They are deliberately not the workflow's: a workflow
  * spawns a handful of agents, while a script's whole point is looping over many
  * cheap tool calls.
  */
-export const RUN_CODE_LIMITS = {
-    /** Total `tools.*` calls one script may make. */
-    maxCalls: 200,
-    /** Parallel-safe calls that may overlap; others take a serial lane of one. */
-    maxConcurrency: 8,
-    /** Per-result cap. A larger result is truncated with an explicit marker. */
-    maxResultChars: 100_000,
-    /** Maximum raw bytes in one media attachment retained outside the script. */
-    maxMediaBytes: 8 * 1024 * 1024,
-    /** Maximum raw bytes and attachment count retained for one script run. */
-    maxMediaTotalBytes: 32 * 1024 * 1024,
-    maxMediaAttachments: 32,
-    maxCodeBytes: 65_536,
-    maxOutputBytes: 262_144,
-    maxConsoleBytes: 262_144,
-};
-/**
- * Tools a script may never call.
- *
- * `run_code` excludes itself because each run owns its own call budget, and
- * nesting would let one run spend many. The rest are the workflow's prohibited
- * set: `run_subagent` in particular spawns agents outside any run budget, so a
- * script could loop on it indefinitely. Shell tools are excluded because their
- * complete approval state also lives in the interactive batch coordinator.
- */
-export const RUN_CODE_PROHIBITED_TOOLS = new Set([
-    ...WORKFLOW_PROHIBITED_TOOLS,
-    TOOL_NAME_RUN_CODE,
-    'ask_mentor',
-    'session_rollover',
-    // Shell approval also depends on coordinator-owned Docker/session state that
-    // the raw policy registry cannot express for an out-of-band script call.
-    'shell',
-    'bash',
-    'enter_worktree',
-    'exit_worktree',
-]);
 export const runCodeParametersSchema = z.object({
     code: z
         .string()
         .min(1)
         .describe('JavaScript (not TypeScript) executed as the body of an async function. Top-level await is available. ' +
         'Return the value you want the model to receive. Use console.log only for debugging.'),
+    inputs: runCodeInputsSchema
+        .optional()
+        .describe('JSON data exposed to the script as the global `inputs`. Use this for patch or file text. ' +
+        'Code and serialized inputs share the 65,536-byte admission limit.'),
     include_console: z
         .boolean()
         .optional()
@@ -95,7 +90,8 @@ const RUN_CODE_DESCRIPTION = 'Write a JavaScript program and execute it. Return
     'but it is included when the script fails or times out. The code runs in an isolated ' +
     'context with no filesystem, network, timers, require, or eval: `tools.*` is the only way out. Auto-approved tools ' +
     'run immediately. Tools that require user approval present the existing approval prompt and resume this script after ' +
-    'a decision; denial is catchable. Some tools are structurally unavailable inside scripts; those remain direct tools.\n\n' +
+    'a decision; denial is catchable. The catalogue below is the complete set of tools a script can call: a name that is ' +
+    'absent from it is not available inside the script, even when the direct tool surface offers it.\n\n' +
     `Each script may admit at most ${RUN_CODE_LIMITS.maxCalls} tools.* calls. Track progress and split large work into chunks; catch individual ` +
     'failures or use Promise.allSettled so you can return partial results. When the call budget is exhausted, the error ' +
     'reports calls admitted and calls remaining: return the partial results and start another run_code call only for ' +
@@ -104,61 +100,24 @@ const RUN_CODE_DESCRIPTION = 'Write a JavaScript program and execute it. Return
     'and larger host results can fail before rendering. For independent reads, preserve successful siblings with ' +
     '`Promise.allSettled`, mapping rejections to `{error: r.reason.message}` before returning. ' +
     'If the final result says `Full output saved to`, read that exact path with `read_file` rather than repeating completed calls; ' +
-    'for a large artifact, use line ranges or a focused `grep` projection. A scripted `read_file` result may itself have ' +
+    'for a large artifact, read line ranges or the fields you need instead of transferring the whole value. A scripted ' +
+    '`read_file` result may itself have ' +
     '`truncated: true` and a `fullOutputPath`; follow that path or narrow the projection before returning it. ' +
-    'Use `tools.describe` before guessing parameters or returned fields. If a patch is scripted, escape backticks and ' +
-    '${...} inside a template literal, or use ordinary quoted strings with escaped newlines. ' +
+    'Use `tools.describe` before guessing parameters or returned fields. If a patch or file body contains JavaScript ' +
+    'syntax such as backticks or `${...}`, pass it through the `inputs` parameter and read it from the global `inputs` ' +
+    'object instead of embedding it in code. Code and serialized inputs share the 65,536-byte admission limit. ' +
     'Example: `const r = await Promise.allSettled([tools.read_file({path:"a.ts"}), tools.read_file({path:"b.ts"})]); ' +
     'return r.map(x => x.status === "fulfilled" ? {content:(typeof x.value === "string" ? x.value : x.value.content).slice(0,2000)} : {error:x.reason.message});`';
-/**
- * Static host-owned classification: exactly the action tools with an explicit
- * outcome adapter. Not a naming convention, not a script declaration, and not
- * the generic `effect` flag (a stall-detection marker, not an action contract).
- */
-const ACTION_SEMANTICS = {
-    configure_task_check_in: (raw) => {
-        const parsed = parseActionPayload(raw);
-        if (!isRecord(parsed) || typeof parsed.ok !== 'boolean') {
-            return { outcome: 'unknown', reason: 'unrecognized action result shape' };
-        }
-        if (parsed.ok === true)
-            return { outcome: 'applied' };
-        const detail = typeof parsed.error === 'string' && parsed.error ? parsed.error : 'action reported ok:false';
-        return { outcome: 'not_applied', reason: detail };
-    },
-    cancel_run: (raw) => {
-        const parsed = parseActionPayload(raw);
-        if (!isRecord(parsed) || typeof parsed.ok !== 'boolean') {
-            return { outcome: 'unknown', reason: 'unrecognized action result shape' };
-        }
-        if (parsed.ok === true &&
-            typeof parsed.runId === 'string' &&
-            parsed.runId.length > 0 &&
-            parsed.status === 'cancelling') {
-            return { outcome: 'applied', reason: 'cancellation requested and accepted; settlement is reported separately' };
-        }
-        if (parsed.ok === false &&
-            parsed.code === 'not_active' &&
-            typeof parsed.target === 'string' &&
-            parsed.target.length > 0) {
-            return { outcome: 'not_applied', reason: `not_active (target: ${parsed.target})` };
-        }
-        return { outcome: 'unknown', reason: 'unrecognized action result shape' };
-    },
-};
-const isActionTool = (name) => ACTION_SEMANTICS[name] !== undefined;
-const parseActionPayload = (raw) => {
-    if (typeof raw !== 'string')
-        return raw;
-    try {
-        return JSON.parse(raw);
-    }
-    catch {
-        return raw;
-    }
-};
-const MAX_RECEIPT_REASON_CHARS = 280;
-const clipReason = (reason) => reason.length <= MAX_RECEIPT_REASON_CHARS ? reason : `${reason.slice(0, MAX_RECEIPT_REASON_CHARS)}…`;
+function attachRunCodeExecution(value, execution) {
+    if (Array.isArray(value)) {
+        const result = [...value];
+        Object.defineProperty(result, RUN_CODE_EXECUTION_RESULT, { value: execution });
+        return result;
+    }
+    const result = new String(value);
+    Object.defineProperty(result, RUN_CODE_EXECUTION_RESULT, { value: execution });
+    return result;
+}
 /**
  * Marks a definition as accepting the final, wrapped tool registry.
  *
@@ -181,45 +140,6 @@ export function bindRunCodeNestedApprovalOwner(tools, owner) {
         tool[NESTED_OWNER_BINDER]?.(owner, tools);
     }
 }
-/**
- * Direct calls are the tools a script structurally cannot reach, including
- * `run_code` itself. Visibility does not depend on `canRequireApproval`.
- */
-export function isDirectlyCallable(tool) {
-    return RUN_CODE_PROHIBITED_TOOLS.has(tool.name);
-}
-function unknownToolMessage(name, registry) {
-    return `Unknown tool "${name}". Available: ${registry.map((entry) => entry.name).join(', ')}`;
-}
-function describeTool(tool) {
-    let parameters;
-    const targetSchema = tool.canonicalParameters ?? tool.parameters;
-    if (isZodToolParameterSchema(targetSchema)) {
-        try {
-            parameters = z.toJSONSchema(targetSchema, { io: 'input' });
-        }
-        catch {
-            parameters = { unconvertible: true };
-        }
-    }
-    else if (targetSchema && typeof targetSchema === 'object') {
-        parameters = targetSchema;
-    }
-    else {
-        parameters = { unconvertible: true };
-    }
-    return {
-        name: tool.name,
-        description: tool.description,
-        parameters,
-        // The scripted-path return contract. Agents discover it here before
-        // calling, and the tools header renders the same string for essential
-        // tools, so both surfaces stay consistent.
-        ...(typeof tool.scriptedReturnShape === 'string' && tool.scriptedReturnShape
-            ? { scriptedReturnShape: tool.scriptedReturnShape }
-            : {}),
-    };
-}
 const summarizeCalls = (calls) => {
     const describeCalls = calls.filter((call) => call.outcome === 'describe');
     const executionCalls = calls.filter((call) => call.outcome !== 'describe');
@@ -263,112 +183,23 @@ const clip = async (text, protectedAction) => {
         prefix = prefix.slice(0, -1);
     return `${prefix}${marker}${action}`;
 };
-const FAILURE_PREFIXES = [
-    'Error:',
-    'Script failed',
-    'Script timed out',
-    'Script was cancelled',
-    'Script exceeded its deadline',
-];
-/**
- * Whether a rendered run_code result reads as unsuccessful. Script-level
- * failures start with a known prefix; a script can also complete at the JS
- * level while its nested result is an error string (status-string tools such as
- * apply_patch), which the renderer places under a `Result:` heading. Lifecycle
- * status stays 'completed' in both cases — this is the call-level success bit,
- * kept separate from script success (visible in the text) and task success
- * (conversation-level).
- */
-const isUnsuccessfulRunCodeOutput = (output) => {
-    if (FAILURE_PREFIXES.some((prefix) => output.startsWith(prefix)))
-        return true;
+/** Compatibility-only reader for old persisted messages. New executions carry
+ * a typed marker and never use rendered text for their success bit. */
+const legacyRunCodeSuccess = (output) => {
+    if (/^(?:Error:|Script failed|Script timed out|Script was cancelled|Script exceeded its deadline)/.test(output)) {
+        return false;
+    }
     if (output.startsWith('Result:')) {
-        // The renderer joins the rendered value and the trailing tool-call summary
-        // with a blank line. Evaluate only the value block, using the shared
-        // success heuristic: an 'Error:' text prefix or a JSON value carrying an
-        // 'error' key (string or structured envelope) both read as unsuccessful.
         const valueBlock = output.slice('Result:'.length).trimStart().split('\n\n')[0];
-        return !isSuccessOutput(valueBlock);
+        return isSuccessOutput(valueBlock);
     }
-    return false;
+    return true;
 };
-/**
- * Truncation is a display concern, but a script may branch on the result, so
- * the marker has to be unmistakable rather than a silent cut.
- */
-const truncate = (text, limit) => text.length <= limit ? text : `${text.slice(0, limit)}\n[truncated: result exceeded ${limit} characters]`;
 const isRecord = (value) => typeof value === 'object' && value !== null;
 const isMediaContentPart = (value) => isRecord(value) && ((value.type === 'image' && 'image' in value) || (value.type === 'file' && 'file' in value));
 const isContentPartArray = (value) => Array.isArray(value) &&
     value.length > 0 &&
     value.every((part) => isRecord(part) && (part.type === 'text' || isMediaContentPart(part)));
-const MEDIA_REFERENCE_KEY = '__term2_run_code_media_reference__';
-const isMediaReference = (value) => isRecord(value) && typeof value[MEDIA_REFERENCE_KEY] === 'string' && Object.keys(value).length === 1;
-/** Count the bytes that will eventually be sent to the model, not its JSON wrapper. */
-function mediaBytes(value) {
-    const payload = value.type === 'image' ? value.image : value.type === 'file' ? value.file : undefined;
-    if (isRecord(payload) && typeof payload.data === 'string') {
-        try {
-            return Buffer.from(payload.data, 'base64').byteLength;
-        }
-        catch {
-            return Buffer.byteLength(payload.data, 'utf8');
-        }
-    }
-    try {
-        return Buffer.byteLength(JSON.stringify(payload) ?? '', 'utf8');
-    }
-    catch {
-        return Number.POSITIVE_INFINITY;
-    }
-}
-/**
- * Keep large media out of both the worker transport and its generic result
- * budget. The reference is deliberately scoped to one execute call: a token
- * from another run is just an ordinary object and cannot recover its bytes.
- */
-function createMediaReferenceStore() {
-    const attachments = new Map();
-    const byValue = new WeakMap();
-    let totalBytes = 0;
-    const capture = (value) => {
-        if (isMediaContentPart(value)) {
-            const existing = byValue.get(value);
-            if (existing !== undefined)
-                return existing ? { [MEDIA_REFERENCE_KEY]: existing } : '[media content omitted]';
-            const size = mediaBytes(value);
-            if (!Number.isFinite(size) ||
-                size > RUN_CODE_LIMITS.maxMediaBytes ||
-                attachments.size >= RUN_CODE_LIMITS.maxMediaAttachments ||
-                totalBytes + size > RUN_CODE_LIMITS.maxMediaTotalBytes) {
-                byValue.set(value, null);
-                return (`[media content omitted: attachment exceeds the ${RUN_CODE_LIMITS.maxMediaBytes}-byte per-image or ` +
-                    `${RUN_CODE_LIMITS.maxMediaTotalBytes}-byte per-run limit]`);
-            }
-            const token = `run_code_media_${randomUUID()}`;
-            byValue.set(value, token);
-            attachments.set(token, value);
-            totalBytes += size;
-            return { [MEDIA_REFERENCE_KEY]: token };
-        }
-        if (Array.isArray(value))
-            return value.map(capture);
-        if (isRecord(value)) {
-            return Object.fromEntries(Object.entries(value).map(([key, entry]) => [key, capture(entry)]));
-        }
-        return value;
-    };
-    const resolve = (value) => {
-        if (isMediaReference(value))
-            return attachments.get(value[MEDIA_REFERENCE_KEY]) ?? value;
-        if (Array.isArray(value))
-            return value.map(resolve);
-        if (isRecord(value))
-            return Object.fromEntries(Object.entries(value).map(([key, entry]) => [key, resolve(entry)]));
-        return value;
-    };
-    return { capture, resolve };
-}
 /** Look through script wrappers without mistaking ordinary arrays for media. */
 function containsMediaContent(value, ancestors = new Set()) {
     if (isMediaContentPart(value))
@@ -384,41 +215,6 @@ function containsMediaContent(value, ancestors = new Set()) {
     ancestors.delete(value);
     return found;
 }
-const serializeResult = async (result, limit, toolName, callsCompleted) => {
-    if (typeof result === 'string')
-        return { ok: true, result: truncate(result, limit) };
-    try {
-        const encoded = JSON.stringify(result);
-        if (encoded === undefined)
-            return { ok: true, result: null };
-        if (encoded.length <= limit)
-            return { ok: true, result: result };
-        // Never turn a multimodal result into a partial JSON string: that both
-        // corrupts image data and makes the failure look like a successful text
-        // result to the script. A clear value lets the script continue (or catch
-        // the omission) without sending an unusable image to the worker.
-        if (containsMediaContent(result)) {
-            return {
-                ok: true,
-                result: `[truncated: media result exceeded ${limit} characters; media content omitted]`,
-            };
-        }
-        let retrieval = '';
-        try {
-            const artifactPath = await saveOutputArtifact(encoded, { filenamePrefix: 'tool-overflow' });
-            retrieval = `Full output saved to: ${artifactPath}. `;
-        }
-        catch {
-            retrieval = 'Full output could not be saved; the omitted result is unavailable. ';
-        }
-        const callUnit = callsCompleted === 1 ? 'call' : 'calls';
-        const message = `Tool "${toolName}" result exceeded ${limit} characters and could not be delivered to script. ${retrieval}${callsCompleted} nested tool ${callUnit} completed — inspect state before retrying; tool effects have already completed.`;
-        return { ok: false, error: message };
-    }
-    catch {
-        return { ok: true, result: truncate(String(result), limit) };
-    }
-};
 /** Replace embedded media with a text marker while retaining the real parts. */
 function stripMediaContent(value, media) {
     if (isMediaContentPart(value)) {
@@ -432,8 +228,6 @@ function stripMediaContent(value, media) {
     }
     return value;
 }
-/** Renders one console.log's arguments the way a terminal would. */
-const renderConsoleValues = (values) => values.map((value) => (typeof value === 'string' ? value : JSON.stringify(value))).join(' ');
 export const formatRunCodeCommandMessage = (item, index, toolCallArgumentsById) => {
     const callId = getCallIdFromItem(item);
     const fallbackArgs = callId && toolCallArgumentsById.has(callId) ? toolCallArgumentsById.get(callId) : null;
@@ -441,36 +235,17 @@ export const formatRunCodeCommandMessage = (item, index, toolCallArgumentsById)
     const description = typeof args?.description === 'string' ? args.description : undefined;
     const code = typeof args?.code === 'string' ? args.code : '';
     const output = getOutputText(item) || 'No output';
+    const semantic = item.runCodeExecution;
     return [
         createBaseMessage(item, index, 0, false, {
             command: description ? `run_code — ${description}` : 'run_code',
             output,
-            success: !isUnsuccessfulRunCodeOutput(output),
+            success: semantic ? semantic.success : legacyRunCodeSuccess(output),
             toolName: TOOL_NAME_RUN_CODE,
             toolArgs: { ...args, code },
         }),
     ];
 };
-function getConversationSessionId(context) {
-    if (!context || typeof context !== 'object')
-        return undefined;
-    const runContext = context.context;
-    if (!runContext || typeof runContext !== 'object')
-        return undefined;
-    const sessionId = runContext.sessionId;
-    return typeof sessionId === 'string' && sessionId.length > 0 ? sessionId : undefined;
-}
-function writeNestedCallRecord(tool, sessionId, outcome) {
-    const logPath = process.env.TERM2_NESTED_CALL_LOG;
-    if (!logPath || !sessionId)
-        return;
-    try {
-        appendFileSync(logPath, `${JSON.stringify({ tool, sessionId, timestamp: new Date().toISOString(), outcome })}\n`, 'utf8');
-    }
-    catch {
-        // Experiment-only logging must never affect tool execution.
-    }
-}
 export function createRunCodeToolDefinition(options) {
     const { loggingService, getCwd = () => options.executionContext?.getCwd() || process.cwd() } = options;
     const approvalRegistry = options.approvalPolicyRegistry;
@@ -478,372 +253,48 @@ export function createRunCodeToolDefinition(options) {
     let boundRegistry;
     let nestedApprovalOwner = options.nestedApprovalOwner;
     const exposedTools = () => (options.getToolRegistry?.() ?? boundRegistry ?? []).filter((tool) => !RUN_CODE_PROHIBITED_TOOLS.has(tool.name));
+    const createRuntime = (registry) => createRunCodeRuntime({
+        registry,
+        graphIdentity: boundRegistry ?? registry,
+        loggingService,
+        approvalPolicyRegistry: approvalRegistry,
+        getCwd,
+        executionContext: options.executionContext,
+        nestedApprovalOwner,
+        sessionAccess: options.sessionAccess,
+        nestedCompatibility: options.nestedCompatibility,
+    });
     const definition = {
         name: TOOL_NAME_RUN_CODE,
         // Read late, after bindRunCodeRegistry, so the model is told which tools
         // the script can actually reach rather than a guess made before wrapping.
         get description() {
-            const header = renderToolsHeader(exposedTools());
+            const header = renderToolsHeader(createRuntime(exposedTools()).discovery());
             return header ? `${RUN_CODE_DESCRIPTION}\n\n${header}` : RUN_CODE_DESCRIPTION;
         },
         parameters: runCodeParametersSchema,
         effect: 'mutating',
         needsApproval: () => false,
-        execute: async (params, context) => {
-            const { code, timeout_ms, description, include_console = false } = params;
+        execute: async (params, context, details) => {
+            const { code, inputs = {}, timeout_ms, description, include_console = false } = params;
             const timeout = timeout_ms ?? DEFAULT_TIMEOUT_MS;
             const callerSignal = context?.signal;
             const registry = exposedTools();
-            const bridgeRunId = createBridgeRunId();
-            const startedAt = Date.now();
-            const calls = [];
-            // Host-private action receipt ledger. Script code has no write path
-            // here: every entry is recorded by prepare/admit/invoke settlement, so
-            // a script cannot catch, relabel, or contradict an observed outcome.
-            const receipts = [];
-            const pendingReceiptByCallId = new Map();
-            let rejectedSeq = 0;
-            const output = [];
-            const sessionId = getConversationSessionId(context);
-            const mediaReferences = createMediaReferenceStore();
-            const record = (tool, outcome, started, directlyCallable) => {
-                calls.push({ tool, outcome, durationMs: Date.now() - started, directlyCallable });
-                if (outcome === 'describe')
-                    return;
-                writeNestedCallRecord(tool, sessionId, outcome === 'ok' ? 'success' : outcome === 'approval_required' ? 'denied-by-approval' : 'failure');
-            };
-            const failed = (message) => ({
-                kind: 'result',
-                result: { ok: false, error: message },
-            });
-            const recordReceipt = (callId, toolName, outcome, reason) => {
-                const pendingIndex = pendingReceiptByCallId.get(callId);
-                if (pendingIndex !== undefined) {
-                    receipts[pendingIndex] = {
-                        callId,
-                        tool: toolName,
-                        outcome,
-                        ...(reason ? { reason: clipReason(reason) } : {}),
-                    };
-                    pendingReceiptByCallId.delete(callId);
-                    return;
-                }
-                receipts.push({
-                    callId,
-                    tool: toolName,
-                    outcome,
-                    ...(reason ? { reason: clipReason(reason) } : {}),
-                });
-            };
-            const tools = {
-                binding: {
-                    name: 'tools',
-                    kind: 'namespace',
-                    members: [...new Set([...registry.map((tool) => tool.name), TOOL_NAME_DESCRIBE])],
-                },
-                limits: {
-                    maxCalls: RUN_CODE_LIMITS.maxCalls,
-                    maxConcurrency: RUN_CODE_LIMITS.maxConcurrency,
-                    limitExceededMessage: `Tool call limit reached (${RUN_CODE_LIMITS.maxCalls} calls per script run).`,
-                },
-                // A budget-exhausted call is the script's problem, not a reason to
-                // discard the work it has already printed.
-                overBudget: ({ usedCalls, maxCalls }, rejected) => {
-                    // The host supplies the exact prepared call that was rejected.
-                    // Preparation is async and concurrent, so a local FIFO would be
-                    // unable to attribute a budget rejection safely.
-                    if (isActionTool(rejected.tool.name)) {
-                        rejectedSeq += 1;
-                        recordReceipt(`${bridgeRunId}:rejected-${rejectedSeq}`, rejected.tool.name, 'unknown', 'call budget exhausted before dispatch');
-                    }
-                    return failed(`Tool call limit reached (${maxCalls} calls per script run; ${usedCalls} calls admitted, ${Math.max(0, maxCalls - usedCalls)} remaining). ` +
-                        'Return the partial results you collected and start another run_code call only for unattempted work; ' +
-                        'Do not repeat completed tool effects.');
-                },
-                onAdmitted: (prepared, callContext) => {
-                    if (!isActionTool(prepared.tool.name))
-                        return;
-                    const callId = `${bridgeRunId}:${callContext.callId}`;
-                    pendingReceiptByCallId.set(callId, receipts.length);
-                    receipts.push({ callId, tool: prepared.tool.name, outcome: 'unknown' });
-                },
-                prepare: async (payload) => {
-                    const started = Date.now();
-                    const name = typeof payload.member === 'string' ? payload.member : '';
-                    const tool = registry.find((candidate) => candidate.name === name);
-                    if (name === TOOL_NAME_DESCRIBE && typeof payload.params === 'string') {
-                        const described = registry.find((candidate) => candidate.name === payload.params);
-                        if (!described)
-                            return failed(unknownToolMessage(payload.params, registry));
-                        record(name, 'describe', started);
-                        return {
-                            kind: 'result',
-                            result: { ok: true, result: describeTool(described) },
-                        };
-                    }
-                    if (!tool) {
-                        record(name || '(unnamed)', 'unknown_tool', started);
-                        if (isActionTool(name)) {
-                            rejectedSeq += 1;
-                            recordReceipt(`${bridgeRunId}:rejected-${rejectedSeq}`, name, 'failed', unknownToolMessage(name, registry));
-                        }
-                        return failed(unknownToolMessage(name, registry));
-                    }
-                    const targetSchema = tool.canonicalParameters ?? tool.parameters;
-                    let normalized;
-                    try {
-                        normalized = normalizeToolParameters(payload.params ?? {}, targetSchema);
-                    }
-                    catch {
-                        normalized = payload.params ?? {};
-                    }
-                    if (isZodToolParameterSchema(targetSchema)) {
-                        const parsed = targetSchema.safeParse(normalized);
-                        if (!parsed.success) {
-                            record(name, 'invalid_params', started);
-                            const issues = parsed.error.issues
-                                .map((issue) => `${issue.path.join('.') || '(root)'}: ${issue.message}`)
-                                .join('; ');
-                            if (isActionTool(name)) {
-                                rejectedSeq += 1;
-                                recordReceipt(`${bridgeRunId}:rejected-${rejectedSeq}`, name, 'failed', `Invalid parameters: ${issues}`);
-                            }
-                            return failed(`Invalid parameters for "${name}": ${issues}\nSignature: ${renderCompactSignature(tool)}`);
-                        }
-                        normalized = parsed.data;
-                    }
-                    const authorityRoot = getCwd();
-                    const authority = await bindPreparedAuthority(name, normalized, authorityRoot, options.executionContext);
-                    if (authority.kind === 'denied') {
-                        record(name, 'approval_required', started, isDirectlyCallable(tool));
-                        if (isActionTool(name)) {
-                            rejectedSeq += 1;
-                            recordReceipt(`${bridgeRunId}:rejected-${rejectedSeq}`, name, 'not_applied', authority.message);
-                        }
-                        return failed(authority.message);
-                    }
-                    const prepared = {
-                        tool,
-                        params: authority.params,
-                        originalParams: normalized,
-                        authorityRoot,
-                        authorityMeaning: fingerprint(authority),
-                        parallelSafe: await isParallelSafe(tool, normalized, context),
-                        started,
-                    };
-                    return prepared;
-                },
-                // Mirrors the run loop: only a definition that declares itself
-                // parallel-safe may overlap another call, because tools such as
-                // enter_worktree mutate shared execution context.
-                lane: (prepared) => (prepared.parallelSafe ? 'default' : 'serial'),
-                invoke: async (prepared, callContext) => {
-                    const decision = await approvalRegistry.evaluate({
-                        toolName: prepared.tool.name,
-                        args: prepared.params,
-                        context,
-                    });
-                    if (decision.kind !== 'auto_approve') {
-                        if (decision.kind === 'prompt' && nestedApprovalOwner) {
-                            const nestedCallId = bridgeRunId + ':' + callContext.callId;
-                            const nestedContext = withAbortSignal(context, mergeAbortSignals(callerSignal, callContext.signal), {
-                                scripted: true,
-                            });
-                            tools.onWaiting?.(callContext);
-                            try {
-                                const resolution = await nestedApprovalOwner.request({
-                                    requestId: nestedCallId,
-                                    sessionId: sessionId ?? 'unknown',
-                                    graphIdentity: boundRegistry ?? registry,
-                                    outerRunId: bridgeRunId,
-                                    nestedCallId,
-                                    toolName: prepared.tool.name,
-                                    preparedArguments: prepared.params,
-                                    authorityContext: context,
-                                    approval: {
-                                        agentName: 'Nested run_code',
-                                        toolName: prepared.tool.name,
-                                        argumentsText: JSON.stringify(prepared.params),
-                                        rawInterruption: null,
-                                        callId: nestedCallId,
-                                        outsideWorkspaceEdit: resolveOutsideWorkspaceEdit(prepared.tool.name, prepared.params, prepared.authorityRoot),
-                                    },
-                                    signal: nestedContext.signal,
-                                    revalidateAuthority: async () => {
-                                        const currentRoot = getCwd();
-                                        const authority = await bindPreparedAuthority(prepared.tool.name, prepared.originalParams, currentRoot, options.executionContext);
-                                        return (authority.kind === 'bound' &&
-                                            currentRoot === prepared.authorityRoot &&
-                                            fingerprint(authority) === prepared.authorityMeaning);
-                                    },
-                                    revalidate: async () => {
-                                        const latest = await approvalRegistry.evaluate({
-                                            toolName: prepared.tool.name,
-                                            args: prepared.params,
-                                            context,
-                                        });
-                                        return latest.kind;
-                                    },
-                                    grant: (nestedDecision) => {
-                                        if (callContext.signal.aborted)
-                                            throw new Error('Tool execution was not approved.');
-                                        const applied = applyApprovalGrant({
-                                            sessionId: sessionId ?? 'unknown',
-                                            sessionAccess: options.sessionAccess,
-                                            nestedCompatibility: options.nestedCompatibility,
-                                            logger: loggingService,
-                                        }, {
-                                            answer: nestedDecision.answer,
-                                            toolName: prepared.tool.name,
-                                            rawArguments: prepared.params,
-                                            callId: nestedCallId,
-                                        });
-                                        if (!applied.isApproved)
-                                            throw new Error('Tool execution was not approved.');
-                                    },
-                                    dispatch: async () => prepared.tool.execute(prepared.params, nestedContext, { toolCall: { callId: nestedCallId } }),
-                                });
-                                if (resolution.kind === 'approved') {
-                                    record(prepared.tool.name, 'ok', prepared.started);
-                                    if (isActionTool(prepared.tool.name)) {
-                                        const semantic = ACTION_SEMANTICS[prepared.tool.name](resolution.result);
-                                        recordReceipt(`${bridgeRunId}:${callContext.callId}`, prepared.tool.name, semantic.outcome, semantic.reason);
-                                    }
-                                    const serialized = await serializeResult(mediaReferences.capture(resolution.result), RUN_CODE_LIMITS.maxResultChars, prepared.tool.name, calls.filter((c) => c.outcome !== 'describe').length);
-                                    return {
-                                        kind: 'result',
-                                        result: serialized,
-                                    };
-                                }
-                                if (resolution.kind === 'failed') {
-                                    record(prepared.tool.name, 'error', prepared.started);
-                                    const message = resolution.error instanceof Error ? resolution.error.message : String(resolution.error);
-                                    if (isActionTool(prepared.tool.name)) {
-                                        recordReceipt(`${bridgeRunId}:${callContext.callId}`, prepared.tool.name, 'failed', message);
-                                    }
-                                    return failed(message);
-                                }
-                                record(prepared.tool.name, 'approval_required', prepared.started, isDirectlyCallable(prepared.tool));
-                                if (isActionTool(prepared.tool.name)) {
-                                    recordReceipt(`${bridgeRunId}:${callContext.callId}`, prepared.tool.name, 'not_applied', resolution.message);
-                                }
-                                return failed(resolution.message);
-                            }
-                            finally {
-                                tools.onResumed?.(callContext);
-                            }
-                        }
-                        const outcome = decision.kind === 'unknown'
-                            ? 'unknown_policy'
-                            : decision.kind === 'error'
-                                ? 'policy_error'
-                                : decision.kind === 'interceptor_denied'
-                                    ? 'interceptor_denied'
-                                    : 'approval_required';
-                        const directlyCallable = isDirectlyCallable(prepared.tool);
-                        record(prepared.tool.name, outcome, prepared.started, directlyCallable);
-                        if (isActionTool(prepared.tool.name)) {
-                            const denialReason = decision.kind === 'unknown'
-                                ? 'no registered approval policy'
-                                : decision.kind === 'interceptor_denied'
-                                    ? 'refused by an approval interceptor'
-                                    : decision.kind === 'error'
-                                        ? 'approval policy failed'
-                                        : 'requires approval and is unavailable from inside a script';
-                            recordReceipt(`${bridgeRunId}:${callContext.callId}`, prepared.tool.name, 'not_applied', denialReason);
-                        }
-                        return failed(decision.kind === 'unknown'
-                            ? `"${prepared.tool.name}" has no registered approval policy and is unavailable from inside a script.`
-                            : decision.kind === 'interceptor_denied'
-                                ? `"${prepared.tool.name}" was refused by an approval interceptor and is unavailable from inside a script.`
-                                : decision.kind === 'error'
-                                    ? `"${prepared.tool.name}" approval policy failed and is unavailable from inside a script.`
-                                    : `"${prepared.tool.name}" requires approval and is unavailable from inside a script.`);
-                    }
-                    const started = Date.now();
-                    const callId = `${bridgeRunId}:${callContext.callId}`;
-                    try {
-                        // Marks the call as originating inside a script: the result goes to the
-                        // script, not into model context, so context-protection caps do not apply.
-                        const nestedContext = withAbortSignal(context, mergeAbortSignals(callerSignal, callContext.signal), {
-                            scripted: true,
-                        });
-                        const result = await prepared.tool.execute(prepared.params, nestedContext, { toolCall: { callId } });
-                        record(prepared.tool.name, 'ok', started);
-                        if (isActionTool(prepared.tool.name)) {
-                            const semantic = ACTION_SEMANTICS[prepared.tool.name](result);
-                            recordReceipt(callId, prepared.tool.name, semantic.outcome, semantic.reason);
-                        }
-                        const serialized = await serializeResult(mediaReferences.capture(result), RUN_CODE_LIMITS.maxResultChars, prepared.tool.name, calls.filter((c) => c.outcome !== 'describe').length);
-                        return {
-                            kind: 'result',
-                            result: serialized,
-                        };
-                    }
-                    catch (error) {
-                        record(prepared.tool.name, 'error', started);
-                        const message = error instanceof Error ? error.message : String(error);
-                        if (isActionTool(prepared.tool.name)) {
-                            recordReceipt(callId, prepared.tool.name, 'failed', message);
-                        }
-                        return failed(message);
-                    }
-                },
-            };
-            loggingService.debug('run_code execution started', {
-                cwd: getCwd(),
+            // The runtime is the single owner of the nested-call lifecycle. The
+            // definition remains responsible for model parameters and presentation;
+            // in particular, it must not expose a partially wrapped registry.
+            const runtime = createRuntime(registry);
+            const runtimeResult = await runtime.execute({
+                code,
+                inputs,
                 timeout,
-                exposedTools: registry.length,
                 description,
-            });
-            const result = await new SandboxedCodeHostImpl().run({
-                code,
-                capabilities: { tools },
-                limits: {
-                    timeoutMs: timeout,
-                    maxCodeBytes: RUN_CODE_LIMITS.maxCodeBytes,
-                    maxOutputBytes: RUN_CODE_LIMITS.maxOutputBytes,
-                    maxConsoleBytes: RUN_CODE_LIMITS.maxConsoleBytes,
-                },
-                subject: 'Script',
-                allowVoidOutput: true,
+                context,
                 signal: callerSignal,
-                onConsole: (values) => output.push(renderConsoleValues(values)),
-            });
-            const describeCalls = calls.filter((call) => call.outcome === 'describe');
-            const executionCalls = calls.filter((call) => call.outcome !== 'describe');
-            loggingService.debug('run_code execution finished', {
-                ok: result.ok,
-                toolCalls: executionCalls.length,
-                schemaLookups: describeCalls.length,
             });
-            // Calls admitted but never settled (timeout, deadline, cancellation,
-            // worker exit) keep their pending `unknown` outcome with an honest
-            // reason rather than vanishing from the ledger.
-            for (const [callId, index] of pendingReceiptByCallId) {
-                receipts[index] = {
-                    ...receipts[index],
-                    outcome: 'unknown',
-                    reason: 'did not settle before the script run ended',
-                };
-                pendingReceiptByCallId.delete(callId);
-            }
-            // Emitted before rendering: a script whose result cannot be rendered has
-            // still produced an outcome worth counting.
-            emitRunCodeCompletionTelemetry(loggingService, {
-                code,
-                result,
-                durationMs: Date.now() - startedAt,
-                timeoutMs: timeout,
-                sessionId,
-                runId: bridgeRunId,
-                calls,
-                receipts,
-            });
-            const resolvedResult = result.ok && !result.voidOutput
-                ? { ...result, output: mediaReferences.resolve(result.output) }
-                : result;
-            return renderResult(resolvedResult, output, calls, receipts, include_console);
+            const runtimeRendered = await renderResult(runtimeResult.execution, runtimeResult.output, include_console);
+            const runtimeTransportCall = details && typeof details === 'object' && 'toolCall' in details && typeof details.toolCall === 'object';
+            return runtimeTransportCall ? attachRunCodeExecution(runtimeRendered, runtimeResult.execution) : runtimeRendered;
         },
         formatCommandMessage: formatRunCodeCommandMessage,
     };
@@ -858,125 +309,6 @@ export function createRunCodeToolDefinition(options) {
     };
     return definition;
 }
-const PATH_TOOLS = new Set([
-    'read_file',
-    'create_file',
-    'search_replace',
-    'apply_patch',
-    'grep',
-    'glob',
-    'read_code_outline',
-    'code_context_search',
-]);
-async function bindPreparedAuthority(toolName, params, cwd, executionContext) {
-    const isRemote = executionContext?.isRemote() ?? false;
-    if (isRemote && PATH_TOOLS.has(toolName)) {
-        return { kind: 'denied', message: 'Cannot establish remote physical path authority for a nested tool call.' };
-    }
-    try {
-        const physicalRoot = isRemote ? cwd : await requirePhysicalPath(cwd, cwd);
-        return { kind: 'bound', physicalRoot, params: await bindPreparedArguments(toolName, params, cwd) };
-    }
-    catch (error) {
-        return {
-            kind: 'denied',
-            message: `Cannot establish physical path authority: ${error instanceof Error ? error.message : String(error)}`,
-        };
-    }
-}
-async function requirePhysicalPath(value, cwd, semantics = 'referent') {
-    const physicalPath = await resolveWorkspacePathPhysically(value, cwd);
-    if (physicalPath === undefined)
-        throw new Error(`Unresolved path: ${value}`);
-    if (semantics === 'unlink-source') {
-        // Move sources are both read and unlinked. Following a leaf symlink would
-        // preserve the read but delete its referent; reject rather than change meaning.
-        const lexicalPath = resolveWorkspacePath(value, cwd, { allowOutsideWorkspace: true });
-        const stats = await lstat(lexicalPath);
-        if (stats.isSymbolicLink())
-            throw new Error(`Symlink unlink source is unsupported: ${value}`);
-    }
-    return physicalPath;
-}
-async function bindPreparedArguments(toolName, params, cwd) {
-    if (!params || typeof params !== 'object' || Array.isArray(params) || !PATH_TOOLS.has(toolName))
-        return params;
-    const record = params;
-    const bindPath = async (value, semantics = 'referent') => typeof value === 'string' ? requirePhysicalPath(value, cwd, semantics) : value;
-    if (toolName === 'apply_patch' && typeof record.patch === 'string') {
-        return { ...record, patch: await bindPatchPaths(record.patch, bindPath) };
-    }
-    return 'path' in record ? { ...record, path: await bindPath(record.path) } : params;
-}
-async function bindPatchPaths(patch, bindPath) {
-    let parsed;
-    try {
-        parsed = parseUpstreamApplyPatch(patch);
-    }
-    catch {
-        return patch;
-    }
-    const targets = parsed.operations.flatMap((operation) => {
-        const moveTo = 'moveTo' in operation ? operation.moveTo : undefined;
-        const semantics = operation.type === 'delete_file' || moveTo ? 'unlink-source' : 'referent';
-        return [{ path: operation.path, semantics }, ...(moveTo ? [{ path: moveTo, semantics: 'referent' }] : [])];
-    });
-    let targetIndex = 0;
-    const lines = patch.replace(/\r\n?/g, '\n').split('\n');
-    const prefixes = ['*** Add File: ', '*** Update File: ', '*** Delete File: ', '*** Move to: '];
-    for (let index = 0; index < lines.length; index += 1) {
-        const prefix = prefixes.find((candidate) => lines[index].startsWith(candidate));
-        if (!prefix)
-            continue;
-        const target = targets[targetIndex++];
-        const bound = await bindPath(target.path, target.semantics);
-        lines[index] = prefix + String(bound);
-    }
-    return lines.join('\n');
-}
-function fingerprint(value) {
-    try {
-        return JSON.stringify(value) ?? String(value);
-    }
-    catch {
-        return String(value);
-    }
-}
-function withAbortSignal(context, signal, extra = {}) {
-    return context && typeof context === 'object'
-        ? { ...context, signal, ...extra }
-        : { signal, ...extra };
-}
-function mergeAbortSignals(callerSignal, hostSignal) {
-    if (!callerSignal || callerSignal === hostSignal)
-        return callerSignal ?? hostSignal;
-    const controller = new AbortController();
-    const abort = () => {
-        callerSignal.removeEventListener('abort', abort);
-        hostSignal.removeEventListener('abort', abort);
-        controller.abort();
-    };
-    if (callerSignal.aborted || hostSignal.aborted) {
-        controller.abort();
-        return controller.signal;
-    }
-    callerSignal.addEventListener('abort', abort, { once: true });
-    hostSignal.addEventListener('abort', abort, { once: true });
-    return controller.signal;
-}
-async function isParallelSafe(tool, params, context) {
-    const declared = tool.parallelSafe;
-    if (declared === undefined || declared === false)
-        return false;
-    if (declared === true)
-        return true;
-    try {
-        return (await declared(params, context)) === true;
-    }
-    catch {
-        return false;
-    }
-}
 const formatActionOutcome = (outcome) => outcome === 'not_applied' ? 'not applied' : outcome;
 /**
  * Host-rendered action section. Present only when at least one covered action
@@ -1007,28 +339,32 @@ const renderActionReceipts = (receipts, includeDetails = true) => {
             'they describe tool behavior, not user-request or task outcomes.',
     ].join('\n');
 };
-function renderResult(result, output, calls, receipts, includeConsole) {
+function renderResult(execution, output, includeConsole) {
     const sections = [];
-    const media = [];
-    if (!result.ok && result.error) {
-        sections.push(result.error.code === 'timeout'
-            ? `Script timed out. ${result.error.message}`
-            : result.error.code === 'deadline'
-                ? `Script exceeded its deadline. ${result.error.message}`
-                : result.error.code === 'cancelled'
-                    ? `Script was cancelled. ${result.error.message}`
-                    : `Script failed: ${result.error.message}`);
-    }
-    else if (result.voidOutput === true) {
+    const media = execution.attachments;
+    const calls = execution.calls;
+    const receipts = execution.actions;
+    if (execution.script.status === 'failed') {
+        const { code, message } = execution.script.diagnostic;
+        sections.push(code === 'timeout'
+            ? `Script timed out. ${message}`
+            : code === 'deadline'
+                ? `Script exceeded its deadline. ${message}`
+                : code === 'cancellation'
+                    ? `Script was cancelled. ${message}`
+                    : `Script failed: ${message}`);
+    }
+    else if (execution.script.voidOutput) {
         sections.push('Script returned no result. Return a value from the script to send it to the model.');
     }
     else {
-        const stripped = containsMediaContent(result.output) ? stripMediaContent(result.output, media) : result.output;
+        const value = execution.script.value;
+        const stripped = containsMediaContent(value) ? stripMediaContent(value, media) : value;
         // A top-level content-part array already has a useful text projection;
         // wrappers (Promise.all, object fields, etc.) retain their shape in JSON,
         // with media replaced by markers so base64 never leaks into text.
-        const rendered = media.length > 0 && isContentPartArray(result.output)
-            ? result.output
+        const rendered = media.length > 0 && isContentPartArray(value)
+            ? value
                 .filter((part) => part.type === 'text' && typeof part.text === 'string')
                 .map((part) => part.text)
                 .join('\n')
@@ -1038,7 +374,7 @@ function renderResult(result, output, calls, receipts, includeConsole) {
         sections.push(`Result:\n${rendered}`);
     }
     const printed = output.join('\n').trim();
-    if (printed && (!result.ok || includeConsole))
+    if (printed && (execution.script.status === 'failed' || includeConsole))
         sections.push(`Console trace (debug):\n${printed}`);
     const refused = calls.filter((call) => call.outcome === 'approval_required');
     const directlyRefused = refused.filter((call) => call.directlyCallable === true);