@myagentroam/agent 0.9.159 → 0.9.161

package/dist/agent-core/tools/local/exec.js

@@ -3,6 +3,7 @@ import { StringDecoder } from 'node:string_decoder';
 import { MarAgentError } from '../../error.js';
 import { directLocalProcessExecutor, signalProcessTree } from '../../host/local-process-executor.js';
 import { TOOL_EXECUTION_LIMITS } from '../execution-limits.js';
+import { validateCoreProcessInput } from '../../extensions/processes.js';
 export const execToolDefinition = {
     name: 'exec',
     allowedCallers: ['direct', 'programmatic'],
@@ -52,7 +53,12 @@ export const execToolDefinition = {
                 type: 'string',
                 description: 'Optional relative/absolute start directory; defaults to workspace. Command-internal relative paths resolve from this directory.'
             },
-            timeoutMs: { type: 'integer', minimum: 1, maximum: TOOL_EXECUTION_LIMITS.execMaxTimeoutMs },
+            timeoutMs: {
+                type: 'integer',
+                minimum: 1,
+                maximum: TOOL_EXECUTION_LIMITS.execMaxTimeoutMs,
+                description: 'Optional process lifetime limit in milliseconds. Omitted means no process timeout; yieldMs only controls waiting.'
+            },
             yieldMs: {
                 type: 'integer',
                 minimum: 0,
@@ -144,7 +150,9 @@ export class ExecTool {
                     this.#removeCompleted(input.processId);
                 return { ...completed.result, cached: true };
             }
-            if (!process || (owner !== undefined && process.ownerSessionId !== owner.sessionId))
+            if (!process ||
+                process.native ||
+                (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.execMaxPollYieldMs), signal);
@@ -160,36 +168,65 @@ export class ExecTool {
             }
             return result;
         }
+        const { id, managed } = await this.#startManaged(async () => {
+            const cwd = await this.paths.resolveWithDisplay(input.cwd ?? '.');
+            return {
+                command: input.command,
+                cwd: cwd.physicalPath,
+                shell: this.shell ?? true,
+                environment: this.environment,
+                displayCwd: cwd.displayPath,
+                detached: process.platform !== 'win32',
+                ...(owner === undefined ? {} : { owner }),
+                ...(signal === undefined ? {} : { signal })
+            };
+        }, owner?.sessionId, false);
+        if (input.timeoutMs !== undefined) {
+            managed.timer = setTimeout(() => {
+                void this.#terminate(managed, true).then(() => this.#retainCompleted(id, managed));
+            }, Math.min(input.timeoutMs, TOOL_EXECUTION_LIMITS.execMaxTimeoutMs));
+            managed.timer.unref();
+        }
+        await waitForExitOrDelay(managed.settled, Math.min(input.yieldMs ?? TOOL_EXECUTION_LIMITS.execDefaultYieldMs, TOOL_EXECUTION_LIMITS.execMaxYieldMs), signal);
+        const result = this.#result(id, managed);
+        if (managed.status !== 'running')
+            this.#retainCompleted(id, managed);
+        return result;
+    }
+    async #startManaged(request, ownerSessionId, native) {
         if (this.#processes.size + this.#startingProcesses.size >= this.maxProcesses)
             throw new MarAgentError('MAR_AGENT_PROCESS_LIMIT', `The Local Host shared managed-process limit (${this.maxProcesses}) was reached.`);
         let resolveStarting;
         const starting = {
-            ...(owner === undefined ? {} : { ownerSessionId: owner.sessionId }),
+            ...(ownerSessionId === undefined ? {} : { ownerSessionId }),
             settled: new Promise((resolve) => (resolveStarting = resolve)),
             resolveSettled: () => resolveStarting()
         };
         this.#startingProcesses.add(starting);
-        const id = randomUUID();
-        let child;
-        let managed;
         try {
-            const cwd = await this.paths.resolveWithDisplay(input.cwd ?? '.');
-            child = await this.processExecutor.spawn({
-                command: input.command,
-                cwd: cwd.physicalPath,
-                shell: this.shell ?? true,
-                environment: this.environment,
-                detached: process.platform !== 'win32',
-                ...(owner === undefined ? {} : { owner }),
-                ...(signal === undefined ? {} : { signal })
-            });
+            const { displayCwd, ...input } = await request();
+            input.signal?.throwIfAborted();
+            let child;
+            try {
+                child = await this.processExecutor.spawn(input);
+            }
+            catch (error) {
+                input.signal?.throwIfAborted();
+                if (!native || error instanceof MarAgentError)
+                    throw error;
+                throw new MarAgentError('MAR_AGENT_PROCESS_START_FAILED', 'Native process executor failed to start.', {
+                    details: { reasonCode: error?.code ?? 'UNKNOWN' }
+                });
+            }
+            const id = randomUUID();
             let resolveExited;
             let resolveSettled;
-            managed = {
+            const managed = {
                 child,
-                ...(owner === undefined ? {} : { ownerSessionId: owner.sessionId }),
+                native,
+                ...(ownerSessionId === undefined ? {} : { ownerSessionId }),
                 command: input.command,
-                cwd: cwd.displayPath,
+                cwd: displayCwd ?? input.cwd,
                 stdout: createOutputBuffer(),
                 stderr: createOutputBuffer(),
                 stdoutHistory: createOutputBuffer(),
@@ -199,65 +236,199 @@ export class ExecTool {
                 settled: new Promise((resolve) => (resolveSettled = resolve)),
                 resolveExited,
                 resolveSettled,
-                exitObserved: child.exitCode !== null,
+                exitObserved: child.exitCode !== null || child.signalCode != null,
+                ...(child.exitCode === null ? {} : { exitCode: child.exitCode }),
+                ...(child.signalCode == null ? {} : { exitSignal: child.signalCode }),
                 finalized: false,
                 waiters: new Set()
             };
             this.#processes.set(id, managed);
+            if (native) {
+                // Keep unread bytes in the Readable buffer: Node otherwise resumes unused stdio at exit.
+                const readable = () => { };
+                child.stdout.on('readable', readable);
+                child.stderr.on('readable', readable);
+                child.once('close', () => {
+                    child.stdout.removeListener('readable', readable);
+                    child.stderr.removeListener('readable', readable);
+                });
+            }
+            if (!native) {
+                const listen = (name) => child[name].on('data', (chunk) => {
+                    if (managed.finalized)
+                        return;
+                    const decoded = Buffer.from(managed[name].decoder.write(chunk));
+                    appendOutput(managed[name], decoded, this.maxOutputBytes, chunk.length);
+                    appendOutput(managed[name === 'stdout' ? 'stdoutHistory' : 'stderrHistory'], decoded, this.maxOutputBytes, chunk.length);
+                    notifyProcessChange(managed);
+                });
+                listen('stdout');
+                listen('stderr');
+            }
+            child.once('exit', (code, signal) => {
+                managed.exitObserved = true;
+                managed.exitCode = code;
+                managed.exitSignal = signal;
+                managed.resolveExited();
+                if (!native)
+                    void finalizeAfterOutputGrace(managed, this.maxOutputBytes).then(() => this.#retainCompleted(id, managed));
+            });
+            child.once('close', (code, signal) => {
+                managed.exitObserved = true;
+                managed.exitSignal = signal;
+                managed.resolveExited();
+                finalizeManagedProcess(managed, this.maxOutputBytes, code);
+                if (native)
+                    this.#processes.delete(id);
+                else
+                    this.#retainCompleted(id, managed);
+            });
+            child.once('error', (error) => {
+                if (managed.finalized)
+                    return;
+                if (native) {
+                    managed.failure = new MarAgentError('MAR_AGENT_PROCESS_START_FAILED', 'Native process failed to start.', {
+                        details: { reasonCode: error.code ?? 'UNKNOWN' }
+                    });
+                    managed.exitObserved = true;
+                    managed.resolveExited();
+                }
+                else {
+                    const message = Buffer.from(error.message);
+                    appendOutput(managed.stderr, message, this.maxOutputBytes);
+                    appendOutput(managed.stderrHistory, message, this.maxOutputBytes);
+                    notifyProcessChange(managed);
+                }
+            });
+            if (managed.exitObserved) {
+                managed.resolveExited();
+                if (child.stdout.closed && child.stderr.closed) {
+                    finalizeManagedProcess(managed, this.maxOutputBytes, child.exitCode);
+                    if (native)
+                        this.#processes.delete(id);
+                    else
+                        this.#retainCompleted(id, managed);
+                }
+            }
+            return { id, managed };
         }
         finally {
             this.#startingProcesses.delete(starting);
             starting.resolveSettled();
         }
-        child.stdout.on('data', (chunk) => {
-            if (managed.finalized)
-                return;
-            const decoded = Buffer.from(managed.stdout.decoder.write(chunk));
-            appendOutput(managed.stdout, decoded, this.maxOutputBytes, chunk.length);
-            appendOutput(managed.stdoutHistory, decoded, this.maxOutputBytes, chunk.length);
-            notifyProcessChange(managed);
+    }
+    async spawn(input, call) {
+        validateCoreProcessInput(input);
+        input = {
+            ...input,
+            ...(input.argv === undefined ? {} : { argv: [...input.argv] }),
+            ...(input.env === undefined ? {} : { env: { ...input.env } }),
+            ...(input.input instanceof Uint8Array ? { input: new Uint8Array(input.input) } : {})
+        };
+        const { id, managed } = await this.#startManaged(async () => {
+            const cwd = await this.paths.resolve(input.cwd ?? '.');
+            return {
+                command: input.executable,
+                args: [...(input.argv ?? [])],
+                cwd,
+                shell: false,
+                environment: { ...this.environment, ...input.env },
+                environmentKeys: Object.keys(input.env ?? {}),
+                ...(input.env === undefined ? {} : { environmentOverrides: input.env }),
+                detached: process.platform !== 'win32',
+                signal: call.signal,
+                owner: {
+                    sessionId: call.sessionId,
+                    operationId: call.operationId,
+                    ...(call.executionId ? { executionId: call.executionId } : {}),
+                    ...(call.ownerInstanceId ? { ownerInstanceId: call.ownerInstanceId } : {})
+                }
+            };
+        }, call.sessionId, true);
+        let cleanup;
+        const cancel = () => (cleanup ??= (async () => {
+            call.signal.removeEventListener('abort', abort);
+            await this.#terminate(managed, false);
+            destroyManagedStreams(managed);
+            this.#processes.delete(id);
+        })());
+        const abort = () => {
+            void cancel().catch(() => undefined);
+        };
+        call.signal.addEventListener('abort', abort, { once: true });
+        managed.child.once('close', () => call.signal.removeEventListener('abort', abort));
+        managed.child.stdin.on('error', (error) => {
+            if (error.code !== 'EPIPE' && !cleanup)
+                managed.failure = new MarAgentError('MAR_AGENT_PROCESS_IO_FAILED', 'Native process input failed.', {
+                    details: { reasonCode: error.code ?? 'UNKNOWN' }
+                });
         });
-        child.stderr.on('data', (chunk) => {
-            if (managed.finalized)
+        managed.child.stdin.end(input.input);
+        if (call.signal.aborted) {
+            await cancel();
+            call.signal.throwIfAborted();
+        }
+        const opened = new Promise((resolve, reject) => {
+            if (managed.child.pid) {
+                resolve();
                 return;
-            const decoded = Buffer.from(managed.stderr.decoder.write(chunk));
-            appendOutput(managed.stderr, decoded, this.maxOutputBytes, chunk.length);
-            appendOutput(managed.stderrHistory, decoded, this.maxOutputBytes, chunk.length);
-            notifyProcessChange(managed);
-        });
-        child.once('exit', (code) => {
-            managed.exitObserved = true;
-            managed.exitCode = code;
-            managed.resolveExited();
-            void finalizeAfterOutputGrace(managed, this.maxOutputBytes).then(() => this.#retainCompleted(id, managed));
-        });
-        child.once('close', (code) => {
-            managed.exitObserved = true;
-            managed.resolveExited();
-            finalizeManagedProcess(managed, this.maxOutputBytes, code);
-            this.#retainCompleted(id, managed);
-        });
-        child.once('error', (error) => {
-            if (managed.finalized)
+            }
+            if (managed.failure) {
+                reject(managed.failure);
                 return;
-            const message = Buffer.from(error.message);
-            appendOutput(managed.stderr, message, this.maxOutputBytes);
-            appendOutput(managed.stderrHistory, message, this.maxOutputBytes);
-            notifyProcessChange(managed);
+            }
+            const spawned = () => {
+                managed.child.removeListener('error', failed);
+                resolve();
+            };
+            const failed = () => {
+                managed.child.removeListener('spawn', spawned);
+                reject(managed.failure);
+            };
+            managed.child.once('spawn', spawned);
+            managed.child.once('error', failed);
         });
-        managed.timer = setTimeout(() => {
-            void this.#terminate(managed, true).then(() => this.#retainCompleted(id, managed));
-        }, Math.min(input.timeoutMs ?? TOOL_EXECUTION_LIMITS.execDefaultTimeoutMs, TOOL_EXECUTION_LIMITS.execMaxTimeoutMs));
-        managed.timer.unref();
-        await waitForExitOrDelay(managed.settled, Math.min(input.yieldMs ?? TOOL_EXECUTION_LIMITS.execDefaultYieldMs, TOOL_EXECUTION_LIMITS.execMaxYieldMs), signal);
-        const result = this.#result(id, managed);
-        if (managed.status !== 'running')
-            this.#retainCompleted(id, managed);
-        return result;
+        try {
+            await opened;
+        }
+        catch (error) {
+            await cancel();
+            throw error;
+        }
+        const stream = (name) => ({
+            async *[Symbol.asyncIterator]() {
+                try {
+                    for await (const chunk of managed.child[name])
+                        yield new Uint8Array(chunk);
+                }
+                catch (error) {
+                    if (!cleanup && !call.signal.aborted)
+                        throw new MarAgentError('MAR_AGENT_PROCESS_IO_FAILED', 'Native process output failed.', {
+                            details: {
+                                stream: name,
+                                reasonCode: error.code ?? 'UNKNOWN'
+                            }
+                        });
+                }
+            }
+        });
+        return {
+            processId: id,
+            stdout: stream('stdout'),
+            stderr: stream('stderr'),
+            cancel,
+            wait: async () => {
+                await managed.exited;
+                call.signal.throwIfAborted();
+                if (managed.failure)
+                    throw managed.failure;
+                return { code: managed.exitCode ?? null, signal: managed.exitSignal ?? null };
+            }
+        };
     }
     listSessionResources(sessionId) {
         return [
-            ...[...this.#processes.entries()].flatMap(([processId, process]) => process.ownerSessionId === sessionId
+            ...[...this.#processes.entries()].flatMap(([processId, process]) => !process.native && process.ownerSessionId === sessionId
                 ? [{ processId, status: process.status, command: process.command, cwd: process.cwd }]
                 : []),
             ...[...this.#completed.entries()].flatMap(([processId, process]) => process.ownerSessionId === sessionId
@@ -292,7 +463,10 @@ export class ExecTool {
         this.#completed.delete(id);
     }
     #retainCompleted(id, process) {
-        if (process.status === 'running' || !process.finalized || this.#processes.get(id) !== process)
+        if (process.native ||
+            process.status === 'running' ||
+            !process.finalized ||
+            this.#processes.get(id) !== process)
             return;
         this.#processes.delete(id);
         const stdout = consumeOutput(process.stdoutHistory);
@@ -325,6 +499,8 @@ export class ExecTool {
             return managed.terminate;
         managed.terminate = (async () => {
             if (managed.exitObserved || managed.child.exitCode !== null) {
+                if (managed.native && !managed.finalized)
+                    await signalProcessTree(managed.child, 'SIGKILL');
                 if (managed.child.exitCode !== null)
                     managed.exitCode = managed.child.exitCode;
                 if (waitForOutputClose) {
@@ -345,6 +521,9 @@ export class ExecTool {
                 await signalProcessTree(managed.child, 'SIGKILL');
                 await managed.exited;
             }
+            // A parent may exit on TERM while descendants ignore it and keep the pipes alive.
+            if (managed.native)
+                await signalProcessTree(managed.child, 'SIGKILL');
             if (waitForOutputClose) {
                 const settled = await waitForExit(managed.settled, TOOL_EXECUTION_LIMITS.execTerminationGraceMs);
                 if (settled)

package/dist/agent-core/tools/local/registry.d.ts

@@ -1,9 +1,13 @@
+import { LocalFileAccess } from '../../host/local-file-access.js';
 import type { LocalProcessExecutor } from '../../host/local-process-executor.js';
 import type { CodeModeEngineFactory } from '../code-mode/engine.js';
 import type { ToolCall, ToolExecutionContext, ToolExecutionResult } from '../contracts.js';
 import { type WorkspacePathMount } from '../shared/path-resolver.js';
+import type { CoreOperationContext } from '../../extensions/operation.js';
 export declare class LocalToolRegistry {
     #private;
+    readonly processes: import('../../extensions/processes.js').CoreProcessesBackend;
+    readonly files: LocalFileAccess;
     constructor(workspace: string, environment?: NodeJS.ProcessEnv, shell?: string, options?: {
         processExecutor?: LocalProcessExecutor;
         codeModeEngineFactory?: CodeModeEngineFactory;
@@ -12,6 +16,8 @@ export declare class LocalToolRegistry {
         pathMounts?: readonly WorkspacePathMount[];
     });
     execute(call: ToolCall, context: ToolExecutionContext): Promise<ToolExecutionResult>;
+    names(): readonly string[];
+    executeOperation(call: ToolCall, operation: CoreOperationContext): Promise<ToolExecutionResult>;
     listSessionResources(sessionId: string): {
         processId: string;
         status: "completed" | "cancelled" | "running";

package/dist/agent-core/tools/local/registry.js

@@ -1,11 +1,29 @@
 import { MarAgentError } from '../../error.js';
-import { ApplyPatchTool, applyPatchToolInput } from './apply-patch.js';
-import { CodeModeTool } from '../code-mode/index.js';
-import { ExecTool, execToolInput } from './exec.js';
-import { ReadTool, formatBatchReadOutput } from './read.js';
+import { LocalFileAccess } from '../../host/local-file-access.js';
+import { ApplyPatchTool, applyPatchToolInput, applyPatchToolDefinition } from './apply-patch.js';
+import { CodeModeTool, codeModeToolDefinition, codeExecWaitToolDefinition } from '../code-mode/index.js';
+import { normalizeToolInput } from '../input.js';
+import { ExecTool, execToolInput, execToolDefinition, execWaitToolDefinition } from './exec.js';
+import { ReadTool, formatBatchReadOutput, readToolDefinition } from './read.js';
 import { WorkspacePathResolver } from '../shared/path-resolver.js';
-import { ViewImageTool } from './view-image.js';
+import { ViewImageTool, viewImageToolDefinition } from './view-image.js';
+const definitions = [
+    readToolDefinition,
+    viewImageToolDefinition,
+    applyPatchToolDefinition,
+    execToolDefinition,
+    execWaitToolDefinition,
+    codeModeToolDefinition,
+    codeExecWaitToolDefinition
+];
+function executionContext(context) {
+    if (!context.executionId)
+        throw new MarAgentError('MAR_AGENT_TOOL_NOT_AVAILABLE', 'Tool requires a real Execution.');
+    return { ...context, executionId: context.executionId };
+}
 export class LocalToolRegistry {
+    processes;
+    files;
     #exec;
     #code;
     #handlers;
@@ -17,14 +35,22 @@ export class LocalToolRegistry {
                 : { rootWritable: options.workspaceWritable }),
             ...(options.pathMounts === undefined ? {} : { mounts: options.pathMounts })
         });
+        this.files = new LocalFileAccess(paths);
         const read = new ReadTool(paths);
         const viewImage = new ViewImageTool(paths);
         const patch = new ApplyPatchTool(paths);
         this.#exec = new ExecTool(paths, undefined, undefined, environment, shell, options.processExecutor);
+        this.processes = { spawn: (input, call) => this.#exec.spawn(input, call) };
         this.#code = new CodeModeTool(paths, environment, options.processExecutor, options.codeModeEngineFactory);
         this.#handlers = new Map([
-            ['code_exec', (arguments_, context) => this.#code.start(arguments_, context)],
-            ['code_exec_wait', (arguments_, context) => this.#code.wait(arguments_, context)],
+            [
+                'code_exec',
+                (arguments_, context) => this.#code.start(arguments_, executionContext(context))
+            ],
+            [
+                'code_exec_wait',
+                (arguments_, context) => this.#code.wait(arguments_, executionContext(context))
+            ],
             [
                 'read',
                 async (arguments_, context) => {
@@ -53,7 +79,17 @@ export class LocalToolRegistry {
                 async (arguments_, context) => {
                     const result = await this.#exec.execute(execToolInput(name, arguments_), context.signal, {
                         sessionId: context.sessionId,
-                        executionId: context.executionId
+                        ...(context.executionId === undefined
+                            ? {}
+                            : { executionId: context.executionId }),
+                        ...(context.operation === undefined
+                            ? {}
+                            : {
+                                operationId: context.operation.operationId,
+                                ...(context.operation.ownerInstanceId === undefined
+                                    ? {}
+                                    : { ownerInstanceId: context.operation.ownerInstanceId })
+                            })
                     });
                     return { content: JSON.stringify(result), data: result, truncated: result.truncated };
                 }
@@ -64,7 +100,22 @@ export class LocalToolRegistry {
         const handler = this.#handlers.get(call.name);
         if (!handler)
             throw new MarAgentError('MAR_AGENT_TOOL_NOT_AVAILABLE', 'Tool is unavailable.');
-        return handler(call.arguments, context);
+        return handler(normalizeToolInput(call.arguments, definitions.find((tool) => tool.name === call.name).inputSchema), context);
+    }
+    names() {
+        return [...this.#handlers.keys()];
+    }
+    executeOperation(call, operation) {
+        const handler = this.#handlers.get(call.name);
+        if (!handler)
+            throw new MarAgentError('MAR_AGENT_TOOL_NOT_AVAILABLE', 'Tool is unavailable.');
+        return handler(normalizeToolInput(call.arguments, definitions.find((tool) => tool.name === call.name).inputSchema), {
+            mode: 'run',
+            signal: operation.signal,
+            sessionId: operation.sessionId,
+            ...(operation.executionId === undefined ? {} : { executionId: operation.executionId }),
+            operation
+        });
     }
     listSessionResources(sessionId) {
         return this.#exec.listSessionResources(sessionId);

package/dist/agent-core/tools/mcp/catalog.d.ts

@@ -8,5 +8,9 @@ export declare const MCP_DEFINITION_LIMITS: Readonly<{
     servers: 256;
 }>;
 /** Shared Host and Node publication boundary, not a provider-specific conversion. */
-export declare function assertMcpToolDefinition(value: unknown): asserts value is ClientToolDefinition;
-export declare function assertMcpToolCatalog(value: unknown): asserts value is McpToolCatalog;
+export declare function assertMcpToolDefinition(value: unknown, options?: {
+    nativeToolNames?: boolean;
+}): asserts value is ClientToolDefinition;
+export declare function assertMcpToolCatalog(value: unknown, options?: {
+    nativeToolNames?: boolean;
+}): asserts value is McpToolCatalog;

package/dist/agent-core/tools/mcp/catalog.js

@@ -136,10 +136,10 @@ function assertSchema(schema) {
     }
 }
 /** Shared Host and Node publication boundary, not a provider-specific conversion. */
-export function assertMcpToolDefinition(value) {
+export function assertMcpToolDefinition(value, options = {}) {
     if (!record(value) ||
         !text(value.name, 256) ||
-        !/^mcp__[A-Za-z0-9_-]+__[A-Za-z0-9_-]+$/u.test(value.name) ||
+        (!options.nativeToolNames && !/^mcp__[A-Za-z0-9_-]+__[A-Za-z0-9_-]+$/u.test(value.name)) ||
         typeof value.description !== 'string' ||
         value.description.length > 65536 ||
         (value.parallelSafety !== undefined &&
@@ -159,7 +159,7 @@ export function assertMcpToolDefinition(value) {
     if (Buffer.byteLength(JSON.stringify(value)) > MCP_DEFINITION_LIMITS.definitionBytes)
         invalid();
 }
-export function assertMcpToolCatalog(value) {
+export function assertMcpToolCatalog(value, options = {}) {
     if (!record(value) ||
         typeof value.revision !== 'string' ||
         value.revision.length > 512 ||
@@ -204,7 +204,7 @@ export function assertMcpToolCatalog(value) {
             !['session', 'execution'].includes(String(tool.lifetime)) ||
             !['direct', 'deferred'].includes(String(tool.exposure)))
             invalid();
-        assertMcpToolDefinition(tool.definition);
+        assertMcpToolDefinition(tool.definition, options);
         if (tool.annotations !== undefined) {
             if (!record(tool.annotations))
                 invalid();

package/dist/agent-core/tools/mcp/history.js

@@ -4,8 +4,8 @@ export function discoveredMcpToolNames(messages) {
     const names = new Set();
     for (const message of messages)
         for (const tool of calls.has(message.callId ?? '') ? (message.toolSearchTools ?? []) : [])
-            if (tool.name.startsWith('mcp__'))
-                names.add(tool.name);
+            // Paired discovery receipts provide candidates; the current captured MCP catalog is authority.
+            names.add(tool.name);
     return [...names];
 }
 export function rebindMcpToolSearchOutputs(messages, registry) {

package/dist/agent-core/tools/mcp/tool-search.d.ts

@@ -20,7 +20,9 @@ export declare class DeferredMcpRegistry {
     #private;
     constructor(discoveredNames: readonly string[]);
     restore(discoveredNames: readonly string[]): void;
-    update(catalog: McpToolCatalog, eligible: (tool: McpCatalogTool) => boolean): void;
+    update(catalog: McpToolCatalog, eligible: (tool: McpCatalogTool) => boolean, options?: {
+        nativeToolNames?: boolean;
+    }): void;
     get hasDeferred(): boolean;
     snapshot(): readonly string[];
     expectedTool(name: string): {

package/dist/agent-core/tools/mcp/tool-search.js

@@ -63,8 +63,8 @@ export class DeferredMcpRegistry {
         // GC may remove evidence, but cannot grant a capability from another Execution.
         this.#executionSelected = new Set([...this.#executionSelected].filter((name) => surviving.has(name)));
     }
-    update(catalog, eligible) {
-        assertMcpToolCatalog(catalog);
+    update(catalog, eligible, options = {}) {
+        assertMcpToolCatalog(catalog, options);
         this.#catalog = { ...catalog, tools: catalog.tools.filter(eligible) };
         const validSession = new Set(this.#catalog.tools
             .filter((tool) => tool.lifetime === 'session' && tool.exposure === 'deferred')

package/dist/agent-core/tools/output-projection.d.ts

@@ -1,5 +1,5 @@
 import type { SubagentTaskSnapshot } from '../subagent/contracts.js';
-import type { ApplyPatchResult, CodeCellEventData, ExecResult, MarAgentToolArtifact, ReadEventData, ViewImageResult } from './contracts.js';
+import type { ApplyPatchResult, CodeCellEventData, ExecResult, MarAgentToolArtifact, ToolExecutionResult, ReadEventData, ViewImageResult } from './contracts.js';
 import type { ToolRuntimeImage } from './runtime-context.js';
 export declare function currentExecutionImages(modelInputImages: readonly {
     readonly mimeType: string;
@@ -12,3 +12,5 @@ export declare function boundedModelToolOutput(toolName: string, value: string,
 /** Project only known, validated tool result shapes into public structured events. */
 export declare function structuredToolEventData(toolName: string, value: unknown): CodeCellEventData | ExecResult | ApplyPatchResult | ReadEventData | ViewImageResult | SubagentTaskSnapshot | undefined;
 export declare function structuredToolArtifacts(value: readonly MarAgentToolArtifact[] | undefined): readonly MarAgentToolArtifact[] | undefined;
+/** Shared result contract for model, programmatic, and native API callers. */
+export declare function validateToolResult(value: ToolExecutionResult): ToolExecutionResult;

package/dist/agent-core/tools/output-projection.js

@@ -149,8 +149,10 @@ export function structuredToolEventData(toolName, value) {
 export function structuredToolArtifacts(value) {
     if (value === undefined)
         return undefined;
-    if (value.length !== 1 ||
-        value.some((artifact) => artifact.kind !== 'image' ||
+    if (!Array.isArray(value) ||
+        value.length !== 1 ||
+        value.some((artifact) => !artifact ||
+            artifact.kind !== 'image' ||
             artifact.mimeType !== 'image/png' ||
             typeof artifact.name !== 'string' ||
             artifact.name.length === 0 ||
@@ -162,6 +164,13 @@ export function structuredToolArtifacts(value) {
         throw new MarAgentError('MAR_AGENT_TOOL_OUTPUT_INVALID', 'Tool image artifact is invalid.');
     return value.map((artifact) => ({ ...artifact }));
 }
+/** Shared result contract for model, programmatic, and native API callers. */
+export function validateToolResult(value) {
+    if (!value || typeof value.content !== 'string')
+        throw new MarAgentError('MAR_AGENT_TOOL_OUTPUT_INVALID', 'Tool result must contain string content.');
+    const artifacts = structuredToolArtifacts(value.artifacts);
+    return artifacts === undefined ? value : { ...value, artifacts };
+}
 function isRecord(value) {
     return value !== null && typeof value === 'object' && !Array.isArray(value);
 }

package/dist/agent-core/tools/runtime-context.d.ts

@@ -51,5 +51,6 @@ export interface ToolRuntimeContext {
     recentImages?: readonly ToolRuntimeImage[];
     searchMcpTools?: (input: unknown, signal: AbortSignal) => Promise<import('./contracts.js').ToolExecutionResult>;
     expectedMcpTool?: import('./contracts.js').McpToolCallContext['expectedTool'];
+    invokeTool?: (call: import('./contracts.js').ToolCall, context: ToolRuntimeContext, caller: import('./contracts.js').ToolCaller) => Promise<import('./contracts.js').ToolExecutionResult>;
     emit(event: ToolRuntimeEvent): Promise<void>;
 }

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

@@ -1,2 +1,4 @@
 import type { ToolRuntimeContext } from './runtime-context.js';
-export declare function executeRegisteredTool(name: string, arguments_: unknown, callId: string, context: ToolRuntimeContext): Promise<import("./contracts.js").ToolExecutionResult>;
+export declare function executeRegisteredTool(name: string, arguments_: unknown, callId: string, context: ToolRuntimeContext, caller?: import('./contracts.js').ToolCaller): Promise<import("./contracts.js").ToolExecutionResult>;
+/** Invoke an already captured source; names never reselect a different backend. */
+export declare function executeCapturedTool(kind: 'builtin' | 'host' | 'mcp', call: import('./contracts.js').ToolCall, context: ToolRuntimeContext): Promise<import('./contracts.js').ToolExecutionResult>;