@myagentroam/agent 0.11.32 → 0.11.34

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

@@ -0,0 +1,338 @@
+import { permissionStopFromError } from '../permissions.js';
+import { RuntimeResourceHandles } from '../runtime-resource-handles.js';
+import { AgentError, describeAgentError } from '../../error.js';
+import { truncateModelText } from '../../runtime/token-budget.js';
+import { TOOL_EXECUTION_LIMITS as limits } from '../execution-limits.js';
+import { waitForToolCondition, waitMetadata } from '../wait.js';
+import { BoundedTextOutput, renderCapturedText } from './text-output.js';
+import { boundObservations, newObservationId } from './observations.js';
+import { selectObservationImages, visibleObservation } from '../../session/code-observation-projection.js';
+/** Keeps a failed tool call observable without discarding earlier explicit output. */
+export class CodeCellExecutionError extends AgentError {
+    result;
+    constructor(error, result) {
+        // Preserve the original chain; the public boundary summarizes its causes only once.
+        const diagnostic = describeAgentError(error, 'MAR_AGENT_CODE_FAILED', undefined, false);
+        super(diagnostic.code, diagnostic.message, {
+            cause: error,
+            ...(error instanceof AgentError ? { retryable: error.retryable } : {})
+        });
+        this.result = result;
+    }
+}
+function options(value, wait) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new AgentError('MAR_AGENT_TOOL_INPUT_INVALID', 'Code Exec options must be an object.');
+    const input = value;
+    const yieldMs = input.yieldMs ?? (wait ? limits.codeDefaultWaitYieldMs : limits.codeDefaultYieldMs);
+    if (!Number.isSafeInteger(yieldMs) ||
+        Number(yieldMs) < 0 ||
+        Number(yieldMs) > (wait ? limits.codeMaxWaitYieldMs : limits.codeMaxYieldMs) ||
+        (wait && (typeof input.cellId !== 'string' || !input.cellId)) ||
+        (input.action !== undefined && input.action !== 'poll' && input.action !== 'cancel'))
+        throw new AgentError('MAR_AGENT_TOOL_INPUT_INVALID', 'Code Exec options are out of range.');
+    return {
+        cellId: input.cellId,
+        yieldMs: Number(yieldMs),
+        action: input.action ?? 'poll'
+    };
+}
+/** Session-owned execution, separate from the cancellable model-tool wait. */
+export class CodeCells {
+    #cells = new Map();
+    #handles = new RuntimeResourceHandles('cell', (id) => this.#cells.has(id));
+    #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 AgentError('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 AgentError)
+                    throw error;
+                throw new AgentError('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 AgentError('MAR_AGENT_CODE_CANCELLED', 'Code Exec resources are being released.');
+        if ([...this.#cells.values()].filter((cell) => cell.status === 'running').length >=
+            limits.codeMaxConcurrentCells)
+            throw new AgentError('MAR_AGENT_PROCESS_LIMIT', `The Local Host shared running-cell limit (${limits.codeMaxConcurrentCells}) was reached.`);
+        const controller = new AbortController();
+        const cell = {
+            cellId: this.#handles.create(),
+            sessionId: context.sessionId,
+            executionId: context.executionId,
+            controller,
+            status: 'running',
+            text: new BoundedTextOutput(limits.codeMaxOutputBytes),
+            images: [],
+            observations: [],
+            calls: new Map(),
+            imageOffset: 0,
+            yielded: false,
+            truncated: 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, waitInterrupt: undefined }, {
+                call: (value) => cell.calls.set(value.callId, value),
+                observe: (value) => cell.observations.push(value),
+                text: (text, originalBytes) => cell.text.append(text, originalBytes),
+                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,
+                    ...(permissionStopFromError(cell.error)
+                        ? { permissionStop: permissionStopFromError(cell.error) }
+                        : {})
+                });
+            }
+            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, context.waitInterrupt);
+    }
+    async wait(value, context) {
+        const input = options(value, true);
+        context.signal.throwIfAborted();
+        this.#handles.assertType(input.cellId);
+        const cell = this.#cells.get(input.cellId);
+        if (!cell || cell.sessionId !== context.sessionId)
+            throw new AgentError('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 AgentError('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, input.action === 'poll' ? context.waitInterrupt : undefined);
+    }
+    async #wait(cell, input, signal, initial, supportsImages, interrupt) {
+        const outcome = input.yieldMs === 0
+            ? undefined
+            : await waitForToolCondition({
+                ready: () => cell.status !== 'running' || cell.yielded,
+                subscribe: (notify) => {
+                    cell.listeners.add(notify);
+                    return () => {
+                        cell.listeners.delete(notify);
+                    };
+                },
+                waitMs: input.yieldMs,
+                signal,
+                interrupt
+            });
+        const wait = waitMetadata(input.yieldMs === 0
+            ? 'snapshot'
+            : cell.status !== 'running'
+                ? 'completion'
+                : cell.yielded
+                    ? 'yield'
+                    : outcome === 'interrupted'
+                        ? 'interrupted'
+                        : 'timeout');
+        signal.throwIfAborted();
+        if (!supportsImages && (cell.images.length || cell.terminal?.images?.length))
+            throw new AgentError('MAR_AGENT_INPUT_CAPABILITY_UNSUPPORTED', 'The current model cannot receive this cell image output.');
+        if (cell.terminal) {
+            if (cell.terminal.observations) {
+                const bounded = boundObservations(cell.terminal.observations, limits.codeMaxOutputTokens);
+                const visible = selectObservationImages(bounded.observations, cell.terminal.images ?? []);
+                const original = cell.terminal.data;
+                const data = {
+                    ...original,
+                    output: truncateModelText(original.output ?? '', limits.codeMaxOutputTokens).content,
+                    observations: visible.observations,
+                    cached: true,
+                    ...wait,
+                    truncated: cell.terminal.truncated === true || bounded.truncated
+                };
+                return {
+                    ...cell.terminal,
+                    observations: visible.observations,
+                    images: visible.images,
+                    content: JSON.stringify({
+                        ...data,
+                        output: undefined,
+                        calls: undefined,
+                        observations: visible.observations.map(visibleObservation)
+                    }),
+                    data,
+                    truncated: data.truncated
+                };
+            }
+            const snapshot = cell.terminal.data;
+            const bounded = truncateModelText(snapshot.output, limits.codeMaxOutputTokens);
+            const data = {
+                ...snapshot,
+                output: bounded.content,
+                truncated: cell.terminal.truncated || bounded.truncated,
+                cached: true,
+                ...wait
+            };
+            return {
+                ...cell.terminal,
+                data,
+                content: JSON.stringify(data),
+                truncated: cell.terminal.truncated || bounded.truncated
+            };
+        }
+        const captured = cell.text.drain();
+        const images = cell.images.splice(0);
+        const text = renderCapturedText(captured, images.length);
+        cell.yielded = false;
+        const bounded = truncateModelText(text, limits.codeMaxOutputTokens);
+        const pending = cell.observations.splice(0);
+        if (!pending.length && captured.text)
+            pending.push({
+                type: 'value',
+                id: newObservationId(),
+                format: 'text',
+                value: captured.text,
+                truncated: captured.droppedBytes > 0
+            });
+        const structured = boundObservations(pending, limits.codeMaxOutputTokens);
+        const visible = selectObservationImages(structured.observations, images, cell.imageOffset);
+        const remapped = visible.observations;
+        const visibleImages = visible.images;
+        cell.imageOffset += images.length;
+        cell.truncated ||= captured.droppedBytes > 0 || bounded.truncated || structured.truncated;
+        const error = cell.error === undefined
+            ? undefined
+            : describeAgentError(cell.error, 'MAR_AGENT_CODE_FAILED');
+        const data = {
+            cellId: cell.cellId,
+            status: cell.status,
+            ...wait,
+            ...(permissionStopFromError(cell.error)
+                ? { permissionStop: permissionStopFromError(cell.error) }
+                : {}),
+            output: bounded.content,
+            observations: remapped,
+            calls: [...cell.calls.values()],
+            ...cell.result?.data,
+            outputBytes: captured.originalBytes,
+            outputDroppedBytes: captured.droppedBytes,
+            truncated: cell.truncated,
+            ...(error ? { error: { code: error.code, message: error.message } } : {}),
+            cached: false
+        };
+        const result = {
+            content: JSON.stringify({
+                ...data,
+                output: undefined,
+                calls: undefined,
+                observations: remapped.map(visibleObservation)
+            }),
+            calls: [...cell.calls.values()],
+            observations: remapped,
+            data,
+            truncated: cell.truncated || structured.truncated,
+            ...(visibleImages.length ? { images: visibleImages } : {})
+        };
+        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 new CodeCellExecutionError(cell.error, result);
+            return result;
+        }
+        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 AgentError('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,20 @@
+import type { ClientToolDefinition } from '../contracts.js';
+import type { AgentEvent } from '../../runtime/events.js';
+import type { McpToolCallContext, ToolCall, ToolExecutionResult } from '../contracts.js';
+import type { ToolRuntimeContext } from '../runtime-context.js';
+import type { createSessionToolScheduler } from '../scheduler.js';
+type ToolEvent = Extract<AgentEvent, {
+    type: 'tool.started' | 'tool.output' | '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>;
+    assertLive: () => void;
+    emit: (event: Payload) => Promise<void>;
+}): (call: ToolCall, signal: AbortSignal) => Promise<ToolExecutionResult>;
+export {};

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

@@ -0,0 +1,80 @@
+import { randomUUID } from 'node:crypto';
+import { AgentError, describeAgentError } from '../../error.js';
+import { toolEventSummary } from '../../runtime/event-projection.js';
+import { allowsToolCaller } from '../callers.js';
+import { boundedModelToolOutput, structuredToolEventData, structuredToolFailureData } from '../output-projection.js';
+import { executeRegisteredTool } from '../runtime.js';
+import { failedToolResultExtensions } from '../result-extensions.js';
+import { permissionStopFromError } from '../permissions.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) => {
+        input.assertLive();
+        const definition = definitions.get(call.name);
+        if (!definition || !allowsToolCaller(definition, 'programmatic'))
+            throw new AgentError('MAR_AGENT_TOOL_NOT_AVAILABLE', 'The requested nested tool is unavailable.');
+        return input.schedule(definition, async () => {
+            input.assertLive();
+            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 {
+                input.assertLive();
+                signal.throwIfAborted();
+                const expected = input.expectations.get(call.name);
+                const result = await executeRegisteredTool(call.name, call.arguments, callId, {
+                    ...input.context,
+                    emit: (event) => event.type === 'tool.output' ? input.emit(event) : input.context.emit(event),
+                    parentCallId: input.parentCallId,
+                    signal,
+                    ...(expected ? { expectedMcpTool: expected } : {})
+                }, 'programmatic');
+                const bounded = boundedModelToolOutput(call.name, result.content, result.data);
+                const data = structuredToolEventData(call.name, result.data);
+                const preview = toolEventSummary(result.content);
+                input.assertLive();
+                await input.emit({
+                    type: 'tool.completed',
+                    ...(result.resultExtensions ? { resultExtensions: result.resultExtensions } : {}),
+                    ...identity,
+                    summary: preview.summary,
+                    ...(data === undefined ? {} : { data }),
+                    truncated: result.truncated === true || bounded.truncated || preview.truncated,
+                    ...(result.artifacts ? { artifacts: result.artifacts } : {})
+                });
+                return {
+                    ...result,
+                    content: bounded.content,
+                    truncated: result.truncated === true || bounded.truncated
+                };
+            }
+            catch (error) {
+                // Retirement must not enqueue a failure event into the replacement Session epoch.
+                try {
+                    input.assertLive();
+                }
+                catch {
+                    throw error;
+                }
+                const diagnostic = describeAgentError(error, 'MAR_AGENT_HOST_OPERATION_FAILED');
+                const data = structuredToolFailureData(call.name, error);
+                await input.emit({
+                    type: 'tool.failed',
+                    ...(failedToolResultExtensions(error)
+                        ? { resultExtensions: failedToolResultExtensions(error) }
+                        : {}),
+                    ...identity,
+                    code: diagnostic.code,
+                    message: diagnostic.message,
+                    ...(permissionStopFromError(error)
+                        ? { permissionStop: permissionStopFromError(error) }
+                        : {}),
+                    ...(data === undefined ? {} : { data })
+                });
+                throw error;
+            }
+        });
+    };
+}

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

@@ -0,0 +1,60 @@
+import type { ToolCall, ToolExecutionResult } from '../contracts.js';
+import type { CodeModeStateEntry, CodeModeStateMutation } from '../../session/code-state.js';
+export type ProgrammaticToolResult = Omit<ToolExecutionResult, 'content'> & {
+    content?: string;
+};
+export interface CodeModeCatalogEntry {
+    readonly name: string;
+    readonly description: string;
+    readonly inputSchema: unknown;
+    readonly inputMode: 'json' | 'freeform';
+}
+/** A trusted, replaceable worker-side engine; no engine handles cross this interface. */
+export interface CodeModeEngine {
+    execute(input: {
+        code: string;
+        tools: readonly string[];
+        catalog: readonly CodeModeCatalogEntry[];
+        state: readonly CodeModeStateEntry[];
+        signal: AbortSignal;
+        limits: {
+            memoryBytes: number;
+            stackBytes: number;
+            /** Cumulative synchronous guest execution budget; asynchronous waiting is excluded. */
+            timeoutMs: number;
+            outputBytes: number;
+            stateEntries: number;
+            stateMutations: number;
+            stateKeyBytes: number;
+            stateValueBytes: number;
+            stateTotalBytes: number;
+            sleepMs: number;
+        };
+        onToolCall(call: ToolCall): Promise<ProgrammaticToolResult>;
+        onText(value: string, originalBytes?: number): void;
+        onImage(value: unknown): void;
+        onObserve(value: {
+            type: 'tool_result';
+            operationId: string;
+        } | {
+            type: 'value';
+            format: 'text' | 'json';
+            value: string;
+            originalBytes: number;
+        } | {
+            type: 'image';
+            value: unknown;
+        }): void;
+        onYield(): void;
+    }): Promise<{
+        readonly stateMutations: readonly CodeModeStateMutation[];
+    }>;
+    dispose(): Promise<void>;
+}
+/** Only the Local Host may supply this descriptor; it is never part of model tool input. */
+export interface CodeModeEngineFactory {
+    readonly moduleUrl: string;
+    readonly runtimeDirectories: readonly string[];
+    readonly options?: Readonly<Record<string, unknown>>;
+}
+export type CreateCodeModeEngine = (options: Readonly<Record<string, unknown>>) => Promise<CodeModeEngine>;

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

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,31 @@
+import type { ClientToolDefinition } from '../contracts.js';
+import type { SessionModelMessage as ModelMessage } from '../../session/model-request.js';
+import type { LocalProcessExecutor } from '../../process/contracts.js';
+import { type CellOutput } from './cells.js';
+import type { CodeModeEngineFactory } from './engine.js';
+import type { ToolExecutionContext, ToolExecutionResult } from '../contracts.js';
+import { WorkspacePathResolver } from '../shared/path-resolver.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. */
+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 signalProcessTree;
+    private readonly engineFactory;
+    start(value: unknown, context: ToolExecutionContext): Promise<ToolExecutionResult>;
+    wait(value: unknown, context: ToolExecutionContext): Promise<ToolExecutionResult>;
+    listSessionResources(sessionId: string): {
+        cellId: string;
+        status: "completed" | "failed" | "cancelled" | "running";
+        executionId: string;
+    }[];
+    constructor(paths: WorkspacePathResolver, environment: NodeJS.ProcessEnv | undefined, executor: LocalProcessExecutor, signalProcessTree: (child: import('node:child_process').ChildProcessWithoutNullStreams, signal: NodeJS.Signals) => Promise<void>, engineFactory?: CodeModeEngineFactory);
+    execute(value: unknown, context: ToolExecutionContext, output?: CellOutput): Promise<ToolExecutionResult>;
+    dispose(sessionId?: string): Promise<void>;
+}