ai-runtime-engine 1.1.0

package/dist/providers/httpClient.js

@@ -0,0 +1,80 @@
+/**
+ * The single HTTP execution path: per-request `AbortSignal.timeout`, same-provider retry on
+ * 429/5xx/network with `Retry-After`, and the `response_format` graceful-degrade for gateways that
+ * reject it. Two deliberate design choices:
+ *   - `fetch` is INJECTABLE (so every adapter test runs offline against a mocked fetch);
+ *   - transport is SPLIT from classification — this layer throws a redacted, categorized AIError; the
+ *     cross-provider fallback decides what to do next.
+ *
+ * SECURITY: the request URL is never interpolated into an error (undici embeds it, and it can carry a
+ * key-in-query); error bodies are redacted and truncated; the API key lives only in the header the
+ * caller built, never in anything this function stores or throws.
+ */
+import { AIError, isRetryable, statusToCategory } from '../core/fallback/errors.js';
+import { redactString } from '../security/redact.js';
+import { systemClock } from '../util/clock.js';
+export async function callHttp(input) {
+    const fetchImpl = input.fetchImpl ?? fetch;
+    const clock = input.clock ?? systemClock;
+    const { providerId, model } = input;
+    let jsonMode = input.jsonMode;
+    let lastError;
+    for (let attempt = 1; attempt <= input.maxRetries + 1; attempt += 1) {
+        const req = input.build(jsonMode);
+        const started = clock.now();
+        try {
+            const res = await fetchImpl(req.url, {
+                method: 'POST',
+                headers: req.headers,
+                body: JSON.stringify(req.body),
+                signal: AbortSignal.timeout(input.timeoutMs),
+            });
+            const text = await res.text();
+            if (!res.ok) {
+                // response_format degrade: a gateway that 400s naming it doesn't support JSON mode.
+                if (res.status === 400 && jsonMode && /response_format/i.test(text)) {
+                    jsonMode = false;
+                    input.onJsonModeDisabled?.();
+                    lastError = new AIError('gateway rejected response_format — retrying without JSON mode', { category: 'INVALID_REQUEST', status: 400, retryable: true, providerId, model });
+                    continue;
+                }
+                const excerpt = redactString(text.slice(0, 300));
+                const category = statusToCategory(res.status);
+                const retryable = isRetryable(category);
+                const err = new AIError(`${providerId} returned HTTP ${res.status}: ${excerpt}`, { category, status: res.status, retryable, providerId, model });
+                if (!retryable)
+                    throw err;
+                lastError = err;
+                const retryAfter = Number(res.headers.get('retry-after'));
+                await clock.sleep(Number.isFinite(retryAfter) && retryAfter > 0 ? Math.min(retryAfter * 1000, 30_000) : attempt * 2000);
+                continue;
+            }
+            let json;
+            try {
+                json = JSON.parse(text);
+            }
+            catch (e) {
+                const why = e instanceof Error ? e.message : String(e);
+                throw new AIError(`${providerId} returned a non-JSON body (${why})`, { category: 'RESPONSE_VALIDATION', status: res.status, retryable: false, providerId, model });
+            }
+            return { status: res.status, json, durationMs: clock.now() - started, attempts: attempt, jsonModeUsed: jsonMode };
+        }
+        catch (e) {
+            if (e instanceof AIError && !e.retryable)
+                throw e;
+            if (e instanceof AIError) {
+                lastError = e;
+            }
+            else {
+                // fetch/undici embeds the full URL in its message — use only the error NAME, never the message.
+                const name = e instanceof Error ? e.name : 'Error';
+                const isTimeout = name === 'TimeoutError' || name === 'AbortError';
+                lastError = new AIError(`${providerId} request failed (${name})`, { category: isTimeout ? 'TIMEOUT' : 'NETWORK', retryable: true, providerId, model });
+            }
+            if (attempt > input.maxRetries)
+                break;
+            await clock.sleep(attempt * 2000);
+        }
+    }
+    throw lastError ?? new AIError(`${providerId} request failed`, { category: 'NETWORK', retryable: true, providerId, model });
+}

package/dist/providers/httpProvider.d.ts

@@ -0,0 +1,49 @@
+/**
+ * HttpProvider — the single concrete adapter behind the whole provider fleet. Every real provider is
+ * this class configured with a wire shape, a base URL, a credential, and a resolved model list. That
+ * is why "adding a provider" is a preset/config change, not new routing code. It covers both the
+ * OpenAI-compatible fleet (Gemini/Groq/Ollama/OpenRouter/Cerebras/Mistral/custom) and Anthropic-native
+ * (via the anthropic wire) through one execute() path.
+ *
+ * SECURITY: the key is read from the Credential only at header-build time; discover() reports the base
+ * URL ORIGIN only; nothing here returns or logs the key.
+ */
+import type { AIProvider } from './provider.js';
+import type { AIRequest, AIResponse, CapabilityProfile, ExecutionEstimate, HealthStatus, ModelMetadata, PrivacyClass, ProviderKind, ProviderMetadata } from '../types.js';
+import type { WireShape } from './wire/types.js';
+import type { FetchLike } from './httpClient.js';
+import type { Clock } from '../util/clock.js';
+import type { Credential } from '../security/credentials.js';
+export interface HttpProviderConfig {
+    id: string;
+    name?: string;
+    kind: ProviderKind;
+    wireShape: WireShape;
+    baseUrl: string;
+    credential: Credential;
+    privacyClass: PrivacyClass;
+    models: ModelMetadata[];
+    defaultModel?: string;
+    headers?: Record<string, string>;
+    supportsModelListing?: boolean;
+    requiresKey?: boolean;
+    fetchImpl?: FetchLike;
+    clock?: Clock;
+    timeoutMs?: number;
+    maxRetries?: number;
+}
+export declare class HttpProvider implements AIProvider {
+    readonly id: string;
+    readonly name: string;
+    readonly kind: ProviderKind;
+    readonly privacyClass: PrivacyClass;
+    private readonly cfg;
+    private jsonMode;
+    constructor(config: HttpProviderConfig);
+    discover(): Promise<ProviderMetadata>;
+    healthCheck(): Promise<HealthStatus>;
+    listModels(): Promise<ModelMetadata[]>;
+    getCapabilities(model: string): Promise<CapabilityProfile>;
+    estimate(request: AIRequest): Promise<ExecutionEstimate>;
+    execute(request: AIRequest): Promise<AIResponse>;
+}

package/dist/providers/httpProvider.js

@@ -0,0 +1,135 @@
+/**
+ * HttpProvider — the single concrete adapter behind the whole provider fleet. Every real provider is
+ * this class configured with a wire shape, a base URL, a credential, and a resolved model list. That
+ * is why "adding a provider" is a preset/config change, not new routing code. It covers both the
+ * OpenAI-compatible fleet (Gemini/Groq/Ollama/OpenRouter/Cerebras/Mistral/custom) and Anthropic-native
+ * (via the anthropic wire) through one execute() path.
+ *
+ * SECURITY: the key is read from the Credential only at header-build time; discover() reports the base
+ * URL ORIGIN only; nothing here returns or logs the key.
+ */
+import { AIError } from '../core/fallback/errors.js';
+import { emptyProfile } from '../core/capabilities/evidence.js';
+import { extractJson } from '../util/extractJson.js';
+import { getWire } from './wire/registry.js';
+import { callHttp } from './httpClient.js';
+function originOf(url) {
+    try {
+        return new URL(url).origin;
+    }
+    catch {
+        return '';
+    }
+}
+export class HttpProvider {
+    id;
+    name;
+    kind;
+    privacyClass;
+    cfg;
+    jsonMode = true;
+    constructor(config) {
+        this.cfg = config;
+        this.id = config.id;
+        this.name = config.name ?? config.id;
+        this.kind = config.kind;
+        this.privacyClass = config.privacyClass;
+    }
+    async discover() {
+        return {
+            id: this.id,
+            name: this.name,
+            kind: this.kind,
+            baseOrigin: originOf(this.cfg.baseUrl),
+            authMode: this.cfg.requiresKey === false ? 'none' : 'env',
+            supportsModelListing: this.cfg.supportsModelListing ?? false,
+            privacyClass: this.privacyClass,
+            models: this.cfg.models,
+            ...(this.cfg.defaultModel ? { defaultModel: this.cfg.defaultModel } : {}),
+        };
+    }
+    async healthCheck() {
+        const needsKey = this.cfg.requiresKey !== false;
+        if (needsKey && !this.cfg.credential.hasKey) {
+            return { providerId: this.id, state: 'NOT_CONFIGURED', routable: false, checkedAt: 0, detail: `missing ${this.cfg.credential.envName ?? 'API key'}` };
+        }
+        return { providerId: this.id, state: 'AVAILABLE', routable: true, checkedAt: 0 };
+    }
+    async listModels() {
+        return this.cfg.models;
+    }
+    async getCapabilities(model) {
+        return this.cfg.models.find((m) => m.id === model)?.capabilities ?? emptyProfile();
+    }
+    async estimate(request) {
+        const model = this.cfg.models.find((m) => m.id === request.model);
+        const inTokens = Math.ceil((request.input.text?.length ?? 0) / 4);
+        const estimate = {
+            providerId: this.id,
+            model: request.model,
+            estInputTokens: inTokens,
+            contextFits: model?.contextWindow ? inTokens < model.contextWindow : true,
+        };
+        if (model?.pricing) {
+            estimate.estCost = { amount: ((model.pricing.inputPerMTok ?? 0) * inTokens) / 1_000_000, currency: model.pricing.currency ?? 'USD', evidence: 'inferred' };
+        }
+        if (model?.latency?.p50Ms !== undefined)
+            estimate.estLatencyMs = { p50: model.latency.p50Ms, evidence: model.latency.evidence };
+        return estimate;
+    }
+    async execute(request) {
+        const needsKey = this.cfg.requiresKey !== false;
+        const apiKey = this.cfg.credential.use();
+        if (needsKey && !apiKey) {
+            throw new AIError(`no ${this.cfg.credential.envName ?? 'API key'} in the environment`, { category: 'AUTHENTICATION', retryable: false, providerId: this.id, model: request.model });
+        }
+        const wire = getWire(this.cfg.wireShape);
+        const maxTokens = request.params?.maxTokens ?? 2000;
+        const ctx = {
+            baseUrl: this.cfg.baseUrl,
+            model: request.model,
+            maxTokens,
+            ...(apiKey ? { apiKey } : {}),
+            ...(this.cfg.headers ? { headers: this.cfg.headers } : {}),
+        };
+        const result = await callHttp({
+            build: (jsonMode) => wire.buildRequest(request, ctx, jsonMode),
+            providerId: this.id,
+            model: request.model,
+            timeoutMs: request.timeoutMs || this.cfg.timeoutMs || 90_000,
+            maxRetries: this.cfg.maxRetries ?? 2,
+            jsonMode: this.jsonMode,
+            ...(this.cfg.fetchImpl ? { fetchImpl: this.cfg.fetchImpl } : {}),
+            ...(this.cfg.clock ? { clock: this.cfg.clock } : {}),
+            onJsonModeDisabled: () => {
+                this.jsonMode = false;
+            },
+        });
+        const parsed = wire.readResponse(result.json);
+        const response = {
+            finishReason: parsed.finishReason,
+            providerId: this.id,
+            model: request.model,
+            latencyMs: result.durationMs,
+        };
+        if (parsed.text !== undefined)
+            response.text = parsed.text;
+        if (parsed.toolCalls !== undefined)
+            response.toolCalls = parsed.toolCalls;
+        const wantsJson = request.output?.format === 'json' || request.output?.format === 'structured_output';
+        if (parsed.json !== undefined)
+            response.json = parsed.json;
+        else if (wantsJson && parsed.text)
+            response.json = extractJson(parsed.text);
+        if (parsed.usage) {
+            const inTok = parsed.usage.inputTokens;
+            const outTok = parsed.usage.outputTokens;
+            response.usage = {
+                ...(inTok !== undefined ? { inputTokens: inTok } : {}),
+                ...(outTok !== undefined ? { outputTokens: outTok } : {}),
+                ...(inTok !== undefined && outTok !== undefined ? { totalTokens: inTok + outTok } : {}),
+            };
+        }
+        return response;
+    }
+}

package/dist/providers/mock/demo.d.ts

@@ -0,0 +1,13 @@
+/**
+ * A demo AI wired with two deterministic mock providers — a frontier "alpha" and a fast/cheap "beta".
+ * Used by the CLI and examples so the whole loop is exercisable offline with no keys. Not part of the
+ * routing core; purely a convenience for demonstrations and smoke checks.
+ */
+import { AI } from '../../plugin/ai.js';
+import type { MockBehavior } from './scenarios.js';
+import type { AIRequest } from '../../types.js';
+export interface DemoOptions {
+    alphaBehavior?: MockBehavior | ((req: AIRequest) => MockBehavior);
+    betaBehavior?: MockBehavior | ((req: AIRequest) => MockBehavior);
+}
+export declare function buildDemoAI(opts?: DemoOptions): AI;

package/dist/providers/mock/demo.js

@@ -0,0 +1,58 @@
+/**
+ * A demo AI wired with two deterministic mock providers — a frontier "alpha" and a fast/cheap "beta".
+ * Used by the CLI and examples so the whole loop is exercisable offline with no keys. Not part of the
+ * routing core; purely a convenience for demonstrations and smoke checks.
+ */
+import { AI } from '../../plugin/ai.js';
+import { MockProvider } from './mockProvider.js';
+import { makeModel } from './scenarios.js';
+export function buildDemoAI(opts = {}) {
+    const alpha = new MockProvider({
+        id: 'alpha',
+        name: 'Alpha (frontier)',
+        privacyClass: 'cloud',
+        models: [
+            makeModel({
+                providerId: 'alpha',
+                id: 'alpha-large',
+                caps: {
+                    intelligence: ['reasoning', 'code_generation', 'code_analysis', 'summarization', 'extraction', 'classification', 'planning'],
+                    output: ['text', 'code', 'json', 'structured_output'],
+                    input: ['text', 'image', 'file'],
+                    agent: ['tool_calling', 'function_calling'],
+                },
+                contextWindow: 200_000,
+                quality: { tier: 'frontier' },
+                pricing: { inputPerMTok: 3, outputPerMTok: 15, currency: 'USD' },
+                latencyP50Ms: 1800,
+                successRate: 0.98,
+            }),
+        ],
+        behavior: opts.alphaBehavior ?? { kind: 'ok' },
+        latencyMs: 1,
+    });
+    const beta = new MockProvider({
+        id: 'beta',
+        name: 'Beta (fast/cheap)',
+        privacyClass: 'cloud',
+        models: [
+            makeModel({
+                providerId: 'beta',
+                id: 'beta-fast',
+                caps: {
+                    intelligence: ['reasoning', 'code_generation', 'code_analysis'],
+                    output: ['text', 'code', 'json'],
+                    input: ['text'],
+                },
+                contextWindow: 128_000,
+                quality: { tier: 'strong' },
+                pricing: { inputPerMTok: 0.5, outputPerMTok: 0.8, currency: 'USD' },
+                latencyP50Ms: 400,
+                successRate: 0.97,
+            }),
+        ],
+        behavior: opts.betaBehavior ?? { kind: 'ok' },
+        latencyMs: 1,
+    });
+    return new AI().registerProvider(alpha).registerProvider(beta);
+}

package/dist/providers/mock/mockProvider.d.ts

@@ -0,0 +1,35 @@
+/**
+ * MockProvider — a deterministic, no-network AIProvider. It is the keystone for offline development and the
+ * chaos-test backbone: scripted behaviors (ok / timeout / rate_limit / server_error / malformed /
+ * auth_fail) let every routing, fallback, and validation path be proven offline with no API keys.
+ */
+import type { AIProvider } from '../provider.js';
+import type { AIRequest, AIResponse, CapabilityProfile, ExecutionEstimate, HealthStatus, ModelMetadata, PrivacyClass, ProviderMetadata } from '../../types.js';
+import type { MockBehavior } from './scenarios.js';
+export interface MockProviderConfig {
+    id: string;
+    name?: string;
+    privacyClass?: PrivacyClass;
+    models: ModelMetadata[];
+    /** Fixed behavior or a function of the request. Defaults to `ok`. */
+    behavior?: MockBehavior | ((req: AIRequest) => MockBehavior);
+    latencyMs?: number;
+}
+export declare class MockProvider implements AIProvider {
+    readonly id: string;
+    readonly name: string;
+    readonly kind: "mock";
+    readonly privacyClass: PrivacyClass;
+    private readonly models;
+    private readonly behavior;
+    private readonly latencyMs;
+    /** Number of times execute() was actually invoked — lets tests assert a poisoned provider is not re-hammered. */
+    executeCalls: number;
+    constructor(config: MockProviderConfig);
+    discover(): Promise<ProviderMetadata>;
+    healthCheck(): Promise<HealthStatus>;
+    listModels(): Promise<ModelMetadata[]>;
+    getCapabilities(model: string): Promise<CapabilityProfile>;
+    estimate(request: AIRequest): Promise<ExecutionEstimate>;
+    execute(request: AIRequest): Promise<AIResponse>;
+}

package/dist/providers/mock/mockProvider.js

@@ -0,0 +1,121 @@
+/**
+ * MockProvider — a deterministic, no-network AIProvider. It is the keystone for offline development and the
+ * chaos-test backbone: scripted behaviors (ok / timeout / rate_limit / server_error / malformed /
+ * auth_fail) let every routing, fallback, and validation path be proven offline with no API keys.
+ */
+import { AIError } from '../../core/fallback/errors.js';
+import { emptyProfile } from '../../core/capabilities/evidence.js';
+export class MockProvider {
+    id;
+    name;
+    kind = 'mock';
+    privacyClass;
+    models;
+    behavior;
+    latencyMs;
+    /** Number of times execute() was actually invoked — lets tests assert a poisoned provider is not re-hammered. */
+    executeCalls = 0;
+    constructor(config) {
+        this.id = config.id;
+        this.name = config.name ?? config.id;
+        this.privacyClass = config.privacyClass ?? 'cloud';
+        this.models = config.models;
+        this.behavior = config.behavior ?? { kind: 'ok' };
+        this.latencyMs = config.latencyMs ?? 1;
+    }
+    async discover() {
+        return {
+            id: this.id,
+            name: this.name,
+            kind: this.kind,
+            authMode: 'none',
+            supportsModelListing: true,
+            privacyClass: this.privacyClass,
+            models: this.models,
+            ...(this.models[0] ? { defaultModel: this.models[0].id } : {}),
+        };
+    }
+    async healthCheck() {
+        return { providerId: this.id, state: 'AVAILABLE', routable: true, checkedAt: 0 };
+    }
+    async listModels() {
+        return this.models;
+    }
+    async getCapabilities(model) {
+        return this.models.find((m) => m.id === model)?.capabilities ?? emptyProfile();
+    }
+    async estimate(request) {
+        const model = this.models.find((m) => m.id === request.model);
+        const inTokens = Math.ceil((request.input.text?.length ?? 0) / 4);
+        const estimate = {
+            providerId: this.id,
+            model: request.model,
+            estInputTokens: inTokens,
+            contextFits: model?.contextWindow ? inTokens < model.contextWindow : true,
+        };
+        if (model?.pricing) {
+            estimate.estCost = {
+                amount: ((model.pricing.inputPerMTok ?? 0) * inTokens) / 1_000_000,
+                currency: model.pricing.currency ?? 'USD',
+                evidence: 'inferred',
+            };
+        }
+        if (model?.latency?.p50Ms !== undefined) {
+            estimate.estLatencyMs = { p50: model.latency.p50Ms, evidence: 'inferred' };
+        }
+        return estimate;
+    }
+    async execute(request) {
+        this.executeCalls += 1;
+        const behavior = typeof this.behavior === 'function' ? this.behavior(request) : this.behavior;
+        const base = { providerId: this.id, model: request.model };
+        switch (behavior.kind) {
+            case 'timeout':
+                throw new AIError(`${this.id} timed out`, { category: 'TIMEOUT', ...base });
+            case 'rate_limit':
+                throw new AIError(`${this.id} rate limited`, { category: 'RATE_LIMIT', status: 429, ...base });
+            case 'server_error':
+                throw new AIError(`${this.id} returned HTTP 503`, { category: 'PROVIDER', status: 503, ...base });
+            case 'auth_fail':
+                throw new AIError(`${this.id} authentication failed`, { category: 'AUTHENTICATION', status: 401, ...base });
+            case 'malformed':
+                throw new AIError(`${this.id} returned an unparseable response`, { category: 'RESPONSE_VALIDATION', ...base });
+            case 'ok': {
+                // A request that supplies tools gets a tool call back (used by the tool-calling probe).
+                if (request.tools && request.tools.length > 0) {
+                    return {
+                        finishReason: 'tool_calls',
+                        providerId: this.id,
+                        model: request.model,
+                        latencyMs: this.latencyMs,
+                        toolCalls: [{ name: request.tools[0].name, arguments: {} }],
+                        usage: { inputTokens: 4, outputTokens: 4 },
+                    };
+                }
+                const wantsJson = request.output?.format === 'json' || request.output?.format === 'structured_output';
+                const response = {
+                    finishReason: 'stop',
+                    providerId: this.id,
+                    model: request.model,
+                    latencyMs: this.latencyMs,
+                    usage: { inputTokens: Math.ceil((request.input.text?.length ?? 0) / 4), outputTokens: 8 },
+                };
+                if (wantsJson)
+                    response.json = behavior.json ?? { ok: true, task: request.taskId };
+                else
+                    response.text = behavior.text ?? `mock(${this.id}/${request.model}) handled ${request.taskId}`;
+                return response;
+            }
+            case 'ok_text': {
+                return {
+                    finishReason: 'stop',
+                    providerId: this.id,
+                    model: request.model,
+                    latencyMs: this.latencyMs,
+                    text: behavior.text ?? `mock(${this.id}/${request.model}) text-only`,
+                    usage: { inputTokens: 4, outputTokens: 8 },
+                };
+            }
+        }
+    }
+}

package/dist/providers/mock/scenarios.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Test helpers for the MockProvider: build normalized ModelMetadata quickly, and name the failure
+ * behaviors the chaos/integration tests script. Shipped in `src/` so downstream consumers can use the
+ * same deterministic double in their own tests.
+ */
+import type { BooleanCapabilityGroup } from '../../core/capabilities/taxonomy.js';
+import type { Evidence, ModelMetadata, Pricing, PrivacyClass, QualityTier } from '../../types.js';
+export type MockBehavior = {
+    kind: 'ok';
+    text?: string;
+    json?: unknown;
+} | {
+    kind: 'ok_text';
+    text?: string;
+} | {
+    kind: 'timeout';
+} | {
+    kind: 'rate_limit';
+} | {
+    kind: 'server_error';
+} | {
+    kind: 'malformed';
+} | {
+    kind: 'auth_fail';
+};
+export interface MakeModelInput {
+    providerId: string;
+    id: string;
+    caps?: Partial<Record<BooleanCapabilityGroup, string[]>>;
+    contextWindow?: number;
+    evidence?: Evidence;
+    quality?: {
+        tier?: QualityTier;
+        score?: number;
+        evidence?: Evidence;
+    };
+    pricing?: Pricing;
+    latencyP50Ms?: number;
+    successRate?: number;
+    enabled?: boolean;
+}
+/** Build a ModelMetadata with declared capabilities tagged at one evidence level (default `documented`). */
+export declare function makeModel(input: MakeModelInput): ModelMetadata;
+export declare const DEFAULT_PRIVACY: PrivacyClass;

package/dist/providers/mock/scenarios.js

@@ -0,0 +1,30 @@
+/**
+ * Test helpers for the MockProvider: build normalized ModelMetadata quickly, and name the failure
+ * behaviors the chaos/integration tests script. Shipped in `src/` so downstream consumers can use the
+ * same deterministic double in their own tests.
+ */
+import { profileFromDeclared } from '../../core/capabilities/evidence.js';
+/** Build a ModelMetadata with declared capabilities tagged at one evidence level (default `documented`). */
+export function makeModel(input) {
+    const evidence = input.evidence ?? 'documented';
+    const capabilities = profileFromDeclared({ ...input.caps, contextWindow: input.contextWindow }, evidence);
+    const model = {
+        providerId: input.providerId,
+        id: input.id,
+        capabilities,
+        enabled: input.enabled ?? true,
+        source: evidence,
+    };
+    if (input.contextWindow !== undefined)
+        model.contextWindow = input.contextWindow;
+    if (input.pricing !== undefined)
+        model.pricing = input.pricing;
+    if (input.quality !== undefined)
+        model.quality = { evidence: input.quality.evidence ?? 'documented', ...(input.quality.tier !== undefined ? { tier: input.quality.tier } : {}), ...(input.quality.score !== undefined ? { score: input.quality.score } : {}) };
+    if (input.latencyP50Ms !== undefined)
+        model.latency = { p50Ms: input.latencyP50Ms, evidence: 'inferred' };
+    if (input.successRate !== undefined)
+        model.reliability = { successRate: input.successRate, evidence: 'inferred' };
+    return model;
+}
+export const DEFAULT_PRIVACY = 'cloud';

package/dist/providers/provider.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The provider contract — the single seam between the vendor-agnostic core and the outside world.
+ *
+ * `core/` only ever holds `AIProvider` instances and reads capabilities / privacyClass / health /
+ * estimates THROUGH this interface. Adding a provider means implementing this (usually by configuring
+ * the generic adapter); it never means editing `core/`.
+ *
+ * SECURITY: an implementation must hold its API key non-enumerably and must never place a key,
+ * a full request URL, or a key-in-query anywhere in the values it returns from these methods.
+ */
+import type { AIRequest, AIResponse, CapabilityProfile, ExecutionEstimate, HealthStatus, ModelMetadata, PrivacyClass, ProviderKind, ProviderMetadata } from '../types.js';
+export interface AIProvider {
+    readonly id: string;
+    readonly name: string;
+    readonly kind: ProviderKind;
+    /** `local` may receive high-sensitivity input; `cloud` is the fail-closed default. First-class so core reads it via the contract. */
+    readonly privacyClass: PrivacyClass;
+    /** One-shot startup discovery: identity + models + capabilities the provider can report. */
+    discover(): Promise<ProviderMetadata>;
+    healthCheck(): Promise<HealthStatus>;
+    listModels(): Promise<ModelMetadata[]>;
+    /** Resolve capabilities for one model. Providers own capability resolution; core never reads the catalog directly. */
+    getCapabilities(model: string): Promise<CapabilityProfile>;
+    execute(request: AIRequest): Promise<AIResponse>;
+    estimate(request: AIRequest): Promise<ExecutionEstimate>;
+}

package/dist/providers/provider.js

@@ -0,0 +1,11 @@
+/**
+ * The provider contract — the single seam between the vendor-agnostic core and the outside world.
+ *
+ * `core/` only ever holds `AIProvider` instances and reads capabilities / privacyClass / health /
+ * estimates THROUGH this interface. Adding a provider means implementing this (usually by configuring
+ * the generic adapter); it never means editing `core/`.
+ *
+ * SECURITY: an implementation must hold its API key non-enumerably and must never place a key,
+ * a full request URL, or a key-in-query anywhere in the values it returns from these methods.
+ */
+export {};

package/dist/providers/wire/anthropicWire.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Anthropic-native wire (`POST {baseUrl}/v1/messages`). A distinct shape from OpenAI-compat:
+ * `x-api-key` + `anthropic-version` headers, top-level `system`, `content[]`/`stop_reason` response.
+ */
+import type { WireModule } from './types.js';
+export declare const anthropicWire: WireModule;