@dsh-cc/tools 0.5.0

package/lib/cc-names.js

@@ -0,0 +1,197 @@
+/**
+ * Claude Code → harness tool-name translation. CC-authored tool names flow
+ * into `tools.restrict()` and other name-level seams through the preset and
+ * skill-loading plugins; the harness registers its own authoritative,
+ * mostly-lowercase global tool set, and a capitalized CC name handed verbatim
+ * to `tools.restrict()` fails the whole session because restrict validates
+ * names strictly. This module owns the canonical mapping between the two
+ * vocabularies so plugins never hand-code the table.
+ * @module @dsh-cc/tools/src/cc-names
+ */
+/**
+ * The authoritative list of global tools the deepseek-harness registers,
+ * observed from its web profile. This is the universe every CC name must be
+ * translated INTO and the lenient policy uses it to distinguish a known
+ * harness name from an unknown CC name. If the harness registry changes, the
+ * {@link KNOWN_HARNESS_TOOLS} test fails loudly rather than silently drifting.
+ */
+const HARNESS_TOOLS = [
+    'EnterWorktree', 'ExitWorktree', 'NotebookEdit', 'Sleep', 'ToolSearch',
+    'ask_user_question', 'bash', 'create_goal', 'edit', 'exit_plan_mode',
+    'get_goal', 'glob', 'grep', 'interrupt_agent', 'job_kill', 'job_list',
+    'job_output', 'list_agents', 'ralph', 'read', 'read_image', 'send_message',
+    'skill', 'subagent', 'subagent_fork', 'todo_write', 'update_goal',
+    'web_fetch', 'web_search', 'workflow', 'write',
+];
+/**
+ * The exact set of authoritative harness tool names {@link KNOWN_HARNESS_TOOLS}
+ * is derived from, kept as a module-private source constant so the exported
+ * set and the reverse index in {@link ccToolAliases} share one spelling.
+ */
+const HARNESS_TOOL_NAMES = HARNESS_TOOLS;
+/**
+ * The set of global tool names the deepseek-harness registers (see
+ * {@link HARNESS_TOOLS}). The lenient translation policy uses it to pass a
+ * known harness name through untouched instead of dropping it, since such a
+ * name is already in the restrict vocabulary and needs no translation.
+ */
+export const KNOWN_HARNESS_TOOLS = new Set(HARNESS_TOOL_NAMES);
+/**
+ * Claude Code tool name → harness tool name(s). One CC tool may answer through
+ * several harness tools (e.g. `Read` covers both `read` and `read_image`), so
+ * each value is a list; an entry that has no distinct harness equivalent maps
+ * to its own capitalized form (the harness exposes it under that exact name,
+ * e.g. `NotebookEdit`).
+ *
+ * Deliberately NOT mapped (and hence rejected-or-dropped by
+ * {@link translateToolNames} depending on policy):
+ * - `LS` — legacy Claude Code alias with no harness equivalent.
+ * - `EnterPlanMode` — the harness has no plan-mode entry point (model-driven
+ *   plan mode is not a tool).
+ * - `CronCreate`/`CronDelete`/`CronList` — lifecycle utilities with no harness
+ *   equivalent in the authoritative global set.
+ * - `mcp__*` names — namespace-qualified MCP paths; the harness exposes MCP
+ *   tools under their own names, which a caller should list explicitly.
+ */
+export const CC_TO_HARNESS_TOOLS = {
+    Read: ['read', 'read_image'],
+    Write: ['write'],
+    Edit: ['edit'],
+    MultiEdit: ['edit'],
+    NotebookEdit: ['NotebookEdit'],
+    Bash: ['bash'],
+    BashOutput: ['job_output'],
+    KillBash: ['job_kill'],
+    Grep: ['grep'],
+    Glob: ['glob'],
+    WebFetch: ['web_fetch'],
+    WebSearch: ['web_search'],
+    TodoWrite: ['todo_write'],
+    Task: ['subagent', 'subagent_fork'],
+    Skill: ['skill'],
+    AskUserQuestion: ['ask_user_question'],
+    ExitPlanMode: ['exit_plan_mode'],
+    Workflow: ['workflow'],
+    Sleep: ['Sleep'],
+    ToolSearch: ['ToolSearch'],
+    EnterWorktree: ['EnterWorktree'],
+    ExitWorktree: ['ExitWorktree'],
+};
+/**
+ * Strip a trailing parenthesized argument specification from a CC name, e.g.
+ * `Bash(git status)` → `Bash` and `WebFetch(domain:example.com)` → `WebFetch`.
+ * `tools.restrict()` is name-level only, so stripping deliberately widens a
+ * name+args constraint to name-level — this is a decision, not an accident: a
+ * name-level restrict cannot honor a per-args constraint, and the alternative
+ * (keeping the arg-spec) would produce a name `tools.restrict()` rejects.
+ * @param name - the raw CC name as it appears in the tool list.
+ * @returns the name with any trailing `(...)` argument specification removed.
+ */
+function stripArgSpec(name) {
+    const paren = name.indexOf('(');
+    return paren === -1 ? name : name.slice(0, paren);
+}
+/**
+ * Translate a list of Claude Code tool names into harness tool names for a
+ * `tools.restrict()`-style name-level filter.
+ *
+ * Each entry is (optionally) stripped of its trailing arg-spec (see
+ * {@link stripArgSpec}), then translated:
+ * - A name in {@link CC_TO_HARNESS_TOOLS} expands to every mapped harness name.
+ * - Under `'strict'`, every other name passes through VERBATIM (unknown names
+ *   then fail loudly on `tools.restrict()`'s own strict validation — fail-fast
+ *   is intended at config/agent load time).
+ * - Under `'lenient'`, a name in {@link KNOWN_HARNESS_TOOLS} passes through,
+ *   and any other name is dropped with a diagnostic via `onDiagnostic`, so a
+ *   single unknown or model-invented name never kills the session.
+ *
+ * Results are deduplicated preserving first-occurrence order.
+ *
+ * @param names - the tool-name list to translate.
+ * @param policy - `'strict'` (trusted config, fail-fast) or `'lenient'` (user/model data, drop unknown).
+ * @param onDiagnostic - invoked for each dropped name (and for an empty lenient result); default no-op.
+ * @returns the translated harness-name list, or `undefined` under `'lenient'`
+ *   when every input was dropped (meaning "no restriction"). Under `'strict'`,
+ *   always returns an array — an empty input yields an empty array copy, never `undefined`.
+ */
+export function translateToolNames(names, policy, onDiagnostic = () => { }) {
+    const diagnose = onDiagnostic;
+    const results = [];
+    for (const rawName of names) {
+        const name = stripArgSpec(rawName);
+        const mapped = CC_TO_HARNESS_TOOLS[name];
+        if (mapped !== undefined) {
+            for (const harnessName of mapped) {
+                if (!results.includes(harnessName))
+                    results.push(harnessName);
+            }
+            continue;
+        }
+        if (policy === 'strict') {
+            if (!results.includes(name))
+                results.push(name);
+            continue;
+        }
+        if (KNOWN_HARNESS_TOOLS.has(name)) {
+            if (!results.includes(name))
+                results.push(name);
+            continue;
+        }
+        diagnose(`dropping unknown tool name "${name}" from CC tool list`);
+    }
+    if (policy === 'lenient') {
+        if (results.length === 0) {
+            diagnose('dropping all CC tool names — resulting tool restriction is empty');
+            return undefined;
+        }
+    }
+    return [...results];
+}
+/**
+ * The distinct names one harness tool answers to for match-time comparison
+ * (permission rules, hook matchers). Returns the input name itself plus every
+ * CC name whose mapping includes the input, derived from
+ * {@link CC_TO_HARNESS_TOOLS} via a reverse index — never a hand-written second
+ * table. When the input IS a CC name found in the map, returns the CC name
+ * first followed by its mapped harness names.
+ *
+ * Examples: `'read'` → `['read', 'Read']`; `'read_image'` → `['read_image',
+ * 'Read']`; `'bash'` → `['bash', 'Bash']`; `'edit'` → `['edit', 'Edit',
+ * 'MultiEdit']`; `'Bash'` → `['Bash', 'bash']`; `'pwsh'` → `['pwsh']`.
+ * @param name - a harness tool name or Claude Code tool name.
+ * @returns every distinct name the harness tool is matched by, input first.
+ */
+export function ccToolAliases(name) {
+    const mapped = CC_TO_HARNESS_TOOLS[name];
+    if (mapped !== undefined)
+        return [name, ...mapped];
+    const aliases = [name];
+    for (const [ccName, harnessNames] of Object.entries(CC_TO_HARNESS_TOOLS)) {
+        if (harnessNames.includes(name) && !aliases.includes(ccName))
+            aliases.push(ccName);
+    }
+    return aliases;
+}
+/**
+ * The CC canonical name for a harness tool — the first CC name in
+ * {@link CC_TO_HARNESS_TOOLS} whose mapping contains the input. This is the
+ * inverse of {@link translateToolNames} for the name-identity direction CC-facing
+ * surfaces need (hook payloads, permissions reports): a hook script written for
+ * Claude Code expects the CC spelling, not the harness's lowercase one.
+ *
+ * Examples: `'read'` → `'Read'`; `'read_image'` → `'Read'`; `'edit'` →
+ * `'Edit'`; `'subagent'` → `'Task'`; `'subagent_fork'` → `'Task'`; `'Bash'` →
+ * `'Bash'`; `'pwsh'` → `'pwsh'` (no CC alias, unchanged); `'ralph'` →
+ * `'ralph'` (harness-only, unchanged).
+ * @param name - a harness tool name (lowercase) or an already-CC canonical name.
+ * @returns the first CC name matching the input, or the input unchanged when no
+ *   CC alias exists (including when the input is itself an existing CC name).
+ */
+export function ccCanonicalToolName(name) {
+    for (const [ccName, harnessNames] of Object.entries(CC_TO_HARNESS_TOOLS)) {
+        if (harnessNames.includes(name))
+            return ccName;
+    }
+    return name;
+}
+//# sourceMappingURL=cc-names.js.map

package/lib/cc-names.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cc-names.js","sourceRoot":"","sources":["../src/cc-names.ts"],"names":[],"mappings":"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"}

package/lib/code-mode.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Code Mode `run_code` transport. Programs call the registry's agent-visible
+ * tools through nested executions scheduled under the native concurrency
+ * contract; each sub-dispatch is logged for reconstruction, while only the
+ * outer curated result enters model history.
+ * @module @dsh-cc/tools/src/code-mode
+ */
+import type { ContentBlock } from '@deepseek-ai/dsh-llm';
+import type { CodeRuntime } from '@deepseek-ai/dsh-code-runtime';
+import type { ToolRuntimeCore } from './runtime-core.ts';
+import type { CodeDispatchLog, ToolDefinition } from './index.ts';
+export { CodeRunFailedError, RUN_CODE_NAME, SDK_SECTION_ORDER } from './run-code-defs.ts';
+export type { CodeSdkLanguage } from './run-code-defs.ts';
+/**
+ * Registry-private capabilities the bridge receives at construction — the
+ * `requireRuntime` idiom: operations only the owning registry can mint stay
+ * off its public service API and flow here as closures instead.
+ */
+export interface RunCodeBridgeOptions {
+    /** Resolves `ctx.codeRuntime` or throws the loud misconfiguration error (shared with the registry's assembly-time checks). */
+    requireRuntime: () => CodeRuntime;
+    /**
+     * Reads `ctx.codeRuntime` without throwing: `undefined` when none is mounted.
+     * Lets schema emission tell "no runtime" (degrade to TS; the readers that
+     * reach it are {@link resolveFlavor}'s) apart from "unknown language" (fail
+     * loud).
+     */
+    peekRuntime: () => CodeRuntime | undefined;
+    /** The run's overlap cap for parallel-classified sub-calls (the registry passes its validated `maxParallelSubCalls`). */
+    maxParallel: number;
+    /** Runs the contained `tools/code-dispatch-log` waterfall over one settled sub-dispatch (the registry's private invoker). */
+    shapeDispatchLog: (dispatch: CodeDispatchLog) => Promise<ContentBlock[]>;
+}
+/**
+ * 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.
+ * @returns the registry-ready definition.
+ */
+export declare function createRunCodeTool(registry: ToolRuntimeCore, options: RunCodeBridgeOptions): ToolDefinition;
+//# sourceMappingURL=code-mode.d.ts.map

package/lib/code-mode.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"code-mode.d.ts","sourceRoot":"","sources":["../src/code-mode.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAA;AACxD,OAAO,KAAK,EAAsC,WAAW,EAAE,MAAM,+BAA+B,CAAA;AAMpG,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAA;AACxD,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAuC,MAAM,YAAY,CAAA;AAGtG,OAAO,EAAE,kBAAkB,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAA;AACzF,YAAY,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAA;AAKzD;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACnC,8HAA8H;IAC9H,cAAc,EAAE,MAAM,WAAW,CAAA;IACjC;;;;;OAKG;IACH,WAAW,EAAE,MAAM,WAAW,GAAG,SAAS,CAAA;IAC1C,yHAAyH;IACzH,WAAW,EAAE,MAAM,CAAA;IACnB,6HAA6H;IAC7H,gBAAgB,EAAE,CAAC,QAAQ,EAAE,eAAe,KAAK,OAAO,CAAC,YAAY,EAAE,CAAC,CAAA;CACzE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,eAAe,EAAE,OAAO,EAAE,oBAAoB,GAAG,cAAc,CA2X1G"}

package/lib/code-mode.js

@@ -0,0 +1,380 @@
+/**
+ * Code Mode `run_code` transport. Programs call the registry's agent-visible
+ * tools through nested executions scheduled under the native concurrency
+ * contract; each sub-dispatch is logged for reconstruction, while only the
+ * outer curated result enters model history.
+ * @module @dsh-cc/tools/src/code-mode
+ */
+import { CallId } from '@deepseek-ai/dsh-llm';
+import { jsonNormalizeArgs, renderValue } from "./json-render.js";
+import { CodeRunFailedError, resolveFlavor, RUN_CODE_DESCRIPTION_PARAM_DESCRIPTION, RUN_CODE_NAME, TYPESCRIPT_FLAVOR } from "./run-code-defs.js";
+import { defineTool, parameterSchemaSpecToJsonSchema } from "./schema.js";
+import { TOOL_RUNTIME_SCHEDULER } from "./scheduler.js";
+export { CodeRunFailedError, RUN_CODE_NAME, SDK_SECTION_ORDER } from "./run-code-defs.js";
+/**
+ * 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.
+ * @returns the registry-ready definition.
+ */
+export function createRunCodeTool(registry, options) {
+    const { requireRuntime, peekRuntime, maxParallel, shapeDispatchLog } = options;
+    const definition = defineTool({
+        name: RUN_CODE_NAME,
+        // The description and `code` parameter description are placeholders here:
+        // the language-aware getters installed below replace both, resolving the
+        // loaded runtime's flavor at schema-emission time so the schema the MODEL
+        // sees matches the SDK section's language. Argument VALIDATION still keys
+        // off this static spec (defineTool closes over it), which is language-
+        // independent (one required string `code`).
+        description: TYPESCRIPT_FLAVOR.description,
+        parameters: {
+            code: { type: 'string', required: true, description: TYPESCRIPT_FLAVOR.codeDescription },
+            description: {
+                type: 'string',
+                required: true,
+                description: RUN_CODE_DESCRIPTION_PARAM_DESCRIPTION,
+            },
+        },
+        output: {
+            schema: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    logs: { type: 'array', required: true, items: { type: 'string' } },
+                    result: { type: 'json' },
+                },
+            },
+            render: (_args, value) => {
+                const rendered = value.result === undefined ? '' : renderValue(value.result);
+                const parts = [value.logs.join('\n'), rendered].filter(part => part.length > 0);
+                return [{ type: 'text', text: parts.length > 0 ? parts.join('\n') : '(run_code completed with no output)' }];
+            },
+        },
+        async execute(args, exec) {
+            if (args.description.trim().length === 0) {
+                throw new Error('invalid description: expected a non-empty string');
+            }
+            const runtime = requireRuntime();
+            // 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();
+                                    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;
+                        }
+                    }
+                    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 = (name) => async (rawArgs) => {
+                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 = CallId(`${String(exec.callId)}:code:${n}`);
+                const input = {
+                    callId: subCallId,
+                    rootCallId: exec.rootCallId,
+                    name,
+                    arguments: normalized.dispatched,
+                    ...exec.agent ? { agent: exec.agent } : {},
+                    parent: exec.token,
+                    signal: runController.signal,
+                };
+                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/code-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,
+                                content: logged,
+                            });
+                        })().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/code-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);
+                            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();
+                });
+                // 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(schema.name) });
+            }
+            try {
+                let result;
+                try {
+                    result = await runtime.run({
+                        program: args.code,
+                        bindings: [{
+                                global: 'tools',
+                                functions,
+                                errorClass: { name: 'ToolCallError', memberNameProperty: 'toolName' },
+                            }],
+                        signal: runController.signal,
+                    });
+                }
+                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')}` : '';
+                    throw new CodeRunFailedError(`code run failed (${result.error.kind}): ${result.error.message}${logsText}`);
+                }
+                return {
+                    logs: result.logs,
+                    ...result.value !== undefined ? { result: result.value } : {},
+                };
+            }
+            finally {
+                exec.signal.removeEventListener('abort', onOuterAbort);
+            }
+        },
+        // The model-authored description is the call's always-visible UI label
+        // (the bash `description` precedent); the program itself rides rawInput.
+        presentCall: args => ({
+            card: 'generic',
+            title: args.description,
+            kind: 'execute',
+            rawInput: args.code,
+        }),
+        // Deliberately no presentResult: the generic card fallback keeps this
+        // title and reads durable result content without duplicating a large raw
+        // result into the host view payload.
+    });
+    // Resolve the language flavor lazily, at the moment the registry projects the
+    // schema (`schemaOf` destructures `description`/`parameters`). The definition
+    // is minted once at registration, before a runtime is known; deferring here
+    // is the least invasive point that still emits the loaded runtime's language.
+    Object.defineProperty(definition, 'description', {
+        enumerable: true,
+        get: () => resolveFlavor(peekRuntime).description,
+    });
+    Object.defineProperty(definition, 'parameters', {
+        enumerable: true,
+        // Recompile through the same spec→schema projection defineTool used, so
+        // the emitted schema always matches the validated specification.
+        get: () => parameterSchemaSpecToJsonSchema({
+            code: { type: 'string', required: true, description: resolveFlavor(peekRuntime).codeDescription },
+            description: { type: 'string', required: true, description: RUN_CODE_DESCRIPTION_PARAM_DESCRIPTION },
+        }),
+    });
+    return definition;
+}
+//# sourceMappingURL=code-mode.js.map