@myagentroam/agent 0.9.138 → 0.9.140

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

@@ -1,5 +1,8 @@
 import type { ToolCall, ToolExecutionResult } from '../../sdk/types.js';
 import type { CodeModeStateEntry, CodeModeStateMutation } from './state.js';
+export type ProgrammaticToolResult = Omit<ToolExecutionResult, 'content'> & {
+    content?: string;
+};
 export interface CodeModeCatalogEntry {
     readonly name: string;
     readonly description: string;
@@ -26,8 +29,8 @@ export interface CodeModeEngine {
             stateTotalBytes: number;
             sleepMs: number;
         };
-        onToolCall(call: ToolCall): Promise<ToolExecutionResult>;
-        onText(value: string): void;
+        onToolCall(call: ToolCall): Promise<ProgrammaticToolResult>;
+        onText(value: string, originalBytes?: number): void;
         onImage(value: unknown): void;
         onYield(): void;
     }): Promise<{

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

@@ -1,3 +1,4 @@
+import { BoundedTextOutput } from './text-output.js';
 // This trusted module runs only in the Host-managed worker, never in the model's JS context.
 /** @returns {Promise<import('./engine.js').CodeModeEngine>} */
 export async function createCodeModeEngine(options) {
@@ -27,6 +28,7 @@ export async function createCodeModeEngine(options) {
             const state = new Map(input.state.map((entry) => [entry.key, entry.value]));
             const stateMutations = [];
             let outputBytes = 0;
+            let textCalls = 0;
             const notify = () => {
                 wake?.();
                 wake = undefined;
@@ -69,16 +71,7 @@ export async function createCodeModeEngine(options) {
             return item;
           });
         };
-        globalThis.__text = value => {
-          if (value === null || ['string', 'number', 'boolean', 'bigint', 'undefined'].includes(typeof value))
-            return String(value);
-          return JSON.stringify(value, (_key, item) => {
-            if (['bigint', 'function', 'symbol', 'undefined'].includes(typeof item))
-              throw Object.assign(new TypeError('Only JSON values may be emitted.'),
-                { code: 'MAR_AGENT_TOOL_INPUT_INVALID' });
-            return item;
-          });
-        };
+        globalThis.__text = ${streamText.toString()};
         globalThis.__deepFreeze = function deepFreeze(value) {
           if (value && typeof value === 'object' && !Object.isFrozen(value)) {
             for (const item of Object.values(value)) deepFreeze(item);
@@ -207,17 +200,32 @@ export async function createCodeModeEngine(options) {
             consumeToolCall.dispose();
             const out = vm.newObject();
             method(out, 'text', (handle) => {
-                const result = vm.callFunction(formatText, vm.undefined, handle ?? vm.undefined);
+                const separatorBytes = textCalls ? 1 : 0;
+                const capture = new BoundedTextOutput(Math.max(0, input.limits.outputBytes - outputBytes - separatorBytes), '');
+                const emit = vm.newFunction('textChunk', (chunk) => {
+                    if (!chunk || vm.typeof(chunk) !== 'string')
+                        return {
+                            error: guestError('MAR_AGENT_TOOL_INPUT_INVALID', 'Text output chunks must be strings.')
+                        };
+                    const length = vm.getProp(chunk, 'length');
+                    const oversized = vm.getNumber(length) > 4096 * 6;
+                    length.dispose();
+                    if (oversized)
+                        return {
+                            error: guestError('MAR_AGENT_TOOL_OUTPUT_LIMIT', 'Text serialization chunk limit exceeded.')
+                        };
+                    capture.append(vm.getString(chunk));
+                    return vm.undefined;
+                });
+                const result = vm.callFunction(formatText, vm.undefined, handle ?? vm.undefined, emit);
+                emit.dispose();
                 if (result.error)
                     return { error: result.error };
                 try {
-                    const value = vm.getString(result.value);
-                    outputBytes += Buffer.byteLength(value) + 1;
-                    if (outputBytes > input.limits.outputBytes)
-                        return {
-                            error: guestError('MAR_AGENT_TOOL_OUTPUT_LIMIT', 'Text output limit exceeded.')
-                        };
-                    input.onText(value);
+                    const captured = capture.snapshot();
+                    outputBytes += captured.retainedBytes + separatorBytes;
+                    textCalls++;
+                    input.onText(captured.text, captured.originalBytes);
                 }
                 finally {
                     result.value.dispose();
@@ -453,6 +461,86 @@ export async function createCodeModeEngine(options) {
         }
     };
 }
+// Compiled inside the guest: stream bounded chunks, never build a complete serialized object.
+function streamText(value, emit) {
+    'use strict';
+    const chunks = (text, quoted = false) => {
+        if (quoted)
+            emit('"');
+        for (let start = 0; start < text.length;) {
+            let end = Math.min(text.length, start + 4096);
+            if (end < text.length &&
+                text.charCodeAt(end - 1) >= 0xd800 &&
+                text.charCodeAt(end - 1) <= 0xdbff &&
+                text.charCodeAt(end) >= 0xdc00 &&
+                text.charCodeAt(end) <= 0xdfff)
+                end--;
+            const part = text.slice(start, end);
+            emit(quoted ? JSON.stringify(part).slice(1, -1) : part);
+            start = end;
+        }
+        if (quoted)
+            emit('"');
+    };
+    if (value === null ||
+        ['string', 'number', 'boolean', 'bigint', 'undefined'].includes(typeof value)) {
+        chunks(String(value));
+        return;
+    }
+    const ancestors = new Set();
+    const write = (item, key) => {
+        if (item && typeof item === 'object' && typeof item.toJSON === 'function')
+            item = item.toJSON(key);
+        if (['bigint', 'function', 'symbol', 'undefined'].includes(typeof item))
+            throw Object.assign(new TypeError('Only JSON values may be emitted.'), {
+                code: 'MAR_AGENT_TOOL_INPUT_INVALID'
+            });
+        if (item instanceof Number || item instanceof String || item instanceof Boolean)
+            item = item.valueOf();
+        if (item instanceof BigInt)
+            throw new TypeError('BigInt objects cannot be emitted.');
+        if (item === null) {
+            emit('null');
+            return;
+        }
+        if (typeof item === 'string') {
+            chunks(item, true);
+            return;
+        }
+        if (typeof item === 'number' || typeof item === 'boolean') {
+            emit(JSON.stringify(item));
+            return;
+        }
+        if (ancestors.has(item))
+            throw new TypeError('Cyclic values cannot be emitted.');
+        ancestors.add(item);
+        if (Array.isArray(item)) {
+            emit('[');
+            const length = item.length;
+            for (let index = 0; index < length; index++) {
+                if (index)
+                    emit(',');
+                write(item[index], String(index));
+            }
+            emit(']');
+        }
+        else {
+            emit('{');
+            let first = true;
+            for (const name of Object.keys(item)) {
+                if (!first)
+                    emit(',');
+                first = false;
+                chunks(name, true);
+                emit(':');
+                write(item[name], name);
+            }
+            emit('}');
+        }
+        ancestors.delete(item);
+    };
+    write(value, '');
+}
 function diagnostic(code, message) {
     return Object.assign(new Error(message), { code });
 }

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

@@ -0,0 +1,21 @@
+export function renderCapturedText(snapshot: any, imageCount?: number): string;
+/** Bounded UTF-8 capture shared by trusted engines, the bridge and retained cells. */
+export class BoundedTextOutput {
+    constructor(maximumBytes: any, separator?: string);
+    maximumBytes: any;
+    separator: string;
+    append(value: any, originalBytes?: number): void;
+    snapshot(): {
+        text: string;
+        originalBytes: number;
+        retainedBytes: number;
+        droppedBytes: number;
+    };
+    drain(): {
+        text: string;
+        originalBytes: number;
+        retainedBytes: number;
+        droppedBytes: number;
+    };
+    #private;
+}

package/dist/tools/code-mode/text-output.js

@@ -0,0 +1,75 @@
+/** Bounded UTF-8 capture shared by trusted engines, the bridge and retained cells. */
+export class BoundedTextOutput {
+    #chunks = [];
+    #used = 0;
+    #original = 0;
+    #retained = 0;
+    #hasValue = false;
+    #sealed = false;
+    constructor(maximumBytes, separator = '\n') {
+        this.maximumBytes = maximumBytes;
+        this.separator = separator;
+    }
+    append(value, originalBytes = Buffer.byteLength(value)) {
+        const separator = this.#hasValue ? this.separator : '';
+        this.#hasValue = true;
+        this.#original += Buffer.byteLength(separator) + originalBytes;
+        this.#capture(separator);
+        this.#capture(value);
+        if (originalBytes > Buffer.byteLength(value))
+            this.#sealed = true;
+    }
+    #capture(value) {
+        const remaining = Math.max(0, this.maximumBytes - this.#used);
+        if (this.#sealed || !value.length)
+            return;
+        if (!remaining) {
+            this.#sealed = true;
+            return;
+        }
+        // Slice UTF-16 first so even a large injected-engine string never creates an unbounded Buffer.
+        let end = Math.min(value.length, remaining);
+        if (end < value.length &&
+            end > 0 &&
+            value.charCodeAt(end - 1) >= 0xd800 &&
+            value.charCodeAt(end - 1) <= 0xdbff &&
+            value.charCodeAt(end) >= 0xdc00 &&
+            value.charCodeAt(end) <= 0xdfff)
+            end--;
+        const bytes = Buffer.from(value.slice(0, end));
+        let length = Math.min(bytes.length, remaining);
+        while (length > 0 && length < bytes.length && (bytes[length] & 0xc0) === 0x80)
+            length--;
+        if (length < Buffer.byteLength(value))
+            this.#sealed = true;
+        if (!length)
+            return;
+        this.#chunks.push(bytes.toString('utf8', 0, length));
+        this.#used += length;
+        this.#retained += length;
+    }
+    snapshot() {
+        return {
+            text: this.#chunks.join(''),
+            originalBytes: this.#original,
+            retainedBytes: this.#retained,
+            droppedBytes: this.#original - this.#retained
+        };
+    }
+    drain() {
+        const snapshot = this.snapshot();
+        this.#chunks = [];
+        this.#original = 0;
+        this.#retained = 0;
+        this.#hasValue = false;
+        // Consuming output never replenishes the cell's capture budget.
+        return snapshot;
+    }
+}
+export function renderCapturedText(snapshot, imageCount = 0) {
+    const text = snapshot.droppedBytes > 0
+        ? `${snapshot.text}\n...[${snapshot.droppedBytes} text bytes omitted; original output: ${snapshot.originalBytes} bytes]...`
+        : snapshot.text;
+    const imageSummary = imageCount > 0 ? `Code Exec emitted ${imageCount} image${imageCount === 1 ? '' : 's'}.` : '';
+    return [text, imageSummary].filter(Boolean).join('\n');
+}

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

@@ -31,7 +31,7 @@ lines.on('line', async (line) => {
             state: frame.state,
             limits: frame.limits,
             signal: controller.signal,
-            onText: (value) => send({ kind: 'text', value }),
+            onText: (value, originalBytes) => send({ kind: 'text', value, originalBytes }),
             onImage: (value) => send({ kind: 'image', value }),
             onYield: () => send({ kind: 'yield' }),
             onToolCall: (call) => new Promise((resolve, reject) => {

package/dist/tools/code-mode.js

@@ -12,6 +12,7 @@ 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 { BoundedTextOutput, renderCapturedText } from './code-mode/text-output.js';
 import { parseCodeModeStateMutations } from './code-mode/state.js';
 export const codeModeToolDefinition = {
     name: 'code_exec',
@@ -20,25 +21,25 @@ export const codeModeToolDefinition = {
 - 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.
+- 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 to start managed processes when permitted; use tools.exec_wait afterward to wait, write stdin or cancel.
 
 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_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.
+- Results use the MAR envelope: { content?: string, data?: unknown, images?: Array<{mimeType:string,dataBase64:string}>, truncated?: boolean }. Redundant JSON content is omitted when it exactly renders data; independent text remains in content. Prefer data for programmatic results: result.data.results[0].text for read source text and result.data.exitCode/result.data.stdout for exec. content, when present, is rendered text, not raw file bytes. Use only fields documented by that tool; do not invent success or ok flags.
+- Tool errors reject with code/message and may be caught. A failed cell preserves already emitted output alongside its status and error; inspect it before retrying completed work. 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.
+- skill, tool_search, question, code_exec, code_exec_wait and direct-only tools cannot be called here. Load Skills directly and read their instructions before the next tool call. 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.
+- out.text(value): void emits text. Strings and scalar values are stringified; JSON-compatible objects/arrays are serialized as compact JSON. Excess ordinary text is truncated with omission metadata, without stopping later code or tools. Cyclic or unsupported object values fail. Only explicitly emitted output reaches the model.
 - out.image(value: {mimeType:string,dataBase64:string}): void emits one returned image; for example out.image(result.images[0]) when that image exists and the model supports images. It does not accept a path, URL, or result.content.
 - 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.
+- Optionally start source with // @options: {"yieldMs": ${limits.codeDefaultYieldMs}, "maxOutputTokens": 10000}. yieldMs defaults to ${limits.codeDefaultYieldMs} ms and is a wait window (0..${limits.codeMaxYieldMs}), not a cell timeout. Explicit values are preserved and do not change nested tools' wait windows. 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.
+- Input max 1 MiB; cumulative text capture max 1 MiB with truncation; 128 calls, 120 seconds. Tool-specific limits apply before explicit text capture. Protocol, image, memory and time limits remain hard failures. Failures do not roll back completed tool work; do not replay successful operations blindly.
 
 Examples (copy the JavaScript source, not the fences; use only tools available in the current directory):
 Independent reads, emitting only source text:
@@ -74,7 +75,13 @@ export const codeExecWaitToolDefinition = {
         type: 'object',
         properties: {
             cellId: { type: 'string' },
-            yieldMs: { type: 'integer', minimum: 0, maximum: limits.codeMaxYieldMs },
+            yieldMs: {
+                type: 'integer',
+                minimum: 0,
+                maximum: limits.codeMaxWaitYieldMs,
+                default: limits.codeDefaultWaitYieldMs,
+                description: `Wait up to this many milliseconds. Defaults to ${limits.codeDefaultWaitYieldMs}; maximum ${limits.codeMaxWaitYieldMs}. Zero returns immediately without stopping the cell. This does not extend the cell execution deadline.`
+            },
             maxOutputTokens: { type: 'integer', minimum: 1, maximum: limits.codeMaxOutputTokens },
             action: {
                 type: 'string',
@@ -259,9 +266,8 @@ export class CodeModeTool {
             owner: { sessionId: context.sessionId, executionId: context.executionId },
             signal: context.signal
         });
-        const text = [];
+        const text = new BoundedTextOutput(limits.codeMaxOutputBytes);
         const images = [];
-        let outputBytes = 0;
         let transportBytes = 0;
         let calls = 0;
         let complete = false;
@@ -312,11 +318,12 @@ export class CodeModeTool {
             if (complete)
                 throw new MarAgentError('MAR_AGENT_CODE_PROTOCOL_ERROR', 'Code Mode sent data after completion.');
             if (frame.kind === 'text' && typeof frame.value === 'string') {
-                outputBytes += Buffer.byteLength(frame.value) + 1;
-                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);
+                const originalBytes = frame.originalBytes ?? Buffer.byteLength(frame.value);
+                if (!Number.isSafeInteger(originalBytes) ||
+                    originalBytes < Buffer.byteLength(frame.value))
+                    throw new MarAgentError('MAR_AGENT_CODE_PROTOCOL_ERROR', 'Code Mode sent invalid text byte counts.');
+                text.append(frame.value, originalBytes);
+                output?.text(frame.value, originalBytes);
             }
             else if (frame.kind === 'image') {
                 if (!context.codeMode?.supportsImages)
@@ -346,7 +353,11 @@ export class CodeModeTool {
                             arguments: frame.arguments,
                             callId: randomUUID()
                         });
-                        await write({ id, ok: true, output });
+                        const { content, ...structured } = output;
+                        const projected = output.data !== undefined && content === JSON.stringify(output.data)
+                            ? structured
+                            : output;
+                        await write({ id, ok: true, output: projected });
                     }
                     catch (error) {
                         if (context.signal.aborted)
@@ -458,9 +469,16 @@ export class CodeModeTool {
                 throw new MarAgentError('MAR_AGENT_CODE_INCOMPLETE', 'Code Mode exited without a completion message.');
             if (stateMutations.length)
                 await context.codeMode.commitState?.(stateMutations);
+            const captured = text.snapshot();
             return {
-                content: text.join('\n') || 'Code Mode completed without emitted text.',
-                data: { toolCalls: calls },
+                content: renderCapturedText(captured, images.length) ||
+                    'Code Mode completed without emitted text.',
+                data: {
+                    toolCalls: calls,
+                    outputBytes: captured.originalBytes,
+                    outputDroppedBytes: captured.droppedBytes
+                },
+                truncated: captured.droppedBytes > 0,
                 ...(images.length ? { images } : {})
             };
         }

package/dist/tools/exec.d.ts

@@ -34,6 +34,9 @@ export interface ExecResult {
     cached?: boolean;
 }
 export declare const execToolDefinition: ClientToolDefinition;
+export declare const execWaitToolDefinition: ClientToolDefinition;
+/** Validate the public entry points before delegating to the single process manager. */
+export declare function execToolInput(name: 'exec' | 'exec_wait', value: unknown): ExecInput;
 export declare class ExecTool {
     #private;
     private readonly paths;

package/dist/tools/exec.js

@@ -7,7 +7,7 @@ export const execToolDefinition = {
     name: 'exec',
     allowedCallers: ['direct', 'programmatic'],
     parallelSafety: 'safe',
-    description: 'Unrestricted general system execution. Providing command starts any platform-native command, script, text/file tool, builder, generator, network client, or program in workspace/default cwd; action may be omitted for start. poll waits up to yieldMs for new output or termination and returns incremental stdout/stderr while running; after termination, poll returns a bounded cached result with earlier output for up to five minutes while the Session remains hosted. write sends stdin to running processes; cancel terminates a running process or removes a completed result. Returns status, processId, stdout/stderr, cumulative stdoutBytes/stderrBytes, per-result dropped bytes, exitCode, and truncated; a completed status does not imply exitCode 0. Always inspect stderr/exitCode and consume terminal output or cancel.',
+    description: 'Start a platform-native command, script, or program in workspace/default cwd. Returns a stable processId, status, bounded stdout/stderr, cumulative byte counts, dropped-byte counts, exitCode and truncated. A completed status does not imply exitCode 0; inspect stderr/exitCode. For subsequent waiting, stdin writes or cancellation, use exec_wait with processId, not exec. Truncation does not stop the process. Cancelling the initial wait does not terminate the process.',
     outputSchema: {
         type: 'object',
         required: ['content', 'data'],
@@ -44,13 +44,9 @@ export const execToolDefinition = {
     inputSchema: {
         type: 'object',
         properties: {
-            action: {
-                enum: ['start', 'poll', 'write', 'cancel'],
-                description: 'Lifecycle operation. Omit when providing command to start a process.'
-            },
             command: {
                 type: 'string',
-                description: 'Required for start; implies start when action is omitted.'
+                description: 'Platform-native command to start.'
             },
             cwd: {
                 type: 'string',
@@ -62,15 +58,58 @@ export const execToolDefinition = {
                 minimum: 0,
                 maximum: TOOL_EXECUTION_LIMITS.execMaxYieldMs,
                 default: TOOL_EXECUTION_LIMITS.execDefaultYieldMs,
-                description: `Wait before yielding output. Defaults to ${TOOL_EXECUTION_LIMITS.execDefaultYieldMs} ms; effective range is 0-${TOOL_EXECUTION_LIMITS.execMaxYieldMs} ms.`
+                description: `Wait before yielding output. Defaults to ${TOOL_EXECUTION_LIMITS.execDefaultYieldMs} ms. Maximum ${TOOL_EXECUTION_LIMITS.execMaxYieldMs} ms. Zero returns immediately. This does not extend the process timeout.`
+            }
+        },
+        required: ['command'],
+        additionalProperties: false
+    }
+};
+export const execWaitToolDefinition = {
+    name: 'exec_wait',
+    allowedCallers: ['direct', 'programmatic'],
+    parallelSafety: 'safe',
+    description: 'Wait for or control a managed process by processId. action defaults to poll: wait for new output or termination and return incremental stdout/stderr. write sends data to stdin; cancel terminates the process or removes its cached result. Terminal polls return a bounded snapshot marked cached for up to five minutes. Cancelling a wait does not terminate the process. Uses the same Session-owned processes as exec; cannot start a process or extend its timeout. Inspect stderr/exitCode; completed does not imply success. Supports direct and programmatic calls; in Code Mode use tools.exec_wait. The cell execution deadline still bounds waits made inside a cell.',
+    outputSchema: execToolDefinition.outputSchema,
+    inputSchema: {
+        type: 'object',
+        properties: {
+            processId: {
+                type: 'string',
+                minLength: 1,
+                description: 'Stable processId returned by exec.'
             },
-            processId: { type: 'string', description: 'Required for poll, write and cancel.' },
-            data: { type: 'string', description: 'stdin data required for write.' }
+            action: { enum: ['poll', 'write', 'cancel'], default: 'poll' },
+            yieldMs: {
+                type: 'integer',
+                minimum: 0,
+                maximum: TOOL_EXECUTION_LIMITS.execMaxPollYieldMs,
+                default: TOOL_EXECUTION_LIMITS.execDefaultYieldMs,
+                description: `Poll wait window in milliseconds; default ${TOOL_EXECUTION_LIMITS.execDefaultYieldMs}, maximum ${TOOL_EXECUTION_LIMITS.execMaxPollYieldMs}. Zero returns immediately. Not a process timeout.`
+            },
+            data: { type: 'string', description: 'Required stdin data for write.' }
         },
-        required: [],
+        required: ['processId'],
         additionalProperties: false
     }
 };
+/** Validate the public entry points before delegating to the single process manager. */
+export function execToolInput(name, value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return invalidExecInput();
+    const input = value;
+    const allowed = name === 'exec'
+        ? ['command', 'cwd', 'timeoutMs', 'yieldMs']
+        : ['processId', 'action', 'yieldMs', 'data'];
+    if (Object.keys(input).some((key) => !allowed.includes(key)))
+        return invalidExecInput();
+    if (name === 'exec')
+        return parseExecInput(input);
+    const action = input.action ?? 'poll';
+    if (!['poll', 'write', 'cancel'].includes(String(action)))
+        return invalidExecInput();
+    return parseExecInput({ ...input, action });
+}
 export class ExecTool {
     paths;
     maxOutputBytes;
@@ -108,7 +147,7 @@ export class ExecTool {
             if (!process || (owner !== undefined && process.ownerSessionId !== owner.sessionId))
                 throw new MarAgentError('MAR_AGENT_PROCESS_NOT_FOUND', 'Managed process was not found.');
             if (input.action === 'poll' && input.yieldMs)
-                await waitForProcessChange(process, Math.min(Math.max(input.yieldMs, 0), TOOL_EXECUTION_LIMITS.execMaxYieldMs), signal);
+                await waitForProcessChange(process, Math.min(Math.max(input.yieldMs, 0), TOOL_EXECUTION_LIMITS.execMaxPollYieldMs), signal);
             if (input.action === 'write')
                 process.child.stdin.write(input.data);
             if (input.action === 'cancel')
@@ -403,11 +442,10 @@ function appendOutput(output, chunk, maximumBytes, receivedBytes = chunk.length)
     const content = span.subarray(output.windowOffset, output.windowOffset + output.bytes);
     output.chunks = [];
     output.bytes = 0;
-    output.droppedBytes += overflow;
     const pushSlice = (start, end) => {
         while (start < end && (content[start] & 0xc0) === 0x80)
             start++;
-        while (end > start && (content[end - 1] & 0xc0) === 0x80)
+        while (end > start && end < content.length && (content[end] & 0xc0) === 0x80)
             end--;
         if (start >= end)
             return;
@@ -417,6 +455,7 @@ function appendOutput(output, chunk, maximumBytes, receivedBytes = chunk.length)
     };
     pushSlice(0, Math.min(head, content.length));
     pushSlice(Math.min(head + overflow, content.length), content.length);
+    output.droppedBytes += content.length - output.bytes;
     output.window = span;
 }
 function consumeOutput(output) {
@@ -436,7 +475,9 @@ function parseExecInput(value) {
     const action = input.action == null && typeof input.command === 'string' ? 'start' : input.action;
     if (!['start', 'poll', 'write', 'cancel'].includes(String(action)))
         return invalidExecInput();
-    const yieldMs = optionalBoundedInteger(input.yieldMs, 0, TOOL_EXECUTION_LIMITS.execMaxYieldMs);
+    const yieldMs = optionalBoundedInteger(input.yieldMs, 0, action === 'poll'
+        ? TOOL_EXECUTION_LIMITS.execMaxPollYieldMs
+        : TOOL_EXECUTION_LIMITS.execMaxYieldMs);
     if (action === 'start') {
         if (typeof input.command !== 'string' || input.command.trim() === '')
             return invalidExecInput();
@@ -457,7 +498,7 @@ function parseExecInput(value) {
         return {
             action,
             processId: input.processId,
-            ...(yieldMs === undefined ? {} : { yieldMs })
+            yieldMs: yieldMs ?? TOOL_EXECUTION_LIMITS.execDefaultYieldMs
         };
     if (action === 'write') {
         if (typeof input.data !== 'string')

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

@@ -10,6 +10,7 @@ export declare const TOOL_EXECUTION_LIMITS: Readonly<{
     execMaxTimeoutMs: 3600000;
     execDefaultYieldMs: 10000;
     execMaxYieldMs: 30000;
+    execMaxPollYieldMs: 300000;
     execTerminationGraceMs: 1000;
     execDefaultMaxOutputBytes: 1000000;
     maxProcesses: 8;
@@ -21,8 +22,10 @@ export declare const TOOL_EXECUTION_LIMITS: Readonly<{
     codeMaxTransportBytes: 67108864;
     codeMaxCalls: 128;
     codeMaxConcurrentCells: 4;
-    codeDefaultYieldMs: 10000;
+    codeDefaultYieldMs: 30000;
+    codeDefaultWaitYieldMs: 10000;
     codeMaxYieldMs: 30000;
+    codeMaxWaitYieldMs: 300000;
     codeMaxOutputTokens: 10000;
     codeCompletedRetentionMs: 300000;
     codeMaxCompletedResults: 16;

package/dist/tools/execution-limits.js

@@ -10,6 +10,7 @@ export const TOOL_EXECUTION_LIMITS = Object.freeze({
     execMaxTimeoutMs: 3_600_000,
     execDefaultYieldMs: 10_000,
     execMaxYieldMs: 30_000,
+    execMaxPollYieldMs: 300_000,
     execTerminationGraceMs: 1_000,
     execDefaultMaxOutputBytes: 1_000_000,
     maxProcesses: 8,
@@ -21,8 +22,10 @@ export const TOOL_EXECUTION_LIMITS = Object.freeze({
     codeMaxTransportBytes: 67_108_864,
     codeMaxCalls: 128,
     codeMaxConcurrentCells: 4,
-    codeDefaultYieldMs: 10_000,
+    codeDefaultYieldMs: 30_000,
+    codeDefaultWaitYieldMs: 10_000,
     codeMaxYieldMs: 30_000,
+    codeMaxWaitYieldMs: 300_000,
     codeMaxOutputTokens: 10_000,
     codeCompletedRetentionMs: 300_000,
     codeMaxCompletedResults: 16,

package/dist/tools/local-registry.js

@@ -2,7 +2,7 @@ import { MarAgentError } from '../error.js';
 import { AGENT_EXECUTION_POLICY } from '../runtime/execution-policy.js';
 import { modelTokenBudgetBytes } from '../runtime/token-budget.js';
 import { ApplyPatchTool } from './apply-patch.js';
-import { ExecTool } from './exec.js';
+import { ExecTool, execToolInput } from './exec.js';
 import { CodeModeTool } from './code-mode.js';
 import { ReadTool } from './read.js';
 import { WorkspacePathResolver } from './shared/path-resolver.js';
@@ -55,16 +55,16 @@ export class LocalToolRegistry {
                     return { content: JSON.stringify(result), data: result };
                 }
             ],
-            [
-                'exec',
+            ...['exec', 'exec_wait'].map((name) => [
+                name,
                 async (arguments_, context) => {
-                    const result = await this.#exec.execute(arguments_, context.signal, {
+                    const result = await this.#exec.execute(execToolInput(name, arguments_), context.signal, {
                         sessionId: context.sessionId,
                         executionId: context.executionId
                     });
                     return { content: JSON.stringify(result), data: result, truncated: result.truncated };
                 }
-            ],
+            ]),
             ...(web.webSearch
                 ? [
                     [

package/dist/tools/registry.js

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