@myagentroam/agent 0.11.32 → 0.11.34

package/dist/host/contracts.d.ts

@@ -0,0 +1,58 @@
+import type { AgentHostExtensionPorts } from '../extensions/host-ports.js';
+import type { AgentEvent } from '../runtime/events.js';
+import type { ClientToolDefinition, McpToolCallContext, McpToolCatalog, McpToolCatalogContext, ToolCall, ToolExecutionContext, ToolExecutionResult } from '../tools/contracts.js';
+export declare const AGENT_HOST_API_VERSION = "1.0";
+import type { HostDescription } from './description.js';
+export type { HostDescription, AgentHostCapability } from './description.js';
+export declare function negotiateHost(description: HostDescription): HostDescription;
+import type { HostSkill } from './skill-contract.js';
+export type { HostSkill } from './skill-contract.js';
+export interface HostExecutionExtensions {
+    readonly tools?: readonly ClientToolDefinition[];
+    readonly skills?: readonly HostSkill[];
+}
+export interface HostSessionResourceSnapshot {
+    codeCells?: readonly {
+        cellId: string;
+        status: 'running' | 'completed' | 'failed' | 'cancelled';
+        executionId: string;
+    }[];
+    idleTtlMs?: number;
+    processes: readonly {
+        processId: string;
+        status: 'running' | 'completed' | 'cancelled';
+        command: string;
+        cwd: string;
+    }[];
+}
+/** The Host owns workspace/tool effects; SessionStore is injected or defaults to SDK-owned JSONL. */
+export interface AgentHost {
+    /** Independent model consumption facts, including child and auxiliary calls. */
+    modelUsage?: import('../model/usage.js').ModelUsageObserver | undefined;
+    publishModelResource?: (image: import('../session/resource-contract.js').SessionResource, context: {
+        sessionId: string;
+        executionId: string;
+        homeDirectory: string;
+    }) => Promise<{
+        url: string;
+        urlExpiresAt: number;
+    } | undefined>;
+    readonly extensionPorts?: AgentHostExtensionPorts;
+    describe(): Promise<HostDescription>;
+    executeTool(call: ToolCall, context: ToolExecutionContext): Promise<ToolExecutionResult>;
+    listExecutionExtensions?(context: McpToolCatalogContext): Promise<HostExecutionExtensions>;
+    listSessionSkills?(context: Pick<McpToolCatalogContext, 'sessionId' | 'modelId'>): Promise<readonly HostSkill[]>;
+    emit(event: AgentEvent): Promise<void> | void;
+    requestToolApproval?: import('../tools/permission-contract.js').ToolApprovalHandler | undefined;
+    requestUserInput?(input: {
+        requestId: string;
+        questions: unknown[];
+    }, signal: AbortSignal): Promise<Record<string, unknown>>;
+    listMcpTools?(context?: McpToolCatalogContext): Promise<readonly ClientToolDefinition[]>;
+    listMcpToolCatalog?(context: McpToolCatalogContext): Promise<McpToolCatalog>;
+    callMcpTool?(call: ToolCall, signal: AbortSignal, context?: McpToolCallContext): Promise<ToolExecutionResult>;
+    listSessionResources?(sessionId: string): Promise<HostSessionResourceSnapshot>;
+    disposeSessionResources?(sessionId: string): Promise<void>;
+    dispose(): Promise<void>;
+}
+export type { AgentHostExtensionPorts, AgentHostToolSource, AgentHostToolsBackend } from '../extensions/host-ports.js';

package/dist/host/contracts.js

@@ -0,0 +1,18 @@
+import { AgentError } from '../error.js';
+export const AGENT_HOST_API_VERSION = '1.0';
+const requiredCapabilities = [
+    'workspace.read',
+    'workspace.patch',
+    'process.manage',
+    'user-input.request',
+    'event.publish'
+];
+export function negotiateHost(description) {
+    const match = /^(\d+)\.(\d+)$/.exec(description.apiVersion);
+    const missing = requiredCapabilities.filter((capability) => !description.capabilities.includes(capability));
+    if (match === null || Number(match[1]) !== 1 || Number(match[2]) < 0 || missing.length > 0)
+        throw new AgentError('MAR_AGENT_HOST_INCOMPATIBLE', 'Host API is incompatible.', {
+            details: { expected: AGENT_HOST_API_VERSION, actual: description.apiVersion, missing }
+        });
+    return description;
+}

package/dist/host/description.d.ts

@@ -0,0 +1,19 @@
+export type AgentHostCapability = 'workspace.read' | 'workspace.patch' | 'process.manage' | 'code.execute' | 'user-input.request' | 'event.publish';
+export interface HostDescription {
+    apiVersion: string;
+    mode: 'normal' | 'node';
+    homeDirectory: string;
+    platform: 'linux' | 'darwin' | 'win32';
+    architecture?: string;
+    shell?: {
+        readonly name: string;
+        readonly path: string;
+    };
+    guaranteedCommands?: Readonly<Record<string, string>>;
+    capabilities: readonly AgentHostCapability[];
+    limits: {
+        maxProcesses: number;
+        maxOutputBytes: number;
+        maxExecutionMs: number;
+    };
+}

package/dist/host/local-agent-host.d.ts

@@ -0,0 +1,96 @@
+import type { AgentEvent } from '../runtime/events.js';
+import type { CodeModeEngineFactory } from '../tools/code-mode/engine.js';
+import type { McpToolCallContext, McpToolCatalog, McpToolCatalogContext, ToolCall, ToolExecutionContext, ToolExecutionResult } from '../tools/contracts.js';
+import type { WorkspacePathMount } from '../tools/shared/path-resolver.js';
+import type { HostDescription, HostExecutionExtensions, HostSkill, AgentHost, AgentHostToolsBackend } from './contracts.js';
+import type { ExtensionNetworkBackend } from '../extensions/network.js';
+import { type LocalProcessExecutor } from './local-process-executor.js';
+import type { ExtensionOperationContext } from '../extensions/operation.js';
+export interface LocalAgentMcpBinding {
+    readonly tools: readonly import('../tools/contracts.js').ClientToolDefinition[];
+    readonly catalog?: () => McpToolCatalog;
+    call(call: ToolCall, signal: AbortSignal, context?: McpToolCallContext): Promise<ToolExecutionResult>;
+}
+export interface LocalAgentExecutionMcpBinding extends LocalAgentMcpBinding {
+    active: boolean;
+    readonly extensions?: LocalAgentExecutionExtensions;
+}
+export interface LocalAgentExecutionExtensions extends HostExecutionExtensions {
+    /** Host-private process environment, snapshotted when bound to an execution. */
+    readonly environment?: Readonly<Record<string, string>>;
+    isToolAvailable?(name: string, context: Pick<ToolExecutionContext, 'sessionId' | 'executionId' | 'modelId'>): boolean;
+    executeTool?(call: ToolCall, context: ToolExecutionContext): Promise<ToolExecutionResult>;
+}
+export declare class LocalAgentHost implements AgentHost {
+    #private;
+    readonly modelUsage: import('../model/usage-observer.js').ModelUsageObserver | undefined;
+    readonly extensionPorts: import('./contracts.js').AgentHostExtensionPorts;
+    readonly events: AgentEvent[];
+    readonly requestToolApproval: AgentHost['requestToolApproval'];
+    readonly publishModelResource?: NonNullable<AgentHost['publishModelResource']>;
+    constructor(input: {
+        mcp?: import('../extensions/mcp.js').ExtensionMcpBackend;
+        operationTools?: AgentHostToolsBackend;
+        beforeOperationToolExecute?: (input: ToolCall, call: ExtensionOperationContext) => Promise<void> | void;
+        callMcpOperation?: (input: ToolCall, call: ExtensionOperationContext, expected: NonNullable<McpToolCallContext['expectedTool']>) => Promise<ToolExecutionResult>;
+        network?: ExtensionNetworkBackend | false;
+        modelUsage?: import('../model/usage-observer.js').ModelUsageObserver;
+        publishModelResource?: AgentHost['publishModelResource'];
+        homeDirectory: string;
+        workspace: string;
+        mode?: 'normal' | 'node';
+        beforeToolExecute?: (call: ToolCall, context: ToolExecutionContext) => Promise<void> | void;
+        approval?: NonNullable<AgentHost['requestToolApproval']> | undefined;
+        question?: (input: {
+            requestId: string;
+            questions: unknown[];
+        }, signal: AbortSignal) => Promise<Record<string, unknown>>;
+        mcpTools?: readonly import('../tools/contracts.js').ClientToolDefinition[];
+        mcpCatalog?: () => McpToolCatalog;
+        callMcp?: (call: ToolCall, signal: AbortSignal, context?: McpToolCallContext) => Promise<ToolExecutionResult>;
+        extensions?: LocalAgentExecutionExtensions;
+        environment?: NodeJS.ProcessEnv;
+        guaranteedCommands?: Readonly<Record<string, string>>;
+        resourceIdleTtlMs?: number;
+        processExecutor?: LocalProcessExecutor;
+        codeModeEngineFactory?: CodeModeEngineFactory;
+        restrictPaths?: boolean;
+        workspaceWritable?: boolean;
+        pathMounts?: readonly WorkspacePathMount[];
+    });
+    describe(): Promise<HostDescription>;
+    executeTool(call: ToolCall, context: ToolExecutionContext): Promise<ToolExecutionResult>;
+    bindExecutionExtensions(extensions: LocalAgentExecutionExtensions, mcp?: LocalAgentMcpBinding): LocalAgentExecutionMcpBinding;
+    listExecutionExtensions(context: McpToolCatalogContext): Promise<HostExecutionExtensions>;
+    listSessionSkills(_context: Pick<McpToolCatalogContext, 'sessionId' | 'modelId'>): Promise<readonly HostSkill[]>;
+    emit(event: AgentEvent): void;
+    requestUserInput(input: {
+        requestId: string;
+        questions: unknown[];
+    }, signal: AbortSignal): Promise<Record<string, unknown>>;
+    bindExecutionMcp(binding?: LocalAgentMcpBinding): LocalAgentExecutionMcpBinding | undefined;
+    unbindExecutionMcp(binding: LocalAgentExecutionMcpBinding | undefined): void;
+    listMcpTools(context?: McpToolCatalogContext): Promise<import("../tools/contracts.js").ClientToolDefinition[]>;
+    listMcpToolCatalog(context: McpToolCatalogContext): Promise<McpToolCatalog>;
+    callMcpTool(call: ToolCall, signal: AbortSignal, context?: McpToolCallContext): Promise<ToolExecutionResult>;
+    listSessionResources(sessionId: string): Promise<{
+        processes: {
+            processId: string;
+            status: "completed" | "cancelled" | "running";
+            command: string;
+            cwd: string;
+        }[];
+        codeCells: {
+            cellId: string;
+            status: "completed" | "failed" | "cancelled" | "running";
+            executionId: string;
+        }[];
+        idleTtlMs?: number;
+    }>;
+    disposeSessionResources(sessionId: string): Promise<void>;
+    dispose(): Promise<void>;
+}
+export declare function selectExecutionShell(environment?: NodeJS.ProcessEnv, platform?: NodeJS.Platform, available?: (path: string) => boolean): {
+    name: string;
+    path: string;
+};

package/dist/host/local-agent-host.js

@@ -0,0 +1,429 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { existsSync } from 'node:fs';
+import { mkdir } from 'node:fs/promises';
+import { basename, delimiter, isAbsolute, join, resolve, win32 } from 'node:path';
+import { AgentError } from '../error.js';
+import { TOOL_EXECUTION_LIMITS } from '../tools/execution-limits.js';
+import { LocalToolRegistry } from './local-tool-registry.js';
+import { AGENT_HOST_API_VERSION } from './contracts.js';
+import { LocalNetworkAccess } from './local-network-access.js';
+import { LocalSessionEnvironment } from './local-session-environment.js';
+import { directLocalProcessExecutor } from './local-process-executor.js';
+import { BUILTIN_TOOL_DEFINITIONS } from '../tools/registry.js';
+import { assertMcpToolCatalog } from '../tools/mcp/catalog.js';
+const BUILTIN_OPERATION_DEFINITIONS = BUILTIN_TOOL_DEFINITIONS.map((definition) => ({
+    definition,
+    revision: createHash('sha256').update(JSON.stringify(definition)).digest('hex')
+}));
+export class LocalAgentHost {
+    modelUsage;
+    extensionPorts;
+    #home;
+    #workspace;
+    #tools;
+    #beforeToolExecute;
+    #question;
+    #mcpTools;
+    #mcpCatalog;
+    #legacyOperationCatalog;
+    #mcpSource = randomUUID();
+    #toolSource = randomUUID();
+    #operationTools;
+    #beforeOperationToolExecute;
+    #callMcpOperation;
+    #callMcp;
+    #executionMcp = new Map();
+    #currentExecutionMcp;
+    #extensions;
+    events = [];
+    requestToolApproval;
+    publishModelResource;
+    #mode;
+    #environment;
+    #sessionEnvironment;
+    #guaranteedCommands;
+    #shell;
+    #resourceIdleTtlMs;
+    constructor(input) {
+        this.modelUsage = input.modelUsage;
+        this.requestToolApproval = input.approval;
+        if (input.publishModelResource !== undefined)
+            this.publishModelResource = input.publishModelResource;
+        this.#home = resolve(input.homeDirectory);
+        this.#workspace = resolve(input.workspace);
+        this.#environment = input.environment ?? process.env;
+        this.#guaranteedCommands = input.guaranteedCommands ?? {};
+        this.#shell = selectExecutionShell(this.#environment);
+        this.#resourceIdleTtlMs = input.resourceIdleTtlMs;
+        const processExecutor = input.processExecutor ?? directLocalProcessExecutor;
+        this.#sessionEnvironment = new LocalSessionEnvironment(this.#environment, (executionId) => {
+            const binding = executionId ? this.#executionMcp.get(executionId) : undefined;
+            return binding?.active ? binding.extensions?.environment : undefined;
+        });
+        this.#tools = new LocalToolRegistry(this.#workspace, this.#environment, this.#shell.path, {
+            ...(input.codeModeEngineFactory === undefined
+                ? {}
+                : { codeModeEngineFactory: input.codeModeEngineFactory }),
+            processExecutor: {
+                spawn: (request) => processExecutor.spawn(this.#sessionEnvironment.forProcess(request))
+            },
+            ...(input.restrictPaths === undefined ? {} : { restrictPaths: input.restrictPaths }),
+            ...(input.workspaceWritable === undefined
+                ? {}
+                : { workspaceWritable: input.workspaceWritable }),
+            ...(input.pathMounts === undefined ? {} : { pathMounts: input.pathMounts })
+        });
+        this.extensionPorts = {
+            tools: {
+                catalog: (sessionId, executionId) => this.#operationToolSources(sessionId, executionId)
+            },
+            environment: this.#sessionEnvironment,
+            ...(input.mcp === undefined ? {} : { mcp: input.mcp }),
+            processes: this.#tools.processes,
+            files: this.#tools.files,
+            ...(input.network === false ? {} : { network: input.network ?? new LocalNetworkAccess() })
+        };
+        this.#beforeToolExecute = input.beforeToolExecute;
+        this.#operationTools = input.operationTools;
+        this.#beforeOperationToolExecute = input.beforeOperationToolExecute;
+        this.#callMcpOperation = input.callMcpOperation;
+        this.#mode = input.mode ?? 'normal';
+        this.#question = input.question;
+        this.#mcpTools = structuredClone(input.mcpTools ?? []);
+        this.#legacyOperationCatalog = {
+            revision: '',
+            servers: [{ id: 'legacy', name: 'External MCP' }],
+            tools: this.#mcpTools.map((definition) => ({
+                definition,
+                serverId: 'legacy',
+                rawName: definition.name,
+                sourceIdentity: this.#mcpSource,
+                definitionRevision: createHash('sha256').update(JSON.stringify(definition)).digest('hex'),
+                lifetime: 'session',
+                exposure: 'deferred'
+            }))
+        };
+        this.#mcpCatalog = input.mcpCatalog;
+        this.#callMcp = input.callMcp;
+        this.#extensions = input.extensions;
+    }
+    async describe() {
+        await mkdir(this.#home, { recursive: true });
+        await mkdir(this.#workspace, { recursive: true });
+        return {
+            apiVersion: AGENT_HOST_API_VERSION,
+            mode: this.#mode,
+            homeDirectory: this.#home,
+            platform: process.platform,
+            architecture: process.arch,
+            shell: this.#shell,
+            guaranteedCommands: this.#guaranteedCommands,
+            capabilities: [
+                'workspace.read',
+                'workspace.patch',
+                'process.manage',
+                'code.execute',
+                'user-input.request',
+                'event.publish'
+            ],
+            limits: {
+                maxProcesses: TOOL_EXECUTION_LIMITS.maxProcesses,
+                maxOutputBytes: TOOL_EXECUTION_LIMITS.execDefaultMaxOutputBytes,
+                maxExecutionMs: TOOL_EXECUTION_LIMITS.execMaxTimeoutMs
+            }
+        };
+    }
+    async executeTool(call, context) {
+        await this.#beforeToolExecute?.(call, context);
+        const binding = this.#executionMcp.get(context.executionId);
+        const extensions = binding?.extensions ?? this.#extensions;
+        if (extensions?.tools?.some((tool) => tool.name === call.name)) {
+            if (binding?.active === false ||
+                !extensions.executeTool ||
+                extensions.isToolAvailable?.(call.name, context) === false)
+                throw new AgentError('MAR_AGENT_TOOL_INPUT_INVALID', 'Host tool execution is unavailable.');
+            context.signal.throwIfAborted();
+            return extensions.executeTool(call, context);
+        }
+        return this.#tools.execute(call, context);
+    }
+    #operationToolSources(sessionId, executionId) {
+        const available = (call) => call.sessionId === sessionId &&
+            (!this.#beforeToolExecute || this.#beforeOperationToolExecute !== undefined);
+        const policy = async (input, call) => {
+            call.signal.throwIfAborted();
+            if (!available(call))
+                throw new AgentError('MAR_AGENT_TOOL_NOT_AVAILABLE', 'Operation tool policy is unavailable.');
+            await this.#beforeOperationToolExecute?.(input, call);
+            call.signal.throwIfAborted();
+        };
+        const local = BUILTIN_OPERATION_DEFINITIONS.filter(({ definition }) => this.#tools.names().includes(definition.name)).map(({ definition, revision }) => ({
+            definition,
+            source: {
+                kind: 'builtin',
+                id: `${this.#toolSource}:${definition.name}`,
+                revision
+            },
+            available: (call) => available(call) && definition.name !== 'code_exec' && definition.name !== 'code_exec_wait',
+            execute: async (input, call) => {
+                await policy(input, call);
+                return this.#tools.executeOperation(input, call);
+            }
+        }));
+        const additional = (this.#operationTools?.catalog(sessionId, executionId) ?? []).map((source) => {
+            const execute = source.execute.bind(source);
+            const check = source.available?.bind(source);
+            return {
+                definition: source.definition,
+                source: { ...source.source },
+                ...(source.mcp === undefined ? {} : { mcp: source.mcp }),
+                available: (call) => available(call) && check?.(call) !== false,
+                execute: async (input, call) => {
+                    await policy(input, call);
+                    if (check?.(call) === false)
+                        throw new AgentError('MAR_AGENT_TOOL_NOT_AVAILABLE', 'Host tool source is unavailable.');
+                    return execute(input, call);
+                }
+            };
+        });
+        const sharedCatalog = () => this.#mcpCatalog?.() ?? this.#legacyOperationCatalog;
+        const catalog = this.#callMcpOperation && executionId === undefined
+            ? structuredClone(sharedCatalog())
+            : { revision: '', servers: [], tools: [] };
+        assertMcpToolCatalog(catalog);
+        const current = (tool) => {
+            const next = sharedCatalog().tools.find((value) => value.definition.name === tool.definition.name);
+            return (next?.lifetime === 'session' &&
+                next.sourceIdentity === tool.sourceIdentity &&
+                next.definitionRevision === tool.definitionRevision);
+        };
+        const mcp = this.#callMcpOperation
+            ? catalog.tools
+                .filter((tool) => tool.lifetime === 'session')
+                .map((tool) => ({
+                definition: tool.definition,
+                mcp: tool,
+                source: { kind: 'mcp', id: tool.sourceIdentity, revision: tool.definitionRevision },
+                available: (call) => available(call) && current(tool),
+                execute: async (input, call) => {
+                    await policy(input, call);
+                    if (!current(tool))
+                        throw new AgentError('MAR_AGENT_MCP_TOOL_DEFINITION_CHANGED', 'MCP tool source changed.');
+                    return this.#callMcpOperation(input, call, {
+                        sourceIdentity: tool.sourceIdentity,
+                        definitionRevision: tool.definitionRevision
+                    });
+                }
+            }))
+            : [];
+        const sources = [...local, ...additional, ...mcp];
+        if (new Set(sources.map((source) => source.definition.name)).size !== sources.length)
+            throw new AgentError('MAR_AGENT_EXTENSION_TOOL_CONFLICT', 'Host tool sources conflict.');
+        return sources;
+    }
+    bindExecutionExtensions(extensions, mcp) {
+        const binding = {
+            tools: mcp?.tools ?? [],
+            ...(mcp?.catalog ? { catalog: mcp.catalog } : {}),
+            call: mcp?.call.bind(mcp) ??
+                (async () => {
+                    throw new AgentError('MAR_AGENT_MCP_FAILED', 'MCP execution is unavailable.');
+                }),
+            extensions: {
+                ...extensions,
+                ...(extensions.environment === undefined
+                    ? {}
+                    : { environment: { ...extensions.environment } })
+            },
+            active: true
+        };
+        this.#currentExecutionMcp = binding;
+        return binding;
+    }
+    async listExecutionExtensions(context) {
+        const binding = this.#executionBinding(context);
+        const { environment: _environment, isToolAvailable, ...extensions } = binding?.extensions ?? this.#extensions ?? {};
+        return {
+            ...extensions,
+            ...(extensions.tools === undefined
+                ? {}
+                : {
+                    tools: extensions.tools.filter((tool) => isToolAvailable?.(tool.name, context) !== false)
+                })
+        };
+    }
+    async listSessionSkills(_context) {
+        return Object.freeze([...(this.#extensions?.skills ?? [])]);
+    }
+    emit(event) {
+        this.events.push(event);
+    }
+    async requestUserInput(input, signal) {
+        if (!this.#question)
+            throw new AgentError('MAR_AGENT_USER_INPUT_UNAVAILABLE', 'User input is unavailable.');
+        return this.#question(input, signal);
+    }
+    bindExecutionMcp(binding) {
+        const current = binding === undefined ? undefined : { ...binding, active: true };
+        if (current === undefined)
+            this.#currentExecutionMcp = undefined;
+        else
+            this.#currentExecutionMcp = current;
+        return current;
+    }
+    unbindExecutionMcp(binding) {
+        if (binding !== undefined)
+            binding.active = false;
+        if (this.#currentExecutionMcp === binding)
+            this.#currentExecutionMcp = undefined;
+        for (const [executionId, candidate] of this.#executionMcp)
+            if (candidate === binding)
+                this.#executionMcp.delete(executionId);
+    }
+    listMcpTools(context) {
+        const execution = this.#executionBinding(context);
+        const tools = [
+            ...(this.#mcpCatalog?.().tools.map((tool) => tool.definition) ?? this.#mcpTools),
+            ...(execution?.active
+                ? (execution.catalog?.().tools.map((tool) => tool.definition) ?? execution.tools)
+                : [])
+        ];
+        if (new Set(tools.map((tool) => tool.name)).size !== tools.length)
+            throw new AgentError('MAR_AGENT_MCP_FAILED', 'MCP tool names conflict.');
+        return Promise.resolve(tools);
+    }
+    async listMcpToolCatalog(context) {
+        const execution = this.#executionBinding(context);
+        const fallback = (tools, lifetime) => ({
+            revision: '',
+            servers: [{ id: 'legacy', name: 'External MCP' }],
+            tools: tools.map((definition) => ({
+                definition,
+                serverId: 'legacy',
+                rawName: definition.name,
+                sourceIdentity: this.#mcpSource,
+                definitionRevision: createHash('sha256').update(JSON.stringify(definition)).digest('hex'),
+                lifetime,
+                exposure: 'deferred'
+            }))
+        });
+        const shared = this.#mcpCatalog?.() ??
+            fallback(execution ? this.#mcpTools : await this.listMcpTools(context), 'session');
+        const scoped = execution?.active
+            ? (execution.catalog?.() ?? fallback(execution.tools, 'execution'))
+            : { revision: '', servers: [], tools: [] };
+        const servers = [
+            ...new Map([...shared.servers, ...scoped.servers].map((server) => [server.id, server])).values()
+        ];
+        const tools = [...shared.tools, ...scoped.tools];
+        if (new Set(tools.map((tool) => tool.definition.name)).size !== tools.length)
+            throw new AgentError('MAR_AGENT_MCP_FAILED', 'MCP tool names conflict.');
+        return {
+            servers,
+            tools,
+            revision: createHash('sha256')
+                .update(JSON.stringify({
+                servers: [...servers].sort((a, b) => a.id.localeCompare(b.id)),
+                tools: [...tools].sort((a, b) => a.definition.name.localeCompare(b.definition.name))
+            }))
+                .digest('hex')
+        };
+    }
+    #executionBinding(context) {
+        const execution = context?.claimExecutionScope === true
+            ? this.#currentExecutionMcp
+            : context?.executionScopeId === undefined
+                ? undefined
+                : this.#executionMcp.get(context.executionScopeId);
+        if (context !== undefined && execution !== undefined)
+            this.#executionMcp.set(context.executionId, execution);
+        return execution;
+    }
+    async callMcpTool(call, signal, context) {
+        signal.throwIfAborted();
+        if (context)
+            await this.#beforeToolExecute?.(call, {
+                mode: context.mode ?? 'run',
+                signal,
+                sessionId: context.sessionId,
+                executionId: context.executionId
+            });
+        signal.throwIfAborted();
+        if (context?.expectedTool) {
+            const current = (await this.listMcpToolCatalog({
+                sessionId: context.sessionId,
+                executionId: context.executionId,
+                executionScopeId: context.executionId
+            })).tools.find((tool) => tool.definition.name === call.name);
+            if (!current ||
+                current.sourceIdentity !== context.expectedTool.sourceIdentity ||
+                current.definitionRevision !== context.expectedTool.definitionRevision)
+                throw new AgentError('MAR_AGENT_MCP_TOOL_DEFINITION_CHANGED', 'MCP tool binding or definition changed.');
+        }
+        signal.throwIfAborted();
+        const execution = context === undefined
+            ? this.#currentExecutionMcp
+            : this.#executionMcp.get(context.executionId);
+        if ((execution?.catalog?.().tools.map((tool) => tool.definition) ?? execution?.tools)?.some((tool) => tool.name === call.name)) {
+            if (!execution.active)
+                throw new AgentError('MAR_AGENT_MCP_FAILED', 'Execution MCP is no longer available.');
+            return execution.call(call, signal, context);
+        }
+        if (!this.#callMcp ||
+            !(this.#mcpCatalog?.().tools.map((tool) => tool.definition) ?? this.#mcpTools).some((tool) => tool.name === call.name))
+            throw new AgentError('MAR_AGENT_MCP_FAILED', 'MCP tool execution is unavailable.');
+        return this.#callMcp(call, signal, context);
+    }
+    listSessionResources(sessionId) {
+        return Promise.resolve({
+            ...(this.#resourceIdleTtlMs === undefined ? {} : { idleTtlMs: this.#resourceIdleTtlMs }),
+            processes: this.#tools.listSessionResources(sessionId),
+            codeCells: this.#tools.listCodeCells(sessionId)
+        });
+    }
+    async disposeSessionResources(sessionId) {
+        try {
+            await this.#tools.disposeSessionResources(sessionId);
+        }
+        finally {
+            this.#sessionEnvironment.clearSession(sessionId);
+        }
+    }
+    async dispose() {
+        try {
+            await this.#tools.dispose();
+        }
+        finally {
+            this.#sessionEnvironment.clear();
+        }
+    }
+}
+export function selectExecutionShell(environment = process.env, platform = process.platform, available = existsSync) {
+    const candidates = platform === 'win32'
+        ? [
+            resolveCommand('pwsh.exe', environment, platform, available),
+            resolveCommand('powershell.exe', environment, platform, available),
+            environment['ComSpec'],
+            environment['COMSPEC'],
+            'cmd.exe'
+        ]
+        : ['/bin/bash', resolveCommand('bash', environment, platform, available), '/bin/sh'];
+    const path = candidates.find((candidate) => candidate && available(candidate)) ?? candidates.at(-1);
+    const name = (platform === 'win32' ? win32.basename(path) : basename(path)).replace(/\.exe$/iu, '');
+    return { name, path };
+}
+function resolveCommand(name, environment, platform, available) {
+    if (isAbsolute(name))
+        return available(name) ? name : undefined;
+    const pathValue = environment[platform === 'win32' ? 'Path' : 'PATH'] ?? environment['PATH'];
+    if (!pathValue)
+        return undefined;
+    const separator = platform === 'win32' ? win32.delimiter : delimiter;
+    const combine = platform === 'win32' ? win32.join : join;
+    for (const directory of pathValue.split(separator).filter(Boolean)) {
+        const candidate = combine(directory, name);
+        if (available(candidate))
+            return candidate;
+    }
+    return undefined;
+}

package/dist/host/local-exec-tool.d.ts

@@ -0,0 +1,26 @@
+import { type LocalProcessExecutor } from './local-process-executor.js';
+import type { ExecOutputSnapshot, ExecResult } from '../tools/contracts.js';
+import { type ToolWaitInterrupt } from '../tools/wait.js';
+import { WorkspacePathResolver } from '../tools/shared/path-resolver.js';
+import { type ExtensionProcessInput, type ExtensionProcessHandle } from '../extensions/processes.js';
+import type { ExtensionOperationContext } from '../extensions/operation.js';
+export declare class ExecTool {
+    #private;
+    private readonly paths;
+    readonly maxOutputBytes: number;
+    readonly maxProcesses: number;
+    private readonly environment;
+    private readonly shell?;
+    private readonly processExecutor;
+    constructor(paths: WorkspacePathResolver, maxOutputBytes?: number, maxProcesses?: number, environment?: NodeJS.ProcessEnv, shell?: string | undefined, processExecutor?: LocalProcessExecutor);
+    execute(arguments_: unknown, signal?: AbortSignal, owner?: NonNullable<import('./local-process-executor.js').LocalProcessSpawnRequest['owner']>, waitInterrupt?: ToolWaitInterrupt, onOutput?: (output: ExecOutputSnapshot) => Promise<void>): Promise<ExecResult>;
+    spawn(input: ExtensionProcessInput, call: ExtensionOperationContext): Promise<ExtensionProcessHandle>;
+    listSessionResources(sessionId: string): {
+        processId: string;
+        status: "completed" | "cancelled" | "running";
+        command: string;
+        cwd: string;
+    }[];
+    disposeSession(sessionId: string): Promise<void>;
+    dispose(): Promise<void>;
+}