ai-runtime-engine 1.2.0 → 2.7.0

package/dist/generation/generateAdapter.js

@@ -6,6 +6,8 @@
  */
 import { AIError } from '../core/fallback/errors.js';
 import { analyzeOpenApiFile } from '../discovery/openapi.js';
+import { extractJson } from '../util/extractJson.js';
+import { wrapUntrusted } from '../tools/untrusted.js';
 /** Turn an OpenAPI analysis into a ProviderConfig. Throws if the spec yielded no usable mapping. */
 export function generateProviderConfig(analysis, overrides = {}) {
     const base = analysis.suggestedProviderConfig;
@@ -28,3 +30,39 @@ export function generateProviderConfig(analysis, overrides = {}) {
 export function generateProviderConfigFromFile(specPath, overrides = {}) {
     return generateProviderConfig(analyzeOpenApiFile(specPath), overrides);
 }
+/**
+ * AI-assisted adapter rung (Phase 21a) — an opt-in gap-filler on top of the DETERMINISTIC
+ * `generateProviderConfig`. When the spec doesn't enumerate models, a model proposes a likely model-id
+ * list; the OUTPUT is STILL produced by `generateProviderConfig` (a validated `ProviderConfig`, never code),
+ * so a bad suggestion can only propose model-id strings the operator then confirms — it can never inject an
+ * unvalidated config. Any model/parse failure falls back to the deterministic result (or its error).
+ */
+export async function suggestProviderConfig(analysis, ai, overrides = {}) {
+    let modelList = Array.isArray(overrides.models) ? overrides.models : [];
+    // Only consult the model when we actually have a gap to fill (no explicit models, none in the spec).
+    const specModels = analysis.suggestedProviderConfig?.models;
+    const needsModels = modelList.length === 0 && (specModels === undefined || specModels === 'auto');
+    if (needsModels) {
+        try {
+            const prompt = `An OpenAPI spec describes an AI provider. Suggest the model IDs it most likely exposes for chat/completions. ` +
+                `Reply ONLY with JSON: {"models": ["<model-id>", ...]}.\n\n` +
+                wrapUntrusted('openapi-summary', `title: ${analysis.title ?? '(unknown)'}\nbaseUrl: ${analysis.baseUrl ?? '(unknown)'}\nwireShape: ${analysis.wireShape}\nendpoints: ${analysis.endpoints.map((e) => e.path).slice(0, 20).join(', ')}`);
+            const run = await ai.run({ task: 'suggest-provider-config', input: prompt, output: { format: 'json' }, requirements: { intelligence: ['reasoning'], output: ['json'] } });
+            if (run.ok && run.response) {
+                const parsed = (run.response.json ?? extractJson(run.response.text ?? ''));
+                if (Array.isArray(parsed?.models))
+                    modelList = parsed.models.filter((m) => typeof m === 'string' && m.trim().length > 0);
+            }
+        }
+        catch {
+            /* a suggestion failure just falls through to the deterministic path */
+        }
+    }
+    try {
+        const config = generateProviderConfig(analysis, { ...overrides, ...(modelList.length && !overrides.models ? { models: modelList } : {}) });
+        return { ok: true, config };
+    }
+    catch (e) {
+        return { ok: false, error: e instanceof Error ? e.message : String(e) };
+    }
+}

package/dist/generation/generateSkill.d.ts

@@ -0,0 +1,26 @@
+/**
+ * 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 type { AI } from '../plugin/ai.js';
+import { type SkillManifest } from '../skills/manifest.js';
+export interface GenerateSkillInput {
+    goal: string;
+    /** Tool ids the drafted manifest may use (the host's registered tools). */
+    tools: string[];
+    ai: AI;
+}
+export interface GenerateSkillResult {
+    ok: boolean;
+    manifest?: SkillManifest;
+    /** The manifest serialized as `*.skill.yaml`, ready to write on confirm. */
+    yaml?: string;
+    error?: string;
+}
+export declare function generateSkillManifest(input: GenerateSkillInput): Promise<GenerateSkillResult>;

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

@@ -20,7 +20,7 @@ export type { FetchLike } from './providers/httpClient.js';
 export { PROVIDER_DEFAULTS } from './config/providerDefaults.js';
 export { resolveModelMetadata } from './discovery/modelCatalog.js';
 export { registerWire } from './providers/wire/registry.js';
-export type { WireModule, WireShape } from './providers/wire/types.js';
+export type { WireDelta, WireModule, WireShape } from './providers/wire/types.js';
 export { AIError, isRetryable, statusToCategory, toAIError } from './core/fallback/errors.js';
 export { capabilitySatisfies, emptyProfile, getCapability, mergeProfiles, profileFromDeclared, rankOf, } from './core/capabilities/evidence.js';
 export { AGENT_CAPABILITIES, INPUT_MODALITIES, INTELLIGENCE_SKILLS, OUTPUT_MODALITIES, } from './core/capabilities/taxonomy.js';
@@ -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;
+    }
+}