@myagentroam/agent 0.11.32 → 0.11.34

package/dist/extensions/manager.js

@@ -0,0 +1,457 @@
+import { AgentError } from '../error.js';
+import { ExtensionOperations } from './operation.js';
+import { ExtensionResourceScope } from './resources.js';
+import { ExtensionServices } from './services.js';
+import { ExtensionSession } from './session.js';
+import { coreSettingsBinding, settingsCapabilities } from './settings.js';
+import { agentCapabilities } from './agents.js';
+/** Agent admission coordinates a single composition generation, never parallel replacement loops. */
+export class ExtensionManager {
+    options;
+    operations = new ExtensionOperations();
+    #diagnostics = [];
+    #sessions = new Map();
+    #epochs = new Map();
+    #controller = new AbortController();
+    #agentServices = new ExtensionServices('agent');
+    #agentScopes = [];
+    #setupFailures = new Set();
+    #strictSetupFailure = false;
+    #strictSessions = new Set();
+    #cleanupFailedSessions = new Set();
+    #cleanupFailed = false;
+    #snapshot;
+    #orders = {
+        agent: { extensions: [], failures: [] },
+        session: { extensions: [], failures: [] }
+    };
+    #tail = Promise.resolve();
+    #disposal;
+    #endings = new WeakMap();
+    capabilities;
+    constructor(options) {
+        this.options = options;
+        const capabilities = Object.freeze([...new Set(options.capabilities)]);
+        this.capabilities = Object.freeze({
+            has: (id) => capabilities.includes(id),
+            list: () => capabilities
+        });
+    }
+    diagnostics() {
+        return [...this.#diagnostics];
+    }
+    session(id) {
+        return this.#sessions.get(id);
+    }
+    get revision() {
+        return this.#snapshot?.revision;
+    }
+    hasReferences() {
+        return [...this.#sessions.values()].some((session) => session.hasReferences);
+    }
+    prepare(sessionId, signal, baseTools, refresh = true) {
+        const loadingSignal = AbortSignal.any([signal, this.#controller.signal]);
+        // A retiring owner may join a child whose admission would otherwise queue behind disposal.
+        if (loadingSignal.aborted)
+            return Promise.reject(loadingSignal.reason);
+        if (this.#sessions.get(sessionId)?.isEnding)
+            return Promise.reject(new AgentError('MAR_AGENT_SESSION_CLOSING', 'Session is closing.'));
+        return this.#serial(async () => {
+            loadingSignal.throwIfAborted();
+            if (this.#sessions.get(sessionId)?.isEnding)
+                throw new AgentError('MAR_AGENT_SESSION_CLOSING', 'Session is closing.');
+            if (this.#cleanupFailed || this.#cleanupFailedSessions.has(sessionId))
+                throw new AgentError('MAR_AGENT_EXTENSION_CLEANUP_FAILED', 'Retired extension resources did not clean up.');
+            const source = this.options.extensions;
+            const resolved = !refresh && this.#snapshot
+                ? this.#snapshot
+                : Array.isArray(source)
+                    ? { revision: 'static', extensions: source }
+                    : await source.resolve({ signal: loadingSignal });
+            loadingSignal.throwIfAborted();
+            this.#validateSnapshot(resolved);
+            if (!this.#snapshot || this.#snapshot.revision !== resolved.revision) {
+                if (this.#snapshot && (this.options.busyExcept(sessionId) || this.hasReferences())) {
+                    this.#diagnose({
+                        code: 'MAR_AGENT_EXTENSION_UPDATE_PENDING',
+                        sessionId,
+                        revision: resolved.revision
+                    });
+                }
+                else {
+                    const orders = {
+                        agent: ordered(resolved.extensions, 'agent'),
+                        session: ordered(resolved.extensions, 'session')
+                    };
+                    await this.#retire();
+                    loadingSignal.throwIfAborted();
+                    this.#snapshot = {
+                        revision: resolved.revision,
+                        extensions: resolved.extensions.map((extension) => Object.freeze({
+                            ...extension,
+                            bindings: Object.freeze({ ...(extension.bindings ?? {}) })
+                        }))
+                    };
+                    this.#orders = orders;
+                    try {
+                        await this.#setup(loadingSignal);
+                    }
+                    catch (error) {
+                        if (loadingSignal.aborted) {
+                            await this.#retire();
+                            this.#snapshot = undefined;
+                        }
+                        throw error;
+                    }
+                }
+            }
+            if (this.#strictSetupFailure)
+                throw new AgentError('MAR_AGENT_EXTENSION_COMPOSITION_FAILED', 'Required extension initialization failed.');
+            let session = this.#sessions.get(sessionId);
+            if (!session) {
+                session = new ExtensionSession(this.options.toolRuntime, sessionId, this.#epochs.get(sessionId) ?? 0, this.#agentServices, this.operations, agentCapabilities(this.capabilities, this.options.agentsBackend?.(sessionId) !== undefined), (diagnostic) => this.#diagnose(diagnostic), (context) => this.options.baseTools?.(sessionId, context) ?? [], this.options.models, this.options.checkpoint, this.options.sessionBackend?.(sessionId), this.options.hostPorts, this.options.agentsBackend?.(sessionId), (name, definition) => this.options.allowTool?.(sessionId, name, definition) ?? true, this.options.scheduleTool?.(sessionId), this.options.store);
+                this.#sessions.set(sessionId, session);
+                try {
+                    await this.#attach(session, loadingSignal, baseTools);
+                }
+                catch (error) {
+                    if (loadingSignal.aborted) {
+                        await session.dispose();
+                        this.#sessions.delete(sessionId);
+                    }
+                    throw error;
+                }
+            }
+            if (this.#strictSessions.has(sessionId))
+                throw new AgentError('MAR_AGENT_EXTENSION_COMPOSITION_FAILED', 'Required Session extension initialization failed.');
+            return session;
+        });
+    }
+    clearSession(id) {
+        this.retireSession(id);
+        return this.#serial(async () => {
+            try {
+                await this.#sessions.get(id)?.dispose();
+            }
+            catch (error) {
+                this.#cleanupFailedSessions.add(id);
+                this.#diagnose({ code: 'MAR_AGENT_EXTENSION_CLEANUP_FAILED', sessionId: id });
+                throw error;
+            }
+            this.#sessions.delete(id);
+            this.#strictSessions.delete(id);
+            this.#epochs.set(id, (this.#epochs.get(id) ?? 0) + 1);
+        });
+    }
+    async endSession(id, reason, resumable = true) {
+        const session = this.#sessions.get(id);
+        if (!session)
+            return;
+        const previous = this.#endings.get(session);
+        if (previous)
+            return previous;
+        session.isEnding = true;
+        const controller = new AbortController();
+        const ending = Promise.resolve().then(async () => {
+            try {
+                await this.operations.enter({
+                    sessionId: id,
+                    sessionEpoch: session.epoch,
+                    actor: 'sdk',
+                    entry: 'native-api',
+                    signal: controller.signal
+                }, (call) => session.hooks.emit('session.ending', { sessionId: id, reason, resumable }, call));
+            }
+            finally {
+                controller.abort();
+            }
+        });
+        this.#endings.set(session, ending);
+        return ending;
+    }
+    retireSession(id) {
+        this.#sessions.get(id)?.retire();
+    }
+    dispose() {
+        if (this.#disposal)
+            return this.#disposal;
+        this.#controller.abort();
+        const endings = [];
+        for (const [id, session] of this.#sessions) {
+            if (session.hooks.hasObservers('session.ending'))
+                endings.push(this.endSession(id, 'other'));
+            else
+                session.retire();
+        }
+        for (const scope of this.#agentScopes)
+            scope.retire();
+        this.#disposal = (async () => {
+            await Promise.all(endings);
+            for (const id of this.#sessions.keys())
+                this.retireSession(id);
+            await this.#serial(() => this.#retire());
+        })();
+        return this.#disposal;
+    }
+    async #setup(signal) {
+        for (const extension of this.#orders.agent.failures) {
+            this.#setupFailures.add(extension.id);
+            this.#strictSetupFailure ||= extension.failurePolicy === 'fail-composition';
+            this.#diagnose({
+                code: 'MAR_AGENT_EXTENSION_DEPENDENCY_CYCLE',
+                extensionId: extension.id,
+                revision: this.#snapshot.revision
+            });
+        }
+        for (const extension of this.#orders.agent.extensions) {
+            const scope = new ExtensionResourceScope();
+            try {
+                this.#check(extension, 'agent', this.#agentServices);
+                const context = {
+                    ...(extension.dataDirectory === undefined
+                        ? {}
+                        : {
+                            data: {
+                                store: this.options.store(extension.dataDirectory, (operation) => scope.run(operation))
+                            }
+                        }),
+                    resources: scope,
+                    services: this.#agentServices.bind(scope),
+                    capabilities: settingsCapabilities(this.capabilities, coreSettingsBinding(extension.bindings) !== undefined),
+                    bindings: extension.bindings ?? {},
+                    observability: {
+                        log: (message) => this.#diagnose({
+                            code: 'MAR_AGENT_EXTENSION_LOG',
+                            extensionId: extension.id,
+                            message: message.slice(0, 1000)
+                        })
+                    }
+                };
+                await ExtensionResourceScope.initialize(async () => {
+                    const release = await extension.setup?.(context);
+                    if (release)
+                        scope.effect(() => release);
+                    await scope.ready();
+                });
+                this.#checkProvides(extension, 'agent', this.#agentServices, scope);
+                signal.throwIfAborted();
+                this.#agentScopes.push(scope);
+            }
+            catch (error) {
+                this.#setupFailures.add(extension.id);
+                this.#strictSetupFailure ||= extension.failurePolicy === 'fail-composition';
+                this.#diagnose({
+                    code: failureCode(error),
+                    extensionId: extension.id,
+                    revision: this.#snapshot.revision
+                });
+                try {
+                    await scope.dispose();
+                }
+                catch (cleanupError) {
+                    this.#agentScopes.push(scope);
+                    this.#cleanupFailed = true;
+                    this.#diagnose({
+                        code: 'MAR_AGENT_EXTENSION_CLEANUP_FAILED',
+                        extensionId: extension.id,
+                        revision: this.#snapshot.revision
+                    });
+                    throw cleanupError;
+                }
+                signal.throwIfAborted();
+            }
+        }
+        for (const scope of this.#agentScopes)
+            scope.activate();
+    }
+    async #attach(session, signal, baseTools) {
+        for (const extension of this.#orders.session.failures) {
+            if (extension.failurePolicy === 'fail-composition')
+                this.#strictSessions.add(session.id);
+            this.#diagnose({
+                code: 'MAR_AGENT_EXTENSION_DEPENDENCY_CYCLE',
+                extensionId: extension.id,
+                sessionId: session.id,
+                revision: this.#snapshot.revision
+            });
+        }
+        for (const extension of this.#orders.session.extensions) {
+            if (this.#setupFailures.has(extension.id))
+                continue;
+            const scope = new ExtensionResourceScope();
+            try {
+                this.#check(extension, 'session', session.services, session.capabilities);
+                await ExtensionResourceScope.initialize(async () => {
+                    const release = await extension.attachSession?.(session.context(extension, scope));
+                    if (release)
+                        scope.effect(() => release);
+                    await scope.ready();
+                });
+                this.#checkProvides(extension, 'session', session.services, scope);
+                session.capture(undefined, true, baseTools);
+                signal.throwIfAborted();
+                session.scopes.push(scope);
+            }
+            catch (error) {
+                if (extension.failurePolicy === 'fail-composition')
+                    this.#strictSessions.add(session.id);
+                this.#diagnose({
+                    code: failureCode(error),
+                    extensionId: extension.id,
+                    sessionId: session.id,
+                    revision: this.#snapshot.revision
+                });
+                try {
+                    await scope.dispose();
+                }
+                catch (cleanupError) {
+                    session.scopes.push(scope);
+                    this.#cleanupFailedSessions.add(session.id);
+                    this.#diagnose({
+                        code: 'MAR_AGENT_EXTENSION_CLEANUP_FAILED',
+                        extensionId: extension.id,
+                        sessionId: session.id,
+                        revision: this.#snapshot.revision
+                    });
+                    throw cleanupError;
+                }
+                signal.throwIfAborted();
+            }
+        }
+        session.activate();
+    }
+    #check(extension, scope, services, availableCapabilities = this.capabilities) {
+        if (extension.apiVersion !== '1.0')
+            throw new AgentError('MAR_AGENT_EXTENSION_API_INCOMPATIBLE', 'Extension API version is incompatible.');
+        const capabilities = settingsCapabilities(availableCapabilities, coreSettingsBinding(extension.bindings) !== undefined);
+        if (extension.requires?.some((requirement) => !capabilities.has(requirement.id)))
+            throw new AgentError('MAR_AGENT_EXTENSION_DEPENDENCY_MISSING', 'Required capability is unavailable.');
+        if (scope === 'agent' && !extension.setup)
+            return;
+        for (const dependency of extension.serviceDependencies ?? []) {
+            if (scope === 'agent' && dependency.key.scope !== 'agent')
+                continue;
+            if (scope === 'session' && dependency.key.scope === 'agent' && extension.setup)
+                continue;
+            if (dependency.key.scope === scope || scope === 'session') {
+                if (!dependency.optional && !services.has(dependency.key))
+                    throw new AgentError('MAR_AGENT_EXTENSION_DEPENDENCY_MISSING', 'Required service is unavailable.');
+            }
+        }
+    }
+    #checkProvides(extension, scope, services, owner) {
+        if (extension.provides?.some((declaration) => declaration.key.scope === scope && !services.hasOwned(declaration.key, owner)))
+            throw new AgentError('MAR_AGENT_EXTENSION_DEPENDENCY_MISSING', 'Declared service was not provided.');
+    }
+    #validateSnapshot(snapshot) {
+        if (!snapshot ||
+            typeof snapshot.revision !== 'string' ||
+            !snapshot.revision ||
+            !Array.isArray(snapshot.extensions) ||
+            snapshot.extensions.some((extension) => !extension || typeof extension.id !== 'string' || !extension.id.trim()) ||
+            new Set(snapshot.extensions.map((extension) => extension.id)).size !==
+                snapshot.extensions.length)
+            throw new AgentError('MAR_AGENT_EXTENSION_SOURCE_INVALID', 'Extension snapshot is inconsistent.');
+    }
+    async #retire() {
+        for (const session of this.#sessions.values())
+            session.retire();
+        for (const scope of this.#agentScopes)
+            scope.retire();
+        let failures = 0;
+        for (const session of this.#sessions.values()) {
+            try {
+                await session.dispose();
+            }
+            catch {
+                failures++;
+            }
+        }
+        for (const scope of [...this.#agentScopes].reverse()) {
+            try {
+                await scope.dispose();
+            }
+            catch {
+                failures++;
+            }
+        }
+        if (failures) {
+            this.#cleanupFailed = true;
+            this.#diagnose({ code: 'MAR_AGENT_EXTENSION_CLEANUP_FAILED' });
+            throw new AgentError('MAR_AGENT_EXTENSION_CLEANUP_FAILED', 'Composition cleanup failed.', {
+                details: { failures }
+            });
+        }
+        this.#sessions.clear();
+        this.#agentScopes = [];
+        this.#agentServices = new ExtensionServices('agent');
+        this.#setupFailures.clear();
+        this.#strictSetupFailure = false;
+        this.#strictSessions.clear();
+        this.#snapshot = undefined;
+    }
+    #diagnose(diagnostic) {
+        this.#diagnostics.push(Object.freeze({ ...diagnostic }));
+        if (this.#diagnostics.length > 200)
+            this.#diagnostics.shift();
+    }
+    #serial(operation) {
+        const result = this.#tail.then(operation);
+        this.#tail = result.catch(() => undefined);
+        return result;
+    }
+}
+function failureCode(error) {
+    return error instanceof AgentError ? error.code : 'MAR_AGENT_EXTENSION_INITIALIZATION_FAILED';
+}
+/** Declared providers precede consumers; array order remains the tiebreaker for unrelated items. */
+function ordered(extensions, scope) {
+    const providers = new Map();
+    for (const extension of extensions)
+        for (const declaration of extension.provides ?? []) {
+            if (declaration.key.scope !== scope)
+                continue;
+            const entries = providers.get(declaration.key.id) ?? [];
+            if (!declaration.intent || declaration.intent === 'provide')
+                entries.unshift(extension);
+            else
+                entries.push(extension);
+            providers.set(declaration.key.id, entries);
+        }
+    const dependencies = new Map(extensions.map((extension) => [extension, new Set()]));
+    for (const entries of providers.values())
+        for (let index = 1; index < entries.length; index++)
+            dependencies.get(entries[index]).add(entries[index - 1]);
+    for (const extension of extensions)
+        for (const dependency of extension.serviceDependencies ?? []) {
+            if (dependency.key.scope !== scope || dependency.optional)
+                continue;
+            const provider = providers.get(dependency.key.id)?.at(-1);
+            if (provider && provider !== extension)
+                dependencies.get(extension).add(provider);
+        }
+    const result = [];
+    const visiting = new Set();
+    const visited = new Set();
+    const failed = new Set();
+    const visit = (extension) => {
+        if (visited.has(extension))
+            return !failed.has(extension);
+        if (visiting.has(extension)) {
+            failed.add(extension);
+            return false;
+        }
+        visiting.add(extension);
+        for (const dependency of dependencies.get(extension))
+            if (!visit(dependency))
+                failed.add(extension);
+        visiting.delete(extension);
+        visited.add(extension);
+        if (!failed.has(extension))
+            result.push(extension);
+        return !failed.has(extension);
+    };
+    for (const extension of extensions)
+        visit(extension);
+    return { extensions: result, failures: extensions.filter((extension) => failed.has(extension)) };
+}

package/dist/extensions/mcp.d.ts

@@ -0,0 +1,116 @@
+import type { McpToolCatalog, ToolExecutionResult } from '../tools/contracts.js';
+import { type ExtensionJsonValue } from './data.js';
+import type { ExtensionHooks } from './hooks.js';
+import type { ExtensionOperationContext } from './operation.js';
+import { ExtensionResourceScope, type ExtensionResourceRegistration } from './resources.js';
+import type { ExtensionToolBinding, ExtensionToolRef, ExtensionToolInvocation, ExtensionTools } from './tools.js';
+export interface ExtensionMcpServerDefinition {
+    readonly id: string;
+    readonly configuration: ExtensionJsonValue;
+}
+export interface ExtensionMcpServerRef {
+    readonly definition: ExtensionMcpServerDefinition;
+    readonly source: Readonly<{
+        extensionId: string;
+        ownerInstanceId: string;
+        revision: string;
+    }>;
+}
+export interface ExtensionMcpServerRegistration extends ExtensionResourceRegistration {
+    readonly ref: ExtensionMcpServerRef;
+}
+export interface ExtensionMcpConnectionRef {
+    readonly id: string;
+    readonly serverId: string;
+    readonly source: ExtensionMcpServerRef['source'];
+}
+export interface ExtensionMcpConnectInput {
+    readonly server: ExtensionMcpServerRef | string;
+    readonly signal?: AbortSignal;
+}
+export interface ExtensionMcpConnectionInput {
+    readonly connection: ExtensionMcpConnectionRef;
+    readonly signal?: AbortSignal;
+}
+export interface ExtensionMcpCallInput {
+    readonly tool: ExtensionToolRef;
+    readonly arguments: unknown;
+    readonly callId?: string;
+    readonly signal?: AbortSignal;
+}
+export interface ExtensionMcpCatalog {
+    readonly revision: string;
+    readonly servers: McpToolCatalog['servers'];
+    readonly tools: readonly ExtensionToolRef[];
+}
+export interface ExtensionMcpApi {
+    register(definition: ExtensionMcpServerDefinition): ExtensionMcpServerRegistration;
+    servers(): readonly ExtensionMcpServerRef[];
+    connect(input: ExtensionMcpConnectInput): Promise<ExtensionMcpConnectionRef>;
+    connections(): readonly ExtensionMcpConnectionRef[];
+    catalog(input: ExtensionMcpConnectionInput): Promise<ExtensionMcpCatalog>;
+    call(input: ExtensionMcpCallInput): Promise<ToolExecutionResult>;
+    disconnect(input: ExtensionMcpConnectionInput): Promise<void>;
+}
+export interface ExtensionMcpToolCall {
+    readonly name: string;
+    readonly serverId: string;
+    readonly rawName: string;
+    readonly arguments: unknown;
+    readonly callId?: string;
+    readonly expectedTool: Readonly<{
+        sourceIdentity: string;
+        definitionRevision: string;
+    }>;
+}
+/** A lease on the application's existing MCP Client. Core never implements a transport. */
+export interface ExtensionMcpConnectionBackend {
+    catalog(call: ExtensionOperationContext): Promise<McpToolCatalog>;
+    call(input: ExtensionMcpToolCall, call: ExtensionOperationContext): Promise<ToolExecutionResult>;
+    close(): Promise<void>;
+}
+export interface ExtensionMcpBackend {
+    connect(definition: ExtensionMcpServerDefinition, call: ExtensionOperationContext): Promise<ExtensionMcpConnectionBackend>;
+}
+export interface ExtensionMcpCompletion {
+    readonly operation: 'connect' | 'catalog' | 'call' | 'disconnect';
+    readonly connectionId: string;
+    readonly toolName?: string;
+    readonly toolCount?: number;
+}
+type Run = <Value>(operation: (call: ExtensionOperationContext) => Promise<Value>, signal?: AbortSignal) => Promise<Value>;
+/** One Session's declarations and owned Client leases feed its sole tool registry. */
+export declare class ExtensionMcp {
+    #private;
+    readonly tools: ExtensionTools;
+    readonly hooks: Pick<ExtensionHooks<DomainMcpOperations, DomainMcpFacts>, 'invoke' | 'emit'>;
+    readonly getTools: (call: ExtensionOperationContext) => ReadonlyMap<string, ExtensionToolBinding>;
+    readonly toolRef: (binding: ExtensionToolBinding) => ExtensionToolRef;
+    readonly isMcpRef: (ref: ExtensionToolRef) => boolean;
+    readonly invoke: (input: ExtensionToolInvocation, call: ExtensionOperationContext) => Promise<ToolExecutionResult>;
+    readonly diagnose: () => void;
+    readonly validateCatalog: (catalog: McpToolCatalog) => void;
+    constructor(tools: ExtensionTools, hooks: Pick<ExtensionHooks<DomainMcpOperations, DomainMcpFacts>, 'invoke' | 'emit'>, getTools: (call: ExtensionOperationContext) => ReadonlyMap<string, ExtensionToolBinding>, toolRef: (binding: ExtensionToolBinding) => ExtensionToolRef, isMcpRef: (ref: ExtensionToolRef) => boolean, invoke: (input: ExtensionToolInvocation, call: ExtensionOperationContext) => Promise<ToolExecutionResult>, diagnose: () => void, validateCatalog: (catalog: McpToolCatalog) => void);
+    bind(owner: ExtensionResourceScope, extensionId: string, backend: ExtensionMcpBackend, run: Run): ExtensionMcpApi;
+    servers(): McpToolCatalog['servers'];
+}
+/** Project the same captured bindings used by invocation; never rediscover a backend by name. */
+export declare function coreMcpCatalog(servers: McpToolCatalog['servers'], bindings: ReadonlyMap<string, ExtensionToolBinding>): McpToolCatalog;
+export interface DomainMcpOperations {
+    'mcp.connect': {
+        input: ExtensionMcpConnectInput;
+        output: ExtensionMcpConnectionRef;
+    };
+    'mcp.catalog': {
+        input: ExtensionMcpConnectionInput;
+        output: ExtensionMcpCatalog;
+    };
+    'mcp.disconnect': {
+        input: ExtensionMcpConnectionInput;
+        output: void;
+    };
+}
+export interface DomainMcpFacts {
+    'mcp.completed': ExtensionMcpCompletion;
+}
+export {};