ai-runtime-engine 1.2.0 → 2.7.0

package/dist/mcp/manager.d.ts

@@ -0,0 +1,151 @@
+/**
+ * MCP server lifecycle (Phase 3.2) — connect, discover, cache, enable/disable/remove, lazy reconnect.
+ *
+ * State machine: `configured` → `connecting` → { `connected` | `auth_failed` | `unreachable` }; a failed
+ * call marks `degraded` (the next use retries with capped backoff); the operator can `disabled` any
+ * server. There is NO background daemon or keepalive — reconnection is lazy, on next use, matching this
+ * codebase's no-scheduler style.
+ *
+ * SECURITY:
+ *  - Credentials are resolved from an env-var NAME through `Credential` (which `registerSecret`s the
+ *    value so every egress is scrubbed) and are handed straight to the transport. The value is never
+ *    stored on the manager, never in `McpServerStatus`, and never persisted.
+ *  - Every persisted file is re-validated with strict zod ON READ: a tampered or corrupt store is
+ *    discarded, not trusted (a checksum only proves integrity, not provenance).
+ *  - Approval/permission decisions use LIVE handshake annotations only; the tool cache exists to make
+ *    the catalog available offline and never to lower a gate.
+ */
+import type { Area } from '../store/area.js';
+import type { Clock } from '../util/clock.js';
+import type { FetchLike } from '../providers/httpClient.js';
+import { McpClient } from './client.js';
+import type { McpTransport } from './transport.js';
+import type { McpCallResult, NormalizedTool } from './protocol.js';
+export type McpTransportKind = 'stdio' | 'http';
+export interface McpServerConfig {
+    transport: McpTransportKind;
+    url?: string;
+    command?: string;
+    args?: string[];
+    /** Env-var NAME (never a value — the config schema rejects key-like strings). */
+    tokenEnv?: string;
+    enabled?: boolean;
+    timeoutMs?: number;
+    /** Reserved: per-server aliasing of this server's tools onto canonical capability ids. NOT consumed —
+     *  use `runtime.capabilities.aliases.<curatedId>: mcp:<server>.<tool>`, which already claims a
+     *  curated id for any provider, MCP included. */
+    capabilities?: Record<string, string[]>;
+}
+export type McpServerState = 'configured' | 'connecting' | 'connected' | 'degraded' | 'auth_failed' | 'unreachable' | 'disabled';
+export interface McpServerStatus {
+    id: string;
+    transport: McpTransportKind;
+    /** `config` = declared in config.yaml; `dynamic` = added via `mcp add` (persisted in the store). */
+    origin: 'config' | 'dynamic';
+    state: McpServerState;
+    enabled: boolean;
+    /**
+     * Where it points, in a form that CANNOT carry a credential: an http server's ORIGIN (no path, no
+     * query — a URL query can hold a token) or a stdio server's bare command (no args — args can hold
+     * paths the operator considers sensitive).
+     */
+    endpoint?: string;
+    /** The env-var NAME and whether it currently resolves — NEVER the value. */
+    tokenEnv?: string;
+    tokenSet: boolean;
+    toolCount: number;
+    rejectedTools: number;
+    truncated: boolean;
+    protocolVersion?: string;
+    serverName?: string;
+    /** Redacted, bounded reason for the last failure. */
+    lastError?: string;
+    lastCheckedAt?: number;
+}
+/** A server id: the same shape the config schema enforces, so both origins are equally constrained. */
+export declare const MCP_SERVER_ID_RE: RegExp;
+export interface McpManagerOptions {
+    /** Servers declared in config (`mcp.servers`). */
+    servers?: Record<string, McpServerConfig>;
+    /** The store area for dynamic servers, enable-state, and the tool cache. Omit for stateless mode. */
+    store?: Area;
+    env?: NodeJS.ProcessEnv;
+    fetchImpl?: FetchLike;
+    clock?: Clock;
+    /** Per-server connect budget. */
+    connectTimeoutMs?: number;
+    /** Test seam: build a transport instead of spawning/fetching. */
+    transportFactory?: (id: string, cfg: McpServerConfig) => McpTransport;
+    /** Called after a successful discovery so the host can register tools + capabilities. */
+    onToolsDiscovered?: (serverId: string, tools: NormalizedTool[]) => void;
+    /** Called when a server is removed/disabled so the host can deregister its tools. */
+    onServerRemoved?: (serverId: string) => void;
+}
+export declare class McpManager {
+    private readonly opts;
+    private readonly entries;
+    private readonly env;
+    private readonly clock;
+    private readonly warnings;
+    /** Explicit operator enable/disable decisions — the only thing `state` persists (see writeState). */
+    private readonly overrides;
+    /** In-flight connect per server, so concurrent lazy callers share one handshake (never two children). */
+    private readonly connecting;
+    constructor(opts?: McpManagerOptions);
+    warningsList(): string[];
+    private readDynamic;
+    private readState;
+    /**
+     * Read a cached catalog. Every entry goes back through `normalizeToolDecl` — the SAME discovery gate a
+     * live declaration passes — because the file is untrusted input like any other: shape validation alone
+     * would let a tampered cache reintroduce an unsafe name or unclamped prompt text. Cached annotations
+     * are then forced to their fail-closed values: a stale `readOnlyHint` must not lower the permission
+     * gate, and a stale `destructiveHint: false` must not REMOVE confirmation. Only a live handshake can
+     * relax either.
+     */
+    private readCache;
+    private writeDynamic;
+    /**
+     * Persist only servers the operator has EXPLICITLY toggled. Snapshotting every entry would turn an
+     * unrelated `mcp add` into a stored `enabled: true` for every server — which then wins over a later
+     * `enabled: false` added to the config file, silently re-enabling something the operator turned off.
+     */
+    private writeState;
+    private buildTransport;
+    /** Connect + handshake + discover one server. Never throws — the state carries the outcome. */
+    private connect;
+    /** Connect every enabled server in parallel. Resilient: a failure is recorded, never thrown. */
+    connectAll(): Promise<McpServerStatus[]>;
+    /** Lazily (re)connect on use, honoring a capped backoff after repeated failures. */
+    ensureConnected(id: string): Promise<McpClient>;
+    /** Whether a server can be called right now (the adapter's honest availability check). */
+    usable(id: string): boolean;
+    call(id: string, tool: string, args: unknown, opts?: {
+        signal?: AbortSignal;
+    }): Promise<McpCallResult>;
+    /** The LIVE annotations for a tool (approval/permission input — never the cache). */
+    liveTool(id: string, tool: string): NormalizedTool | undefined;
+    tools(id: string): NormalizedTool[];
+    /** Add a dynamic server (persisted to the STORE — the runtime never edits config.yaml). */
+    addServer(id: string, cfg: McpServerConfig): Promise<McpServerStatus>;
+    /** Remove a DYNAMIC server. Config-declared servers must be removed from config.yaml by the operator. */
+    removeServer(id: string): {
+        ok: boolean;
+        reason?: string;
+    };
+    setEnabled(id: string, enabled: boolean): {
+        ok: boolean;
+        reason?: string;
+    };
+    /** Force an active check: connect + handshake + list + ping. */
+    test(id: string): Promise<McpServerStatus & {
+        pingMs?: number;
+    }>;
+    private statusOf;
+    list(): McpServerStatus[];
+    status(id: string): McpServerStatus | undefined;
+    diagnostics(id: string): string[];
+    ids(): string[];
+    /** Close every client (stdio children included). Idempotent; safe to call on exit. */
+    close(): Promise<void>;
+}

package/dist/mcp/manager.js

@@ -0,0 +1,493 @@
+/**
+ * MCP server lifecycle (Phase 3.2) — connect, discover, cache, enable/disable/remove, lazy reconnect.
+ *
+ * State machine: `configured` → `connecting` → { `connected` | `auth_failed` | `unreachable` }; a failed
+ * call marks `degraded` (the next use retries with capped backoff); the operator can `disabled` any
+ * server. There is NO background daemon or keepalive — reconnection is lazy, on next use, matching this
+ * codebase's no-scheduler style.
+ *
+ * SECURITY:
+ *  - Credentials are resolved from an env-var NAME through `Credential` (which `registerSecret`s the
+ *    value so every egress is scrubbed) and are handed straight to the transport. The value is never
+ *    stored on the manager, never in `McpServerStatus`, and never persisted.
+ *  - Every persisted file is re-validated with strict zod ON READ: a tampered or corrupt store is
+ *    discarded, not trusted (a checksum only proves integrity, not provenance).
+ *  - Approval/permission decisions use LIVE handshake annotations only; the tool cache exists to make
+ *    the catalog available offline and never to lower a gate.
+ */
+import { z } from 'zod';
+import { AIError } from '../core/fallback/errors.js';
+import { redactString } from '../security/redact.js';
+import { Credential } from '../security/credentials.js';
+import { systemClock } from '../util/clock.js';
+import { McpClient } from './client.js';
+import { HttpTransport, StdioTransport } from './transport.js';
+import { clampText, normalizeToolDecl } from './protocol.js';
+import { KEY_LIKE } from '../config/schema.js';
+/** A server id: the same shape the config schema enforces, so both origins are equally constrained. */
+export const MCP_SERVER_ID_RE = /^[a-z0-9][a-z0-9_-]{0,32}$/;
+/**
+ * Persisted, secret-free records — strictly re-validated on read, and to the SAME standard as the config
+ * file. A weaker store schema would be a privilege gap: a forged `servers` file could otherwise name a
+ * credential env var and an arbitrary URL, and the manager would dutifully send the token there.
+ */
+const persistedServer = z
+    .object({
+    transport: z.enum(['stdio', 'http']),
+    url: z.string().url().optional(),
+    command: z.string().optional(),
+    args: z.array(z.string()).optional(),
+    tokenEnv: z
+        .string()
+        .refine((v) => !KEY_LIKE.test(v), { message: 'tokenEnv must be an env-var NAME, not a token value' })
+        .optional(),
+    enabled: z.boolean().optional(),
+    timeoutMs: z.number().optional(),
+    capabilities: z.record(z.string(), z.array(z.string())).optional(),
+})
+    .strict()
+    .refine((sv) => (sv.transport === 'stdio' ? Boolean(sv.command) && !sv.url : Boolean(sv.url) && !sv.command), {
+    message: "transport 'stdio' requires command (and no url); transport 'http' requires url (and no command)",
+});
+const persistedServers = z.record(z.string().regex(MCP_SERVER_ID_RE), persistedServer);
+const persistedState = z.record(z.string().regex(MCP_SERVER_ID_RE), z.object({ enabled: z.boolean().optional() }).strict());
+const cachedTools = z
+    .object({
+    at: z.number(),
+    tools: z.array(z.unknown()),
+})
+    .strict();
+const BACKOFF_MS = [0, 1_000, 5_000, 30_000];
+/** A displayable, credential-free rendering of where a server points (see `McpServerStatus.endpoint`). */
+function safeEndpoint(cfg) {
+    if (cfg.transport === 'http') {
+        if (!cfg.url)
+            return undefined;
+        try {
+            return new URL(cfg.url).origin;
+        }
+        catch {
+            return undefined; // an unparseable url is never echoed back
+        }
+    }
+    return cfg.command ? cfg.command.split(/[\\/]/).pop() : undefined;
+}
+export class McpManager {
+    opts;
+    entries = new Map();
+    env;
+    clock;
+    warnings = [];
+    /** Explicit operator enable/disable decisions — the only thing `state` persists (see writeState). */
+    overrides = new Map();
+    /** In-flight connect per server, so concurrent lazy callers share one handshake (never two children). */
+    connecting = new Map();
+    constructor(opts = {}) {
+        this.opts = opts;
+        this.env = opts.env ?? process.env;
+        this.clock = opts.clock ?? systemClock;
+        // Config-declared servers first, then dynamic ones from the store (config wins on id collision).
+        for (const [id, cfg] of Object.entries(opts.servers ?? {})) {
+            this.entries.set(id, { id, cfg, origin: 'config', state: cfg.enabled === false ? 'disabled' : 'configured', tools: [], rejected: 0, truncated: false, failures: 0 });
+        }
+        for (const [id, cfg] of Object.entries(this.readDynamic())) {
+            if (this.entries.has(id)) {
+                this.warnings.push(`MCP server '${id}' is declared in config; the stored copy was ignored`);
+                continue;
+            }
+            this.entries.set(id, { id, cfg, origin: 'dynamic', state: cfg.enabled === false ? 'disabled' : 'configured', tools: [], rejected: 0, truncated: false, failures: 0 });
+        }
+        // Operator enable/disable overrides apply to both origins.
+        for (const [id, st] of Object.entries(this.readState())) {
+            if (st.enabled === undefined)
+                continue;
+            this.overrides.set(id, st.enabled);
+            const e = this.entries.get(id);
+            if (!e)
+                continue;
+            if (st.enabled === false)
+                e.state = 'disabled';
+            else if (e.state === 'disabled')
+                e.state = 'configured';
+        }
+        // Seed the cached catalog so `capabilities`/planning work before (or without) a connection.
+        for (const e of this.entries.values()) {
+            if (e.state === 'disabled')
+                continue;
+            const cached = this.readCache(e.id);
+            if (cached)
+                e.tools = cached;
+        }
+    }
+    warningsList() {
+        return [...this.warnings];
+    }
+    // ── store IO (every read strictly validated; invalid ⇒ discarded) ──────────
+    readDynamic() {
+        const raw = this.opts.store?.tryReadJson('servers');
+        if (raw === undefined)
+            return {};
+        const parsed = persistedServers.safeParse(raw);
+        if (!parsed.success) {
+            this.warnings.push('stored MCP servers file was invalid and has been ignored');
+            return {};
+        }
+        return parsed.data;
+    }
+    readState() {
+        const raw = this.opts.store?.tryReadJson('state');
+        if (raw === undefined)
+            return {};
+        const parsed = persistedState.safeParse(raw);
+        if (!parsed.success) {
+            this.warnings.push('stored MCP state file was invalid and has been ignored');
+            return {};
+        }
+        return parsed.data;
+    }
+    /**
+     * Read a cached catalog. Every entry goes back through `normalizeToolDecl` — the SAME discovery gate a
+     * live declaration passes — because the file is untrusted input like any other: shape validation alone
+     * would let a tampered cache reintroduce an unsafe name or unclamped prompt text. Cached annotations
+     * are then forced to their fail-closed values: a stale `readOnlyHint` must not lower the permission
+     * gate, and a stale `destructiveHint: false` must not REMOVE confirmation. Only a live handshake can
+     * relax either.
+     */
+    readCache(id) {
+        const raw = this.opts.store?.tryReadJson(`tools-${id}`);
+        if (raw === undefined)
+            return undefined;
+        const parsed = cachedTools.safeParse(raw);
+        if (!parsed.success) {
+            this.warnings.push(`cached tool list for '${id}' was invalid and has been ignored`);
+            return undefined;
+        }
+        const out = [];
+        let rejected = 0;
+        for (const decl of parsed.data.tools) {
+            const norm = normalizeToolDecl(decl);
+            if (!norm) {
+                rejected += 1;
+                continue;
+            }
+            out.push({ ...norm, readOnly: false, destructive: true });
+        }
+        if (rejected)
+            this.warnings.push(`${rejected} cached tool declaration(s) for '${id}' failed validation and were dropped`);
+        return out.length ? out : undefined;
+    }
+    writeDynamic() {
+        const out = {};
+        for (const e of this.entries.values())
+            if (e.origin === 'dynamic')
+                out[e.id] = e.cfg;
+        this.opts.store?.writeJson('servers', out);
+    }
+    /**
+     * Persist only servers the operator has EXPLICITLY toggled. Snapshotting every entry would turn an
+     * unrelated `mcp add` into a stored `enabled: true` for every server — which then wins over a later
+     * `enabled: false` added to the config file, silently re-enabling something the operator turned off.
+     */
+    writeState() {
+        const out = {};
+        for (const [id, enabled] of this.overrides)
+            out[id] = { enabled };
+        this.opts.store?.writeJson('state', out);
+    }
+    // ── connection ─────────────────────────────────────────────────────────────
+    buildTransport(e) {
+        if (this.opts.transportFactory)
+            return this.opts.transportFactory(e.id, e.cfg);
+        const cred = e.cfg.tokenEnv ? new Credential(e.cfg.tokenEnv, this.env) : undefined;
+        if (e.cfg.transport === 'http') {
+            if (!e.cfg.url)
+                throw new AIError(`MCP server '${e.id}' has transport http but no url`, { category: 'CONFIG' });
+            const token = cred?.use();
+            return new HttpTransport({ url: e.cfg.url, ...(token ? { token } : {}), ...(this.opts.fetchImpl ? { fetchImpl: this.opts.fetchImpl } : {}), ...(e.cfg.timeoutMs ? { timeoutMs: e.cfg.timeoutMs } : {}) });
+        }
+        if (!e.cfg.command)
+            throw new AIError(`MCP server '${e.id}' has transport stdio but no command`, { category: 'CONFIG' });
+        const token = cred?.use();
+        return new StdioTransport({
+            command: e.cfg.command,
+            ...(e.cfg.args ? { args: e.cfg.args } : {}),
+            ...(e.cfg.tokenEnv && token ? { tokenEnvName: e.cfg.tokenEnv, tokenValue: token } : {}),
+            env: this.env,
+        });
+    }
+    /** Connect + handshake + discover one server. Never throws — the state carries the outcome. */
+    async connect(e) {
+        if (e.state === 'disabled')
+            return;
+        e.state = 'connecting';
+        // Declared OUTSIDE the try: a handshake that throws must still be closed, or a spawned stdio child
+        // keeps running (and holding its transport) for the life of the process.
+        let client;
+        // Whatever the entry already holds is superseded by this attempt — close it, or `mcp test` on a
+        // connected stdio server abandons a live child every time.
+        const previous = e.client;
+        delete e.client;
+        if (previous)
+            await previous.close().catch(() => { });
+        try {
+            const transport = this.buildTransport(e);
+            client = new McpClient(transport, { serverId: e.id, clock: this.clock, timeoutMs: e.cfg.timeoutMs ?? this.opts.connectTimeoutMs ?? 30_000 });
+            // Held even on failure so `mcp <id>` can still show WHY (the stderr ring lives on the transport).
+            e.lastDiagnostics = () => client?.diagnostics() ?? [];
+            const hs = await client.initialize();
+            const list = await client.listTools();
+            e.client = client;
+            e.tools = list.tools;
+            e.rejected = list.rejected;
+            e.truncated = list.truncated;
+            e.protocolVersion = hs.protocolVersion;
+            if (hs.serverName)
+                e.serverName = hs.serverName;
+            e.state = hs.versionMismatch ? 'degraded' : 'connected';
+            if (hs.versionMismatch)
+                e.lastError = clampText(`server speaks protocol ${hs.protocolVersion}; this client speaks a different version`, 200);
+            else
+                delete e.lastError;
+            e.failures = 0;
+            e.lastCheckedAt = this.clock.now();
+            // Caching is a CONVENIENCE. A failed write (read-only home, full disk, bad id) must not be
+            // reported as an unreachable server and must not tear down a working connection.
+            try {
+                this.opts.store?.writeJson(`tools-${e.id}`, { at: this.clock.now(), tools: e.tools });
+            }
+            catch {
+                this.warnings.push(`could not cache the tool list for '${e.id}' (the connection is unaffected)`);
+            }
+            this.opts.onToolsDiscovered?.(e.id, e.tools);
+        }
+        catch (err) {
+            e.failures += 1;
+            e.lastCheckedAt = this.clock.now();
+            const category = err instanceof AIError ? err.category : 'UNKNOWN';
+            e.state = category === 'AUTHENTICATION' ? 'auth_failed' : 'unreachable';
+            e.lastError = clampText(redactString(err instanceof Error ? err.message : String(err)), 200);
+            await client?.close().catch(() => { }); // closes the half-open connection whether or not it was adopted
+            delete e.client;
+        }
+    }
+    /** Connect every enabled server in parallel. Resilient: a failure is recorded, never thrown. */
+    async connectAll() {
+        await Promise.all([...this.entries.values()]
+            .filter((e) => e.state !== 'disabled')
+            .map((e) => {
+            const inFlight = this.connecting.get(e.id);
+            if (inFlight)
+                return inFlight;
+            const attempt = this.connect(e).finally(() => this.connecting.delete(e.id));
+            this.connecting.set(e.id, attempt);
+            return attempt;
+        }));
+        return this.list();
+    }
+    /** Lazily (re)connect on use, honoring a capped backoff after repeated failures. */
+    async ensureConnected(id) {
+        const e = this.entries.get(id);
+        if (!e)
+            throw new AIError(`no MCP server '${id}'`, { category: 'CONFIG' });
+        if (e.state === 'disabled')
+            throw new AIError(`MCP server '${id}' is disabled`, { category: 'CONFIG' });
+        if (e.client && (e.state === 'connected' || e.state === 'degraded'))
+            return e.client;
+        const waited = this.clock.now() - (e.lastCheckedAt ?? 0);
+        const backoff = BACKOFF_MS[Math.min(e.failures, BACKOFF_MS.length - 1)];
+        if (e.failures > 0 && waited < backoff) {
+            throw new AIError(`MCP server '${id}' is ${e.state}${e.lastError ? ` (${e.lastError})` : ''}`, { category: 'NETWORK', retryable: true });
+        }
+        // Concurrent callers (a parallel wave of tool steps) must share ONE handshake: two overlapping
+        // connects would spawn two children and abandon whichever lost the assignment race.
+        const inFlight = this.connecting.get(id);
+        if (inFlight)
+            await inFlight;
+        else {
+            const attempt = this.connect(e).finally(() => this.connecting.delete(id));
+            this.connecting.set(id, attempt);
+            await attempt;
+        }
+        if (!e.client)
+            throw new AIError(`MCP server '${id}' is ${e.state}${e.lastError ? ` (${e.lastError})` : ''}`, { category: e.state === 'auth_failed' ? 'AUTHENTICATION' : 'NETWORK', retryable: e.state !== 'auth_failed' });
+        return e.client;
+    }
+    /** Whether a server can be called right now (the adapter's honest availability check). */
+    usable(id) {
+        const e = this.entries.get(id);
+        if (!e || e.state === 'disabled')
+            return false;
+        return e.state !== 'auth_failed';
+    }
+    async call(id, tool, args, opts = {}) {
+        const client = await this.ensureConnected(id);
+        try {
+            return await client.callTool(tool, args, opts);
+        }
+        catch (err) {
+            const e = this.entries.get(id);
+            // A well-formed JSON-RPC error (bad params, unknown method) or a caller's own cancellation says
+            // nothing about the CONNECTION — tearing it down would kill and respawn the child on every such
+            // call, and reset the failure counter each time so the capped backoff never engaged.
+            const category = err instanceof AIError ? err.category : 'UNKNOWN';
+            const connectionFailed = category === 'NETWORK' || (category === 'TIMEOUT' && !opts.signal?.aborted);
+            // A dropped HTTP session is only recoverable by a fresh handshake, so it forces the client out
+            // from ANY state — including `degraded`, where the state guard below would otherwise keep reusing
+            // a session the server has already forgotten, forever.
+            if (e && e.client?.sessionExpired()) {
+                e.state = 'degraded';
+                e.lastError = 'the server invalidated our session; reconnecting on next use';
+                const stale = e.client;
+                delete e.client;
+                await stale.close().catch(() => { });
+                throw err;
+            }
+            if (e && connectionFailed && e.state === 'connected') {
+                e.state = 'degraded'; // a broken transport schedules a lazy reconnect on next use
+                e.failures += 1; // count it, so repeated breakage actually engages the backoff
+                e.lastCheckedAt = this.clock.now();
+                e.lastError = clampText(redactString(err instanceof Error ? err.message : String(err)), 200);
+                await e.client?.close().catch(() => { });
+                delete e.client;
+            }
+            throw err;
+        }
+    }
+    /** The LIVE annotations for a tool (approval/permission input — never the cache). */
+    liveTool(id, tool) {
+        const e = this.entries.get(id);
+        if (!e || (e.state !== 'connected' && e.state !== 'degraded'))
+            return undefined;
+        return e.tools.find((t) => t.name === tool);
+    }
+    tools(id) {
+        return [...(this.entries.get(id)?.tools ?? [])];
+    }
+    // ── operator actions ───────────────────────────────────────────────────────
+    /** Add a dynamic server (persisted to the STORE — the runtime never edits config.yaml). */
+    async addServer(id, cfg) {
+        // The config path enforces this shape; the dynamic path must too. A dotted id (`demo.evil`) would
+        // otherwise generate tool ids inside ANOTHER server's namespace and mis-scope deregistration, and a
+        // store-illegal id would throw from deep inside the store on write.
+        if (!MCP_SERVER_ID_RE.test(id))
+            throw new AIError(`invalid MCP server id '${id}' — use lowercase letters, digits, '_' or '-' (max 33 chars)`, { category: 'CONFIG' });
+        if (cfg.tokenEnv && KEY_LIKE.test(cfg.tokenEnv))
+            throw new AIError('tokenEnv must be an env-var NAME, not a token value', { category: 'CONFIG' });
+        if (cfg.transport === 'http' ? !cfg.url || cfg.command : !cfg.command || cfg.url) {
+            throw new AIError("transport 'stdio' requires command (and no url); transport 'http' requires url (and no command)", { category: 'CONFIG' });
+        }
+        if (this.entries.has(id))
+            throw new AIError(`MCP server '${id}' already exists`, { category: 'CONFIG' });
+        const e = { id, cfg, origin: 'dynamic', state: 'configured', tools: [], rejected: 0, truncated: false, failures: 0 };
+        this.entries.set(id, e);
+        this.writeDynamic();
+        await this.connect(e);
+        return this.statusOf(e);
+    }
+    /** Remove a DYNAMIC server. Config-declared servers must be removed from config.yaml by the operator. */
+    removeServer(id) {
+        const e = this.entries.get(id);
+        if (!e)
+            return { ok: false, reason: `no MCP server '${id}'` };
+        if (e.origin === 'config')
+            return { ok: false, reason: `'${id}' is declared in your config file — remove it there` };
+        void e.client?.close().catch(() => { });
+        this.entries.delete(id);
+        this.overrides.delete(id);
+        // Store cleanup is best-effort: a failure here must not abort the removal half-way and leave a
+        // zombie entry that is gone from memory but still persisted.
+        try {
+            this.opts.store?.remove(`tools-${id}`);
+        }
+        catch {
+            this.warnings.push(`could not remove the cached tool list for '${id}'`);
+        }
+        this.writeDynamic();
+        this.writeState();
+        this.opts.onServerRemoved?.(id);
+        return { ok: true };
+    }
+    setEnabled(id, enabled) {
+        const e = this.entries.get(id);
+        if (!e)
+            return { ok: false, reason: `no MCP server '${id}'` };
+        this.overrides.set(id, enabled);
+        if (!enabled) {
+            e.state = 'disabled';
+            void e.client?.close().catch(() => { });
+            delete e.client;
+            this.opts.onServerRemoved?.(id);
+        }
+        else if (e.state === 'disabled') {
+            e.state = 'configured';
+            e.failures = 0;
+            // Disabling DEREGISTERED the tools, so re-enabling must put them back. Waiting for a reconnect is
+            // not enough: `connectMcp` is latched per process, so nothing would ever re-register them. The
+            // entry's declarations are re-gated to their fail-closed values — only a live handshake relaxes.
+            if (e.tools.length) {
+                e.tools = e.tools.map((t) => ({ ...t, readOnly: false, destructive: true }));
+                this.opts.onToolsDiscovered?.(id, e.tools);
+            }
+        }
+        this.writeState();
+        return { ok: true };
+    }
+    /** Force an active check: connect + handshake + list + ping. */
+    async test(id) {
+        const e = this.entries.get(id);
+        if (!e)
+            throw new AIError(`no MCP server '${id}'`, { category: 'CONFIG' });
+        if (e.state === 'disabled')
+            return this.statusOf(e);
+        e.failures = 0;
+        await this.connect(e);
+        const ping = e.client ? await e.client.ping() : undefined;
+        return { ...this.statusOf(e), ...(ping ? { pingMs: ping.latencyMs } : {}) };
+    }
+    statusOf(e) {
+        const tokenSet = e.cfg.tokenEnv ? Boolean(new Credential(e.cfg.tokenEnv, this.env).hasKey) : false;
+        return {
+            id: e.id,
+            transport: e.cfg.transport,
+            origin: e.origin,
+            state: e.state,
+            enabled: e.state !== 'disabled',
+            ...(safeEndpoint(e.cfg) ? { endpoint: safeEndpoint(e.cfg) } : {}),
+            ...(e.cfg.tokenEnv ? { tokenEnv: e.cfg.tokenEnv } : {}),
+            tokenSet,
+            toolCount: e.tools.length,
+            rejectedTools: e.rejected,
+            truncated: e.truncated,
+            ...(e.protocolVersion ? { protocolVersion: e.protocolVersion } : {}),
+            ...(e.serverName ? { serverName: e.serverName } : {}),
+            ...(e.lastError ? { lastError: e.lastError } : {}),
+            ...(e.lastCheckedAt ? { lastCheckedAt: e.lastCheckedAt } : {}),
+        };
+    }
+    list() {
+        return [...this.entries.values()].map((e) => this.statusOf(e)).sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+    }
+    status(id) {
+        const e = this.entries.get(id);
+        return e ? this.statusOf(e) : undefined;
+    }
+    diagnostics(id) {
+        const e = this.entries.get(id);
+        // `e.client` is unset on a failed connect — exactly when the operator needs the stderr ring most.
+        if (e && !e.client && e.lastDiagnostics)
+            return e.lastDiagnostics();
+        return this.entries.get(id)?.client?.diagnostics() ?? [];
+    }
+    ids() {
+        return [...this.entries.keys()];
+    }
+    /** Close every client (stdio children included). Idempotent; safe to call on exit. */
+    async close() {
+        await Promise.all([...this.entries.values()].map(async (e) => {
+            const c = e.client;
+            delete e.client;
+            if (c)
+                await c.close().catch(() => { });
+        }));
+    }
+}