@myagentroam/agent 0.9.136 → 0.9.138

package/dist/tools/code-mode/cells.js

@@ -0,0 +1,250 @@
+import { randomUUID } from 'node:crypto';
+import { MarAgentError, describeMarAgentError } from '../../error.js';
+import { TOOL_EXECUTION_LIMITS as limits } from '../execution-limits.js';
+import { truncateModelText } from '../../runtime/token-budget.js';
+function options(value, wait) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new MarAgentError('MAR_AGENT_TOOL_INPUT_INVALID', 'Code Exec options must be an object.');
+    const input = value;
+    const keys = wait
+        ? ['cellId', 'yieldMs', 'maxOutputTokens', 'action']
+        : ['yieldMs', 'maxOutputTokens'];
+    if (Object.keys(input).some((key) => !keys.includes(key)))
+        throw new MarAgentError('MAR_AGENT_TOOL_INPUT_INVALID', 'Unknown Code Exec option.');
+    const yieldMs = input.yieldMs ?? limits.codeDefaultYieldMs;
+    const maxOutputTokens = input.maxOutputTokens ?? limits.codeMaxOutputTokens;
+    if (!Number.isSafeInteger(yieldMs) ||
+        Number(yieldMs) < 0 ||
+        Number(yieldMs) > limits.codeMaxYieldMs ||
+        !Number.isSafeInteger(maxOutputTokens) ||
+        Number(maxOutputTokens) < 1 ||
+        Number(maxOutputTokens) > limits.codeMaxOutputTokens ||
+        (wait && (typeof input.cellId !== 'string' || !input.cellId)) ||
+        (input.action !== undefined && input.action !== 'poll' && input.action !== 'cancel'))
+        throw new MarAgentError('MAR_AGENT_TOOL_INPUT_INVALID', 'Code Exec options are out of range.');
+    return {
+        cellId: input.cellId,
+        yieldMs: Number(yieldMs),
+        maxOutputTokens: Number(maxOutputTokens),
+        action: input.action ?? 'poll'
+    };
+}
+/** Session-owned execution, separate from the cancellable model-tool wait. */
+export class CodeCells {
+    #cells = new Map();
+    #closed = false;
+    #disposing = new Set();
+    async start(value, context, run) {
+        const source = typeof value === 'string'
+            ? value
+            : value &&
+                typeof value === 'object' &&
+                !Array.isArray(value) &&
+                Object.keys(value).length === 1 &&
+                'code' in value
+                ? value.code
+                : undefined;
+        if (typeof source !== 'string' ||
+            !source.trim() ||
+            Buffer.byteLength(source) > limits.codeMaxInputBytes)
+            throw new MarAgentError('MAR_AGENT_TOOL_INPUT_INVALID', 'Code must be a nonempty bounded JavaScript string.');
+        let settings = options({}, false);
+        const pragma = /^\/\/ @options:\s*([^\r\n]*)(?:\r?\n|$)/u.exec(source);
+        if (pragma) {
+            try {
+                settings = options(JSON.parse(pragma[1]), false);
+            }
+            catch (error) {
+                if (error instanceof MarAgentError)
+                    throw error;
+                throw new MarAgentError('MAR_AGENT_TOOL_INPUT_INVALID', 'Code Exec options must be valid JSON.');
+            }
+        }
+        context.signal.throwIfAborted();
+        if (this.#closed || this.#disposing.has(context.sessionId))
+            throw new MarAgentError('MAR_AGENT_CODE_CANCELLED', 'Code Exec resources are being released.');
+        if ([...this.#cells.values()].filter((cell) => cell.status === 'running').length >=
+            limits.codeMaxConcurrentCells)
+            throw new MarAgentError('MAR_AGENT_PROCESS_LIMIT', 'The Code Exec cell limit was reached.');
+        const controller = new AbortController();
+        const cell = {
+            cellId: randomUUID(),
+            sessionId: context.sessionId,
+            executionId: context.executionId,
+            controller,
+            status: 'running',
+            text: [],
+            images: [],
+            yielded: false,
+            listeners: new Set(),
+            done: Promise.resolve()
+        };
+        this.#cells.set(cell.cellId, cell);
+        const notify = () => {
+            for (const listener of cell.listeners)
+                listener();
+        };
+        let releaseSession;
+        let outcome = 'running';
+        cell.done = Promise.resolve()
+            .then(async () => {
+            releaseSession = await context.codeMode?.retainSession?.();
+            return run(source, { ...context, signal: controller.signal }, {
+                text: (text) => cell.text.push(text),
+                image: (image) => cell.images.push(image),
+                yield: () => {
+                    cell.yielded = true;
+                    notify();
+                }
+            });
+        })
+            .then((result) => {
+            cell.result = {
+                content: '',
+                ...(result.data === undefined ? {} : { data: result.data })
+            };
+            outcome = 'completed';
+        }, (error) => {
+            cell.error = error;
+            outcome = controller.signal.aborted ? 'cancelled' : 'failed';
+        })
+            .then(async () => {
+            try {
+                await context.codeMode?.onSettled?.({ cellId: cell.cellId, status: outcome });
+            }
+            catch (error) {
+                cell.error = error;
+                outcome = 'failed';
+            }
+            try {
+                await releaseSession?.();
+            }
+            catch (error) {
+                cell.error = error;
+                outcome = 'failed';
+            }
+            cell.status = outcome;
+            // Terminal capacity follows completion order, not the original start order.
+            this.#cells.delete(cell.cellId);
+            this.#cells.set(cell.cellId, cell);
+            cell.retention = setTimeout(() => this.#cells.delete(cell.cellId), limits.codeCompletedRetentionMs);
+            cell.retention.unref();
+            const completed = [...this.#cells.values()].filter((entry) => entry.sessionId === cell.sessionId && entry.status !== 'running');
+            for (const entry of completed.slice(0, Math.max(0, completed.length - limits.codeMaxCompletedResults))) {
+                clearTimeout(entry.retention);
+                this.#cells.delete(entry.cellId);
+            }
+            notify();
+        });
+        return this.#wait(cell, settings, context.signal, true, context.codeMode?.supportsImages === true);
+    }
+    async wait(value, context) {
+        const input = options(value, true);
+        context.signal.throwIfAborted();
+        const cell = this.#cells.get(input.cellId);
+        if (!cell || cell.sessionId !== context.sessionId)
+            throw new MarAgentError('MAR_AGENT_CODE_CELL_NOT_FOUND', 'Code Exec cell is unavailable in this Session.');
+        if (input.action === 'cancel' && cell.status === 'running') {
+            cell.controller.abort(new MarAgentError('MAR_AGENT_CODE_CANCELLED', 'Code Exec cell was terminated.'));
+            await new Promise((resolve, reject) => {
+                const abort = () => reject(context.signal.reason);
+                context.signal.addEventListener('abort', abort, { once: true });
+                void cell.done.then(() => {
+                    context.signal.removeEventListener('abort', abort);
+                    resolve();
+                });
+                if (context.signal.aborted)
+                    abort();
+            });
+        }
+        return this.#wait(cell, input, context.signal, false, context.codeMode?.supportsImages === true);
+    }
+    async #wait(cell, input, signal, initial, supportsImages) {
+        if (cell.status === 'running' && !cell.yielded) {
+            await new Promise((resolve, reject) => {
+                const finish = () => {
+                    clearTimeout(timer);
+                    cell.listeners.delete(finish);
+                    signal.removeEventListener('abort', abort);
+                    resolve();
+                };
+                const abort = () => {
+                    clearTimeout(timer);
+                    cell.listeners.delete(finish);
+                    signal.removeEventListener('abort', abort);
+                    reject(signal.reason);
+                };
+                const timer = setTimeout(finish, input.yieldMs);
+                cell.listeners.add(finish);
+                signal.addEventListener('abort', abort, { once: true });
+                if (signal.aborted)
+                    abort();
+            });
+        }
+        signal.throwIfAborted();
+        if (!supportsImages && (cell.images.length || cell.terminal?.images?.length))
+            throw new MarAgentError('MAR_AGENT_INPUT_CAPABILITY_UNSUPPORTED', 'The current model cannot receive this cell image output.');
+        if (cell.terminal) {
+            const snapshot = cell.terminal.data;
+            const bounded = truncateModelText(snapshot.output, input.maxOutputTokens);
+            const data = { ...snapshot, output: bounded.content, cached: true };
+            return {
+                ...cell.terminal,
+                data,
+                content: JSON.stringify(data),
+                truncated: cell.terminal.truncated || bounded.truncated
+            };
+        }
+        const text = cell.text.splice(0).join('\n');
+        const images = cell.images.splice(0);
+        cell.yielded = false;
+        const bounded = truncateModelText(text, input.maxOutputTokens);
+        const error = cell.error === undefined
+            ? undefined
+            : describeMarAgentError(cell.error, 'MAR_AGENT_CODE_FAILED');
+        const data = {
+            cellId: cell.cellId,
+            status: cell.status,
+            output: bounded.content,
+            ...cell.result?.data,
+            ...(error ? { error: { code: error.code, message: error.message } } : {}),
+            cached: false
+        };
+        const result = {
+            content: JSON.stringify(data),
+            data,
+            truncated: bounded.truncated,
+            ...(images.length ? { images } : {})
+        };
+        if (cell.status !== 'running')
+            cell.terminal = result;
+        // Keep synchronous completion compatible; retained waits always include explicit lifecycle metadata.
+        if (initial && cell.status !== 'running') {
+            if (cell.error !== undefined)
+                throw cell.error;
+            return { ...result, content: bounded.content || 'Code Exec completed without emitted text.' };
+        }
+        return result;
+    }
+    snapshot(sessionId) {
+        return [...this.#cells.values()]
+            .filter((cell) => cell.sessionId === sessionId)
+            .map(({ cellId, status, executionId }) => ({ cellId, status, executionId }));
+    }
+    async dispose(sessionId) {
+        if (sessionId === undefined)
+            this.#closed = true;
+        else
+            this.#disposing.add(sessionId);
+        const cells = [...this.#cells.values()].filter((cell) => sessionId === undefined || cell.sessionId === sessionId);
+        for (const cell of cells)
+            cell.controller.abort(new MarAgentError('MAR_AGENT_CODE_CANCELLED', 'Code Exec resources were released.'));
+        await Promise.all(cells.map((cell) => cell.done));
+        for (const cell of cells) {
+            clearTimeout(cell.retention);
+            this.#cells.delete(cell.cellId);
+        }
+        if (sessionId !== undefined)
+            this.#disposing.delete(sessionId);
+    }
+}

package/dist/tools/code-mode/dispatch.d.ts

@@ -0,0 +1,21 @@
+import type { ClientToolDefinition } from '../../model/contracts.js';
+import type { MarAgentEvent, ToolCall, ToolExecutionResult, McpToolCallContext } from '../../sdk/types.js';
+import type { ToolRuntimeContext } from '../runtime-context.js';
+import type { createSessionToolScheduler } from '../scheduler.js';
+type ToolEvent = Extract<MarAgentEvent, {
+    type: 'tool.started' | 'tool.completed' | 'tool.failed';
+}>;
+type Payload<T = ToolEvent> = T extends ToolEvent ? Omit<T, 'eventId' | 'sequence' | 'timestamp' | 'sessionId' | 'executionId' | 'turnId'> : never;
+/** Capture only the cell's immutable dispatch identity, never the model loop or its AbortSignal. */
+export declare function createCodeToolDispatch(input: {
+    context: Omit<ToolRuntimeContext, 'signal' | 'codeMode' | 'expectedMcpTool' | 'searchMcpTools'>;
+    tools: readonly ClientToolDefinition[];
+    expectations: ReadonlyMap<string, McpToolCallContext['expectedTool']>;
+    parentCallId: string;
+    schedule: ReturnType<typeof createSessionToolScheduler>;
+    emit: (event: Payload) => Promise<void>;
+    projectData: (name: string, data: unknown) => Extract<ToolEvent, {
+        type: 'tool.completed';
+    }>['data'];
+}): (call: ToolCall, signal: AbortSignal) => Promise<ToolExecutionResult>;
+export {};

package/dist/tools/code-mode/dispatch.js

@@ -0,0 +1,53 @@
+import { randomUUID } from 'node:crypto';
+import { MarAgentError, describeMarAgentError } from '../../error.js';
+import { executeRegisteredTool } from '../runtime.js';
+import { allowsToolCaller } from '../callers.js';
+import { truncateModelText } from '../../runtime/token-budget.js';
+import { AGENT_EXECUTION_POLICY } from '../../runtime/execution-policy.js';
+/** Capture only the cell's immutable dispatch identity, never the model loop or its AbortSignal. */
+export function createCodeToolDispatch(input) {
+    const definitions = new Map(input.tools.map((tool) => [tool.name, tool]));
+    return async (call, signal) => {
+        const definition = definitions.get(call.name);
+        if (!definition || !allowsToolCaller(definition, 'programmatic'))
+            throw new MarAgentError('MAR_AGENT_TOOL_NOT_AVAILABLE', 'The requested nested tool is unavailable.');
+        return input.schedule(definition, async () => {
+            signal.throwIfAborted();
+            const callId = call.callId ?? randomUUID();
+            const identity = { toolName: call.name, callId, parentCallId: input.parentCallId };
+            await input.emit({ type: 'tool.started', ...identity, input: call.arguments });
+            try {
+                const expected = input.expectations.get(call.name);
+                const result = await executeRegisteredTool(call.name, call.arguments, callId, {
+                    ...input.context,
+                    signal,
+                    ...(expected ? { expectedMcpTool: expected } : {})
+                });
+                const bounded = truncateModelText(result.content, AGENT_EXECUTION_POLICY.modelToolOutputTokens);
+                const data = input.projectData(call.name, result.data);
+                const summary = result.content.slice(0, AGENT_EXECUTION_POLICY.toolEventSummaryCharacters);
+                await input.emit({
+                    type: 'tool.completed',
+                    ...identity,
+                    summary,
+                    ...(data === undefined ? {} : { data }),
+                    truncated: result.truncated === true ||
+                        bounded.truncated ||
+                        summary.length < result.content.length,
+                    ...(result.artifacts ? { artifacts: result.artifacts } : {})
+                });
+                return { ...result, content: bounded.content };
+            }
+            catch (error) {
+                const diagnostic = describeMarAgentError(error, 'MAR_AGENT_HOST_OPERATION_FAILED');
+                await input.emit({
+                    type: 'tool.failed',
+                    ...identity,
+                    code: diagnostic.code,
+                    message: diagnostic.message
+                });
+                throw error;
+            }
+        });
+    };
+}

package/dist/tools/code-mode/engine.d.ts

@@ -29,6 +29,7 @@ export interface CodeModeEngine {
         onToolCall(call: ToolCall): Promise<ToolExecutionResult>;
         onText(value: string): void;
         onImage(value: unknown): void;
+        onYield(): void;
     }): Promise<{
         readonly stateMutations: readonly CodeModeStateMutation[];
     }>;

package/dist/tools/code-mode/quickjs-engine.js

@@ -307,6 +307,10 @@ export async function createCodeModeEngine(options) {
             vm.setProp(vm.global, 'catalog', catalog);
             catalog.dispose();
             const cell = vm.newObject();
+            method(cell, 'yield_control', () => {
+                input.onYield();
+                return vm.undefined;
+            });
             method(cell, 'sleep', (durationHandle) => {
                 if (!durationHandle || vm.typeof(durationHandle) !== 'number')
                     return {

package/dist/tools/code-mode/worker.js

@@ -33,6 +33,7 @@ lines.on('line', async (line) => {
             signal: controller.signal,
             onText: (value) => send({ kind: 'text', value }),
             onImage: (value) => send({ kind: 'image', value }),
+            onYield: () => send({ kind: 'yield' }),
             onToolCall: (call) => new Promise((resolve, reject) => {
                 const id = ++sequence;
                 pending.set(id, { resolve, reject });

package/dist/tools/code-mode.d.ts

@@ -1,18 +1,29 @@
 import { type LocalProcessExecutor } from '../host/local-process-executor.js';
-import type { ClientToolDefinition } from '../model/contracts.js';
+import type { ClientToolDefinition, ModelMessage } from '../model/contracts.js';
 import type { ToolExecutionContext, ToolExecutionResult } from '../sdk/types.js';
 import { WorkspacePathResolver } from './shared/path-resolver.js';
 import type { CodeModeEngineFactory } from './code-mode/engine.js';
+import { type CellOutput } from './code-mode/cells.js';
 export declare const codeModeToolDefinition: ClientToolDefinition;
-/** Direct model tools and bounded input-only declarations for the programmatic surface. */
-export declare function projectCodeModeTools(tools: readonly ClientToolDefinition[]): ClientToolDefinition[];
+export declare const codeExecWaitToolDefinition: ClientToolDefinition;
+/** Deferred definitions travel in search results, not in the stable Code Mode description. */
+export declare function projectCodeModeTools(tools: readonly ClientToolDefinition[], residentTools?: readonly ClientToolDefinition[]): ClientToolDefinition[];
+/** Preserve native search definitions while providing the same discovery evidence to other protocols. */
+export declare function projectCodeModeSearchResult(message: ModelMessage, codeModeEnabled: boolean): ModelMessage;
 export declare class CodeModeTool {
     #private;
     private readonly paths;
     private readonly environment;
     private readonly executor;
     private readonly engineFactory;
+    start(value: unknown, context: ToolExecutionContext): Promise<ToolExecutionResult>;
+    wait(value: unknown, context: ToolExecutionContext): Promise<ToolExecutionResult>;
+    listSessionResources(sessionId: string): {
+        cellId: string;
+        status: "completed" | "cancelled" | "running" | "failed";
+        executionId: string;
+    }[];
     constructor(paths: WorkspacePathResolver, environment?: NodeJS.ProcessEnv, executor?: LocalProcessExecutor, engineFactory?: CodeModeEngineFactory);
-    execute(value: unknown, context: ToolExecutionContext): Promise<ToolExecutionResult>;
+    execute(value: unknown, context: ToolExecutionContext, output?: CellOutput): Promise<ToolExecutionResult>;
     dispose(sessionId?: string): Promise<void>;
 }

package/dist/tools/code-mode.js

@@ -10,12 +10,14 @@ import { directLocalProcessExecutor, signalProcessTree } from '../host/local-pro
 import { TOOL_EXECUTION_LIMITS as limits } from './execution-limits.js';
 import { createToolCallScheduler } from './scheduler.js';
 import { detectImageMime } from './view-image.js';
-import { allowsToolCaller } from './callers.js';
+import { allowsDirectTool, allowsToolCaller } from './callers.js';
+import { CodeCells } from './code-mode/cells.js';
 import { parseCodeModeStateMutations } from './code-mode/state.js';
 export const codeModeToolDefinition = {
-    name: 'code_mode',
+    name: 'code_exec',
     description: `Run JavaScript to orchestrate or compose tool calls.
-- Use for bounded combinations of tools or filtering large intermediate results. A single direct tool call is preferable when that tool allows direct calls and composition adds no benefit.
+- Code Mode Only: call the programmatic tools listed below through tools.NAME inside this tool, including single-tool operations. They are omitted from the top-level tool list. Direct-only tools remain separate model tools and cannot be called here.
+- Use bounded combinations, parallel independent calls, and filtering of large intermediate results to reduce model round trips.
 - Evaluates source in a fresh restricted ECMAScript runtime with top-level await and Promise.all. It is not Node.js or a browser. JavaScript globals do not survive between cells; bounded JSON state is available through state.
 - Accepts raw JavaScript source text, not JSON, quoted strings, or markdown code fences. Responses uses the source directly; Anthropic uses the code field of its tool input object. In either case, do not quote or fence the source again.
 - Use only standard ECMAScript built-ins and the explicitly documented tools, out, state, catalog and cell namespaces. Do not use Node.js, browser or Web APIs. Module imports, filesystem and network APIs are unavailable. Obtain external capabilities only through available tools. Use tools.exec for managed background processes when permitted.
@@ -24,7 +26,7 @@ Tool calls:
 - tools.NAME(input) returns a Promise. Use the existing tool input schema; freeform tools such as apply_patch accept a raw string, not a JSON wrapper.
 - Results use the MAR envelope: { content: string, data?: unknown, images?: Array<{mimeType:string,dataBase64:string}>, truncated?: boolean }. content is rendered text, not raw file bytes. Use result.data.results[0].text for read source text and result.data.exitCode/result.data.stdout for exec. Use only fields documented by that tool; do not invent success or ok flags.
 - Tool errors reject with code/message and may be caught. Await every call; unawaited calls fail the cell. Use Promise.all for independent calls and sequential await for dependencies. Runtime preserves safe/serial barriers and Host checks.
-- tool_search, question, code_mode and direct-only tools cannot be called here. Use direct tool_search before a later code cell for deferred tools; the current cell's tools do not change.
+- tool_search, question, code_exec, code_exec_wait and direct-only tools cannot be called here. Use direct tool_search before a later code cell for deferred tools; the current cell's tools do not change.
 
 Built-in namespaces:
 - out.text(value): void emits text. Strings and scalar values are stringified; JSON-compatible objects/arrays are serialized as compact JSON. Cyclic or unsupported object values fail. Only explicitly emitted output reaches the model.
@@ -32,6 +34,9 @@ Built-in namespaces:
 - state.get(key), state.has(key), state.set(key, value), state.delete(key) access bounded session JSON state. Mutations commit atomically only when the cell succeeds; failed or cancelled cells discard them.
 - catalog.tools() returns a read-only snapshot of the tools callable in this cell, including name, description, inputSchema and inputMode. It does not discover or authorize additional tools.
 - await cell.sleep(ms) performs a cancellable Host-side delay up to 30000 ms and remains subject to the cell deadline.
+- await cell.yield_control() returns accumulated output to the model immediately while this cell continues running.
+- Optionally start source with // @options: {"yieldMs": 10000, "maxOutputTokens": 10000}. yieldMs is a wait window (0..30000), not a cell timeout. A running result includes cellId; use direct code_exec_wait for new output, completion or termination.
+- Registered cells are Session warm resources: ending or cancelling the model Execution cancels its wait, not the cell. Reuse retained cellId; do not start duplicate work. Host cleanup or explicit termination stops the cell.
 - tools, out, state, catalog and cell are frozen bindings. Do not shadow their names.
 - Input/text output max 1 MiB, 128 calls, 120 seconds. Failures do not roll back completed tool work; do not replay successful operations blindly.
 
@@ -62,16 +67,37 @@ out.text({ files: patched.data.files.length });
     allowedCallers: ['direct'],
     parallelSafety: 'serial'
 };
-/** Direct model tools and bounded input-only declarations for the programmatic surface. */
-export function projectCodeModeTools(tools) {
-    const direct = tools.filter((tool) => allowsToolCaller(tool, 'direct'));
-    if (!direct.some((tool) => tool.name === 'code_mode'))
+export const codeExecWaitToolDefinition = {
+    name: 'code_exec_wait',
+    description: 'Wait for a retained Code Exec cell by cellId. Returns only new output, or a bounded terminal snapshot marked cached on repeat reads. yieldMs is a wait window, not a timeout. action defaults to poll (wait); action cancel stops the cell and waits for cleanup. Cancelling this wait does not cancel the cell. Cells belong to the current Session and cannot survive Host restart. Call directly, never inside code_exec.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            cellId: { type: 'string' },
+            yieldMs: { type: 'integer', minimum: 0, maximum: limits.codeMaxYieldMs },
+            maxOutputTokens: { type: 'integer', minimum: 1, maximum: limits.codeMaxOutputTokens },
+            action: {
+                type: 'string',
+                enum: ['poll', 'cancel'],
+                description: 'Defaults to poll; cancel terminates the cell rather than just its current wait.'
+            }
+        },
+        required: ['cellId'],
+        additionalProperties: false
+    },
+    allowedCallers: ['direct'],
+    parallelSafety: 'safe'
+};
+/** Deferred definitions travel in search results, not in the stable Code Mode description. */
+export function projectCodeModeTools(tools, residentTools = tools) {
+    const codeModeEnabled = tools.some((tool) => tool.name === 'code_exec' && allowsToolCaller(tool, 'direct'));
+    const direct = tools.filter((tool) => allowsDirectTool(tool, codeModeEnabled));
+    if (!codeModeEnabled)
         return direct;
-    const programmatic = tools.filter((tool) => allowsToolCaller(tool, 'programmatic'));
-    const hidden = programmatic.filter((tool) => !allowsToolCaller(tool, 'direct'));
+    const programmatic = residentTools.filter((tool) => allowsToolCaller(tool, 'programmatic'));
     const directory = JSON.stringify({
         callableNames: programmatic.map((tool) => tool.name),
-        programmaticOnly: hidden.map((tool) => ({
+        programmaticOnly: programmatic.map((tool) => ({
             name: tool.name,
             description: tool.description,
             inputSchema: tool.inputSchema,
@@ -80,13 +106,37 @@ export function projectCodeModeTools(tools) {
     });
     if (Buffer.byteLength(directory) > 32 * 1024)
         throw new MarAgentError('MAR_AGENT_TOOL_EXPOSURE_LIMIT', 'Programmatic tool directory is too large.');
-    return direct.map((tool) => tool.name === 'code_mode'
+    return direct.map((tool) => tool.name === 'code_exec'
         ? {
             ...tool,
-            description: `${codeModeToolDefinition.description}\nProgrammatic tools (other schemas are provided by their direct tool definitions): ${directory}`
+            description: `${codeModeToolDefinition.description}\nDeferred MCP definitions are returned by direct tool_search and become callable from the next model response, not later in the same response; they are not appended to this description.\nProgrammatic tools (call only inside code_exec): ${directory}`
         }
         : tool);
 }
+/** Preserve native search definitions while providing the same discovery evidence to other protocols. */
+export function projectCodeModeSearchResult(message, codeModeEnabled) {
+    if (!message.toolSearchTools)
+        return message;
+    if (!codeModeEnabled)
+        return {
+            ...message,
+            toolSearchTools: message.toolSearchTools.filter((tool) => allowsToolCaller(tool, 'direct'))
+        };
+    const tools = message.toolSearchTools.map((tool) => ({
+        name: tool.name,
+        description: allowsToolCaller(tool, 'programmatic')
+            ? `Call only as tools.${tool.name} inside code_exec, never as a direct model tool.\n${tool.description}`
+            : tool.description,
+        inputSchema: tool.inputSchema,
+        inputMode: tool.inputMode ?? 'json',
+        caller: allowsToolCaller(tool, 'programmatic') ? 'programmatic' : 'direct'
+    }));
+    return {
+        ...message,
+        content: JSON.stringify({ tools }),
+        toolSearchTools: tools.map(({ caller: _caller, ...tool }) => tool)
+    };
+}
 function defaultEngineFactory() {
     const core = import.meta.resolve('quickjs-emscripten-core');
     const variant = import.meta.resolve('@jitl/quickjs-wasmfile-release-sync');
@@ -125,6 +175,16 @@ export class CodeModeTool {
     environment;
     executor;
     engineFactory;
+    #cells = new CodeCells();
+    start(value, context) {
+        return this.#cells.start(value, context, (code, detached, output) => this.execute(code, detached, output));
+    }
+    wait(value, context) {
+        return this.#cells.wait(value, context);
+    }
+    listSessionResources(sessionId) {
+        return this.#cells.snapshot(sessionId);
+    }
     #active = new Map();
     constructor(paths, environment = {}, executor = directLocalProcessExecutor, engineFactory = defaultEngineFactory()) {
         this.paths = paths;
@@ -132,7 +192,7 @@ export class CodeModeTool {
         this.executor = executor;
         this.engineFactory = engineFactory;
     }
-    async execute(value, context) {
+    async execute(value, context, output) {
         const code = typeof value === 'string'
             ? value
             : value &&
@@ -160,7 +220,7 @@ export class CodeModeTool {
         this.#active.set(controller, { sessionId: context.sessionId, done });
         const timer = setTimeout(() => controller.abort(new MarAgentError('MAR_AGENT_CODE_TIMEOUT', 'Code Mode exceeded its execution time limit.')), limits.codeTimeoutMs);
         try {
-            return await this.#run(code, { ...context, signal }, controller);
+            return await this.#run(code, { ...context, signal }, controller, output);
         }
         finally {
             clearTimeout(timer);
@@ -169,12 +229,13 @@ export class CodeModeTool {
         }
     }
     async dispose(sessionId) {
+        await this.#cells.dispose(sessionId);
         const active = [...this.#active].filter(([, entry]) => sessionId === undefined || entry.sessionId === sessionId);
         for (const [controller] of active)
             controller.abort(new MarAgentError('MAR_AGENT_CODE_CANCELLED', 'Code Mode resources were released.'));
         await Promise.all(active.map(([, entry]) => entry.done));
     }
-    async #run(code, context, controller) {
+    async #run(code, context, controller, output) {
         const cwd = await this.paths.resolve('.');
         context.signal.throwIfAborted();
         const environment = Object.fromEntries(environmentKeys.flatMap((key) => {
@@ -255,6 +316,7 @@ export class CodeModeTool {
                 if (outputBytes > limits.codeMaxOutputBytes)
                     throw new MarAgentError('MAR_AGENT_TOOL_OUTPUT_LIMIT', 'Code Mode emitted too much text.');
                 text.push(frame.value);
+                output?.text(frame.value);
             }
             else if (frame.kind === 'image') {
                 if (!context.codeMode?.supportsImages)
@@ -263,6 +325,10 @@ export class CodeModeTool {
                 if (images.length >= 5)
                     throw new MarAgentError('MAR_AGENT_TOOL_OUTPUT_LIMIT', 'Code Mode emitted too many images.');
                 images.push(image);
+                output?.image(image);
+            }
+            else if (frame.kind === 'yield') {
+                output?.yield();
             }
             else if (frame.kind === 'call' &&
                 Number.isSafeInteger(frame.id) &&
@@ -273,7 +339,7 @@ export class CodeModeTool {
                 seen.add(id);
                 const job = (async () => {
                     try {
-                        if (frame.name === 'code_mode' || !available.has(frame.name))
+                        if (frame.name === 'code_exec' || !available.has(frame.name))
                             throw new MarAgentError('MAR_AGENT_TOOL_NOT_AVAILABLE', 'The requested nested tool is unavailable.');
                         const output = await invoke({
                             name: frame.name,

package/dist/tools/execution-limits.d.ts

@@ -21,6 +21,11 @@ export declare const TOOL_EXECUTION_LIMITS: Readonly<{
     codeMaxTransportBytes: 67108864;
     codeMaxCalls: 128;
     codeMaxConcurrentCells: 4;
+    codeDefaultYieldMs: 10000;
+    codeMaxYieldMs: 30000;
+    codeMaxOutputTokens: 10000;
+    codeCompletedRetentionMs: 300000;
+    codeMaxCompletedResults: 16;
     codeStateMaxEntries: 128;
     codeStateMaxMutations: 128;
     codeStateMaxKeyBytes: 256;

package/dist/tools/execution-limits.js

@@ -21,6 +21,11 @@ export const TOOL_EXECUTION_LIMITS = Object.freeze({
     codeMaxTransportBytes: 67_108_864,
     codeMaxCalls: 128,
     codeMaxConcurrentCells: 4,
+    codeDefaultYieldMs: 10_000,
+    codeMaxYieldMs: 30_000,
+    codeMaxOutputTokens: 10_000,
+    codeCompletedRetentionMs: 300_000,
+    codeMaxCompletedResults: 16,
     codeStateMaxEntries: 128,
     codeStateMaxMutations: 128,
     codeStateMaxKeyBytes: 256,

package/dist/tools/local-registry.d.ts

@@ -24,6 +24,11 @@ export declare class LocalToolRegistry {
         command: string;
         cwd: string;
     }[];
+    listCodeCells(sessionId: string): {
+        cellId: string;
+        status: "completed" | "cancelled" | "running" | "failed";
+        executionId: string;
+    }[];
     disposeSessionResources(sessionId: string): Promise<void>;
     dispose(): Promise<void>;
 }

package/dist/tools/local-registry.js

@@ -25,7 +25,8 @@ export class LocalToolRegistry {
         this.#exec = new ExecTool(paths, undefined, undefined, environment, shell, web.processExecutor);
         this.#code = new CodeModeTool(paths, environment, web.processExecutor, web.codeModeEngineFactory);
         this.#handlers = new Map([
-            ['code_mode', (arguments_, context) => this.#code.execute(arguments_, context)],
+            ['code_exec', (arguments_, context) => this.#code.start(arguments_, context)],
+            ['code_exec_wait', (arguments_, context) => this.#code.wait(arguments_, context)],
             [
                 'read',
                 async (arguments_, context) => {
@@ -124,6 +125,9 @@ export class LocalToolRegistry {
     listSessionResources(sessionId) {
         return this.#exec.listSessionResources(sessionId);
     }
+    listCodeCells(sessionId) {
+        return this.#code.listSessionResources(sessionId);
+    }
     async disposeSessionResources(sessionId) {
         await Promise.all([this.#exec.disposeSession(sessionId), this.#code.dispose(sessionId)]);
     }