@myagentroam/agent 0.9.137 → 0.9.138

package/dist/session/jsonl-store.js

@@ -157,6 +157,9 @@ export class JsonlSessionStore {
             indexDirty: false,
             dirtySessionVersions: new Map(),
             pendingPublishIds: new Set(),
+            codeStateWrites: new Map(),
+            recordWrites: new Map(),
+            writerLeases: new Map(),
             segments: new Map(),
             executionModelReads: new Map()
         };
@@ -897,6 +900,22 @@ export class JsonlSessionStore {
         };
     }
     async append(sessionId, input) {
+        return this.#serializeRecordOperation(sessionId, () => this.#appendRecord(sessionId, input));
+    }
+    async #serializeRecordOperation(sessionId, action) {
+        const operation = (this.#shared.recordWrites.get(sessionId) ?? Promise.resolve())
+            .catch(() => undefined)
+            .then(action);
+        this.#shared.recordWrites.set(sessionId, operation);
+        try {
+            return await operation;
+        }
+        finally {
+            if (this.#shared.recordWrites.get(sessionId) === operation)
+                this.#shared.recordWrites.delete(sessionId);
+        }
+    }
+    async #appendRecord(sessionId, input) {
         this.#assertOpen();
         const meta = this.#shared.index.sessions.find((item) => item.id === sessionId) ??
             this.#shared.pendingSessions.get(sessionId);
@@ -974,6 +993,9 @@ export class JsonlSessionStore {
         return record;
     }
     async read(sessionId) {
+        return this.#serializeRecordOperation(sessionId, () => this.#readRecords(sessionId));
+    }
+    async #readRecords(sessionId) {
         this.#assertOpen();
         try {
             const records = [];
@@ -991,17 +1013,32 @@ export class JsonlSessionStore {
         return restoreCodeModeState(await this.read(sessionId));
     }
     async commitCodeModeState(sessionId, mutations, input) {
-        const parsed = parseCodeModeStateMutations(mutations);
-        if (parsed.length === 0)
-            return this.readCodeModeState(sessionId);
-        const state = applyCodeModeStateMutations(await this.readCodeModeState(sessionId), parsed);
-        await this.append(sessionId, {
-            type: 'code.state.updated',
-            payload: { mutations: parsed },
-            executionId: input.executionId,
-            turnId: input.turnId
+        const operation = (this.#shared.codeStateWrites.get(sessionId) ?? Promise.resolve())
+            .catch(() => undefined)
+            .then(async () => {
+            const parsed = parseCodeModeStateMutations(mutations);
+            if (parsed.length === 0)
+                return this.readCodeModeState(sessionId);
+            const current = await this.readCodeModeState(sessionId);
+            if (input.expectedState && !isDeepStrictEqual(current, input.expectedState))
+                throw new MarAgentError('MAR_AGENT_CODE_STATE_CONFLICT', 'Session state changed while this cell was running.');
+            const state = applyCodeModeStateMutations(current, parsed);
+            await this.append(sessionId, {
+                type: 'code.state.updated',
+                payload: { mutations: parsed },
+                executionId: input.executionId,
+                turnId: input.turnId
+            });
+            return state;
         });
-        return state;
+        this.#shared.codeStateWrites.set(sessionId, operation);
+        try {
+            return await operation;
+        }
+        finally {
+            if (this.#shared.codeStateWrites.get(sessionId) === operation)
+                this.#shared.codeStateWrites.delete(sessionId);
+        }
     }
     async readExecutionState(sessionId) {
         this.#assertOpen();
@@ -1155,8 +1192,64 @@ export class JsonlSessionStore {
             ...(input.turnId ? { turnId: input.turnId } : {})
         });
     }
+    /** A warm cell retains physical writer ownership between Executions of the same Agent. */
+    async acquireSessionLease(sessionId, owner) {
+        return this.#serializeRecordOperation(sessionId, async () => {
+            this.#assertOpen();
+            let lease = this.#shared.writerLeases.get(sessionId);
+            if (lease) {
+                if (lease.executing || owner === undefined || lease.owner !== owner)
+                    throw new MarAgentError('MAR_AGENT_SESSION_LOCKED', 'Session already has a writer.');
+                lease.executing = true;
+            }
+            else {
+                const release = await this.#acquireSessionLease(sessionId);
+                lease = { owner, executing: true, retained: 0, release };
+                this.#shared.writerLeases.set(sessionId, lease);
+            }
+            const current = lease;
+            let released = false;
+            return () => this.#serializeRecordOperation(sessionId, async () => {
+                if (released)
+                    return;
+                released = true;
+                current.executing = false;
+                await this.#releaseUnusedWriter(sessionId, current);
+            });
+        });
+    }
+    hasRetainedSessionLease(sessionId, owner) {
+        const lease = this.#shared.writerLeases.get(sessionId);
+        return lease?.owner === owner && lease.retained > 0;
+    }
+    async retainSessionLease(sessionId, owner) {
+        return this.#serializeRecordOperation(sessionId, async () => {
+            const lease = this.#shared.writerLeases.get(sessionId);
+            if (!lease || !lease.executing || lease.owner !== owner)
+                throw new MarAgentError('MAR_AGENT_SESSION_LOCKED', 'Retained work requires its originating Session writer.');
+            lease.retained++;
+            let released = false;
+            return () => this.#serializeRecordOperation(sessionId, async () => {
+                if (released)
+                    return;
+                released = true;
+                lease.retained--;
+                await this.#releaseUnusedWriter(sessionId, lease);
+            });
+        });
+    }
+    async #releaseUnusedWriter(sessionId, lease) {
+        if (lease.executing || lease.retained)
+            return;
+        try {
+            await lease.release();
+        }
+        finally {
+            this.#shared.writerLeases.delete(sessionId);
+        }
+    }
     /** Recover files under the sole writer lock; flush dirty index state before releasing it. */
-    async acquireSessionLease(sessionId) {
+    async #acquireSessionLease(sessionId) {
         this.#assertOpen();
         await this.#refreshIndex();
         if (!this.#shared.index.sessions.some((item) => item.id === sessionId))
@@ -1509,7 +1602,7 @@ export class JsonlSessionStore {
         const latestPath = paths.at(-1);
         await repairSegmentTail(latestPath);
         const records = await readRecords(latestPath);
-        await recoverPendingInputImages(this.sessionDirectory(sessionId), () => this.read(sessionId));
+        await recoverPendingInputImages(this.sessionDirectory(sessionId), () => this.#readRecords(sessionId));
         const last = records.at(-1);
         const match = /events-(\d{6})\.jsonl$/.exec(latestPath);
         const segment = Number(match?.[1] ?? 1);

package/dist/subagent/session-controller.d.ts

@@ -83,6 +83,8 @@ export declare class SubagentSessionController implements SubagentController {
         };
     }): Promise<SubagentSessionController>;
     beginParentExecution(execution: SubagentParentExecution): Promise<void>;
+    /** A retained cell must not borrow a later model Execution's identity or task budget. */
+    captureExecution(): SubagentController;
     endParentExecution(executionId: string): void;
     run(input: SubagentTaskInput, options?: SubagentRunOptions): Promise<SubagentTaskSnapshot>;
     output(agentId: string, options?: SubagentOutputOptions): Promise<SubagentTaskSnapshot>;

package/dist/subagent/session-controller.js

@@ -1,3 +1,4 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
 import { randomUUID } from 'node:crypto';
 import { MarAgentError, describeMarAgentError } from '../error.js';
 import { TOOL_EXECUTION_LIMITS } from '../tools/execution-limits.js';
@@ -14,7 +15,8 @@ export class SubagentSessionController {
     #resourceRevision = 0;
     #running = 0;
     #disposed = false;
-    #createdInExecution = 0;
+    #creationBudget = { count: 0 };
+    #retainedExecution = new AsyncLocalStorage();
     #execution;
     constructor(parentSessionId, rootSessionId, backend, limits = { maxTasks: 8, maxConcurrent: 4 }) {
         this.parentSessionId = parentSessionId;
@@ -36,10 +38,23 @@ export class SubagentSessionController {
         if (this.#disposed)
             throw new MarAgentError('MAR_AGENT_SUBAGENT_LIMIT', 'Subagent controller is disposed.');
         this.#execution = execution;
-        this.#createdInExecution = 0;
+        this.#creationBudget = { count: 0 };
         for (const state of this.#agents.values())
             await this.#publishTerminal(state);
     }
+    /** A retained cell must not borrow a later model Execution's identity or task budget. */
+    captureExecution() {
+        const context = { execution: this.#requireExecution(), budget: this.#creationBudget };
+        return {
+            run: (input, options) => this.#retainedExecution.run(context, () => this.run(input, options)),
+            message: (id, message, options) => this.#retainedExecution.run(context, () => this.message(id, message, options)),
+            output: (id, options) => this.output(id, options),
+            outputAny: (options) => this.outputAny(options),
+            cancel: (id) => this.cancel(id),
+            listSessionResources: () => this.listSessionResources(),
+            dispose: () => this.dispose()
+        };
+    }
     endParentExecution(executionId) {
         if (this.#execution?.executionId === executionId)
             this.#execution = undefined;
@@ -48,7 +63,8 @@ export class SubagentSessionController {
         options.signal?.throwIfAborted();
         const execution = this.#requireExecution();
         validateTaskInput(input);
-        if (this.#createdInExecution >= this.limits.maxTasks)
+        if ((this.#retainedExecution.getStore()?.budget ?? this.#creationBudget).count >=
+            this.limits.maxTasks)
             throw new MarAgentError('MAR_AGENT_SUBAGENT_LIMIT', 'Subagent task limit was reached.');
         const source = {
             type: 'subagent',
@@ -85,7 +101,7 @@ export class SubagentSessionController {
             terminalObserved: false,
             resourceRevision: ++this.#resourceRevision
         };
-        this.#createdInExecution++;
+        (this.#retainedExecution.getStore()?.budget ?? this.#creationBudget).count++;
         this.#agents.set(state.agentId, state);
         const knownModel = execution.models.get(input.modelId ?? execution.modelId);
         if (knownModel) {
@@ -589,9 +605,10 @@ export class SubagentSessionController {
     #requireExecution() {
         if (this.#disposed)
             throw new MarAgentError('MAR_AGENT_DISPOSED', 'Subagent controller is disposed.');
-        if (!this.#execution)
+        const execution = this.#retainedExecution.getStore()?.execution ?? this.#execution;
+        if (!execution)
             throw new MarAgentError('MAR_AGENT_SUBAGENT_FAILED', 'Subagent control requires an active parent execution.');
-        return this.#execution;
+        return execution;
     }
     #receiptSnapshot(state) {
         return this.#snapshot(state, {

package/dist/tools/callers.js

@@ -12,7 +12,8 @@ export function toolCallers(tool) {
 }
 export function allowsToolCaller(tool, caller) {
     // Control tools cannot be widened by a Host override or historical definition.
-    if (caller === 'programmatic' && ['code_mode', 'tool_search', 'question'].includes(tool.name))
+    if (caller === 'programmatic' &&
+        ['code_exec', 'code_exec_wait', 'code_mode', 'tool_search', 'question'].includes(tool.name))
         return false;
     return toolCallers(tool).includes(caller);
 }

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

@@ -0,0 +1,20 @@
+import type { ToolExecutionContext, ToolExecutionResult } from '../../sdk/types.js';
+export interface CellOutput {
+    text(value: string): void;
+    image(value: NonNullable<ToolExecutionResult['images']>[number]): void;
+    yield(): void;
+}
+type Status = 'running' | 'completed' | 'failed' | 'cancelled';
+/** Session-owned execution, separate from the cancellable model-tool wait. */
+export declare class CodeCells {
+    #private;
+    start(value: unknown, context: ToolExecutionContext, run: (code: string, context: ToolExecutionContext, output: CellOutput) => Promise<ToolExecutionResult>): Promise<ToolExecutionResult>;
+    wait(value: unknown, context: ToolExecutionContext): Promise<ToolExecutionResult>;
+    snapshot(sessionId: string): {
+        cellId: string;
+        status: Status;
+        executionId: string;
+    }[];
+    dispose(sessionId?: string): Promise<void>;
+}
+export {};

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

@@ -3,7 +3,9 @@ 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;
+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. */
@@ -14,7 +16,14 @@ export declare class CodeModeTool {
     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>;
 }