@myagentroam/agent 0.9.158 → 0.9.160

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

@@ -6,8 +6,13 @@ import { MarAgentError } from '../error.js';
 import { TOOL_EXECUTION_LIMITS } from '../tools/execution-limits.js';
 import { LocalToolRegistry } from '../tools/local/registry.js';
 import { MAR_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';
 export class LocalAgentHost {
+    extensionPorts;
     #home;
     #workspace;
     #tools;
@@ -16,6 +21,10 @@ export class LocalAgentHost {
     #mcpTools;
     #mcpCatalog;
     #mcpSource = randomUUID();
+    #toolSource = randomUUID();
+    #operationTools;
+    #beforeOperationToolExecute;
+    #callMcpOperation;
     #callMcp;
     #executionMcp = new Map();
     #currentExecutionMcp;
@@ -23,6 +32,7 @@ export class LocalAgentHost {
     events = [];
     #mode;
     #environment;
+    #sessionEnvironment;
     #guaranteedCommands;
     #shell;
     #resourceIdleTtlMs;
@@ -34,28 +44,16 @@ export class LocalAgentHost {
         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) => {
-                    const binding = request.owner && this.#executionMcp.get(request.owner.executionId);
-                    const environment = binding?.active ? binding.extensions?.environment : undefined;
-                    return processExecutor.spawn(environment === undefined
-                        ? request
-                        : {
-                            ...request,
-                            environment: { ...request.environment, ...environment },
-                            ...(request.environmentKeys === undefined
-                                ? {}
-                                : {
-                                    environmentKeys: [
-                                        ...new Set([...request.environmentKeys, ...Object.keys(environment)])
-                                    ]
-                                })
-                        });
-                }
+                spawn: (request) => processExecutor.spawn(this.#sessionEnvironment.forProcess(request))
             },
             ...(input.restrictPaths === undefined ? {} : { restrictPaths: input.restrictPaths }),
             ...(input.workspaceWritable === undefined
@@ -63,7 +61,20 @@ export class LocalAgentHost {
                 : { 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 = input.mcpTools ?? [];
@@ -112,6 +123,94 @@ export class LocalAgentHost {
         }
         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 MarAgentError('MAR_AGENT_TOOL_NOT_AVAILABLE', 'Operation tool policy is unavailable.');
+            await this.#beforeOperationToolExecute?.(input, call);
+            call.signal.throwIfAborted();
+        };
+        const local = BUILTIN_TOOL_DEFINITIONS.filter((definition) => this.#tools.names().includes(definition.name)).map((definition) => ({
+            definition,
+            source: {
+                kind: 'builtin',
+                id: `${this.#toolSource}:${definition.name}`,
+                revision: createHash('sha256').update(JSON.stringify(definition)).digest('hex')
+            },
+            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 MarAgentError('MAR_AGENT_TOOL_NOT_AVAILABLE', 'Host tool source is unavailable.');
+                    return execute(input, call);
+                }
+            };
+        });
+        const sharedCatalog = () => structuredClone(this.#mcpCatalog?.() ?? {
+            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'
+            }))
+        });
+        const catalog = this.#callMcpOperation && executionId === undefined
+            ? 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 MarAgentError('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 MarAgentError('MAR_AGENT_EXTENSION_TOOL_CONFLICT', 'Host tool sources conflict.');
+        return sources;
+    }
     bindExecutionExtensions(extensions, mcp) {
         const binding = {
             tools: mcp?.tools ?? [],
@@ -143,6 +242,9 @@ export class LocalAgentHost {
                 })
         };
     }
+    async listSessionSkills(_context) {
+        return Object.freeze([...(this.#extensions?.skills ?? [])]);
+    }
     emit(event) {
         this.events.push(event);
     }
@@ -269,11 +371,21 @@ export class LocalAgentHost {
             codeCells: this.#tools.listCodeCells(sessionId)
         });
     }
-    disposeSessionResources(sessionId) {
-        return this.#tools.disposeSessionResources(sessionId);
+    async disposeSessionResources(sessionId) {
+        try {
+            await this.#tools.disposeSessionResources(sessionId);
+        }
+        finally {
+            this.#sessionEnvironment.clearSession(sessionId);
+        }
     }
     async dispose() {
-        await this.#tools.dispose();
+        try {
+            await this.#tools.dispose();
+        }
+        finally {
+            this.#sessionEnvironment.clear();
+        }
     }
 }
 export function selectExecutionShell(environment = process.env, platform = process.platform, available = existsSync) {

package/dist/agent-core/host/local-file-access.d.ts

@@ -0,0 +1,30 @@
+import type { CoreFilesBackend, CoreFilePath, CoreFileWrite, CoreFileRemove, CoreFileTransfer, CoreFileType } from '../extensions/files.js';
+import type { CoreOperationContext } from '../extensions/operation.js';
+import { WorkspacePathResolver } from '../tools/shared/path-resolver.js';
+/** Raw native access shares the exact resolver used by the Host's model-facing tools. */
+export declare class LocalFileAccess implements CoreFilesBackend {
+    #private;
+    readonly paths: WorkspacePathResolver;
+    constructor(paths: WorkspacePathResolver);
+    read(input: CoreFilePath, call: CoreOperationContext): Promise<Uint8Array<ArrayBuffer>>;
+    write(input: CoreFileWrite, call: CoreOperationContext): Promise<{
+        bytesWritten: number;
+    }>;
+    stat(input: CoreFilePath, call: CoreOperationContext): Promise<{
+        path: string;
+        type: CoreFileType;
+        size: number;
+        modifiedAtMs: number;
+        createdAtMs: number;
+    }>;
+    list(input: CoreFilePath, call: CoreOperationContext): Promise<{
+        name: string;
+        type: CoreFileType;
+    }[]>;
+    mkdir(input: CoreFilePath & {
+        readonly recursive?: boolean;
+    }, call: CoreOperationContext): Promise<void>;
+    remove(input: CoreFileRemove, call: CoreOperationContext): Promise<void>;
+    move(input: CoreFileTransfer, call: CoreOperationContext): Promise<void>;
+    copy(input: CoreFileTransfer, call: CoreOperationContext): Promise<void>;
+}

package/dist/agent-core/host/local-file-access.js

@@ -0,0 +1,107 @@
+import { copyFile, lstat, mkdir, readFile, readdir, rename, rm, writeFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { MarAgentError } from '../error.js';
+/** Raw native access shares the exact resolver used by the Host's model-facing tools. */
+export class LocalFileAccess {
+    paths;
+    constructor(paths) {
+        this.paths = paths;
+    }
+    read(input, call) {
+        return this.#execute('read', call, async () => new Uint8Array(await readFile(await this.#path(input.path), { signal: call.signal })));
+    }
+    write(input, call) {
+        return this.#execute('write', call, async () => {
+            if (!(input.bytes instanceof Uint8Array))
+                throw new MarAgentError('MAR_AGENT_FILE_INPUT_INVALID', 'File bytes must be a Uint8Array.');
+            const bytes = Buffer.from(input.bytes);
+            const path = await this.#path(input.path, true);
+            call.signal.throwIfAborted();
+            if (input.createParents)
+                await mkdir(dirname(path), { recursive: true });
+            await writeFile(path, bytes, { signal: call.signal });
+            return { bytesWritten: bytes.byteLength };
+        });
+    }
+    stat(input, call) {
+        return this.#execute('stat', call, async () => {
+            const path = await this.paths.resolveWithDisplay(this.#validatePath(input.path));
+            const info = await lstat(path.physicalPath);
+            return {
+                path: path.displayPath,
+                type: fileType(info),
+                size: info.size,
+                modifiedAtMs: info.mtimeMs,
+                createdAtMs: info.birthtimeMs
+            };
+        });
+    }
+    list(input, call) {
+        return this.#execute('list', call, async () => (await readdir(await this.#path(input.path), { withFileTypes: true })).map((entry) => ({
+            name: entry.name,
+            type: fileType(entry)
+        })));
+    }
+    mkdir(input, call) {
+        return this.#execute('mkdir', call, async () => {
+            const path = await this.#path(input.path, true);
+            call.signal.throwIfAborted();
+            await mkdir(path, { recursive: input.recursive ?? false });
+        });
+    }
+    remove(input, call) {
+        return this.#execute('remove', call, async () => {
+            const path = await this.#path(input.path, true);
+            call.signal.throwIfAborted();
+            await rm(path, { recursive: input.recursive ?? false, force: input.force ?? false });
+        });
+    }
+    move(input, call) {
+        return this.#execute('move', call, async () => {
+            const from = await this.#path(input.from, true);
+            const to = await this.#path(input.to, true);
+            call.signal.throwIfAborted();
+            await rename(from, to);
+        });
+    }
+    copy(input, call) {
+        return this.#execute('copy', call, async () => {
+            const from = await this.#path(input.from);
+            const to = await this.#path(input.to, true);
+            call.signal.throwIfAborted();
+            await copyFile(from, to);
+        });
+    }
+    #validatePath(path) {
+        if (typeof path !== 'string')
+            throw new MarAgentError('MAR_AGENT_FILE_INPUT_INVALID', 'File path must be a string.');
+        return path;
+    }
+    #path(path, write = false) {
+        return this.paths.resolve(this.#validatePath(path), write, write ? 'write' : 'read');
+    }
+    async #execute(operation, call, action) {
+        call.signal.throwIfAborted();
+        try {
+            return await action();
+        }
+        catch (cause) {
+            call.signal.throwIfAborted();
+            if (cause instanceof MarAgentError)
+                throw cause;
+            throw new MarAgentError('MAR_AGENT_FILE_OPERATION_FAILED', 'Native file operation failed.', {
+                details: { operation, reason: cause.code ?? 'UNKNOWN' },
+                cause
+            });
+        }
+    }
+}
+function fileType(info) {
+    return info.isSymbolicLink()
+        ? 'symlink'
+        : info.isFile()
+            ? 'file'
+            : info.isDirectory()
+                ? 'directory'
+                : 'other';
+}

package/dist/agent-core/host/local-network-access.d.ts

@@ -0,0 +1,6 @@
+import type { CoreHttpRequest, CoreHttpResponse, CoreNetworkBackend } from '../extensions/network.js';
+import type { CoreOperationContext } from '../extensions/operation.js';
+/** Raw HTTP transport; presentation, retries, and browser fetch remain separate tools. */
+export declare class LocalNetworkAccess implements CoreNetworkBackend {
+    fetch(input: CoreHttpRequest, call: CoreOperationContext): Promise<CoreHttpResponse>;
+}

package/dist/agent-core/host/local-network-access.js

@@ -0,0 +1,97 @@
+import { MarAgentError } from '../error.js';
+/** Raw HTTP transport; presentation, retries, and browser fetch remain separate tools. */
+export class LocalNetworkAccess {
+    async fetch(input, call) {
+        call.signal.throwIfAborted();
+        if (!input || typeof input.url !== 'string')
+            throw new MarAgentError('MAR_AGENT_NETWORK_REQUEST_INVALID', 'HTTP URL is required.');
+        let url;
+        try {
+            url = new URL(input.url);
+        }
+        catch {
+            throw new MarAgentError('MAR_AGENT_NETWORK_REQUEST_INVALID', 'HTTP URL is invalid.');
+        }
+        if (!['http:', 'https:'].includes(url.protocol))
+            throw new MarAgentError('MAR_AGENT_NETWORK_REQUEST_INVALID', 'An HTTP or HTTPS URL is required.');
+        const controller = new AbortController();
+        const signal = AbortSignal.any([
+            call.signal,
+            controller.signal,
+            ...(input.signal ? [input.signal] : [])
+        ]);
+        let response;
+        try {
+            response = await globalThis.fetch(url, {
+                ...(input.method === undefined ? {} : { method: input.method }),
+                ...(input.headers === undefined ? {} : { headers: input.headers.map((pair) => [...pair]) }),
+                ...(input.body === undefined
+                    ? {}
+                    : { body: typeof input.body === 'string' ? input.body : Buffer.from(input.body) }),
+                ...(input.redirect === undefined ? {} : { redirect: input.redirect }),
+                signal
+            });
+        }
+        catch (error) {
+            signal.throwIfAborted();
+            const cause = error && typeof error === 'object'
+                ? error.cause
+                : undefined;
+            throw new MarAgentError('MAR_AGENT_NETWORK_FAILED', 'HTTP request failed.', {
+                ...(typeof cause?.code === 'string' ? { details: { reasonCode: cause.code } } : {})
+            });
+        }
+        const reader = response.body?.getReader();
+        let closing;
+        const close = () => {
+            closing ??= (async () => {
+                signal.removeEventListener('abort', onAbort);
+                controller.abort();
+                try {
+                    await reader?.cancel();
+                }
+                catch (error) {
+                    // An already-aborted Fetch reader rejects cancel with that same cancellation reason.
+                    if (!signal.aborted || error !== signal.reason)
+                        throw error;
+                }
+                finally {
+                    reader?.releaseLock();
+                }
+            })();
+            return closing;
+        };
+        const onAbort = () => {
+            void close().catch(() => undefined);
+        };
+        signal.addEventListener('abort', onAbort, { once: true });
+        if (signal.aborted) {
+            await close();
+            signal.throwIfAborted();
+        }
+        const body = async function* () {
+            try {
+                while (reader) {
+                    signal.throwIfAborted();
+                    const next = await reader.read();
+                    signal.throwIfAborted();
+                    if (next.done)
+                        return;
+                    yield next.value;
+                }
+            }
+            finally {
+                await close();
+            }
+        };
+        return {
+            url: response.url,
+            status: response.status,
+            statusText: response.statusText,
+            redirected: response.redirected,
+            headers: [...response.headers.entries()],
+            body: body(),
+            close
+        };
+    }
+}

package/dist/agent-core/host/local-process-executor.d.ts

@@ -5,13 +5,17 @@ export interface LocalProcessSpawnRequest {
     readonly cwd: string;
     readonly shell?: boolean | string;
     readonly environment: NodeJS.ProcessEnv;
+    /** Explicit per-start values take precedence over execution-bound Host environment. */
+    readonly environmentOverrides?: Readonly<Record<string, string>>;
     readonly environmentKeys?: readonly string[];
     /** Trusted, bounded read-only worker assets; never supplied by model tool input. */
     readonly runtimeDirectories?: readonly string[];
     readonly detached: boolean;
     readonly owner?: {
         readonly sessionId: string;
-        readonly executionId: string;
+        readonly executionId?: string;
+        readonly operationId?: string;
+        readonly ownerInstanceId?: string;
     };
     readonly signal?: AbortSignal;
 }

package/dist/agent-core/host/local-session-environment.d.ts

@@ -0,0 +1,18 @@
+import type { CoreEnvironmentBackend, CoreEnvironmentKey, CoreEnvironmentSet } from '../extensions/environment.js';
+import type { CoreOperationContext } from '../extensions/operation.js';
+import type { LocalProcessSpawnRequest } from './local-process-executor.js';
+/** Session-owned overlay, shared by native and model/programmatic process starts. */
+export declare class LocalSessionEnvironment implements CoreEnvironmentBackend {
+    #private;
+    private readonly base;
+    private readonly executionEnvironment;
+    private readonly platform;
+    constructor(base: NodeJS.ProcessEnv, executionEnvironment: (executionId?: string) => Readonly<Record<string, string>> | undefined, platform?: NodeJS.Platform);
+    get(input: CoreEnvironmentKey, call: CoreOperationContext): Promise<string | undefined>;
+    set(input: CoreEnvironmentSet, call: CoreOperationContext): Promise<{
+        changed: boolean;
+    }>;
+    forProcess(request: LocalProcessSpawnRequest): LocalProcessSpawnRequest;
+    clearSession(sessionId: string): void;
+    clear(): void;
+}

package/dist/agent-core/host/local-session-environment.js

@@ -0,0 +1,102 @@
+import { validateEnvironmentInput } from '../extensions/environment.js';
+/** Session-owned overlay, shared by native and model/programmatic process starts. */
+export class LocalSessionEnvironment {
+    base;
+    executionEnvironment;
+    platform;
+    #sessions = new Map();
+    constructor(base, executionEnvironment, platform = process.platform) {
+        this.base = base;
+        this.executionEnvironment = executionEnvironment;
+        this.platform = platform;
+    }
+    #key(key) {
+        return this.platform === 'win32' ? key.toUpperCase() : key;
+    }
+    #read(environment, key) {
+        if (this.platform !== 'win32')
+            return Object.hasOwn(environment, key) ? environment[key] : undefined;
+        const name = Object.keys(environment).find((name) => this.#key(name) === this.#key(key));
+        return name === undefined ? undefined : environment[name];
+    }
+    async get(input, call) {
+        validateEnvironmentInput(input);
+        call.signal.throwIfAborted();
+        const overlay = this.#sessions.get(call.sessionId)?.get(this.#key(input.key));
+        if (overlay)
+            return overlay.value;
+        const execution = this.executionEnvironment(call.executionId);
+        if (execution && Object.keys(execution).some((key) => this.#key(key) === this.#key(input.key)))
+            return this.#read(execution, input.key);
+        return this.#read(this.base, input.key);
+    }
+    async set(input, call) {
+        validateEnvironmentInput(input);
+        call.signal.throwIfAborted();
+        const key = this.#key(input.key);
+        const entries = this.#sessions.get(call.sessionId) ?? new Map();
+        const before = entries.get(key);
+        const changed = !before || before.value !== input.value;
+        // The tombstone is a real change even if the current lower layer happens to be unset.
+        entries.set(key, { key: input.key, value: input.value });
+        this.#sessions.set(call.sessionId, entries);
+        return { changed };
+    }
+    forProcess(request) {
+        const execution = this.executionEnvironment(request.owner?.executionId);
+        const entries = request.owner && this.#sessions.get(request.owner.sessionId);
+        if (execution === undefined &&
+            !entries?.size &&
+            (this.platform !== 'win32' || request.environmentOverrides === undefined))
+            return request;
+        const environment = { ...request.environment };
+        const assign = (key, value) => {
+            if (this.platform === 'win32') {
+                for (const current of Object.keys(environment))
+                    if (this.#key(current) === this.#key(key))
+                        delete environment[current];
+            }
+            if (value === undefined)
+                delete environment[key];
+            else
+                Object.defineProperty(environment, key, {
+                    value,
+                    enumerable: true,
+                    writable: true,
+                    configurable: true
+                });
+        };
+        for (const [key, value] of Object.entries(execution ?? {}))
+            assign(key, value);
+        for (const entry of entries?.values() ?? [])
+            assign(entry.key, entry.value);
+        for (const [key, value] of Object.entries(request.environmentOverrides ?? {}))
+            assign(key, value);
+        return {
+            ...request,
+            environment,
+            ...(request.environmentKeys === undefined
+                ? {}
+                : {
+                    environmentKeys: [
+                        ...new Set([
+                            ...request.environmentKeys,
+                            ...Object.keys(execution ?? {}),
+                            ...Object.keys(request.environmentOverrides ?? {}),
+                            ...[...(entries?.values() ?? [])].map((entry) => entry.key)
+                        ]
+                            .map((key) => this.platform === 'win32'
+                            ? Object.keys(environment).find((name) => this.#key(name) === this.#key(key))
+                            : key)
+                            .filter((key) => key !== undefined && environment[key] !== undefined))
+                    ]
+                })
+        };
+    }
+    clearSession(sessionId) {
+        this.#sessions.delete(sessionId);
+    }
+    clear() {
+        this.#sessions.clear();
+    }
+}