@qilin-agent/tools 3.1.4 → 3.1.6

package/lib/types/ptc.js

@@ -5,43 +5,37 @@
  * outer curated result enters model history.
  * @module @qilin-agent/tools/src/ptc
  */
+import { symbols } from '@qilin-agent/kylin';
 import { brandString } from '@qilin-agent/brand';
 import { createUserMessage, HarnessError } from '@qilin-agent/llm';
 import { approveEscalation, ESCALATION_TARGETS, validateEscalationArgs } from '@qilin-agent/sandbox';
 import { deepFreeze, snapshotJsonValue } from '@qilin-agent/util-values';
 import { defineTool, parameterSchemaSpecToJsonSchema } from "./schema.js";
+import { PtcCalls } from "./ptc-calls.js";
 import { TOOL_RUNTIME_SCHEDULER } from "./index.js";
 /** The model-facing name of the PTC mode tool. */
 export const RUN_CODE_NAME = 'run_code';
-/**
- * The TypeScript flavor: the fallback for a schema read with no runtime
- * mounted ({@link resolveFlavor} owns which readers reach that). A real
- * assembly always resolves a runtime first, so the model never sees this
- * fallback outside its own language.
- */
-const TYPESCRIPT_FLAVOR = {
-    description: 'Execute a TypeScript program against the available tools. Takes two required '
-        + 'arguments: `description`, a short summary of what the program does, and `code`, '
-        + 'the BODY of an async function (erasable syntax only; top-level `await` and '
-        + '`return` work). Call tools as `await tools.name(args)` per the declarations in the system '
-        + 'prompt. Only what you print or return is program output — curate it. Image-bearing '
-        + 'subtool results are attached after the run.',
+/** Keep tool-call rules here; the runtime owns evaluation syntax and state retention. */
+function runCodeFlavor(language, execution = {
+    programDescription: 'the program to execute',
+    outputInstruction: 'Curate the program output.',
+    codeDescription: `The ${language} program to execute, following this tool's execution instructions.`,
+}) {
+    return {
+        description: `Execute a ${language} program against the available tools. Takes two required arguments: `
+            + `\`description\`, a short summary of what the program does, and \`code\`, ${execution.programDescription}. `
+            + 'Call tools as `await tools.name(args)` per the declarations in the system prompt. '
+            + `${execution.outputInstruction} Image-bearing subtool results are attached after the run.`,
+        codeDescription: execution.codeDescription,
+    };
+}
+const TYPESCRIPT_FLAVOR = runCodeFlavor('TypeScript');
+const TYPESCRIPT_FUNCTION_FLAVOR = runCodeFlavor('TypeScript', {
+    programDescription: 'the BODY of an async function (erasable syntax only; top-level `await` and `return` work)',
+    outputInstruction: 'Only what you print or return is program output — curate it.',
     codeDescription: 'The program: the body of an async TypeScript function.',
-};
-/**
- * The Python flavor: the body of an async function, top-level `await` and
- * `return`, answer via `print` and/or the returned value, matching
- * {@link ./py-types.ts}'s SDK instructions.
- */
-const PYTHON_FLAVOR = {
-    description: 'Execute a Python program against the available tools. Takes two required '
-        + 'arguments: `description`, a short summary of what the program does, and `code`, '
-        + 'the BODY of an async function (top-level `await` and `return` work). Call tools as '
-        + '`await tools.name(args)` per the declarations in the system prompt. Use '
-        + '`print(...)` and/or `return <value>` for program output — curate it. Image-bearing '
-        + 'subtool results are attached after the run.',
-    codeDescription: 'The program: the body of an async Python function.',
-};
+});
+const PYTHON_FLAVOR = runCodeFlavor('Python');
 /** Per-language `run_code` schema flavors (see {@link RunCodeFlavor}); one entry per {@link PtcSdkLanguage}. */
 const RUN_CODE_FLAVORS = {
     typescript: TYPESCRIPT_FLAVOR,
@@ -111,7 +105,8 @@ function resolveFlavor(peekRuntime) {
         const known = Object.keys(RUN_CODE_FLAVORS).map(name => JSON.stringify(name)).join(', ');
         throw new Error(`qilin-tools: no run_code schema flavor registered for runtime language ${JSON.stringify(runtime.language)} (known: ${known})`);
     }
-    return flavor;
+    return runtime.language === 'typescript' && runtime.programFormat === 'function-body'
+        ? TYPESCRIPT_FUNCTION_FLAVOR : flavor;
 }
 /**
  * Thrown by `run_code` when the program run itself failed — a program
@@ -231,18 +226,21 @@ function renderValue(value) {
     return typeof value === 'string' ? value : renderJsonValue(value);
 }
 /**
- * Build the `run_code` {@link ToolDefinition}: required `description` and
- * `code` parameters, executed through the dispatch bridge described
+ * Build the `run_code` {@link ToolDefinition}: required `code` and
+ * `description` parameters, executed through the dispatch bridge described
  * above. The
  * registry reserves it as presentation infrastructure under non-native modes,
  * outside the filterable global/scoped capability layers.
  * @param registry - the owning registry (sub-calls go through its `execute`,
  *   bindings cover its registered tools).
  * @param options - the registry-private capabilities described above.
+ * @param ctx - Owning registry context, independent of the calling Agent.
  * @returns the registry-ready definition.
  */
-export function createRunCodeTool(registry, options) {
+export function createRunCodeTool(registry, options, ctx) {
     const { requireRuntime, peekRuntime, maxParallel, shapeDispatchLog } = options;
+    const stateOwners = new WeakMap();
+    const calls = new PtcCalls(ctx);
     const definition = defineTool({
         name: RUN_CODE_NAME,
         // The description and `code` parameter description are placeholders here:
@@ -294,331 +292,354 @@ export function createRunCodeTool(registry, options) {
                 throw new Error('invalid description: expected a non-empty string');
             }
             const runtime = requireRuntime();
-            validateEscalationArgs(args.sandbox_permissions, args.justification);
-            if (args.timeoutMs !== undefined && runtime.timeout === undefined) {
-                throw new Error('timeoutMs is not available for this PTC runtime');
-            }
-            if (args.timeoutMs !== undefined && (!Number.isFinite(args.timeoutMs) || args.timeoutMs <= 0)) {
-                throw new Error('invalid timeoutMs: expected a positive finite number');
-            }
-            const standingPolicy = runtime.sandboxMode === undefined ? undefined : options.resolveSandboxPolicy(exec);
-            let policy = standingPolicy;
-            if (args.sandbox_permissions !== undefined && args.justification !== undefined) {
-                if (standingPolicy === undefined)
-                    throw new Error('sandbox_permissions is not available for this PTC runtime');
-                const approvedMode = await approveEscalation({
-                    requestedMode: args.sandbox_permissions,
-                    justification: args.justification,
-                    effectiveMode: standingPolicy.mode,
-                    subject: 'program',
-                }, {
-                    approver: options.peekApprover(), agent: exec.agent, callId: exec.callId,
-                    toolName: RUN_CODE_NAME, signal: exec.signal,
-                });
-                policy = { ...standingPolicy, mode: approvedMode };
-            }
-            const cwd = await options.resolveWorkingDirectory(exec);
-            exec.signal.throwIfAborted();
-            // The run-scoped abort: follows the outer signal in, and fires when the
-            // run settles for ANY reason, so an in-flight sub-dispatch is aborted
-            // (its executor kills on this signal) instead of orphaned, and
-            // queued-unstarted dispatches are abandoned.
-            const runController = new AbortController();
-            const onOuterAbort = () => { runController.abort(exec.signal.reason); };
-            exec.signal.addEventListener('abort', onOuterAbort, { once: true });
-            let dispatches = 0;
-            const pendingQueue = [];
-            const inFlight = new Set();
-            /** Tracked settle-event side work (log-content listener + append), drained at run settlement. */
-            const logWork = new Set();
-            const commitQueue = [];
-            let exclusiveActive = false;
-            let driving = false;
-            let driverRun = Promise.resolve();
-            let wake;
-            const wakeup = () => {
-                const release = wake;
-                wake = undefined;
-                release?.();
-            };
-            /**
-             * The single ordered lane. Each pass commits the head-of-line settled
-             * dispatch (ordered post-execute), then starts the next queued entry if
-             * its slot is free (ordered pre-execute), and otherwise sleeps until a
-             * body settles or a new submission arrives. One run reaching the
-             * empty-queues/empty-pool state is quiescence.
-             */
-            const drive = () => {
-                if (driving)
-                    return driverRun;
-                driving = true;
-                driverRun = (async () => {
-                    try {
-                        for (;;) {
-                            // Create the wakeup promise before inspecting state so a settle or submission arriving
-                            // between the checks and the await below cannot be lost.
-                            const signal = new Promise((resolve) => { wake = resolve; });
-                            const commitHead = commitQueue[0];
-                            if (commitHead !== undefined && commitHead.settled) {
-                                commitQueue.shift();
-                                await commitHead.commit();
-                                // The barrier covers post-execute: later starts wait for the
-                                // exclusive call's full pipeline, as under the native loop.
-                                if (commitHead.mode === 'exclusive')
-                                    exclusiveActive = false;
-                                continue;
-                            }
-                            const head = pendingQueue[0];
-                            if (head !== undefined) {
-                                if (runController.signal.aborted) {
-                                    pendingQueue.shift();
-                                    head.abandon();
+            const run = async (callSignal) => {
+                validateEscalationArgs(args.sandbox_permissions, args.justification);
+                if (args.timeoutMs !== undefined && runtime.timeout === undefined) {
+                    throw new Error('timeoutMs is not available for this PTC runtime');
+                }
+                if (args.timeoutMs !== undefined && (!Number.isFinite(args.timeoutMs) || args.timeoutMs <= 0)) {
+                    throw new Error('invalid timeoutMs: expected a positive finite number');
+                }
+                const standingPolicy = runtime.sandboxMode === undefined ? undefined : options.resolveSandboxPolicy(exec);
+                let policy = standingPolicy;
+                if (args.sandbox_permissions !== undefined && args.justification !== undefined) {
+                    if (standingPolicy === undefined)
+                        throw new Error('sandbox_permissions is not available for this PTC runtime');
+                    const approvedMode = await approveEscalation({
+                        requestedMode: args.sandbox_permissions,
+                        justification: args.justification,
+                        effectiveMode: standingPolicy.mode,
+                        subject: 'program',
+                    }, {
+                        approver: options.peekApprover(), agent: exec.agent, callId: exec.callId,
+                        toolName: RUN_CODE_NAME, signal: callSignal,
+                    });
+                    policy = { ...standingPolicy, mode: approvedMode };
+                }
+                const cwd = await options.resolveWorkingDirectory({ ...exec, signal: callSignal });
+                callSignal.throwIfAborted();
+                // The run-scoped abort: follows the outer signal in, and fires when the
+                // run settles for ANY reason, so an in-flight sub-dispatch is aborted
+                // (its executor kills on this signal) instead of orphaned, and
+                // queued-unstarted dispatches are abandoned.
+                const runController = new AbortController();
+                const onOuterAbort = () => { runController.abort(callSignal.reason); };
+                callSignal.addEventListener('abort', onOuterAbort, { once: true });
+                let dispatches = 0;
+                const pendingQueue = [];
+                const inFlight = new Set();
+                /** Tracked settle-event side work (log-content listener + append), drained at run settlement. */
+                const logWork = new Set();
+                const commitQueue = [];
+                let exclusiveActive = false;
+                let driving = false;
+                let driverRun = Promise.resolve();
+                let wake;
+                const wakeup = () => {
+                    const release = wake;
+                    wake = undefined;
+                    release?.();
+                };
+                /**
+                 * The single ordered lane. Each pass commits the head-of-line settled
+                 * dispatch (ordered post-execute), then starts the next queued entry if
+                 * its slot is free (ordered pre-execute), and otherwise sleeps until a
+                 * body settles or a new submission arrives. One run reaching the
+                 * empty-queues/empty-pool state is quiescence.
+                 */
+                const drive = () => {
+                    if (driving)
+                        return driverRun;
+                    driving = true;
+                    driverRun = (async () => {
+                        try {
+                            for (;;) {
+                                // Create the wakeup promise before inspecting state so a settle or submission arriving
+                                // between the checks and the await below cannot be lost.
+                                const signal = new Promise((resolve) => { wake = resolve; });
+                                const commitHead = commitQueue[0];
+                                if (commitHead !== undefined && commitHead.settled) {
+                                    commitQueue.shift();
+                                    await commitHead.commit();
+                                    // The barrier covers post-execute: later starts wait for the
+                                    // exclusive call's full pipeline, as under the native loop.
+                                    if (commitHead.mode === 'exclusive')
+                                        exclusiveActive = false;
                                     continue;
                                 }
-                                // Reclassify at start time (fail-closed on registry changes).
-                                const mode = head.classify();
-                                const capacity = !exclusiveActive
-                                    && (mode === 'exclusive' ? inFlight.size === 0 : inFlight.size < maxParallel);
-                                if (capacity) {
-                                    if (mode === 'exclusive')
-                                        exclusiveActive = true;
-                                    head.mode = mode;
-                                    pendingQueue.shift();
-                                    // Joined before start() so the commit cursor sees submission
-                                    // order; nothing commits it until `settled` flips.
-                                    commitQueue.push(head);
-                                    await head.start();
-                                    const flight = head.flight.finally(() => {
-                                        inFlight.delete(flight);
-                                        wakeup();
-                                    });
-                                    inFlight.add(flight);
-                                    continue;
+                                const head = pendingQueue[0];
+                                if (head !== undefined) {
+                                    if (runController.signal.aborted) {
+                                        pendingQueue.shift();
+                                        head.abandon();
+                                        continue;
+                                    }
+                                    // Reclassify at start time (fail-closed on registry changes).
+                                    const mode = head.classify();
+                                    const capacity = !exclusiveActive
+                                        && (mode === 'exclusive' ? inFlight.size === 0 : inFlight.size < maxParallel);
+                                    if (capacity) {
+                                        if (mode === 'exclusive')
+                                            exclusiveActive = true;
+                                        head.mode = mode;
+                                        pendingQueue.shift();
+                                        // Joined before start() so the commit cursor sees submission
+                                        // order; nothing commits it until `settled` flips.
+                                        commitQueue.push(head);
+                                        await head.start();
+                                        const flight = head.flight.finally(() => {
+                                            inFlight.delete(flight);
+                                            wakeup();
+                                        });
+                                        inFlight.add(flight);
+                                        continue;
+                                    }
                                 }
+                                if (pendingQueue.length === 0 && commitQueue.length === 0 && inFlight.size === 0)
+                                    return;
+                                await signal;
                             }
-                            if (pendingQueue.length === 0 && commitQueue.length === 0 && inFlight.size === 0)
-                                return;
-                            await signal;
                         }
-                    }
-                    finally {
-                        driving = false;
-                        wake = undefined;
-                    }
-                })();
-                return driverRun;
-            };
-            /** Every dispatch settled AND committed; nothing can start (the run is aborted at call time). */
-            const drainDispatches = async () => {
-                // The abort already fired: the driver abandons queued-unstarted
-                // entries, awaits the live pool, and drains the ordered commit lane —
-                // including a commit already in progress when the program returned.
-                await drive();
-                // Every settle event is appended inside the open run_code turn
-                // (tasks self-remove on settlement).
-                while (logWork.size > 0)
-                    await Promise.allSettled([...logWork]);
-            };
-            // Read through a call, not a bare property: the abort state genuinely
-            // changes across awaits, and a direct `.aborted` re-check after one
-            // would be narrowed away by control flow analysis.
-            const runOver = () => runController.signal.aborted;
-            const binding = (schema) => async (rawArgs) => {
-                const { name } = schema;
-                if (runOver()) {
-                    throw new Error(`run_code run is over (${String(runController.signal.reason)}); ${name} not dispatched`);
-                }
-                const normalized = jsonNormalizeArgs(rawArgs);
-                const n = ++dispatches;
-                const subCallId = brandString(`${String(exec.callId)}:ptc:${n}`);
-                const input = {
-                    callId: subCallId,
-                    rootCallId: exec.rootCallId,
-                    name,
-                    schema,
-                    arguments: normalized.dispatched,
-                    ...exec.agent ? { agent: exec.agent } : {},
-                    parent: exec.token,
-                    signal: runController.signal,
+                        finally {
+                            driving = false;
+                            wake = undefined;
+                        }
+                    })();
+                    return driverRun;
+                };
+                /** Every dispatch settled AND committed; nothing can start (the run is aborted at call time). */
+                const drainDispatches = async () => {
+                    // The abort already fired: the driver abandons queued-unstarted
+                    // entries, awaits the live pool, and drains the ordered commit lane —
+                    // including a commit already in progress when the program returned.
+                    await drive();
+                    // Every settle event is appended inside the open run_code turn
+                    // (tasks self-remove on settlement).
+                    while (logWork.size > 0)
+                        await Promise.allSettled([...logWork]);
                 };
-                const scheduler = registry[TOOL_RUNTIME_SCHEDULER];
-                const outcome = await new Promise((resolve, reject) => {
-                    // Set by the dispatch stage (or start() for a pre-settled result): what commit() finalizes in submission order.
-                    let parked;
-                    const settle = (result) => {
-                        // The program gets its value NOW: the log-content listener (for
-                        // example, a spill backend) must never delay the binding or occupy
-                        // a dispatch slot. The event append is tracked side work; the run's
-                        // settlement drains logWork so every settle event is still appended
-                        // inside the open turn (shapeDispatchLog is contained, so this
-                        // chain cannot reject).
-                        resolve(result.isError
-                            ? { isError: true, message: result.error.message }
-                            : { isError: false, value: result.value });
-                        const agent = exec.agent;
-                        if (agent === undefined)
-                            return;
-                        const task = (async () => {
-                            // The listener may replace the durable copy with a preview and
-                            // locator; the program's value and model-visible result are
-                            // untouched.
-                            const logged = await shapeDispatchLog({
-                                exec, agent, subCallId, name, isError: result.isError,
-                                // The registry deep-froze this projection at result
-                                // finalization; append snapshots the final copy again, so
-                                // the log stays detached.
-                                content: result.content,
-                            });
-                            agent.session.append('tool/ptc-dispatch', {
-                                rootCallId: exec.rootCallId,
-                                parentCallId: exec.callId,
-                                subCallId,
-                                name,
-                                // The SIBLING parse of the dispatched value: byte-identical JSON,
-                                // but a separate object — a tool mutating its args cannot desync
-                                // this record from what it actually received.
-                                arguments: normalized.logged,
-                                isError: result.isError,
-                                ...result.error?.info === undefined ? {} : { error: result.error.info },
-                                content: logged,
-                                ...result.meta === undefined ? {} : { meta: result.meta },
-                            });
-                        })().finally(() => { logWork.delete(task); });
-                        logWork.add(task);
+                // Read through a call, not a bare property: the abort state genuinely
+                // changes across awaits, and a direct `.aborted` re-check after one
+                // would be narrowed away by control flow analysis.
+                const runOver = () => runController.signal.aborted;
+                const binding = (schema) => async (rawArgs) => {
+                    const { name } = schema;
+                    if (runOver()) {
+                        throw new Error(`run_code run is over (${String(runController.signal.reason)}); ${name} not dispatched`);
+                    }
+                    const normalized = jsonNormalizeArgs(rawArgs);
+                    const n = ++dispatches;
+                    const subCallId = brandString(`${String(exec.callId)}:ptc:${n}`);
+                    const input = {
+                        callId: subCallId,
+                        rootCallId: exec.rootCallId,
+                        name,
+                        schema,
+                        arguments: normalized.dispatched,
+                        ...exec.agent ? { agent: exec.agent } : {},
+                        parent: exec.token,
+                        signal: runController.signal,
                     };
-                    pendingQueue.push({
-                        flight: Promise.resolve(),
-                        settled: false,
-                        // Re-read per driver pass against the same agent view the SDK
-                        // declared; fail-closed exclusive when undeclared/invalid.
-                        classify: () => registry.executionMode(input).kind,
-                        abandon: () => {
-                            reject(new Error(`run_code run is over (${String(runController.signal.reason)}); ${name} tool call abandoned`));
-                        },
-                        async start() {
-                            exec.agent?.session.append('tool/ptc-dispatch-start', {
-                                rootCallId: exec.rootCallId,
-                                parentCallId: exec.callId,
-                                subCallId,
-                                name,
-                                arguments: normalized.logged,
-                            });
-                            // Ordered prepare runs INSIDE the driver lane: the next entry's
-                            // pre-execute waits for this resolution, as under the native
-                            // scheduler. Only the launched body below overlaps.
-                            const prepared = await scheduler.prepare(input);
-                            if (prepared.kind === 'dispatch') {
-                                this.flight = scheduler.dispatch(prepared.exec).then((dispatchOutcome) => {
-                                    parked = { kind: dispatchOutcome.kind, exec: prepared.exec, result: dispatchOutcome.result };
-                                    this.settled = true;
-                                });
-                                return;
-                            }
-                            parked = { kind: prepared.kind, exec: prepared.exec, result: prepared.result };
-                            this.settled = true;
-                        },
-                        async commit() {
-                            /* v8 ignore next -- commit() runs only after `settled` flipped, which set parked. */
-                            if (parked === undefined)
+                    const scheduler = registry[TOOL_RUNTIME_SCHEDULER];
+                    const outcome = await new Promise((resolve, reject) => {
+                        // Set by the dispatch stage (or start() for a pre-settled result): what commit() finalizes in submission order.
+                        let parked;
+                        const settle = (result) => {
+                            // The program gets its value NOW: the log-content listener (for
+                            // example, a spill backend) must never delay the binding or occupy
+                            // a dispatch slot. The event append is tracked side work; the run's
+                            // settlement drains logWork so every settle event is still appended
+                            // inside the open turn (shapeDispatchLog is contained, so this
+                            // chain cannot reject).
+                            resolve(result.isError
+                                ? { isError: true, message: result.error.message }
+                                : { isError: false, value: result.value });
+                            const agent = exec.agent;
+                            if (agent === undefined)
                                 return;
-                            const result = parked.kind === 'post-result'
-                                ? await scheduler.finalize(parked.exec, parked.result)
-                                : scheduler.finish(parked.exec, parked.result);
-                            if (!result.isError && result.content.some(block => block.type === 'image')) {
-                                exec.deferContext(createUserMessage({
+                            const task = (async () => {
+                                // The listener may replace the durable copy with a preview and
+                                // locator; the program's value and model-visible result are
+                                // untouched.
+                                const logged = await shapeDispatchLog({
+                                    exec, agent, subCallId, name, isError: result.isError,
+                                    // The registry deep-froze this projection at result
+                                    // finalization; append snapshots the final copy again, so
+                                    // the log stays detached.
                                     content: result.content,
-                                    source: { kind: 'ptc-mode' },
-                                }));
-                            }
-                            for (const context of result.additionalContexts ?? []) {
-                                exec.deferContext(context);
-                            }
-                            // The composite forwards `additionalContexts` above and
-                            // `concludesTurn` here from the nested result. Only a successful
-                            // nested result can carry the terminal marker
-                            // (ToolExecutionFailure types it never), so a policy-converted
-                            // failure cannot stop the turn through a recovering program.
-                            if (result.concludesTurn)
-                                exec.concludeTurn();
-                            settle(result);
-                            // Backpressure on pending event-append tasks: each task retains
-                            // a full result while a slow backend stores it, so the pool cap
-                            // bounds their count. Beyond the cap, the
-                            // ordered lane waits, so later sub-calls cannot start and
-                            // pending I/O/memory cannot grow without bound.
-                            while (logWork.size > maxParallel)
-                                await Promise.race(logWork);
-                        },
+                                });
+                                agent.session.append('tool/ptc-dispatch', {
+                                    rootCallId: exec.rootCallId,
+                                    parentCallId: exec.callId,
+                                    subCallId,
+                                    name,
+                                    // The SIBLING parse of the dispatched value: byte-identical JSON,
+                                    // but a separate object — a tool mutating its args cannot desync
+                                    // this record from what it actually received.
+                                    arguments: normalized.logged,
+                                    isError: result.isError,
+                                    ...result.error?.info === undefined ? {} : { error: result.error.info },
+                                    content: logged,
+                                    ...result.meta === undefined ? {} : { meta: result.meta },
+                                });
+                            })().finally(() => { logWork.delete(task); });
+                            logWork.add(task);
+                        };
+                        pendingQueue.push({
+                            flight: Promise.resolve(),
+                            settled: false,
+                            // Re-read per driver pass against the same agent view the SDK
+                            // declared; fail-closed exclusive when undeclared/invalid.
+                            classify: () => registry.executionMode(input).kind,
+                            abandon: () => {
+                                reject(new Error(`run_code run is over (${String(runController.signal.reason)}); ${name} tool call abandoned`));
+                            },
+                            async start() {
+                                exec.agent?.session.append('tool/ptc-dispatch-start', {
+                                    rootCallId: exec.rootCallId,
+                                    parentCallId: exec.callId,
+                                    subCallId,
+                                    name,
+                                    arguments: normalized.logged,
+                                });
+                                // Ordered prepare runs INSIDE the driver lane: the next entry's
+                                // pre-execute waits for this resolution, as under the native
+                                // scheduler. Only the launched body below overlaps.
+                                const prepared = await scheduler.prepare(input);
+                                if (prepared.kind === 'dispatch') {
+                                    this.flight = scheduler.dispatch(prepared.exec).then((dispatchOutcome) => {
+                                        parked = { kind: dispatchOutcome.kind, exec: prepared.exec, result: dispatchOutcome.result };
+                                        this.settled = true;
+                                    });
+                                    return;
+                                }
+                                parked = { kind: prepared.kind, exec: prepared.exec, result: prepared.result };
+                                this.settled = true;
+                            },
+                            async commit() {
+                                /* v8 ignore next -- commit() runs only after `settled` flipped, which set parked. */
+                                if (parked === undefined)
+                                    return;
+                                const result = parked.kind === 'post-result'
+                                    ? await scheduler.finalize(parked.exec, parked.result)
+                                    : scheduler.finish(parked.exec, parked.result);
+                                if (!result.isError && result.content.some(block => block.type === 'image')) {
+                                    exec.deferContext(createUserMessage({
+                                        content: result.content,
+                                        source: { kind: 'ptc-mode' },
+                                    }));
+                                }
+                                for (const context of result.additionalContexts ?? []) {
+                                    exec.deferContext(context);
+                                }
+                                // The composite forwards `additionalContexts` above and
+                                // `concludesTurn` here from the nested result. Only a successful
+                                // nested result can carry the terminal marker
+                                // (ToolExecutionFailure types it never), so a policy-converted
+                                // failure cannot stop the turn through a recovering program.
+                                if (result.concludesTurn)
+                                    exec.concludeTurn();
+                                settle(result);
+                                // Backpressure on pending event-append tasks: each task retains
+                                // a full result while a slow backend stores it, so the pool cap
+                                // bounds their count. Beyond the cap, the
+                                // ordered lane waits, so later sub-calls cannot start and
+                                // pending I/O/memory cannot grow without bound.
+                                while (logWork.size > maxParallel)
+                                    await Promise.race(logWork);
+                            },
+                        });
+                        wakeup();
+                        void drive();
                     });
-                    wakeup();
-                    void drive();
-                });
-                // A budget expiry or outer cancel that occurs while this call was in
-                // flight already aborted the dispatch; stop the program now rather
-                // than hand it a result from a run that is over.
-                if (runOver()) {
-                    throw new Error(`run_code run is over (${String(runController.signal.reason)}); ${name} result discarded`);
+                    // A budget expiry or outer cancel that occurs while this call was in
+                    // flight already aborted the dispatch; stop the program now rather
+                    // than hand it a result from a run that is over.
+                    if (runOver()) {
+                        throw new Error(`run_code run is over (${String(runController.signal.reason)}); ${name} result discarded`);
+                    }
+                    // The worker turns a binding rejection into ToolCallError and adds
+                    // only the binding name. Native content and internal error metadata
+                    // stay outside the program-facing failure contract.
+                    if (outcome.isError)
+                        throw new Error(outcome.message);
+                    return outcome.value;
+                };
+                // Null-prototype + defineProperty, mirroring the worker-side namespace
+                // build: a registered tool named `__proto__` must become an ordinary
+                // own key (a plain-object assignment would hit the prototype setter,
+                // silently dropping the binding), and the runtime host resolves
+                // binding names as own properties only.
+                const functions = Object.create(null);
+                // Enumerate the CALLING AGENT's visible set (scoped tools join,
+                // restricted globals vanish) — the same view the SDK section declared,
+                // so a program can bind exactly what its prompt promised; sub-dispatch
+                // re-resolves per call through the same view (exec.agent threads down).
+                for (const schema of registry.schemas(exec.agent)) {
+                    if (schema.name === RUN_CODE_NAME)
+                        continue;
+                    Object.defineProperty(functions, schema.name, { enumerable: true, value: binding(deepFreeze(schema)) });
                 }
-                // The worker turns a binding rejection into ToolCallError and adds
-                // only the binding name. Native content and internal error metadata
-                // stay outside the program-facing failure contract.
-                if (outcome.isError)
-                    throw new Error(outcome.message);
-                return outcome.value;
-            };
-            // Null-prototype + defineProperty, mirroring the worker-side namespace
-            // build: a registered tool named `__proto__` must become an ordinary
-            // own key (a plain-object assignment would hit the prototype setter,
-            // silently dropping the binding), and the runtime host resolves
-            // binding names as own properties only.
-            const functions = Object.create(null);
-            // Enumerate the CALLING AGENT's visible set (scoped tools join,
-            // restricted globals vanish) — the same view the SDK section declared,
-            // so a program can bind exactly what its prompt promised; sub-dispatch
-            // re-resolves per call through the same view (exec.agent threads down).
-            for (const schema of registry.schemas(exec.agent)) {
-                if (schema.name === RUN_CODE_NAME)
-                    continue;
-                Object.defineProperty(functions, schema.name, { enumerable: true, value: binding(deepFreeze(schema)) });
-            }
-            try {
-                let result;
                 try {
-                    result = await runtime.run(runtime.resolve({
-                        program: args.code,
-                        bindings: [{
-                                global: 'tools',
-                                functions,
-                                errorClass: { name: 'ToolCallError', memberNameProperty: 'toolName' },
-                            }],
-                        signal: runController.signal,
-                        ...cwd !== undefined ? { cwd } : {},
-                        ...policy !== undefined ? { sandboxPolicy: policy } : {},
-                        ...args.timeoutMs !== undefined ? { timeoutMs: args.timeoutMs } : {},
-                    }));
+                    let result;
+                    try {
+                        if (exec.agent !== undefined) {
+                            const agent = exec.agent;
+                            let runtimes = stateOwners.get(agent);
+                            if (runtimes === undefined)
+                                stateOwners.set(agent, runtimes = new WeakSet());
+                            // Cordis can wrap service returns repeatedly; cleanup belongs to the original provider.
+                            let provider = runtime;
+                            for (;;) {
+                                const original = provider[symbols.original];
+                                if (original === undefined)
+                                    break;
+                                provider = original;
+                            }
+                            if (!runtimes.has(provider)) {
+                                agent.ctx.effect(() => () => runtime.release(agent), 'PTC retained environment');
+                                runtimes.add(provider);
+                            }
+                        }
+                        result = await runtime.run(runtime.resolve({
+                            program: args.code,
+                            ...exec.agent === undefined || policy?.mode !== standingPolicy?.mode ? {} : { stateOwner: exec.agent },
+                            bindings: [{
+                                    global: 'tools',
+                                    functions,
+                                    errorClass: { name: 'ToolCallError', memberNameProperty: 'toolName' },
+                                }],
+                            signal: runController.signal,
+                            ...cwd !== undefined ? { cwd } : {},
+                            ...policy !== undefined ? { sandboxPolicy: policy } : {},
+                            ...args.timeoutMs !== undefined ? { timeoutMs: args.timeoutMs } : {},
+                        }));
+                    }
+                    finally {
+                        // Abort sub-dispatches and drain every in-flight dispatch before
+                        // closing the turn (queued-unstarted ones are abandoned unlogged).
+                        // Binding failures remain observable through their individual promises.
+                        runController.abort('run_code settled');
+                        await drainDispatches();
+                    }
+                    if (result.error) {
+                        const logsText = result.logs.length > 0 ? `\nCaptured output:\n${result.logs.join('\n')}` : '';
+                        const sandboxText = result.sandbox === undefined ? ''
+                            : `\nFile sandbox: ${result.sandbox.mode}${result.sandbox.enforcement === undefined ? '' : `; enforcement: ${result.sandbox.enforcement}`}${result.sandbox.denied ? '; operation denied' : ''}.`;
+                        throw new CodeRunFailedError(`code run failed (${result.error.kind}): ${result.error.message}${logsText}${sandboxText}${result.sandbox?.denied ? escalationGuidance(runtime) : ''}`);
+                    }
+                    return {
+                        logs: result.logs,
+                        ...result.sandbox === undefined ? {} : { sandbox: result.sandbox },
+                        ...result.value !== undefined ? { result: result.value } : {},
+                    };
                 }
                 finally {
-                    // Abort sub-dispatches and drain every in-flight dispatch before
-                    // closing the turn (queued-unstarted ones are abandoned unlogged).
-                    // Binding failures remain observable through their individual promises.
-                    runController.abort('run_code settled');
-                    await drainDispatches();
-                }
-                if (result.error) {
-                    const logsText = result.logs.length > 0 ? `\nCaptured output:\n${result.logs.join('\n')}` : '';
-                    const sandboxText = result.sandbox === undefined ? ''
-                        : `\nFile sandbox: ${result.sandbox.mode}${result.sandbox.enforcement === undefined ? '' : `; enforcement: ${result.sandbox.enforcement}`}${result.sandbox.denied ? '; operation denied' : ''}.`;
-                    throw new CodeRunFailedError(`code run failed (${result.error.kind}): ${result.error.message}${logsText}${sandboxText}${result.sandbox?.denied ? escalationGuidance(runtime) : ''}`);
+                    callSignal.removeEventListener('abort', onOuterAbort);
                 }
-                return {
-                    logs: result.logs,
-                    ...result.sandbox === undefined ? {} : { sandbox: result.sandbox },
-                    ...result.value !== undefined ? { result: result.value } : {},
-                };
-            }
-            finally {
-                exec.signal.removeEventListener('abort', onOuterAbort);
-            }
+            };
+            return runtime.sandboxMode === undefined || exec.agent === undefined ? run(exec.signal)
+                : calls.run(exec.agent.session.id, exec.signal, () => options.resolveSandboxPolicy(exec).mode, run);
         },
         // The model-authored description is the call's always-visible UI label
         // (the bash `description` precedent); the program itself rides rawInput.