@myagentroam/agent 0.9.141 → 0.9.143

package/dist/{tools → agent-core/tools}/code-mode/quickjs-engine.js

@@ -29,6 +29,7 @@ export async function createCodeModeEngine(options) {
             const stateMutations = [];
             let outputBytes = 0;
             let textCalls = 0;
+            const origins = [];
             const notify = () => {
                 wake?.();
                 wake = undefined;
@@ -72,6 +73,28 @@ export async function createCodeModeEngine(options) {
           });
         };
         globalThis.__text = ${streamText.toString()};
+        globalThis.__snapshot = (() => {
+          const keys = Reflect.ownKeys, descriptor = Object.getOwnPropertyDescriptor;
+          const create = Object.create, stringify = JSON.stringify;
+          return (value, errorSnapshot) => {
+            const seen = create(null); let depth = 0;
+            function walk(item) {
+              if (item === null || typeof item === 'string' || typeof item === 'number' || typeof item === 'boolean') return stringify(item);
+              if (typeof item !== 'object') throw new Error('Not an original JSON object.');
+              for (let i = 0; i < depth; i++) if (seen[i] === item) throw new Error('Cyclic object.');
+              seen[depth++] = item;
+              const names = keys(item); let text = '{';
+              for (let i = 0; i < names.length; i++) {
+                const name = names[i], field = descriptor(item, name);
+                if (errorSnapshot && depth === 1 && name !== 'code' && name !== 'message' && name !== 'name') continue;
+                if (typeof name !== 'string' || !field || !('value' in field)) throw new Error('Accessor object.');
+                text += stringify(name) + ':' + Number(field.enumerable) + Number(field.writable) + Number(field.configurable) + walk(field.value) + ';';
+              }
+              depth--; return text + '}';
+            }
+            try { return walk(value); } catch { return ''; }
+          };
+        })();
         globalThis.__deepFreeze = function deepFreeze(value) {
           if (value && typeof value === 'object' && !Object.isFrozen(value)) {
             for (const item of Object.values(value)) deepFreeze(item);
@@ -86,6 +109,20 @@ export async function createCodeModeEngine(options) {
             const parseJson = vm.getProp(vm.global, '__parseJson');
             const serialize = vm.getProp(vm.global, '__serialize');
             const formatText = vm.getProp(vm.global, '__text');
+            const snapshotFunction = vm.getProp(vm.global, '__snapshot');
+            const snapshot = (handle, errorSnapshot = false) => {
+                const value = vm.callFunction(snapshotFunction, vm.undefined, handle, errorSnapshot ? vm.true : vm.false);
+                if (value.error) {
+                    value.error.dispose();
+                    return '';
+                }
+                try {
+                    return vm.getString(value.value);
+                }
+                finally {
+                    value.value.dispose();
+                }
+            };
             const deepFreeze = vm.getProp(vm.global, '__deepFreeze');
             const parse = (value) => {
                 const handle = vm.newString(JSON.stringify(value));
@@ -142,11 +179,17 @@ export async function createCodeModeEngine(options) {
                     const deferred = vm.newPromise();
                     deferreds.add(deferred);
                     const job = Promise.resolve()
-                        .then(() => input.onToolCall({ name, arguments: parsed.value }))
+                        .then(() => input.onToolCall({ name, arguments: parsed.value, callId: String(operationId) }))
                         .then((output) => {
                         if (disposed || input.signal.aborted)
                             return;
                         const handle = parse(output);
+                        origins.push({
+                            handle: handle.dup(),
+                            snapshot: snapshot(handle),
+                            errorSnapshot: false,
+                            operationId: String(operationId)
+                        });
                         try {
                             deferred.resolve(handle);
                         }
@@ -163,6 +206,12 @@ export async function createCodeModeEngine(options) {
                         const code = vm.newString(String(error?.code ?? 'MAR_AGENT_HOST_OPERATION_FAILED'));
                         vm.setProp(handle, 'code', code);
                         code.dispose();
+                        origins.push({
+                            handle: handle.dup(),
+                            snapshot: snapshot(handle, true),
+                            errorSnapshot: true,
+                            operationId: String(operationId)
+                        });
                         try {
                             deferred.reject(handle);
                         }
@@ -198,8 +247,28 @@ export async function createCodeModeEngine(options) {
             });
             vm.setProp(vm.global, '__consumeToolCall', consumeToolCall);
             consumeToolCall.dispose();
-            const out = vm.newObject();
-            method(out, 'text', (handle) => {
+            const observeValue = (handle, kind) => {
+                for (const origin of origins) {
+                    if (handle &&
+                        vm.eq(handle, origin.handle) &&
+                        origin.snapshot &&
+                        snapshot(handle, origin.errorSnapshot) === origin.snapshot) {
+                        input.onObserve({ type: 'tool_result', operationId: origin.operationId });
+                        return vm.undefined;
+                    }
+                }
+                if (kind === 'result')
+                    return {
+                        error: guestError('MAR_AGENT_TOOL_INPUT_INVALID', 'observe.result requires an unmodified original tool result or error.')
+                    };
+                // A standalone image is a value, never an original tool-result observation.
+                if (kind === 'image') {
+                    const parsed = jsonValue(handle);
+                    if (parsed.error)
+                        return parsed;
+                    input.onObserve({ type: 'image', value: parsed.value });
+                    return 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) => {
@@ -225,22 +294,23 @@ export async function createCodeModeEngine(options) {
                     const captured = capture.snapshot();
                     outputBytes += captured.retainedBytes + separatorBytes;
                     textCalls++;
-                    input.onText(captured.text, captured.originalBytes);
+                    input.onObserve({
+                        type: 'value',
+                        format: handle && vm.typeof(handle) === 'object' ? 'json' : 'text',
+                        value: captured.text,
+                        originalBytes: captured.originalBytes
+                    });
                 }
                 finally {
                     result.value.dispose();
                 }
                 return vm.undefined;
-            });
-            method(out, 'image', (handle) => {
-                const parsed = jsonValue(handle ?? vm.undefined);
-                if (parsed.error)
-                    return parsed;
-                input.onImage(parsed.value);
-                return vm.undefined;
-            });
-            vm.setProp(vm.global, 'out', out);
-            out.dispose();
+            };
+            const observe = vm.newObject();
+            for (const kind of ['result', 'text', 'image'])
+                method(observe, kind, (handle) => observeValue(handle, kind));
+            vm.setProp(vm.global, 'observe', observe);
+            observe.dispose();
             const stateObject = vm.newObject();
             method(stateObject, 'get', (keyHandle) => {
                 const parsed = key(keyHandle);
@@ -384,7 +454,7 @@ export async function createCodeModeEngine(options) {
               { code: 'MAR_AGENT_TOOL_NOT_AVAILABLE' }); };
           return target[name];
         }});
-        for (const name of ['tools', 'out', 'state', 'catalog', 'cell']) {
+        for (const name of ['tools', 'observe', 'state', 'catalog', 'cell']) {
           const value = globalThis[name];
           Object.freeze(value);
           Object.defineProperty(globalThis, name, {
@@ -394,6 +464,7 @@ export async function createCodeModeEngine(options) {
         delete globalThis.__parseJson;
         delete globalThis.__serialize;
         delete globalThis.__text;
+        delete globalThis.__snapshot;
         delete globalThis.__deepFreeze;
         delete globalThis.__consumeToolCall;
       `);
@@ -449,6 +520,9 @@ export async function createCodeModeEngine(options) {
                 parseJson.dispose();
                 serialize.dispose();
                 formatText.dispose();
+                snapshotFunction.dispose();
+                for (const origin of origins)
+                    origin.handle.dispose();
                 deepFreeze.dispose();
             }
         },
@@ -528,7 +602,7 @@ function streamText(value, emit) {
             emit('{');
             let first = true;
             const names = Object.keys(item);
-            // Special-case view_image and native MCP image objects: text omits Base64; out.image keeps pixels.
+            // Special-case view_image and native MCP image objects: text omits Base64; observe.image keeps pixels.
             const imagePayload = names.includes('mimeType') &&
                 typeof item.mimeType === 'string' &&
                 item.mimeType.startsWith('image/');
@@ -542,7 +616,7 @@ function streamText(value, emit) {
                 write(imagePayload &&
                     (name === 'dataBase64' || (name === 'data' && item.type === 'image')) &&
                     typeof field === 'string'
-                    ? '[image payload omitted; use out.image]'
+                    ? '[image payload omitted; use observe.image]'
                     : field, name);
             }
             emit('}');

package/dist/{tools → agent-core/tools}/code-mode/state.d.ts

@@ -1,15 +1,5 @@
-export interface CodeModeStateEntry {
-    readonly key: string;
-    readonly value: unknown;
-}
-export type CodeModeStateMutation = {
-    readonly operation: 'set';
-    readonly key: string;
-    readonly value: unknown;
-} | {
-    readonly operation: 'delete';
-    readonly key: string;
-};
+import type { CodeModeStateEntry, CodeModeStateMutation } from '../contracts.js';
+export type { CodeModeStateEntry, CodeModeStateMutation } from '../contracts.js';
 type StateRecord = {
     readonly type: string;
     readonly payload: unknown;
@@ -17,4 +7,3 @@ type StateRecord = {
 export declare function parseCodeModeStateMutations(value: unknown): CodeModeStateMutation[];
 export declare function restoreCodeModeState(records: readonly StateRecord[]): CodeModeStateEntry[];
 export declare function applyCodeModeStateMutations(entries: readonly CodeModeStateEntry[], mutations: readonly CodeModeStateMutation[]): CodeModeStateEntry[];
-export {};

package/dist/agent-core/tools/code-mode/worker.d.ts

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

package/dist/{tools → agent-core/tools}/code-mode/worker.js

@@ -34,10 +34,17 @@ lines.on('line', async (line) => {
             onText: (value, originalBytes) => send({ kind: 'text', value, originalBytes }),
             onImage: (value) => send({ kind: 'image', value }),
             onYield: () => send({ kind: 'yield' }),
+            onObserve: (value) => send({ kind: 'observe', observation: value }),
             onToolCall: (call) => new Promise((resolve, reject) => {
                 const id = ++sequence;
                 pending.set(id, { resolve, reject });
-                send({ kind: 'call', id, name: call.name, arguments: call.arguments });
+                send({
+                    kind: 'call',
+                    id,
+                    operationId: call.callId,
+                    name: call.name,
+                    arguments: call.arguments
+                });
             })
         });
         if (pending.size)

package/dist/agent-core/tools/contracts.d.ts

@@ -0,0 +1,172 @@
+import type { ExecutionMode } from '../runtime/contracts.js';
+export type ToolCaller = 'direct' | 'programmatic';
+export interface ClientToolDefinition {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+    /** Runtime-only provider lowering hint; unsupported adapters fall back to a normal function tool. */
+    nativeType?: 'tool_search';
+    /** Runtime-only result contract; never forwarded as an upstream tool field. */
+    outputSchema?: Record<string, unknown>;
+    /** Runtime-only policy. MCP defaults to both callers; other tools default to direct only. */
+    allowedCallers?: readonly ToolCaller[];
+    inputMode?: 'json' | 'freeform';
+    parallelSafety?: 'safe' | 'serial';
+    /** Runtime-only Agent catalog scope; never forwarded as an upstream tool field. */
+    agentScope?: 'ROOT_AND_SUBAGENTS' | 'ROOT_ONLY';
+}
+export interface ToolCall {
+    name: string;
+    arguments: unknown;
+    callId?: string;
+}
+export interface ToolExecutionContext {
+    mode: ExecutionMode;
+    signal: AbortSignal;
+    sessionId: string;
+    executionId: string;
+    recentImages?: readonly {
+        readonly mimeType: string;
+        readonly data: Buffer;
+    }[];
+    codeMode?: {
+        retainSession?(): Promise<() => Promise<void>>;
+        onSettled?(result: CodeCellEventData): Promise<void>;
+        supportsImages?: boolean;
+        tools: readonly ClientToolDefinition[];
+        state?: readonly CodeModeStateEntry[];
+        commitState?(mutations: readonly CodeModeStateMutation[]): Promise<readonly CodeModeStateEntry[]>;
+        invoke(call: ToolCall, signal: AbortSignal): Promise<ToolExecutionResult>;
+    };
+}
+export interface McpToolCatalogContext extends Pick<ToolExecutionContext, 'sessionId' | 'executionId'> {
+    executionScopeId?: string;
+    claimExecutionScope?: boolean;
+}
+export interface McpToolCatalog {
+    readonly revision: string;
+    readonly servers: readonly {
+        readonly id: string;
+        readonly name: string;
+        readonly description?: string;
+        readonly instructions?: string;
+    }[];
+    readonly tools: readonly McpCatalogTool[];
+}
+export interface McpCatalogTool {
+    readonly definition: ClientToolDefinition;
+    readonly serverId: string;
+    readonly rawName: string;
+    readonly sourceIdentity: string;
+    readonly definitionRevision: string;
+    readonly lifetime: 'session' | 'execution';
+    readonly exposure: 'direct' | 'deferred';
+    /** Untrusted MCP hints; never an authorization or parallel-safety decision. */
+    readonly annotations?: Readonly<Record<string, unknown>>;
+}
+export interface McpToolCallContext extends Pick<ToolExecutionContext, 'sessionId' | 'executionId'> {
+    readonly mode?: ExecutionMode;
+    readonly expectedTool?: {
+        readonly sourceIdentity: string;
+        readonly definitionRevision: string;
+    };
+}
+export interface MarAgentToolImageArtifact {
+    kind: 'image';
+    name: string;
+    mimeType: 'image/png';
+    byteSize: number;
+    sha256: string;
+    fileName: string;
+}
+export type MarAgentToolArtifact = MarAgentToolImageArtifact;
+export interface ToolExecutionResult {
+    calls?: readonly import('./code-mode/observations.js').CodeToolCallRecord[];
+    content: string;
+    observations?: readonly import('./code-mode/observations.js').CodeObservation[];
+    data?: unknown;
+    /** Runtime-only definitions used to encode a Tool Search output. */
+    toolSearchTools?: readonly ClientToolDefinition[];
+    truncated?: boolean;
+    images?: readonly {
+        mimeType: string;
+        dataBase64: string;
+    }[];
+    artifacts?: readonly MarAgentToolArtifact[];
+}
+export interface CodeCellEventData {
+    calls?: readonly import('./code-mode/observations.js').CodeToolCallRecord[];
+    cellId: string;
+    status: 'running' | 'completed' | 'failed' | 'cancelled';
+    cached?: boolean;
+    observations?: readonly import('./code-mode/observations.js').CodeObservation[];
+}
+export interface ExecResult {
+    status: 'running' | 'completed' | 'cancelled';
+    processId?: string;
+    stdout: string;
+    stderr: string;
+    exitCode?: number | null;
+    truncated: boolean;
+    stdoutBytes: number;
+    stderrBytes: number;
+    stdoutDroppedBytes: number;
+    stderrDroppedBytes: number;
+    /** A terminal snapshot replay rather than new process output. */
+    cached?: boolean;
+}
+export interface ApplyPatchFileResult {
+    path: string;
+    targetPath?: string;
+    operation: 'added' | 'modified' | 'deleted' | 'moved';
+    addedLines: number;
+    deletedLines: number;
+}
+export interface ApplyPatchResult {
+    files: ApplyPatchFileResult[];
+    totals: {
+        files: number;
+        addedLines: number;
+        deletedLines: number;
+    };
+}
+export interface ReadEventData {
+    mode: 'batch';
+    results: Array<{
+        path: string;
+        startLine?: number;
+        endLine?: number;
+        error?: {
+            code: string;
+            message: string;
+        };
+    }>;
+    truncated: boolean;
+}
+export interface ViewImageResult {
+    path: string;
+    mimeType: 'image/png' | 'image/jpeg' | 'image/webp';
+    bytes: number;
+    sha256: string;
+}
+export interface TodoItem {
+    id: string;
+    step: string;
+    status: 'pending' | 'in_progress' | 'completed';
+}
+export interface TodoSnapshot {
+    revision: number;
+    items: TodoItem[];
+}
+export interface CodeModeStateEntry {
+    readonly key: string;
+    readonly value: unknown;
+}
+export type CodeModeStateMutation = {
+    readonly operation: 'set';
+    readonly key: string;
+    readonly value: unknown;
+} | {
+    readonly operation: 'delete';
+    readonly key: string;
+};

package/dist/agent-core/tools/contracts.js

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

package/dist/agent-core/tools/execution.d.ts

@@ -0,0 +1,36 @@
+import type { ModelEvent } from '../model/contracts.js';
+import type { EventPayload } from '../runtime/events.js';
+import type { ClientToolDefinition, McpToolCallContext, ToolExecutionContext, ToolExecutionResult } from './contracts.js';
+import type { ToolRuntimeContext, ToolRuntimeImage } from './runtime-context.js';
+import { type createSessionToolScheduler } from './scheduler.js';
+export type ClientToolCall = Extract<ModelEvent, {
+    type: 'client_tool.call';
+}>;
+export type ExecutedToolCall = {
+    call: ClientToolCall;
+    content: string;
+    images?: ToolExecutionResult['images'];
+    observations?: ToolExecutionResult['observations'];
+    calls?: ToolExecutionResult['calls'];
+} & ({
+    failed: false;
+    output: ToolExecutionResult;
+} | {
+    failed: true;
+    error: unknown;
+});
+/** One immutable model round's catalog; execution resources remain owned by the SDK/Host. */
+export interface RoundToolScope {
+    readonly context: Omit<ToolRuntimeContext, 'codeMode' | 'expectedMcpTool' | 'searchMcpTools' | 'recentImages'>;
+    readonly tools: readonly ClientToolDefinition[];
+    readonly expectations: ReadonlyMap<string, McpToolCallContext['expectedTool']>;
+    readonly extensionToolNames: ReadonlySet<string>;
+    readonly schedule: ReturnType<typeof createSessionToolScheduler>;
+    readonly emit: (event: EventPayload) => Promise<void>;
+    readonly searchMcpTools: NonNullable<ToolRuntimeContext['searchMcpTools']>;
+    readonly recentImages: () => ToolRuntimeImage[];
+    readonly captureCodeContext: () => Omit<ToolRuntimeContext, 'signal' | 'codeMode' | 'expectedMcpTool' | 'searchMcpTools'>;
+    readonly codeModeContext: (call: ClientToolCall) => Promise<Omit<NonNullable<ToolExecutionContext['codeMode']>, 'invoke'>>;
+}
+/** Complete every call in model order even if individual execution fails. */
+export declare function executeRoundTools(calls: readonly ClientToolCall[], scope: RoundToolScope): Promise<ExecutedToolCall[]>;

package/dist/agent-core/tools/execution.js

@@ -0,0 +1,111 @@
+import { MarAgentError, describeMarAgentError } from '../error.js';
+import { AGENT_EXECUTION_POLICY } from '../runtime/execution-policy.js';
+import { allowsToolCaller } from './callers.js';
+import { CodeCellExecutionError } from './code-mode/cells.js';
+import { createCodeToolDispatch } from './code-mode/dispatch.js';
+import { boundedModelToolOutput, structuredToolArtifacts, structuredToolEventData } from './output-projection.js';
+import { executeRegisteredTool } from './runtime.js';
+import { scheduleToolCallBatch } from './scheduler.js';
+/** Complete every call in model order even if individual execution fails. */
+export async function executeRoundTools(calls, scope) {
+    const executeCall = async (call, signal = scope.context.signal, caller = 'direct', parentCallId) => {
+        await scope.emit({
+            type: 'tool.started',
+            toolName: call.name,
+            callId: call.callId,
+            ...(parentCallId === undefined ? {} : { parentCallId }),
+            input: call.arguments
+        });
+        try {
+            if (call.argumentError)
+                throw new MarAgentError('MAR_AGENT_TOOL_INPUT_INVALID', call.argumentError);
+            if (!scope.tools.some((tool) => tool.name === call.name && allowsToolCaller(tool, caller)))
+                throw new MarAgentError('MAR_AGENT_TOOL_NOT_AVAILABLE', 'Tool is unavailable in this execution.');
+            const codeMode = await scope.codeModeContext(call);
+            const runTool = () => {
+                signal.throwIfAborted();
+                return executeRegisteredTool(call.name, call.arguments, call.callId, {
+                    ...scope.context,
+                    ...(scope.expectations.get(call.name)
+                        ? { expectedMcpTool: scope.expectations.get(call.name) }
+                        : {}),
+                    searchMcpTools: scope.searchMcpTools,
+                    signal,
+                    codeMode: {
+                        ...codeMode,
+                        invoke: createCodeToolDispatch({
+                            context: scope.captureCodeContext(),
+                            tools: scope.tools,
+                            expectations: scope.expectations,
+                            parentCallId: call.callId,
+                            schedule: scope.schedule,
+                            emit: scope.emit
+                        })
+                    },
+                    ...(scope.extensionToolNames.has(call.name) ? { recentImages: scope.recentImages() } : {})
+                });
+            };
+            const output = call.name === 'code_exec' || call.name === 'code_exec_wait'
+                ? await runTool()
+                : await scope.schedule(scope.tools.find((tool) => tool.name === call.name), runTool);
+            const modelOutput = boundedModelToolOutput(call.name, output.content, output.data);
+            const eventSummary = output.content.slice(0, AGENT_EXECUTION_POLICY.toolEventSummaryCharacters);
+            const structuredData = structuredToolEventData(call.name, output.data);
+            const artifacts = structuredToolArtifacts(output.artifacts);
+            await scope.emit({
+                type: 'tool.completed',
+                toolName: call.name,
+                callId: call.callId,
+                ...(parentCallId === undefined ? {} : { parentCallId }),
+                summary: eventSummary,
+                truncated: output.truncated === true ||
+                    modelOutput.truncated ||
+                    eventSummary.length < output.content.length,
+                ...(artifacts === undefined ? {} : { artifacts }),
+                ...(structuredData === undefined ? {} : { data: structuredData })
+            });
+            return {
+                call,
+                output,
+                content: modelOutput.content,
+                ...(output.calls ? { calls: output.calls } : {}),
+                ...(output.observations ? { observations: output.observations } : {}),
+                ...(output.images?.length ? { images: output.images } : {}),
+                failed: false
+            };
+        }
+        catch (error) {
+            const diagnostic = describeMarAgentError(error, 'MAR_AGENT_HOST_OPERATION_FAILED');
+            const partial = error instanceof CodeCellExecutionError ? error.result : undefined;
+            await scope.emit({
+                type: 'tool.failed',
+                toolName: call.name,
+                callId: call.callId,
+                ...(parentCallId === undefined ? {} : { parentCallId }),
+                code: diagnostic.code,
+                message: diagnostic.message,
+                ...(partial?.data === undefined
+                    ? {}
+                    : {
+                        data: structuredToolEventData(call.name, partial.data)
+                    })
+            });
+            return {
+                call,
+                content: partial === undefined
+                    ? JSON.stringify({
+                        error: diagnostic.code,
+                        message: diagnostic.message,
+                        ...(error instanceof MarAgentError && error.retryable ? { retryable: true } : {})
+                    })
+                    : boundedModelToolOutput(call.name, partial.content, partial.data).content,
+                ...(partial?.images?.length ? { images: partial.images } : {}),
+                failed: true,
+                ...(partial?.calls ? { calls: partial.calls } : {}),
+                ...(partial?.observations ? { observations: partial.observations } : {}),
+                error
+            };
+        }
+    };
+    return scheduleToolCallBatch(calls, scope.tools, executeCall);
+}

package/dist/agent-core/tools/local/apply-patch.d.ts

@@ -0,0 +1,19 @@
+import type { ClientToolDefinition } from '../../model/contracts.js';
+import type { ApplyPatchResult } from '../contracts.js';
+import { WorkspacePathResolver } from '../shared/path-resolver.js';
+export type { ApplyPatchFileResult, ApplyPatchResult } from '../contracts.js';
+export declare const applyPatchToolDefinition: ClientToolDefinition;
+export declare function applyPatchToolInput(input: unknown): string;
+interface PatchFileOperations {
+    rename(source: string, target: string): Promise<void>;
+    rm(path: string, options?: {
+        force?: boolean;
+        recursive?: boolean;
+    }): Promise<void>;
+}
+export declare class ApplyPatchTool {
+    #private;
+    private readonly paths;
+    constructor(paths: WorkspacePathResolver, operations?: Partial<PatchFileOperations>);
+    execute(patch: string): Promise<ApplyPatchResult>;
+}

package/dist/{tools → agent-core/tools/local}/apply-patch.js

@@ -2,8 +2,8 @@ import { randomUUID } from 'node:crypto';
 import { chmod, lstat, mkdir, readFile, rename, rm, rmdir, writeFile } from 'node:fs/promises';
 import { dirname, isAbsolute, parse, resolve } from 'node:path';
 import { TextDecoder } from 'node:util';
-import { MarAgentError } from '../error.js';
-import { TOOL_EXECUTION_LIMITS } from './execution-limits.js';
+import { MarAgentError } from '../../error.js';
+import { TOOL_EXECUTION_LIMITS } from '../execution-limits.js';
 export const applyPatchToolDefinition = {
     name: 'apply_patch',
     allowedCallers: ['direct', 'programmatic'],
@@ -53,6 +53,12 @@ export const applyPatchToolDefinition = {
         additionalProperties: false
     }
 };
+export function applyPatchToolInput(input) {
+    const patch = typeof input === 'string' ? input : input?.patch;
+    if (typeof patch !== 'string')
+        throw new MarAgentError('MAR_AGENT_TOOL_INPUT_INVALID', 'Patch is required.');
+    return patch;
+}
 const defaultFileOperations = { rename, rm };
 const utf8Decoder = new TextDecoder('utf-8', { fatal: true });
 export class ApplyPatchTool {

package/dist/{tools → agent-core/tools/local}/exec.d.ts

@@ -1,6 +1,8 @@
-import type { ClientToolDefinition } from '../model/contracts.js';
-import { type LocalProcessExecutor } from '../host/local-process-executor.js';
-import { WorkspacePathResolver } from './shared/path-resolver.js';
+import { type LocalProcessExecutor } from '../../host/local-process-executor.js';
+import type { ClientToolDefinition } from '../../model/contracts.js';
+import type { ExecResult } from '../contracts.js';
+import { WorkspacePathResolver } from '../shared/path-resolver.js';
+export type { ExecResult } from '../contracts.js';
 export type ExecInput = {
     action?: 'start';
     command: string;
@@ -19,20 +21,6 @@ export type ExecInput = {
     action: 'cancel';
     processId: string;
 };
-export interface ExecResult {
-    status: 'running' | 'completed' | 'cancelled';
-    processId?: string;
-    stdout: string;
-    stderr: string;
-    exitCode?: number | null;
-    truncated: boolean;
-    stdoutBytes: number;
-    stderrBytes: number;
-    stdoutDroppedBytes: number;
-    stderrDroppedBytes: number;
-    /** A terminal snapshot replay rather than new process output. */
-    cached?: boolean;
-}
 export declare const execToolDefinition: ClientToolDefinition;
 export declare const execWaitToolDefinition: ClientToolDefinition;
 /** Validate the public entry points before delegating to the single process manager. */

package/dist/{tools → agent-core/tools/local}/exec.js

@@ -1,13 +1,13 @@
-import { directLocalProcessExecutor, signalProcessTree } from '../host/local-process-executor.js';
 import { randomUUID } from 'node:crypto';
 import { StringDecoder } from 'node:string_decoder';
-import { MarAgentError } from '../error.js';
-import { TOOL_EXECUTION_LIMITS } from './execution-limits.js';
+import { MarAgentError } from '../../error.js';
+import { directLocalProcessExecutor, signalProcessTree } from '../../host/local-process-executor.js';
+import { TOOL_EXECUTION_LIMITS } from '../execution-limits.js';
 export const execToolDefinition = {
     name: 'exec',
     allowedCallers: ['direct', 'programmatic'],
     parallelSafety: 'safe',
-    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.',
+    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, call exec_wait directly 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'],