@myagentroam/agent 0.9.137 → 0.9.138

package/dist/tools/code-mode.js

@@ -11,9 +11,10 @@ import { TOOL_EXECUTION_LIMITS as limits } from './execution-limits.js';
 import { createToolCallScheduler } from './scheduler.js';
 import { detectImageMime } from './view-image.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.
 - 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.
@@ -25,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.
@@ -33,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.
 
@@ -63,9 +67,30 @@ out.text({ files: patched.data.files.length });
     allowedCallers: ['direct'],
     parallelSafety: 'serial'
 };
+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_mode' && allowsToolCaller(tool, 'direct'));
+    const codeModeEnabled = tools.some((tool) => tool.name === 'code_exec' && allowsToolCaller(tool, 'direct'));
     const direct = tools.filter((tool) => allowsDirectTool(tool, codeModeEnabled));
     if (!codeModeEnabled)
         return direct;
@@ -81,10 +106,10 @@ export function projectCodeModeTools(tools, residentTools = 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}\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_mode): ${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);
 }
@@ -100,7 +125,7 @@ export function projectCodeModeSearchResult(message, codeModeEnabled) {
     const tools = message.toolSearchTools.map((tool) => ({
         name: tool.name,
         description: allowsToolCaller(tool, 'programmatic')
-            ? `Call only as tools.${tool.name} inside code_mode, never as a direct model tool.\n${tool.description}`
+            ? `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',
@@ -150,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;
@@ -157,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 &&
@@ -185,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);
@@ -194,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) => {
@@ -280,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)
@@ -288,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) &&
@@ -298,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)]);
     }

package/dist/tools/registry.js

@@ -1,6 +1,6 @@
 import { applyPatchToolDefinition } from './apply-patch.js';
 import { execToolDefinition } from './exec.js';
-import { codeModeToolDefinition } from './code-mode.js';
+import { codeModeToolDefinition, codeExecWaitToolDefinition } from './code-mode.js';
 import { executeQuestion, questionToolDefinition } from './question.js';
 import { readToolDefinition } from './read.js';
 import { viewImageToolDefinition } from './view-image.js';
@@ -21,6 +21,7 @@ export const BUILTIN_TOOL_DEFINITIONS = [
     viewImageToolDefinition,
     execToolDefinition,
     codeModeToolDefinition,
+    codeExecWaitToolDefinition,
     applyPatchToolDefinition,
     questionToolDefinition,
     todoReadToolDefinition,

package/dist/tools/scheduler.d.ts

@@ -1,4 +1,6 @@
 import type { ClientToolDefinition } from '../model/contracts.js';
+/** One barrier domain for foreground tools and all retained cells in a Session. */
+export declare function createSessionToolScheduler(): <T>(definition: ClientToolDefinition | undefined, run: () => Promise<T>) => Promise<T>;
 /** Schedules an incremental stream while preserving the same safe/serial barriers as batches. */
 export declare function createToolCallScheduler<TCall extends {
     readonly name: string;

package/dist/tools/scheduler.js

@@ -1,3 +1,14 @@
+/** One barrier domain for foreground tools and all retained cells in a Session. */
+export function createSessionToolScheduler() {
+    const schedule = createToolCallScheduler([
+        { name: 'safe', parallelSafety: 'safe' },
+        { name: 'serial', parallelSafety: 'serial' }
+    ], (job) => job.run());
+    return (definition, run) => schedule({
+        name: definition?.parallelSafety === 'safe' ? 'safe' : 'serial',
+        run
+    });
+}
 /** Schedules an incremental stream while preserving the same safe/serial barriers as batches. */
 export function createToolCallScheduler(definitions, execute) {
     const safety = new Map(definitions.map((definition) => [definition.name, definition.parallelSafety]));

package/dist/tools/tool-search.js

@@ -13,7 +13,7 @@ export const TOOL_SEARCH_LIMITS = Object.freeze({
 });
 export const toolSearchToolDefinition = {
     name: 'tool_search',
-    description: 'Search deferred MCP metadata and return matching tool definitions for the next model call. Use the full callable name for exact selection, or keywords for BM25 search. Never executes the discovered tools. With Code Mode Only, programmatic tools must be called through code_mode, not directly. Already exposed tools need not be searched again. The selected definitions must fit the exposure budget or the search fails atomically.',
+    description: 'Search deferred MCP metadata and return matching tool definitions for the next model call. Use the full callable name for exact selection, or keywords for BM25 search. Never executes the discovered tools. With Code Mode Only, programmatic tools must be called through code_exec, not directly. Already exposed tools need not be searched again. The selected definitions must fit the exposure budget or the search fails atomically.',
     inputSchema: {
         type: 'object',
         properties: {
@@ -207,7 +207,7 @@ export class DeferredMcpRegistry {
         const direct = projectCodeModeTools(resident);
         const residentNames = new Set(resident.map((tool) => tool.name));
         const definitions = active.filter((tool) => !residentNames.has(tool.name));
-        const searchResult = projectCodeModeSearchResult({ role: 'tool', content: '', toolSearchTools: definitions }, base.some((tool) => tool.name === 'code_mode'));
+        const searchResult = projectCodeModeSearchResult({ role: 'tool', content: '', toolSearchTools: definitions }, base.some((tool) => tool.name === 'code_exec'));
         // Search-result definitions still consume context even when Only mode hides direct tools.
         const estimated = countModelTokens(searchResult.content || JSON.stringify(searchResult.toolSearchTools));
         const full = Math.max(countModelTokens(JSON.stringify(tools)), countModelTokens(JSON.stringify(direct)) + estimated);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@myagentroam/agent",
-  "version": "0.9.137",
+  "version": "0.9.138",
   "description": "Embeddable MAR coding agent SDK and CLI.",
   "license": "Apache-2.0",
   "type": "module",