ai-runtime-engine 1.1.0

package/dist/orchestration/plan.d.ts

@@ -0,0 +1,37 @@
+/**
+ * ExecutionPlan + PlanStep — a structured, versioned plan the orchestrator executes. A step names a
+ * REGISTERED skill or tool; a plan referencing anything unregistered is invalid (never executed). Plans
+ * are data: the model proposes them, the Runtime owns execution and permission enforcement.
+ */
+export type PlanStepStatus = 'pending' | 'running' | 'succeeded' | 'failed' | 'skipped';
+export interface PlanStep {
+    id: string;
+    description: string;
+    /** A registered skill id (skill and tool are mutually exclusive per step). */
+    skill?: string;
+    /** A registered tool id. */
+    tool?: string;
+    input?: unknown;
+    /** Ids of steps that must succeed first. */
+    dependsOn?: string[];
+    status: PlanStepStatus;
+}
+export interface ExecutionPlan {
+    id: string;
+    goal: string;
+    version: number;
+    steps: PlanStep[];
+    /** Why this version was (re)created — set on replans. */
+    reason?: string;
+}
+export interface PlanValidation {
+    ok: boolean;
+    errors: string[];
+}
+/** Validate that every step references a registered skill/tool and dependencies/DAG are sound. */
+export declare function validatePlan(plan: ExecutionPlan, available: {
+    skills: string[];
+    tools: string[];
+}): PlanValidation;
+/** A topological execution order → array of "waves" (each wave's steps can run in parallel). */
+export declare function executionWaves(steps: PlanStep[]): PlanStep[][];

package/dist/orchestration/plan.js

@@ -0,0 +1,70 @@
+/**
+ * ExecutionPlan + PlanStep — a structured, versioned plan the orchestrator executes. A step names a
+ * REGISTERED skill or tool; a plan referencing anything unregistered is invalid (never executed). Plans
+ * are data: the model proposes them, the Runtime owns execution and permission enforcement.
+ */
+/** Validate that every step references a registered skill/tool and dependencies/DAG are sound. */
+export function validatePlan(plan, available) {
+    const errors = [];
+    const skills = new Set(available.skills);
+    const tools = new Set(available.tools);
+    const ids = new Set(plan.steps.map((s) => s.id));
+    if (plan.steps.length === 0)
+        errors.push('plan has no steps');
+    if (ids.size !== plan.steps.length)
+        errors.push('plan has duplicate step ids'); // dupes would silently drop a step
+    for (const step of plan.steps) {
+        if (!step.skill && !step.tool)
+            errors.push(`step ${step.id}: names neither a skill nor a tool`);
+        if (step.skill && step.tool)
+            errors.push(`step ${step.id}: names both a skill and a tool`);
+        if (step.skill && !skills.has(step.skill))
+            errors.push(`step ${step.id}: unknown skill '${step.skill}'`);
+        if (step.tool && !tools.has(step.tool))
+            errors.push(`step ${step.id}: unknown tool '${step.tool}'`);
+        for (const dep of step.dependsOn ?? []) {
+            if (!ids.has(dep))
+                errors.push(`step ${step.id}: depends on unknown step '${dep}'`);
+            if (dep === step.id)
+                errors.push(`step ${step.id}: depends on itself`);
+        }
+    }
+    if (hasCycle(plan.steps))
+        errors.push('plan has a dependency cycle');
+    return { ok: errors.length === 0, errors };
+}
+function hasCycle(steps) {
+    const deps = new Map(steps.map((s) => [s.id, s.dependsOn ?? []]));
+    const state = new Map(); // 0=unseen,1=in-stack,2=done
+    const visit = (id) => {
+        if (state.get(id) === 1)
+            return true;
+        if (state.get(id) === 2)
+            return false;
+        state.set(id, 1);
+        for (const d of deps.get(id) ?? [])
+            if (deps.has(d) && visit(d))
+                return true;
+        state.set(id, 2);
+        return false;
+    };
+    return steps.some((s) => visit(s.id));
+}
+/** A topological execution order → array of "waves" (each wave's steps can run in parallel). */
+export function executionWaves(steps) {
+    const byId = new Map(steps.map((s) => [s.id, s]));
+    const remaining = new Set(steps.map((s) => s.id));
+    const done = new Set();
+    const waves = [];
+    while (remaining.size) {
+        const ready = [...remaining].filter((id) => (byId.get(id).dependsOn ?? []).every((d) => done.has(d) || !byId.has(d)));
+        if (ready.length === 0)
+            break; // cycle or dangling dep (validatePlan catches these)
+        waves.push(ready.map((id) => byId.get(id)));
+        for (const id of ready) {
+            remaining.delete(id);
+            done.add(id);
+        }
+    }
+    return waves;
+}

package/dist/orchestration/planner.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Planner — asks a model (via AI.run structured output) for a plan, then validates it references ONLY
+ * registered skills/tools. An unparseable or invalid plan is a planning failure, never something we
+ * execute. When nothing maps to the goal, the planner surfaces a clarification rather than guessing.
+ */
+import type { AI } from '../plugin/ai.js';
+import type { RoutingPreferences } from '../types.js';
+import type { Skill } from '../skills/skill.js';
+import type { ExecutionPlan } from './plan.js';
+export interface PlannerInput {
+    goal: string;
+    ai: AI;
+    skills: Skill[];
+    tools: string[];
+    version?: number;
+    reason?: string;
+    /** Observations from a prior attempt, to inform a replan. */
+    priorObservations?: string[];
+    /** User exclude/prefer routing applied to the planning model call. */
+    routing?: RoutingPreferences;
+}
+export interface PlannerResult {
+    plan?: ExecutionPlan;
+    /** Set when the planner needs the user to disambiguate or enable a capability. */
+    clarification?: string;
+    error?: string;
+}
+/** Generate and validate a plan for a goal. */
+export declare function generatePlan(input: PlannerInput): Promise<PlannerResult>;

package/dist/orchestration/planner.js

@@ -0,0 +1,69 @@
+/**
+ * Planner — asks a model (via AI.run structured output) for a plan, then validates it references ONLY
+ * registered skills/tools. An unparseable or invalid plan is a planning failure, never something we
+ * execute. When nothing maps to the goal, the planner surfaces a clarification rather than guessing.
+ */
+import { validatePlan } from './plan.js';
+function catalog(skills, tools) {
+    const skillLines = skills.map((s) => `  - skill "${s.id}": ${s.description}`).join('\n') || '  (none)';
+    const toolLines = tools.map((t) => `  - tool "${t}"`).join('\n') || '  (none)';
+    return `Available skills:\n${skillLines}\nAvailable tools:\n${toolLines}`;
+}
+/** Generate and validate a plan for a goal. */
+export async function generatePlan(input) {
+    if (input.skills.length === 0 && input.tools.length === 0) {
+        return { clarification: 'No skills or tools are available to act on this. Register a skill/tool or enable a skill pack.' };
+    }
+    const prompt = [
+        `Goal: ${input.goal}`,
+        input.priorObservations?.length ? `Prior attempt observations:\n${input.priorObservations.map((o) => `  - ${o}`).join('\n')}` : '',
+        catalog(input.skills, input.tools),
+        'Produce a minimal JSON plan: {"steps":[{"id","description","skill" OR "tool","input","dependsOn":[ids]}]}.',
+        'Use ONLY the skills/tools listed above. If nothing fits, return {"steps":[],"clarification":"<question>"}.',
+    ]
+        .filter(Boolean)
+        .join('\n\n');
+    const run = await input.ai.run({
+        task: 'plan',
+        input: prompt,
+        output: { format: 'json' },
+        requirements: { intelligence: ['planning', 'reasoning'], output: ['json'] },
+        ...(input.routing ? { routing: input.routing } : {}),
+    });
+    if (!run.ok)
+        return { error: `planner run failed: ${run.error?.category ?? 'unknown'}` };
+    const json = run.response?.json;
+    if (!json || !Array.isArray(json.steps))
+        return { error: 'planner did not return a valid plan object' };
+    // A clarification always wins — never build a guessed plan when the model asked a question.
+    if (typeof json.clarification === 'string' && json.clarification.trim())
+        return { clarification: json.clarification };
+    // Every step must be a non-null object; anything else is a malformed plan (fail cleanly, never crash).
+    if (json.steps.some((s) => s === null || typeof s !== 'object' || Array.isArray(s)))
+        return { error: 'planner returned a malformed step' };
+    const rawSteps = json.steps;
+    const steps = rawSteps.map((s, i) => ({
+        id: s.id && typeof s.id === 'string' ? s.id : `auto${i + 1}`,
+        description: s.description ?? '',
+        ...(s.skill ? { skill: s.skill } : {}),
+        ...(s.tool ? { tool: s.tool } : {}),
+        ...(s.input !== undefined ? { input: s.input } : {}),
+        ...(Array.isArray(s.dependsOn) ? { dependsOn: s.dependsOn } : {}),
+        status: 'pending',
+    }));
+    const plan = {
+        id: `plan_${input.version ?? 1}`,
+        goal: input.goal,
+        version: input.version ?? 1,
+        steps,
+        ...(input.reason ? { reason: input.reason } : {}),
+    };
+    const validation = validatePlan(plan, { skills: input.skills.map((s) => s.id), tools: input.tools });
+    if (!validation.ok) {
+        // Empty plan with no steps → treat as "nothing to do / needs clarification" rather than a hard error.
+        if (steps.length === 0)
+            return { clarification: 'I could not form a plan for this goal. Can you clarify what you want done?' };
+        return { error: `invalid plan: ${validation.errors.join('; ')}` };
+    }
+    return { plan };
+}

package/dist/plugin/ai.d.ts

@@ -0,0 +1,82 @@
+/**
+ * The AI facade — the ONE public interface. Callers name a task and get a normalized result; they
+ * never touch a provider directly. Providers are pluggable: registered programmatically here, or
+ * built from config. No method ever returns an API key.
+ */
+import { ProviderRegistry } from '../core/registry/registry.js';
+import type { TelemetrySink } from '../telemetry/telemetry.js';
+import { PerformanceStore } from '../learning/performanceStore.js';
+import type { ProbeName, ProbeReport } from '../probing/probe.js';
+import type { AIProvider } from '../providers/provider.js';
+import type { FetchLike } from '../providers/httpClient.js';
+import type { McpToolSource } from '../mcp/mcp.js';
+import type { GenerateOptions } from '../generation/generateAdapter.js';
+import type { OpenApiAnalysis } from '../discovery/openapi.js';
+import type { Clock } from '../util/clock.js';
+import type { HealthStatus, ProviderConfig, ProviderMetadata, RouterConfig, RunRequest, RunResult, TaskDefinition, TelemetryEvent, ToolSpec } from '../types.js';
+export interface AIOptions {
+    /** Inject a fetch implementation for offline tests of real adapters. */
+    fetchImpl?: FetchLike;
+    /** Inject a clock for deterministic timing in tests. */
+    clock?: Clock;
+    /** Override the environment used to resolve credentials (defaults to process.env). */
+    env?: NodeJS.ProcessEnv;
+    /** Extra telemetry sinks for centralized observability (e.g. a collector exporter). */
+    sinks?: TelemetrySink[];
+}
+/** A key-free view of a registered provider — safe to return from the public API. */
+export interface ProviderInfo {
+    id: string;
+    name: string;
+    kind: AIProvider['kind'];
+    privacyClass: AIProvider['privacyClass'];
+    enabled: boolean;
+}
+export declare class AI {
+    private readonly config;
+    private readonly registry;
+    private readonly tasks;
+    private readonly telemetry;
+    private readonly health;
+    private readonly performance?;
+    private readonly overlay;
+    private readonly mcp;
+    private readonly buildOpts;
+    private readonly router;
+    constructor(config?: RouterConfig, options?: AIOptions);
+    /** Build an AI from a local config file/path or a remote http(s) URL. */
+    static load(pathOrUrl?: string, options?: AIOptions): Promise<AI>;
+    /** Register a provider instance (pluggable adapter). Chainable. */
+    registerProvider(provider: AIProvider, enabled?: boolean): this;
+    /** Register or override a task definition (the QA Brain extension seam). Chainable. */
+    registerTask(def: TaskDefinition): this;
+    run(request: RunRequest): Promise<RunResult>;
+    /** Register an MCP tool source. Its tools are offered to the selected model on `mcp` runs. */
+    registerMcpSource(source: McpToolSource): this;
+    /** Aggregate tools across registered MCP sources (namespaced by source id). */
+    mcpTools(): Promise<ToolSpec[]>;
+    /** Add a provider from the marketplace preset catalog. */
+    addPreset(presetId: string, overrides?: Partial<ProviderConfig>, enabled?: boolean): this;
+    /**
+     * Dynamic adapter generation: build and register a provider from an OpenAPI analysis
+     * or spec file. Only CONFIG is generated (validated), never code — so it is safe by construction.
+     */
+    registerFromOpenApi(specPathOrAnalysis: string | OpenApiAnalysis, overrides?: GenerateOptions, enabled?: boolean): AIProvider;
+    /** Key-free provider listing. */
+    providers(): ProviderInfo[];
+    tasksList(): TaskDefinition[];
+    telemetryEvents(): TelemetryEvent[];
+    /** Run each provider's healthCheck(), seed the monitor, and return the statuses (for `doctor`). */
+    checkHealth(): Promise<HealthStatus[]>;
+    /** Discover provider identity, models, and capabilities (for `providers`/`models`/`capabilities`). */
+    discover(): Promise<ProviderMetadata[]>;
+    /** Observed per-(task,provider,model) performance the learning layer has accumulated. */
+    performanceSnapshot(): ReturnType<PerformanceStore['snapshot']>;
+    /**
+     * Opt-in capability probing. Runs minimal probes against a model and applies any VERIFIED
+     * results to the routing overlay so later runs trust them. Costs tokens — call deliberately.
+     */
+    probe(providerId: string, model: string, which?: ProbeName[]): Promise<ProbeReport>;
+    /** Internal accessor for tools that operate over the same registry (benchmark, verification). */
+    get registryRef(): ProviderRegistry;
+}

package/dist/plugin/ai.js

@@ -0,0 +1,167 @@
+/**
+ * The AI facade — the ONE public interface. Callers name a task and get a normalized result; they
+ * never touch a provider directly. Providers are pluggable: registered programmatically here, or
+ * built from config. No method ever returns an API key.
+ */
+import { Router } from '../core/router/router.js';
+import { ProviderRegistry } from '../core/registry/registry.js';
+import { TaskRegistry } from '../core/registry/taskRegistry.js';
+import { resolveConfig } from '../config/defaults.js';
+import { loadConfigAsync } from '../config/load.js';
+import { MemorySink, MultiSink } from '../telemetry/telemetry.js';
+import { FileSink } from '../telemetry/sinks/file.js';
+import { HealthMonitor } from '../core/health/monitor.js';
+import { PerformanceStore } from '../learning/performanceStore.js';
+import { CapabilityOverlay } from '../core/capabilities/overlay.js';
+import { probeModel, ALL_PROBES } from '../probing/probe.js';
+import { buildProvider } from '../providers/factory.js';
+import { McpRegistry } from '../mcp/mcp.js';
+import { presetToConfig } from '../marketplace/presets.js';
+import { generateProviderConfig, generateProviderConfigFromFile } from '../generation/generateAdapter.js';
+export class AI {
+    config;
+    registry = new ProviderRegistry();
+    tasks;
+    telemetry;
+    health;
+    performance;
+    overlay = new CapabilityOverlay();
+    mcp = new McpRegistry();
+    buildOpts;
+    router;
+    constructor(config = { providers: [] }, options = {}) {
+        this.config = resolveConfig(config);
+        this.tasks = new TaskRegistry(this.config.tasks);
+        const memory = new MemorySink();
+        const sinks = [memory];
+        if (this.config.telemetry.enabled && this.config.telemetry.sink === 'file' && this.config.telemetry.path)
+            sinks.push(new FileSink(this.config.telemetry.path));
+        if (options.sinks)
+            sinks.push(...options.sinks);
+        this.telemetry = sinks.length > 1 ? new MultiSink(sinks) : memory;
+        this.health = new HealthMonitor(this.telemetry, options.clock);
+        if (this.config.learning.enabled)
+            this.performance = new PerformanceStore();
+        this.router = new Router({
+            registry: this.registry,
+            tasks: this.tasks,
+            config: this.config,
+            telemetry: this.telemetry,
+            health: this.health,
+            overlay: this.overlay,
+            ...(this.performance ? { performance: this.performance } : {}),
+            ...(options.clock ? { clock: options.clock } : {}),
+        });
+        // Build concrete adapters from config (credential resolved from the env-var NAME). Providers of
+        // kind 'mock' are registered programmatically instead.
+        this.buildOpts = {
+            ...(options.fetchImpl ? { fetchImpl: options.fetchImpl } : {}),
+            ...(options.clock ? { clock: options.clock } : {}),
+            ...(options.env ? { env: options.env } : {}),
+        };
+        for (const providerCfg of this.config.providers) {
+            if (providerCfg.kind === 'mock')
+                continue;
+            const provider = buildProvider(providerCfg, this.buildOpts);
+            this.registry.register(provider, providerCfg.enabled ?? true);
+        }
+    }
+    /** Build an AI from a local config file/path or a remote http(s) URL. */
+    static async load(pathOrUrl, options = {}) {
+        return new AI(await loadConfigAsync(pathOrUrl), options);
+    }
+    /** Register a provider instance (pluggable adapter). Chainable. */
+    registerProvider(provider, enabled = true) {
+        this.registry.register(provider, enabled);
+        return this;
+    }
+    /** Register or override a task definition (the QA Brain extension seam). Chainable. */
+    registerTask(def) {
+        this.tasks.register(def);
+        return this;
+    }
+    async run(request) {
+        // Attach MCP tools when requested and sources exist (MCP = tool/context layer, not a provider).
+        if (request.mcp && this.mcp.list().length > 0) {
+            const tools = [...(request.tools ?? []), ...(await this.mcp.allTools())];
+            return this.router.run({ ...request, tools });
+        }
+        return this.router.run(request);
+    }
+    /** Register an MCP tool source. Its tools are offered to the selected model on `mcp` runs. */
+    registerMcpSource(source) {
+        this.mcp.register(source);
+        return this;
+    }
+    /** Aggregate tools across registered MCP sources (namespaced by source id). */
+    mcpTools() {
+        return this.mcp.allTools();
+    }
+    /** Add a provider from the marketplace preset catalog. */
+    addPreset(presetId, overrides = {}, enabled = true) {
+        const cfg = presetToConfig(presetId, overrides);
+        this.registry.register(buildProvider(cfg, this.buildOpts), enabled);
+        return this;
+    }
+    /**
+     * Dynamic adapter generation: build and register a provider from an OpenAPI analysis
+     * or spec file. Only CONFIG is generated (validated), never code — so it is safe by construction.
+     */
+    registerFromOpenApi(specPathOrAnalysis, overrides = {}, enabled = true) {
+        const cfg = typeof specPathOrAnalysis === 'string' ? generateProviderConfigFromFile(specPathOrAnalysis, overrides) : generateProviderConfig(specPathOrAnalysis, overrides);
+        const provider = buildProvider(cfg, this.buildOpts);
+        this.registry.register(provider, enabled);
+        return provider;
+    }
+    /** Key-free provider listing. */
+    providers() {
+        return this.registry.all().map((p) => ({
+            id: p.id,
+            name: p.name,
+            kind: p.kind,
+            privacyClass: p.privacyClass,
+            enabled: this.registry.isEnabled(p.id),
+        }));
+    }
+    tasksList() {
+        return this.tasks.list();
+    }
+    telemetryEvents() {
+        return this.telemetry.events?.() ?? [];
+    }
+    /** Run each provider's healthCheck(), seed the monitor, and return the statuses (for `doctor`). */
+    async checkHealth() {
+        const out = [];
+        for (const provider of this.registry.all()) {
+            const status = await provider.healthCheck();
+            this.health.seed(status);
+            out.push(status);
+        }
+        return out;
+    }
+    /** Discover provider identity, models, and capabilities (for `providers`/`models`/`capabilities`). */
+    async discover() {
+        return Promise.all(this.registry.all().map((p) => p.discover()));
+    }
+    /** Observed per-(task,provider,model) performance the learning layer has accumulated. */
+    performanceSnapshot() {
+        return this.performance?.snapshot() ?? [];
+    }
+    /**
+     * Opt-in capability probing. Runs minimal probes against a model and applies any VERIFIED
+     * results to the routing overlay so later runs trust them. Costs tokens — call deliberately.
+     */
+    async probe(providerId, model, which = ALL_PROBES) {
+        const provider = this.registry.get(providerId);
+        if (!provider)
+            throw new Error(`unknown provider '${providerId}'`);
+        const report = await probeModel(provider, model, which);
+        if (report.results.some((r) => r.status === 'verified'))
+            this.overlay.set(providerId, model, report.profile);
+        return report;
+    }
+    /** Internal accessor for tools that operate over the same registry (benchmark, verification). */
+    get registryRef() {
+        return this.registry;
+    }
+}

package/dist/probing/probe.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Capability probing. Runs minimal, controlled requests against a real model to VERIFY
+ * capabilities the catalog only documents. Opt-in (it costs tokens), minimal, and it never sends
+ * secrets or proprietary data — only tiny synthetic prompts. A positive probe promotes a capability to
+ * `verified`; a failure is inconclusive and changes nothing (never a silent demotion of documented).
+ */
+import type { AIProvider } from '../providers/provider.js';
+import type { CapabilityProfile } from '../types.js';
+export type ProbeName = 'text' | 'structured_output' | 'tool_calling';
+export interface ProbeResult {
+    probe: ProbeName;
+    group: 'input' | 'output' | 'intelligence' | 'agent';
+    key: string;
+    status: 'verified' | 'inconclusive';
+    detail?: string;
+}
+export interface ProbeReport {
+    providerId: string;
+    model: string;
+    results: ProbeResult[];
+    /** The verified capabilities as a profile, ready to merge into an overlay. */
+    profile: CapabilityProfile;
+}
+export declare const ALL_PROBES: ProbeName[];
+export declare function probeModel(provider: AIProvider, model: string, which?: ProbeName[]): Promise<ProbeReport>;

package/dist/probing/probe.js

@@ -0,0 +1,63 @@
+/**
+ * Capability probing. Runs minimal, controlled requests against a real model to VERIFY
+ * capabilities the catalog only documents. Opt-in (it costs tokens), minimal, and it never sends
+ * secrets or proprietary data — only tiny synthetic prompts. A positive probe promotes a capability to
+ * `verified`; a failure is inconclusive and changes nothing (never a silent demotion of documented).
+ */
+import { emptyProfile } from '../core/capabilities/evidence.js';
+const baseRequest = (model, over) => ({
+    taskId: 'probe',
+    model,
+    input: { text: 'ping' },
+    timeoutMs: 20_000,
+    sensitivity: 'low',
+    params: { maxTokens: 64 },
+    ...over,
+});
+export const ALL_PROBES = ['text', 'structured_output', 'tool_calling'];
+export async function probeModel(provider, model, which = ALL_PROBES) {
+    const results = [];
+    const profile = emptyProfile();
+    const verify = (group, key) => {
+        const bucket = profile[group];
+        bucket[key] = { value: true, evidence: 'verified' };
+    };
+    for (const probe of which) {
+        try {
+            if (probe === 'text') {
+                const res = await provider.execute(baseRequest(model, { input: { text: 'Reply with the single word: ok' } }));
+                const ok = Boolean(res.text && res.text.trim());
+                results.push({ probe, group: 'output', key: 'text', status: ok ? 'verified' : 'inconclusive' });
+                if (ok) {
+                    verify('output', 'text');
+                    verify('input', 'text');
+                }
+            }
+            else if (probe === 'structured_output') {
+                const res = await provider.execute(baseRequest(model, { input: { text: 'Return JSON {"probe": true}' }, output: { format: 'json' } }));
+                const ok = res.json !== undefined;
+                results.push({ probe, group: 'output', key: 'structured_output', status: ok ? 'verified' : 'inconclusive' });
+                if (ok) {
+                    verify('output', 'json');
+                    verify('output', 'structured_output');
+                }
+            }
+            else if (probe === 'tool_calling') {
+                const res = await provider.execute(baseRequest(model, {
+                    input: { text: 'Call the ping tool.' },
+                    tools: [{ name: 'ping', description: 'returns pong', parameters: { type: 'object', properties: {} } }],
+                }));
+                const ok = Boolean(res.toolCalls && res.toolCalls.length > 0 && res.toolCalls.some((c) => c.name === 'ping'));
+                results.push({ probe, group: 'agent', key: 'tool_calling', status: ok ? 'verified' : 'inconclusive' });
+                if (ok) {
+                    verify('agent', 'tool_calling');
+                    verify('agent', 'function_calling');
+                }
+            }
+        }
+        catch (e) {
+            results.push({ probe, group: 'output', key: probe, status: 'inconclusive', detail: e instanceof Error ? e.name : 'error' });
+        }
+    }
+    return { providerId: provider.id, model, results, profile };
+}

package/dist/providers/factory.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Build a concrete provider from a ProviderConfig. This is the seam that makes providers pluggable by
+ * CONFIG: pick vendor defaults, resolve the credential from the env-var NAME, resolve model metadata
+ * from the catalog + operator-declared capabilities, and hand it all to the one HttpProvider class.
+ * No routing code changes when a provider is added.
+ *
+ * SECURITY: config may carry only an env-var NAME (`apiKeyEnv`), never a raw key — validated here.
+ */
+import type { AIProvider } from './provider.js';
+import type { ProviderConfig } from '../types.js';
+import type { FetchLike } from './httpClient.js';
+import type { Clock } from '../util/clock.js';
+export interface BuildOptions {
+    fetchImpl?: FetchLike;
+    clock?: Clock;
+    env?: NodeJS.ProcessEnv;
+}
+export declare function buildProvider(cfg: ProviderConfig, opts?: BuildOptions): AIProvider;

package/dist/providers/factory.js

@@ -0,0 +1,54 @@
+/**
+ * Build a concrete provider from a ProviderConfig. This is the seam that makes providers pluggable by
+ * CONFIG: pick vendor defaults, resolve the credential from the env-var NAME, resolve model metadata
+ * from the catalog + operator-declared capabilities, and hand it all to the one HttpProvider class.
+ * No routing code changes when a provider is added.
+ *
+ * SECURITY: config may carry only an env-var NAME (`apiKeyEnv`), never a raw key — validated here.
+ */
+import { AIError } from '../core/fallback/errors.js';
+import { Credential } from '../security/credentials.js';
+import { PROVIDER_DEFAULTS } from '../config/providerDefaults.js';
+import { resolveModelMetadata } from '../discovery/modelCatalog.js';
+import { HttpProvider } from './httpProvider.js';
+const KEY_LIKE = /^(sk-|gsk_|Bearer\s|[A-Za-z0-9_-]{40,}$)/;
+export function buildProvider(cfg, opts = {}) {
+    if (cfg.kind === 'mock') {
+        throw new AIError(`provider '${cfg.id}': kind 'mock' cannot be built from config — register it programmatically`, { category: 'CONFIG' });
+    }
+    const def = PROVIDER_DEFAULTS[cfg.kind];
+    const baseUrl = cfg.baseUrl ?? def.baseUrl;
+    if (!baseUrl) {
+        throw new AIError(`provider '${cfg.id}' (${cfg.kind}) requires a baseUrl`, { category: 'CONFIG' });
+    }
+    const apiKeyEnv = cfg.apiKeyEnv ?? def.apiKeyEnv;
+    if (apiKeyEnv && KEY_LIKE.test(apiKeyEnv)) {
+        throw new AIError(`provider '${cfg.id}': apiKeyEnv must be an env-var NAME, not a key value`, { category: 'CONFIG' });
+    }
+    const credential = new Credential(apiKeyEnv, opts.env);
+    const privacyClass = cfg.privacyClass ?? def.privacyClass;
+    const wireShape = cfg.wireShape ?? def.wireShape;
+    const modelIds = Array.isArray(cfg.models) && cfg.models.length > 0
+        ? cfg.models
+        : cfg.defaultModel
+            ? [cfg.defaultModel]
+            : def.defaultModels;
+    const models = modelIds.map((id) => resolveModelMetadata(cfg.id, cfg.kind, id, cfg.capabilities));
+    const config = {
+        id: cfg.id,
+        name: def.name,
+        kind: cfg.kind,
+        wireShape,
+        baseUrl,
+        credential,
+        privacyClass,
+        models,
+        requiresKey: def.requiresKey,
+        supportsModelListing: def.supportsModelListing,
+        ...(cfg.defaultModel ? { defaultModel: cfg.defaultModel } : modelIds[0] ? { defaultModel: modelIds[0] } : {}),
+        ...(cfg.headers ? { headers: cfg.headers } : {}),
+        ...(opts.fetchImpl ? { fetchImpl: opts.fetchImpl } : {}),
+        ...(opts.clock ? { clock: opts.clock } : {}),
+    };
+    return new HttpProvider(config);
+}

package/dist/providers/httpClient.d.ts

@@ -0,0 +1,34 @@
+/**
+ * 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 type { Clock } from '../util/clock.js';
+import type { WireRequest } from './wire/types.js';
+export type FetchLike = typeof fetch;
+export interface CallHttpInput {
+    build: (jsonMode: boolean) => WireRequest;
+    providerId: string;
+    model: string;
+    timeoutMs: number;
+    maxRetries: number;
+    jsonMode: boolean;
+    fetchImpl?: FetchLike;
+    clock?: Clock;
+    onJsonModeDisabled?: () => void;
+}
+export interface CallHttpResult {
+    status: number;
+    json: unknown;
+    durationMs: number;
+    attempts: number;
+    jsonModeUsed: boolean;
+}
+export declare function callHttp(input: CallHttpInput): Promise<CallHttpResult>;