ai-runtime-engine 1.3.0 → 2.7.0

package/dist/generation/generateSkill.js

@@ -0,0 +1,51 @@
+/**
+ * Skill scaffolding (Phase 21a) — the generative seam for skills, mirroring `generateAdapter`'s
+ * "emit validated CONFIG/manifest, never code" rule. A model drafts a `*.skill.yaml` MANIFEST (pure data,
+ * parsed by the existing `parseManifest`); we then validate it three ways before offering it:
+ *   1. `parseManifest` (shape),
+ *   2. every step names an AVAILABLE tool (a `validatePlan`-style membership check — no invented tools),
+ *   3. a dry `manifestToSkill` compile (it must not throw).
+ * Nothing is written here — the caller writes it only on explicit confirm into the consented
+ * `.ai-runtime/skills/` directory. A drafted manifest that fails any check is refused with a reason.
+ */
+import { stringify as toYaml } from 'yaml';
+import { parseManifest, manifestToSkill } from '../skills/manifest.js';
+import { wrapUntrusted } from '../tools/untrusted.js';
+import { extractJson } from '../util/extractJson.js';
+export async function generateSkillManifest(input) {
+    const goal = String(input.goal ?? '').trim();
+    if (!goal)
+        return { ok: false, error: 'a goal is required' };
+    const tools = input.tools ?? [];
+    if (tools.length === 0)
+        return { ok: false, error: 'no tools are available to compose a skill from' };
+    const prompt = `Draft an ai-runtime skill MANIFEST (pure data — NOT code) that achieves the goal below. ` +
+        `The manifest runs a sequence of tool steps. Use ONLY these registered tools: ${tools.join(', ')}.\n\n` +
+        `Goal:\n${wrapUntrusted('scaffold-goal', goal)}\n\n` +
+        `Reply ONLY with JSON of this exact shape: {"id":"<kebab-case-id>","version":"1.0.0","name":"<short name>",` +
+        `"description":"<one line>","runtimeCompatibility":">=1.0.0","steps":[{"tool":"<one of the tools>","description":"<what this step does>"}]}.`;
+    // The whole model round-trip is wrapped: a bad model reply (e.g. non-JSON, which makes `extractJson`
+    // throw) must surface as { ok:false }, never as a thrown error — scaffolding is an assist, not a hard op.
+    try {
+        const run = await input.ai.run({ task: 'generate-skill', input: prompt, output: { format: 'json' }, requirements: { intelligence: ['reasoning'], output: ['json'] } });
+        if (!run.ok || !run.response)
+            return { ok: false, error: `generation failed (${run.error?.category ?? 'no response'})` };
+        const raw = run.response.json ?? extractJson(run.response.text ?? '');
+        const { manifest, error } = parseManifest(raw);
+        if (!manifest)
+            return { ok: false, error: `drafted manifest is invalid: ${error ?? 'unparseable'}` };
+        // Membership: a drafted step may only name a tool the host actually has (no invented capabilities).
+        const unknown = [...new Set(manifest.steps.map((s) => s.tool).filter((t) => !tools.includes(t)))];
+        if (unknown.length)
+            return { ok: false, error: `manifest names unregistered tool(s): ${unknown.join(', ')}` };
+        // A safe, filesystem-friendly id (also the filename); reject anything that could escape the skills dir.
+        if (!/^[a-z0-9][a-z0-9-]{0,63}$/.test(manifest.id))
+            return { ok: false, error: `manifest id must be kebab-case ([a-z0-9-]): got ${JSON.stringify(manifest.id)}` };
+        // Dry compile — the manifest must produce a runnable Skill without throwing.
+        manifestToSkill(manifest, '(scaffold)');
+        return { ok: true, manifest, yaml: toYaml(manifest) };
+    }
+    catch (e) {
+        return { ok: false, error: `could not scaffold a skill: ${e instanceof Error ? e.message : String(e)}` };
+    }
+}

package/dist/index.d.ts

@@ -44,14 +44,20 @@ export { analyzeOpenApi, analyzeOpenApiFile } from './discovery/openapi.js';
 export type { OpenApiAnalysis } from './discovery/openapi.js';
 export { benchmark } from './benchmark/benchmark.js';
 export type { BenchResult, BenchTaskSpec } from './benchmark/benchmark.js';
-export { generateProviderConfig, generateProviderConfigFromFile } from './generation/generateAdapter.js';
-export type { GenerateOptions } from './generation/generateAdapter.js';
+export { generateProviderConfig, generateProviderConfigFromFile, suggestProviderConfig } from './generation/generateAdapter.js';
+export type { GenerateOptions, SuggestResult } from './generation/generateAdapter.js';
+export { generateSkillManifest } from './generation/generateSkill.js';
+export type { GenerateSkillInput, GenerateSkillResult } from './generation/generateSkill.js';
 export { McpRegistry, StaticMcpSource } from './mcp/mcp.js';
 export type { McpToolSource } from './mcp/mcp.js';
 export { setCredentialResolver, Credential } from './security/credentials.js';
 export type { CredentialResolver } from './security/credentials.js';
 export { CallbackSink, MemorySink, MultiSink, NullSink } from './telemetry/telemetry.js';
 export type { TelemetrySink } from './telemetry/telemetry.js';
+export { FileSink } from './telemetry/sinks/file.js';
+export { OtlpSink } from './telemetry/sinks/otlp.js';
+export type { OtlpSinkOptions } from './telemetry/sinks/otlp.js';
+export { KeyedSemaphore } from './util/semaphore.js';
 export { MARKETPLACE, listPresets, findPreset, presetToConfig } from './marketplace/presets.js';
 export type { ProviderPreset } from './marketplace/presets.js';
 export { loadRemoteConfig, loadConfigAsync } from './config/load.js';
@@ -64,6 +70,7 @@ export { resolvePolicy, defaultAutonomyForMode } from './runtime/policy.js';
 export type { ExecutionPolicy, PermissionPolicy, Autonomy, ApprovalLevel, PolicyOverrides } from './runtime/policy.js';
 export { parseRuntimeConfig, loadRuntimeConfig, findRuntimeConfigFile } from './runtime/config.js';
 export { HeuristicIntentClassifier } from './runtime/intent/classifier.js';
+export { AIIntentClassifier } from './runtime/intent/aiClassifier.js';
 export type { IntentClassifier, IntentClassification, IntentInput } from './runtime/intent/classifier.js';
 export { detectWorkspace, summarizeWorkspace } from './runtime/workspace/workspace.js';
 export type { WorkspaceInfo } from './runtime/workspace/workspace.js';
@@ -77,8 +84,29 @@ export type { AccessState, ProviderView, ModelView, ProviderViewSource } from '.
 export { RuntimeStore, STORE_VERSION } from './store/store.js';
 export type { RuntimeStoreOptions, StorePaths } from './store/store.js';
 export { FileArea, NullArea } from './store/area.js';
-export type { Area, IntegrityIssue } from './store/area.js';
-export { resolveHome, projectId, repositoryId, findRepoRoot } from './store/paths.js';
+export type { Area, IntegrityIssue, ContentCodec } from './store/area.js';
+export { makeCodec, deriveKey, encryptString, decryptString, ENVELOPE_PREFIX } from './store/crypto.js';
+export { resolveHome, projectId, repositoryId, organizationId, findRepoRoot } from './store/paths.js';
+export { deriveCapabilities, deriveCapabilitiesOffline, candidatesFrom, candidateSlate, DERIVE_MAX_CANDIDATES, DERIVE_MAX_IDS } from './runtime/planning/deriveCapabilities.js';
+export type { CapabilityCandidate, DeriveCapabilitiesInput, DeriveCapabilitiesResult } from './runtime/planning/deriveCapabilities.js';
+export { ActionCapabilityRegistry, capabilityReportFrom } from './capabilities/registry.js';
+export type { ActionCapabilityQuery, CapabilityConfig, RegistryAccessors } from './capabilities/registry.js';
+export { CURATED_VOCABULARY, curated, isCurated } from './capabilities/vocabulary.js';
+export type { CuratedCapability, PermissionHint } from './capabilities/vocabulary.js';
+export type { ActionCapability, ActionCapabilityDecl, ActionCapabilityEffect, ActionCapabilityProvider, ActionCapabilitySource, CapabilityGap, CapabilityGapReason, CapabilityResolution, GapSuggestion, MissingCapabilityReport, ProviderAvailability, } from './capabilities/capability.js';
+export type { AgentDefinition } from './agents/definition.js';
+export type { AgentEnvelope } from './agents/envelope.js';
+export type { AgentTaskRecord, AgentTaskState } from './agents/task.js';
+export type { Finding, FindingEvidence, FindingEvidenceKind, FindingStatus } from './agents/finding.js';
+export type { AdmissionRejection, AdmissionResult } from './agents/admit.js';
+export type { StepObservationCode } from './orchestration/executor.js';
+export { PLAN_STEP_STATUSES } from './orchestration/plan.js';
+export { mcpToolId } from './mcp/toolAdapter.js';
+export { MCP_PROTOCOL_VERSION } from './mcp/protocol.js';
+export type { McpServerConfig, McpServerState, McpServerStatus, McpTransportKind } from './mcp/manager.js';
+export type { McpServerSettings } from './runtime/types.js';
+export type { McpServerGrant } from './tools/permissions.js';
+export { clampMcpPermissions, clampPermissions } from './tools/permissions.js';
 export type { StoreScope } from './store/paths.js';
 export { ConversationStore } from './conversations/conversations.js';
 export type { ConversationTurn, ConversationMeta, TurnRole } from './conversations/conversations.js';
@@ -87,9 +115,18 @@ export type { MemoryRecord, MemoryScope, MemorySource, RememberInput, SearchOpti
 export { classifyMemory } from './memory/classifier.js';
 export type { MemoryCandidate } from './memory/classifier.js';
 export { bm25Search, tokenize } from './memory/bm25.js';
+export { cosineSimilarity, semanticRank } from './memory/semantic.js';
+export type { VecDoc, RankedHit } from './memory/semantic.js';
+export { HashEmbedder } from './memory/embedders/hash.js';
+export { HttpEmbedder } from './memory/embedders/http.js';
+export type { HttpEmbedderConfig } from './memory/embedders/http.js';
 export type { MemoryTrace } from './runtime/types.js';
 export { compileContext } from './context/compiler.js';
 export type { ContextBlock, CompiledBlock, CompiledContext, CompileMetrics, CompileOptions, ContextValidation, RetentionLevel } from './context/compiler.js';
+export { verifyContextLoss } from './context/lossVerifier.js';
+export type { VerifyLossInput, LossCheck } from './context/lossVerifier.js';
+export { summarizeOverBudget } from './context/summarize.js';
+export type { SummarizeInput } from './context/summarize.js';
 export { TokenEstimator, estimateTokens } from './context/tokens.js';
 export { resolveContextBudget, DEFAULT_CONTEXT_TOKENS } from './context/budget.js';
 export type { ContextBudgetInputs } from './context/budget.js';
@@ -141,6 +178,8 @@ export type { LearningOutcome, LearnedStat, SkillRef } from './learning/learning
 export { classifyFeedback } from './learning/feedback.js';
 export type { FeedbackSignal } from './learning/feedback.js';
 export { resolveRoutingPrefs, withPreferredProviders } from './runtime/routing.js';
+export { parseModelProfile, parseDirective, resolveModelDirective, directiveToOverrides, loadModelProfile } from './runtime/models/modelProfile.js';
+export type { ModelProfile, ModelDirective } from './runtime/models/modelProfile.js';
 export type { RoutingSources } from './runtime/routing.js';
 export { isExcluded, isPreferred } from './core/router/routingPrefs.js';
 export type { RoutingPreferences } from './types.js';

package/dist/index.js

@@ -40,10 +40,14 @@ export { runVerification } from './verification/verify.js';
 export { analyzeOpenApi, analyzeOpenApiFile } from './discovery/openapi.js';
 export { benchmark } from './benchmark/benchmark.js';
 // Enterprise & extensibility — dynamic adapters, MCP, enterprise credentials, observability, policy, marketplace, remote
-export { generateProviderConfig, generateProviderConfigFromFile } from './generation/generateAdapter.js';
+export { generateProviderConfig, generateProviderConfigFromFile, suggestProviderConfig } from './generation/generateAdapter.js';
+export { generateSkillManifest } from './generation/generateSkill.js';
 export { McpRegistry, StaticMcpSource } from './mcp/mcp.js';
 export { setCredentialResolver, Credential } from './security/credentials.js';
 export { CallbackSink, MemorySink, MultiSink, NullSink } from './telemetry/telemetry.js';
+export { FileSink } from './telemetry/sinks/file.js';
+export { OtlpSink } from './telemetry/sinks/otlp.js';
+export { KeyedSemaphore } from './util/semaphore.js';
 export { MARKETPLACE, listPresets, findPreset, presetToConfig } from './marketplace/presets.js';
 export { loadRemoteConfig, loadConfigAsync } from './config/load.js';
 // ── Runtime (Phase 1) — high-level facade over the router: modes, workspace, policy ──
@@ -52,6 +56,7 @@ export { RUNTIME_MODES } from './runtime/types.js';
 export { resolvePolicy, defaultAutonomyForMode } from './runtime/policy.js';
 export { parseRuntimeConfig, loadRuntimeConfig, findRuntimeConfigFile } from './runtime/config.js';
 export { HeuristicIntentClassifier } from './runtime/intent/classifier.js';
+export { AIIntentClassifier } from './runtime/intent/aiClassifier.js';
 export { detectWorkspace, summarizeWorkspace } from './runtime/workspace/workspace.js';
 export { MODE_AVAILABILITY, IMPLEMENTED_MODES } from './runtime/modes/availability.js';
 export { CHAT_TASK } from './runtime/modes/chat.js';
@@ -61,13 +66,31 @@ export { deriveAccessState, buildProviderViews, ProviderViewCache } from './runt
 // ── Runtime (Phase 3) — local store, conversations, memory ──
 export { RuntimeStore, STORE_VERSION } from './store/store.js';
 export { FileArea, NullArea } from './store/area.js';
-export { resolveHome, projectId, repositoryId, findRepoRoot } from './store/paths.js';
+export { makeCodec, deriveKey, encryptString, decryptString, ENVELOPE_PREFIX } from './store/crypto.js';
+export { resolveHome, projectId, repositoryId, organizationId, findRepoRoot } from './store/paths.js';
+// ── Capability-first planning (Phase 3.3) — offline BM25 derivation, one model rung under it ──
+export { deriveCapabilities, deriveCapabilitiesOffline, candidatesFrom, candidateSlate, DERIVE_MAX_CANDIDATES, DERIVE_MAX_IDS } from './runtime/planning/deriveCapabilities.js';
+// ── Action capabilities (Phase 3.1) — what the runtime can DO, and who provides it ──
+export { ActionCapabilityRegistry, capabilityReportFrom } from './capabilities/registry.js';
+export { CURATED_VOCABULARY, curated, isCurated } from './capabilities/vocabulary.js';
+export { PLAN_STEP_STATUSES } from './orchestration/plan.js';
+// ── MCP connectivity (Phase 3.2) — external servers as ordinary Runtime tools ──
+// The CONFIG + STATUS surface is public; the client, transports, and manager internals are not, so the
+// wire implementation stays free to change without a breaking release.
+export { mcpToolId } from './mcp/toolAdapter.js';
+export { MCP_PROTOCOL_VERSION } from './mcp/protocol.js';
+export { clampMcpPermissions, clampPermissions } from './tools/permissions.js';
 export { ConversationStore } from './conversations/conversations.js';
 export { MemoryStore } from './memory/memory.js';
 export { classifyMemory } from './memory/classifier.js';
 export { bm25Search, tokenize } from './memory/bm25.js';
+export { cosineSimilarity, semanticRank } from './memory/semantic.js';
+export { HashEmbedder } from './memory/embedders/hash.js';
+export { HttpEmbedder } from './memory/embedders/http.js';
 // ── Runtime (Phase 4) — context compiler + token budgets ──
 export { compileContext } from './context/compiler.js';
+export { verifyContextLoss } from './context/lossVerifier.js';
+export { summarizeOverBudget } from './context/summarize.js';
 export { TokenEstimator, estimateTokens } from './context/tokens.js';
 export { resolveContextBudget, DEFAULT_CONTEXT_TOKENS } from './context/budget.js';
 // ── Runtime (Phase 5) — tools, permissions, skills, untrusted-data boundary ──
@@ -104,4 +127,5 @@ export { renderComparison } from './comparison/render.js';
 export { LearningStore } from './learning/learningStore.js';
 export { classifyFeedback } from './learning/feedback.js';
 export { resolveRoutingPrefs, withPreferredProviders } from './runtime/routing.js';
+export { parseModelProfile, parseDirective, resolveModelDirective, directiveToOverrides, loadModelProfile } from './runtime/models/modelProfile.js';
 export { isExcluded, isPreferred } from './core/router/routingPrefs.js';

package/dist/mcp/client.d.ts

@@ -0,0 +1,70 @@
+/**
+ * MCP client (Phase 3.2) — the JSON-RPC conversation over any `McpTransport`: `initialize` (with
+ * version negotiation), `tools/list` (bounded pagination), `tools/call` (per-call timeout + abort), and
+ * `ping`. Requests are correlated by a monotonic id through a pending map, so concurrent calls to one
+ * server multiplex correctly.
+ *
+ * Every thrown error is an `AIError` with a redacted, URL-free message and a mapped category, so a
+ * caller (the manager → the Tool adapter) can classify auth vs timeout vs transport without ever seeing
+ * a credential or an endpoint.
+ */
+import type { Clock } from '../util/clock.js';
+import type { McpTransport } from './transport.js';
+import type { McpCallResult, NormalizedTool } from './protocol.js';
+export interface McpClientOptions {
+    serverId: string;
+    clock?: Clock;
+    /** Default per-request timeout (ms). */
+    timeoutMs?: number;
+    /** Max `tools/list` pages to follow — a malicious server must not loop us forever. */
+    maxPages?: number;
+    /** Max tools accepted from one server (registry-flood bound). */
+    maxTools?: number;
+}
+export interface McpHandshake {
+    protocolVersion: string;
+    serverName?: string;
+    serverVersion?: string;
+    /** True when the server answered with a version we did not ask for (we still proceed, marked degraded). */
+    versionMismatch: boolean;
+}
+export interface McpToolList {
+    tools: NormalizedTool[];
+    /** Declarations that failed validation/normalization and were NOT registered. */
+    rejected: number;
+    /** True when pagination hit `maxPages`/`maxTools` and the list is therefore partial. */
+    truncated: boolean;
+}
+export declare class McpClient {
+    private readonly transport;
+    private readonly opts;
+    private nextId;
+    private readonly pending;
+    private readonly clock;
+    private started;
+    /** Errors the server sent with no correlatable id, plus discovery anomalies — surfaced as diagnostics. */
+    private readonly protocolErrors;
+    constructor(transport: McpTransport, opts: McpClientOptions);
+    private onMessage;
+    /** Drop a pending entry and release everything attached to it (timer + abort listener). */
+    private settle;
+    private request;
+    /** Connect + negotiate. A counter-proposed version is accepted but reported as a mismatch. */
+    initialize(): Promise<McpHandshake>;
+    /** List tools, following `nextCursor` up to `maxPages`. Every declaration is normalized (or rejected). */
+    listTools(opts?: {
+        signal?: AbortSignal;
+    }): Promise<McpToolList>;
+    callTool(name: string, args: unknown, opts?: {
+        signal?: AbortSignal;
+        timeoutMs?: number;
+    }): Promise<McpCallResult>;
+    ping(): Promise<{
+        ok: boolean;
+        latencyMs: number;
+    }>;
+    close(): Promise<void>;
+    diagnostics(): string[];
+    /** Whether the transport says our session is gone and only a fresh handshake can recover. */
+    sessionExpired(): boolean;
+}

package/dist/mcp/client.js

@@ -0,0 +1,221 @@
+/**
+ * MCP client (Phase 3.2) — the JSON-RPC conversation over any `McpTransport`: `initialize` (with
+ * version negotiation), `tools/list` (bounded pagination), `tools/call` (per-call timeout + abort), and
+ * `ping`. Requests are correlated by a monotonic id through a pending map, so concurrent calls to one
+ * server multiplex correctly.
+ *
+ * Every thrown error is an `AIError` with a redacted, URL-free message and a mapped category, so a
+ * caller (the manager → the Tool adapter) can classify auth vs timeout vs transport without ever seeing
+ * a credential or an endpoint.
+ */
+import { AIError } from '../core/fallback/errors.js';
+import { redactString } from '../security/redact.js';
+import { systemClock } from '../util/clock.js';
+import { clampText, MCP_CLIENT_INFO, MCP_PROTOCOL_VERSION, JSONRPC_AUTH_CODES, initializeResult, listToolsResult, normalizeToolDecl, flattenCallResult, } from './protocol.js';
+export class McpClient {
+    transport;
+    opts;
+    nextId = 1;
+    pending = new Map();
+    clock;
+    started = false;
+    /** Errors the server sent with no correlatable id, plus discovery anomalies — surfaced as diagnostics. */
+    protocolErrors = [];
+    constructor(transport, opts) {
+        this.transport = transport;
+        this.opts = opts;
+        this.clock = opts.clock ?? systemClock;
+        this.transport.onMessage((msg) => this.onMessage(msg));
+    }
+    onMessage(msg) {
+        // A RESPONSE carries an id and exactly one of result/error, and never a method. A server-initiated
+        // REQUEST also carries an id — correlating on the id alone would resolve our pending call with
+        // `undefined` the moment a server sends one (sampling, roots, elicitation all do).
+        const m = msg;
+        if (typeof m.method === 'string')
+            return; // a request or notification from the server — not ours
+        if (m.id === undefined || m.id === null) {
+            // A parse/invalid-request error has no id, so it cannot be correlated. Recording it is the honest
+            // outcome: the affected request still times out, but the reason is visible in diagnostics.
+            if (m.error)
+                this.protocolErrors.push(clampText(`unattributable error ${m.error.code}: ${redactString(String(m.error.message ?? ''))}`, 200));
+            return;
+        }
+        // We only ever send numeric ids; a server that echoes ours as a string is still talking to us.
+        const key = typeof m.id === 'number' ? m.id : Number(m.id);
+        if (!Number.isFinite(key))
+            return;
+        const p = this.pending.get(key);
+        if (!p)
+            return;
+        this.settle(key, p);
+        if (m.error) {
+            const category = JSONRPC_AUTH_CODES.has(m.error.code) ? 'AUTHENTICATION' : 'PROVIDER';
+            // The message is server-controlled: redacted, flattened, and clamped before it can reach a status
+            // line, a diagnostic, or a replan prompt.
+            p.reject(new AIError(`MCP '${this.opts.serverId}' error ${m.error.code}: ${clampText(redactString(String(m.error.message ?? '')), 200)}`, { category, retryable: category !== 'AUTHENTICATION' }));
+            return;
+        }
+        p.resolve(m.result);
+    }
+    /** Drop a pending entry and release everything attached to it (timer + abort listener). */
+    settle(id, p) {
+        this.pending.delete(id);
+        clearTimeout(p.timer);
+        p.detach?.(); // an abort listener outlives `{ once: true }` when the signal never fires
+    }
+    async request(method, params, opts = {}) {
+        const id = this.nextId++;
+        const req = { jsonrpc: '2.0', id, method, ...(params !== undefined ? { params } : {}) };
+        const timeoutMs = opts.timeoutMs ?? this.opts.timeoutMs ?? 30_000;
+        // NOTE: `result` is not awaited until `send()` returns, so a timeout that fires DURING send would
+        // otherwise be an unhandled rejection (fatal by default). A no-op catch marks it handled; the
+        // caller still observes the rejection through the returned promise.
+        // An already-aborted caller must not reach the wire at all: sending the request and THEN cancelling
+        // it would run the remote tool, and `notifications/cancelled` for an id we never issued is noise.
+        if (opts.signal?.aborted)
+            throw new AIError(`MCP '${this.opts.serverId}' request cancelled`, { category: 'TIMEOUT', retryable: false });
+        let sent = false;
+        const result = new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.pending.delete(id);
+                reject(new AIError(`MCP '${this.opts.serverId}' request timed out after ${timeoutMs}ms (${method})`, { category: 'TIMEOUT', retryable: true }));
+            }, timeoutMs);
+            // NOT unref'd on purpose: the timer is how a stalled server becomes a TIMEOUT error. If it were
+            // unref'd and the loop drained (stdio child gone), the caller's await would never settle at all.
+            const entry = { resolve, reject, timer };
+            this.pending.set(id, entry);
+            if (opts.signal) {
+                const signal = opts.signal;
+                const onAbort = () => {
+                    const p = this.pending.get(id);
+                    if (!p)
+                        return;
+                    this.settle(id, p);
+                    // Cooperative cancel, but only for a request that actually reached the wire.
+                    if (sent)
+                        void this.transport.send({ jsonrpc: '2.0', method: 'notifications/cancelled', params: { requestId: id } }).catch(() => { });
+                    p.reject(new AIError(`MCP '${this.opts.serverId}' request cancelled`, { category: 'TIMEOUT', retryable: false }));
+                };
+                signal.addEventListener('abort', onAbort, { once: true });
+                entry.detach = () => signal.removeEventListener('abort', onAbort);
+            }
+        });
+        result.catch(() => { });
+        try {
+            await this.transport.send(req);
+            sent = true;
+        }
+        catch (e) {
+            // The request never reached the wire: settle and drop the pending entry NOW. Leaving it behind
+            // would strand its timer (holding the process open) and fire an unhandled rejection later.
+            const p = this.pending.get(id);
+            if (p) {
+                this.settle(id, p);
+                p.reject(e);
+            }
+            throw e;
+        }
+        return result;
+    }
+    /** Connect + negotiate. A counter-proposed version is accepted but reported as a mismatch. */
+    async initialize() {
+        if (!this.started) {
+            await this.transport.start();
+            this.started = true;
+        }
+        const raw = await this.request('initialize', {
+            protocolVersion: MCP_PROTOCOL_VERSION,
+            capabilities: {},
+            clientInfo: MCP_CLIENT_INFO,
+        });
+        const parsed = initializeResult.safeParse(raw ?? {});
+        const data = parsed.success ? parsed.data : {};
+        // The negotiated version is echoed into status lines and error text, so it is clamped like any
+        // other server string (a "version" of 4 KB of prose is otherwise a free prompt-injection channel).
+        const version = typeof data.protocolVersion === 'string' && data.protocolVersion ? clampText(data.protocolVersion, 40) : MCP_PROTOCOL_VERSION;
+        // The spec requires MCP-Protocol-Version on every request AFTER the handshake; the transport owns
+        // the header, so tell it what we settled on before the first post-handshake call.
+        this.transport.setProtocolVersion?.(version);
+        // Per spec the client confirms readiness with a notification (servers may ignore it).
+        await this.transport.send({ jsonrpc: '2.0', method: 'notifications/initialized' }).catch(() => { });
+        return {
+            protocolVersion: version,
+            ...(data.serverInfo?.name ? { serverName: clampText(data.serverInfo.name, 80) } : {}),
+            ...(data.serverInfo?.version ? { serverVersion: clampText(data.serverInfo.version, 40) } : {}),
+            versionMismatch: version !== MCP_PROTOCOL_VERSION,
+        };
+    }
+    /** List tools, following `nextCursor` up to `maxPages`. Every declaration is normalized (or rejected). */
+    async listTools(opts = {}) {
+        const maxPages = this.opts.maxPages ?? 20;
+        const maxTools = this.opts.maxTools ?? 500;
+        const tools = [];
+        const seen = new Set();
+        let rejected = 0;
+        let truncated = false;
+        let cursor;
+        for (let page = 0; page < maxPages; page += 1) {
+            const raw = await this.request('tools/list', cursor ? { cursor } : {}, opts);
+            const parsed = listToolsResult.safeParse(raw ?? {});
+            if (!parsed.success) {
+                // A malformed page means the catalog is PARTIAL — saying otherwise would cache a truncated list
+                // as complete and silently hide the server's remaining tools.
+                this.protocolErrors.push(`tools/list page ${page + 1} was malformed; the catalog is partial`);
+                truncated = true;
+                break;
+            }
+            for (const decl of parsed.data.tools ?? []) {
+                const norm = normalizeToolDecl(decl);
+                if (!norm) {
+                    rejected += 1;
+                    continue;
+                }
+                if (seen.has(norm.name))
+                    continue; // a server repeating a name adds nothing
+                if (tools.length >= maxTools) {
+                    truncated = true;
+                    break;
+                }
+                seen.add(norm.name);
+                tools.push(norm);
+            }
+            cursor = parsed.data.nextCursor;
+            if (!cursor || truncated)
+                break;
+            if (page === maxPages - 1)
+                truncated = true;
+        }
+        return { tools, rejected, truncated };
+    }
+    async callTool(name, args, opts = {}) {
+        const raw = await this.request('tools/call', { name, arguments: args ?? {} }, opts);
+        return flattenCallResult(raw ?? {});
+    }
+    async ping() {
+        const started = this.clock.now();
+        try {
+            await this.request('ping', {}, { timeoutMs: Math.min(this.opts.timeoutMs ?? 30_000, 5_000) });
+            return { ok: true, latencyMs: this.clock.now() - started };
+        }
+        catch {
+            return { ok: false, latencyMs: this.clock.now() - started };
+        }
+    }
+    async close() {
+        for (const [, p] of this.pending) {
+            clearTimeout(p.timer);
+            p.detach?.();
+            p.reject(new AIError(`MCP '${this.opts.serverId}' closed`, { category: 'NETWORK', retryable: true }));
+        }
+        this.pending.clear();
+        await this.transport.close();
+    }
+    diagnostics() {
+        return [...this.protocolErrors.slice(-5), ...this.transport.diagnostics()];
+    }
+    /** Whether the transport says our session is gone and only a fresh handshake can recover. */
+    sessionExpired() {
+        return this.transport.sessionExpired === true;
+    }
+}

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>;
+}