ai-runtime-engine 1.1.0

package/dist/discovery/modelCatalog.js

@@ -0,0 +1,105 @@
+/**
+ * Hand-curated, `documented`-tier facts for well-known models. This is the ONLY place vendor model
+ * knowledge lives, and it is in the discovery layer — providers call `resolveModelMetadata`, `core/`
+ * never imports this. A model with no catalog entry and no operator-declared capabilities resolves to
+ * an all-`unknown` profile (routable only via an explicit pin), honoring the never-promote rule.
+ */
+import { emptyProfile, mergeProfiles, profileFromDeclared } from '../core/capabilities/evidence.js';
+const TEXT_CODE = ['reasoning', 'code_generation', 'code_analysis', 'summarization', 'extraction', 'classification'];
+const TOOLS = ['tool_calling', 'function_calling'];
+/** Keyed by provider KIND so any provider of that kind benefits, then by model id. */
+const CATALOG = {
+    gemini: {
+        'gemini-3.6-flash': {
+            caps: { intelligence: [...TEXT_CODE, 'planning'], output: ['text', 'json', 'structured_output', 'code'], input: ['text', 'image', 'pdf', 'file'], agent: TOOLS },
+            contextWindow: 1_000_000,
+            pricing: { inputPerMTok: 0.15, outputPerMTok: 0.6, currency: 'USD' },
+            quality: { tier: 'strong' },
+            latencyP50Ms: 900,
+            successRate: 0.98,
+        },
+        'gemini-2.5-flash-lite': {
+            caps: { intelligence: TEXT_CODE, output: ['text', 'json', 'code'], input: ['text', 'image'], agent: TOOLS },
+            contextWindow: 1_000_000,
+            pricing: { inputPerMTok: 0.075, outputPerMTok: 0.3, currency: 'USD' },
+            quality: { tier: 'mid' },
+            latencyP50Ms: 600,
+            successRate: 0.97,
+        },
+    },
+    groq: {
+        'llama-3.3-70b': {
+            caps: { intelligence: TEXT_CODE, output: ['text', 'json', 'code'], input: ['text'], agent: TOOLS },
+            contextWindow: 128_000,
+            pricing: { inputPerMTok: 0.59, outputPerMTok: 0.79, currency: 'USD' },
+            quality: { tier: 'strong' },
+            latencyP50Ms: 300,
+            successRate: 0.97,
+        },
+    },
+    anthropic: {
+        'claude-sonnet-5': {
+            caps: { intelligence: [...TEXT_CODE, 'planning'], output: ['text', 'json', 'structured_output', 'code'], input: ['text', 'image', 'pdf'], agent: TOOLS },
+            contextWindow: 200_000,
+            maxOutputTokens: 64_000,
+            pricing: { inputPerMTok: 3, outputPerMTok: 15, currency: 'USD' },
+            quality: { tier: 'frontier' },
+            latencyP50Ms: 1500,
+            successRate: 0.99,
+        },
+        'claude-haiku-4-5': {
+            caps: { intelligence: TEXT_CODE, output: ['text', 'json', 'code'], input: ['text', 'image'], agent: TOOLS },
+            contextWindow: 200_000,
+            pricing: { inputPerMTok: 0.8, outputPerMTok: 4, currency: 'USD' },
+            quality: { tier: 'strong' },
+            latencyP50Ms: 700,
+            successRate: 0.98,
+        },
+    },
+    ollama: {
+        'llama3.1': {
+            caps: { intelligence: ['reasoning', 'code_generation', 'code_analysis', 'summarization'], output: ['text', 'json', 'code'], input: ['text'] },
+            contextWindow: 128_000,
+            quality: { tier: 'mid' },
+            latencyP50Ms: 3500,
+            successRate: 0.95,
+        },
+    },
+};
+export function lookupCatalog(kind, modelId) {
+    return CATALOG[kind]?.[modelId];
+}
+/**
+ * Build normalized ModelMetadata for one model by merging catalog facts with operator-declared
+ * capabilities (both `documented`). No source → all-`unknown` capabilities and `source: 'unknown'`.
+ */
+export function resolveModelMetadata(providerId, kind, modelId, declared, enabled = true) {
+    const entry = lookupCatalog(kind, modelId);
+    const hasFacts = Boolean(entry) || Boolean(declared);
+    const evidence = hasFacts ? 'documented' : 'unknown';
+    let capabilities = emptyProfile(entry?.contextWindow ?? declared?.contextWindow ?? 0);
+    if (entry)
+        capabilities = mergeProfiles(capabilities, profileFromDeclared({ ...entry.caps, contextWindow: entry.contextWindow }, 'documented'));
+    if (declared) {
+        capabilities = mergeProfiles(capabilities, profileFromDeclared({ input: declared.input, output: declared.output, intelligence: declared.intelligence, agent: declared.agent, contextWindow: declared.contextWindow }, 'documented'));
+    }
+    const model = { providerId, id: modelId, capabilities, enabled, source: evidence };
+    const contextWindow = entry?.contextWindow ?? declared?.contextWindow;
+    if (contextWindow !== undefined)
+        model.contextWindow = contextWindow;
+    if (entry?.maxOutputTokens !== undefined)
+        model.maxOutputTokens = entry.maxOutputTokens;
+    if (entry?.family !== undefined)
+        model.family = entry.family;
+    if (entry?.displayName !== undefined)
+        model.displayName = entry.displayName;
+    if (entry?.pricing !== undefined)
+        model.pricing = entry.pricing;
+    if (entry?.quality !== undefined)
+        model.quality = { evidence: 'documented', ...(entry.quality.tier !== undefined ? { tier: entry.quality.tier } : {}), ...(entry.quality.score !== undefined ? { score: entry.quality.score } : {}) };
+    if (entry?.latencyP50Ms !== undefined)
+        model.latency = { p50Ms: entry.latencyP50Ms, evidence: 'documented' };
+    if (entry?.successRate !== undefined)
+        model.reliability = { successRate: entry.successRate, evidence: 'documented' };
+    return model;
+}

package/dist/discovery/openapi.d.ts

@@ -0,0 +1,25 @@
+/**
+ * OpenAPI-based provider discovery. DETERMINISTIC inspection of an OpenAPI 3.x
+ * document to propose how an unknown provider maps onto the router. The spec is treated as EVIDENCE,
+ * not proof — a suggested config still requires the operator to confirm and to supply the key via an
+ * env var. No LLM and no secrets are involved (AI-assisted discovery is a later phase).
+ */
+import type { ProviderConfig } from '../types.js';
+export interface OpenApiEndpoint {
+    path: string;
+    methods: string[];
+}
+export interface OpenApiAnalysis {
+    title?: string;
+    version?: string;
+    baseUrl?: string;
+    authMode: 'bearer' | 'apiKey-header' | 'none' | 'unknown';
+    authHeaderName?: string;
+    wireShape: 'openai' | 'unknown';
+    chatEndpoint?: string;
+    endpoints: OpenApiEndpoint[];
+    suggestedProviderConfig?: ProviderConfig;
+    notes: string[];
+}
+export declare function analyzeOpenApi(spec: unknown): OpenApiAnalysis;
+export declare function analyzeOpenApiFile(path: string): OpenApiAnalysis;

package/dist/discovery/openapi.js

@@ -0,0 +1,76 @@
+/**
+ * OpenAPI-based provider discovery. DETERMINISTIC inspection of an OpenAPI 3.x
+ * document to propose how an unknown provider maps onto the router. The spec is treated as EVIDENCE,
+ * not proof — a suggested config still requires the operator to confirm and to supply the key via an
+ * env var. No LLM and no secrets are involved (AI-assisted discovery is a later phase).
+ */
+import { readFileSync } from 'node:fs';
+import { parse as parseYaml } from 'yaml';
+const CHAT_HINT = /(chat\/completions|\/completions|\/generate|\/v1\/messages)/i;
+const HTTP_METHODS = ['get', 'post', 'put', 'patch', 'delete'];
+export function analyzeOpenApi(spec) {
+    const doc = (spec ?? {});
+    const notes = [];
+    const baseUrl = doc.servers?.[0]?.url;
+    if (!baseUrl)
+        notes.push('No servers[].url found — baseUrl must be supplied manually.');
+    const endpoints = Object.entries(doc.paths ?? {}).map(([path, ops]) => ({
+        path,
+        methods: Object.keys(ops ?? {}).filter((m) => HTTP_METHODS.includes(m.toLowerCase())),
+    }));
+    const chat = endpoints.find((e) => CHAT_HINT.test(e.path));
+    const wireShape = chat && /chat\/completions/i.test(chat.path) ? 'openai' : 'unknown';
+    if (chat)
+        notes.push(`Detected a chat-like endpoint: ${chat.path}`);
+    else
+        notes.push('No chat/completions-style endpoint detected — a custom mapping may be required.');
+    // Auth scheme
+    let authMode = 'unknown';
+    let authHeaderName;
+    const schemes = doc.components?.securitySchemes ?? {};
+    for (const scheme of Object.values(schemes)) {
+        if (scheme.type === 'http' && scheme.scheme === 'bearer') {
+            authMode = 'bearer';
+            break;
+        }
+        if (scheme.type === 'apiKey' && scheme.in === 'header') {
+            authMode = 'apiKey-header';
+            authHeaderName = scheme.name;
+            break;
+        }
+        if (scheme.type === 'http' && scheme.scheme === 'none')
+            authMode = 'none';
+    }
+    if (authMode === 'unknown')
+        notes.push('Could not determine an auth scheme — set it in the provider config.');
+    const analysis = {
+        ...(doc.info?.title ? { title: doc.info.title } : {}),
+        ...(doc.info?.version ? { version: doc.info.version } : {}),
+        ...(baseUrl ? { baseUrl } : {}),
+        authMode,
+        ...(authHeaderName ? { authHeaderName } : {}),
+        wireShape,
+        ...(chat ? { chatEndpoint: chat.path } : {}),
+        endpoints,
+        notes,
+    };
+    // Suggest a config only when we found an OpenAI-compatible chat endpoint and a base URL.
+    if (wireShape === 'openai' && baseUrl) {
+        const base = baseUrl.replace(/\/chat\/completions$/i, '').replace(/\/+$/, '');
+        analysis.suggestedProviderConfig = {
+            id: 'openapi-provider',
+            kind: 'openai-compatible',
+            baseUrl: base,
+            apiKeyEnv: 'OPENAPI_PROVIDER_API_KEY',
+            wireShape: 'openai',
+            models: 'auto',
+        };
+        notes.push('Suggested an openai-compatible provider config — review it, set models, and supply the key via OPENAPI_PROVIDER_API_KEY.');
+    }
+    return analysis;
+}
+export function analyzeOpenApiFile(path) {
+    const text = readFileSync(path, 'utf8');
+    const raw = path.endsWith('.json') ? JSON.parse(text) : parseYaml(text);
+    return analyzeOpenApi(raw);
+}

package/dist/executions/checkpoint.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Checkpoint capture + reconciliation. A checkpoint fingerprints the workspace (git HEAD, hashes of
+ * files the plan touches, the runtime config, and the versions of the skills in play). On resume we
+ * recompute and compare: any difference is DRIFT, which forces a replan rather than blindly continuing.
+ */
+import type { Clock } from '../util/clock.js';
+import type { Skill } from '../skills/skill.js';
+import type { ExecutionPlan } from '../orchestration/plan.js';
+import type { Checkpoint } from './execution.js';
+/** git HEAD sha (resolving a symbolic ref), or undefined when not a repo. The ref path is jailed to
+ * `.git` so a crafted HEAD (`ref: ../../etc/x`) can't read outside the workspace. */
+export declare function gitHead(root: string): string | undefined;
+export interface CaptureInput {
+    root: string;
+    plan?: ExecutionPlan;
+    skills: Skill[];
+    completedSteps: string[];
+    clock?: Clock;
+}
+export declare function captureCheckpoint(input: CaptureInput): Checkpoint;
+export interface Reconciliation {
+    drifted: boolean;
+    reasons: string[];
+}
+/** Recompute the fingerprint and compare to a checkpoint. Any difference is drift. */
+export declare function reconcile(checkpoint: Checkpoint, root: string, skills: Skill[]): Reconciliation;

package/dist/executions/checkpoint.js

@@ -0,0 +1,114 @@
+/**
+ * Checkpoint capture + reconciliation. A checkpoint fingerprints the workspace (git HEAD, hashes of
+ * files the plan touches, the runtime config, and the versions of the skills in play). On resume we
+ * recompute and compare: any difference is DRIFT, which forces a replan rather than blindly continuing.
+ */
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { systemClock } from '../util/clock.js';
+import { resolveInJail } from '../tools/jail.js';
+function sha(text) {
+    return createHash('sha256').update(text).digest('hex').slice(0, 16);
+}
+/** git HEAD sha (resolving a symbolic ref), or undefined when not a repo. The ref path is jailed to
+ * `.git` so a crafted HEAD (`ref: ../../etc/x`) can't read outside the workspace. */
+export function gitHead(root) {
+    const gitDir = join(root, '.git');
+    const headPath = join(gitDir, 'HEAD');
+    if (!existsSync(headPath))
+        return undefined;
+    try {
+        const head = readFileSync(headPath, 'utf8').trim();
+        const m = /^ref:\s*(.+)$/.exec(head);
+        if (!m)
+            return head; // detached HEAD → raw sha
+        const ref = m[1].trim();
+        // Reject a ref that isn't a plain in-.git path (no absolute, no traversal).
+        if (ref.startsWith('/') || ref.includes('..') || ref.includes('\0'))
+            return head;
+        const refPath = resolveInJail(gitDir, ref);
+        return existsSync(refPath) ? readFileSync(refPath, 'utf8').trim() : head;
+    }
+    catch {
+        return undefined;
+    }
+}
+function hashFile(root, rel) {
+    try {
+        const abs = resolveInJail(root, rel);
+        return existsSync(abs) ? sha(readFileSync(abs, 'utf8')) : '∅'; // absent → a distinct, comparable marker
+    }
+    catch {
+        return '∅';
+    }
+}
+/** Files the plan touches (step inputs with a string `path`), plus the config, are fingerprinted. */
+function planPaths(plan) {
+    const paths = new Set();
+    for (const step of plan?.steps ?? []) {
+        const input = step.input;
+        if (input && typeof input.path === 'string')
+            paths.add(input.path);
+    }
+    return [...paths];
+}
+function configHash(root) {
+    for (const rel of ['.ai-runtime/config.yaml', '.ai-runtime/config.yml', 'ai-runtime.yaml']) {
+        const abs = join(root, rel);
+        if (existsSync(abs)) {
+            try {
+                return sha(readFileSync(abs, 'utf8'));
+            }
+            catch {
+                return undefined;
+            }
+        }
+    }
+    return undefined;
+}
+export function captureCheckpoint(input) {
+    const clock = input.clock ?? systemClock;
+    const fileHashes = {};
+    for (const p of planPaths(input.plan))
+        fileHashes[p] = hashFile(input.root, p);
+    const skillVersions = {};
+    for (const s of input.skills)
+        skillVersions[s.id] = s.version;
+    const head = gitHead(input.root);
+    const cfg = configHash(input.root);
+    return {
+        at: clock.now(),
+        planVersion: input.plan?.version ?? 0,
+        ...(head !== undefined ? { gitHead: head } : {}),
+        fileHashes,
+        ...(cfg !== undefined ? { configHash: cfg } : {}),
+        skillVersions,
+        completedSteps: [...input.completedSteps],
+    };
+}
+/** Recompute the fingerprint and compare to a checkpoint. Any difference is drift. */
+export function reconcile(checkpoint, root, skills) {
+    const reasons = [];
+    // Compare directly so an ADDITION (absent at capture, present now — e.g. git initialized, config
+    // added) also counts as drift, not just a change to something already captured.
+    const head = gitHead(root);
+    if (checkpoint.gitHead !== head)
+        reasons.push(`git HEAD changed (${checkpoint.gitHead ?? 'none'} → ${head ?? 'none'})`);
+    const cfg = configHash(root);
+    if (checkpoint.configHash !== cfg)
+        reasons.push('runtime config changed');
+    for (const [rel, hash] of Object.entries(checkpoint.fileHashes)) {
+        if (hashFile(root, rel) !== hash)
+            reasons.push(`file changed: ${rel}`);
+    }
+    const versions = new Map(skills.map((s) => [s.id, s.version]));
+    for (const [id, ver] of Object.entries(checkpoint.skillVersions)) {
+        const cur = versions.get(id);
+        if (cur === undefined)
+            reasons.push(`skill ${id} was removed`);
+        else if (cur !== ver)
+            reasons.push(`skill ${id} version changed (${ver} → ${cur})`);
+    }
+    return { drifted: reasons.length > 0, reasons };
+}

package/dist/executions/execution.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Execution — a persistent, resumable unit of orchestration work. It carries the plan, per-step
+ * progress, observations, artifacts, checkpoints, and a best-effort LEASE that keeps two owners from
+ * running the same execution (heartbeat-renewed while running; not a hard OS mutex — see store.ts).
+ * Waiting states (approval / clarification) persist across process exit and resume on answer.
+ */
+import type { ExecutionPlan } from '../orchestration/plan.js';
+import type { StepObservation } from '../orchestration/executor.js';
+import type { ArtifactRef } from '../runtime/types.js';
+export type ExecutionStatus = 'planned' | 'running' | 'paused' | 'waiting_for_input' | 'waiting_for_clarification' | 'completed' | 'failed' | 'cancelled';
+/** A time-boxed claim on an execution by one process. */
+export interface Lease {
+    owner: string;
+    heartbeatAt: number;
+    expiresAt: number;
+}
+/** A fingerprint of the workspace at a point in time, used to detect drift on resume. */
+export interface Checkpoint {
+    at: number;
+    planVersion: number;
+    gitHead?: string;
+    fileHashes: Record<string, string>;
+    configHash?: string;
+    skillVersions: Record<string, string>;
+    completedSteps: string[];
+}
+/** What an execution is waiting for (approval or clarification), persisted so a restart can resume it. */
+export interface PendingInput {
+    kind: 'approval' | 'clarification';
+    question?: string;
+    action?: string;
+}
+export interface Execution {
+    id: string;
+    requestId?: string;
+    goal: string;
+    mode: string;
+    planVersion: number;
+    plan?: ExecutionPlan;
+    status: ExecutionStatus;
+    completedSteps: string[];
+    observations: StepObservation[];
+    artifacts: ArtifactRef[];
+    checkpoints: Checkpoint[];
+    pending?: PendingInput;
+    createdAt: number;
+    updatedAt: number;
+    lease?: Lease;
+}
+export declare const RESUMABLE: ReadonlySet<ExecutionStatus>;
+export declare const TERMINAL: ReadonlySet<ExecutionStatus>;

package/dist/executions/execution.js

@@ -0,0 +1,8 @@
+/**
+ * Execution — a persistent, resumable unit of orchestration work. It carries the plan, per-step
+ * progress, observations, artifacts, checkpoints, and a best-effort LEASE that keeps two owners from
+ * running the same execution (heartbeat-renewed while running; not a hard OS mutex — see store.ts).
+ * Waiting states (approval / clarification) persist across process exit and resume on answer.
+ */
+export const RESUMABLE = new Set(['planned', 'running', 'paused', 'waiting_for_input', 'waiting_for_clarification']);
+export const TERMINAL = new Set(['completed', 'failed', 'cancelled']);

package/dist/executions/store.d.ts

@@ -0,0 +1,52 @@
+/**
+ * ExecutionStore — persists executions and coordinates owners via a BEST-EFFORT lease. A live lease
+ * held by another owner blocks acquisition; an expired lease is stolen (process-death recovery);
+ * `commit` refuses to overwrite an execution a live different owner holds; `acquire` re-reads after
+ * writing to detect a lost race. This narrows — but on a shared filesystem does not fully eliminate —
+ * concurrent access (there is no OS file lock; a true hard mutex is post-1.0). Long runs must heartbeat
+ * to keep the lease alive. Idempotency: a requestId maps to one execution (reserve it under the store
+ * lock before running).
+ */
+import type { Clock } from '../util/clock.js';
+import type { Area } from '../store/area.js';
+import type { Execution, ExecutionStatus } from './execution.js';
+export interface ExecutionStoreOptions {
+    clock?: Clock;
+    owner?: string;
+    heartbeatMs?: number;
+    expiryMs?: number;
+}
+export interface AcquireResult {
+    ok: boolean;
+    execution?: Execution;
+    reason?: string;
+}
+export declare class ExecutionStore {
+    private readonly area;
+    readonly owner: string;
+    private readonly clock;
+    private readonly expiryMs;
+    readonly heartbeatMs: number;
+    private counter;
+    constructor(area: Area, options?: ExecutionStoreOptions);
+    get enabled(): boolean;
+    private nextId;
+    /** Create + persist a new execution (owned by this store). */
+    create(fields: Omit<Execution, 'id' | 'createdAt' | 'updatedAt' | 'completedSteps' | 'observations' | 'artifacts' | 'checkpoints'> & Partial<Pick<Execution, 'completedSteps' | 'observations' | 'artifacts' | 'checkpoints'>>): Execution;
+    save(exec: Execution): void;
+    get(id: string): Execution | undefined;
+    list(): Execution[];
+    /** Idempotency: find an existing execution for a caller requestId. */
+    byRequestId(requestId: string): Execution | undefined;
+    private leaseLive;
+    /** Claim an execution. Fails if a DIFFERENT owner holds a live lease; steals an expired one. Re-reads
+     * after writing to detect losing a concurrent steal (best-effort — no OS lock). */
+    acquire(id: string): AcquireResult;
+    /** Write only if we still hold the lease (or it's free/expired) — never clobber a live different owner. */
+    commit(exec: Execution): boolean;
+    /** Renew this owner's lease. Returns false if we no longer hold it. */
+    heartbeat(id: string): boolean;
+    release(id: string): void;
+    setStatus(id: string, status: ExecutionStatus): void;
+    delete(id: string): void;
+}

package/dist/executions/store.js

@@ -0,0 +1,124 @@
+/**
+ * ExecutionStore — persists executions and coordinates owners via a BEST-EFFORT lease. A live lease
+ * held by another owner blocks acquisition; an expired lease is stolen (process-death recovery);
+ * `commit` refuses to overwrite an execution a live different owner holds; `acquire` re-reads after
+ * writing to detect a lost race. This narrows — but on a shared filesystem does not fully eliminate —
+ * concurrent access (there is no OS file lock; a true hard mutex is post-1.0). Long runs must heartbeat
+ * to keep the lease alive. Idempotency: a requestId maps to one execution (reserve it under the store
+ * lock before running).
+ */
+import { hostname } from 'node:os';
+import { systemClock } from '../util/clock.js';
+export class ExecutionStore {
+    area;
+    owner;
+    clock;
+    expiryMs;
+    heartbeatMs;
+    counter = 0;
+    constructor(area, options = {}) {
+        this.area = area;
+        this.clock = options.clock ?? systemClock;
+        this.expiryMs = options.expiryMs ?? 60_000;
+        this.heartbeatMs = options.heartbeatMs ?? 15_000;
+        this.owner = options.owner ?? `${hostname()}:${process.pid}:${Math.random().toString(36).slice(2, 8)}`;
+    }
+    get enabled() {
+        return this.area.enabled;
+    }
+    nextId() {
+        return `exec_${this.clock.now().toString(36)}_${process.pid.toString(36)}_${(this.counter += 1).toString(36)}`;
+    }
+    /** Create + persist a new execution (owned by this store). */
+    create(fields) {
+        const now = this.clock.now();
+        const exec = {
+            id: this.nextId(),
+            completedSteps: [],
+            observations: [],
+            artifacts: [],
+            checkpoints: [],
+            ...fields,
+            createdAt: now,
+            updatedAt: now,
+            lease: { owner: this.owner, heartbeatAt: now, expiresAt: now + this.expiryMs },
+        };
+        this.area.writeJson(exec.id, exec);
+        return exec;
+    }
+    save(exec) {
+        exec.updatedAt = this.clock.now();
+        this.area.writeJson(exec.id, exec);
+    }
+    get(id) {
+        return this.area.tryReadJson(id);
+    }
+    list() {
+        return this.area
+            .listIds()
+            .map((id) => this.area.tryReadJson(id))
+            .filter((e) => e !== undefined)
+            .sort((a, b) => b.updatedAt - a.updatedAt);
+    }
+    /** Idempotency: find an existing execution for a caller requestId. */
+    byRequestId(requestId) {
+        return this.list().find((e) => e.requestId === requestId);
+    }
+    leaseLive(exec, now) {
+        return !!exec.lease && exec.lease.expiresAt > now;
+    }
+    /** Claim an execution. Fails if a DIFFERENT owner holds a live lease; steals an expired one. Re-reads
+     * after writing to detect losing a concurrent steal (best-effort — no OS lock). */
+    acquire(id) {
+        const exec = this.get(id);
+        if (!exec)
+            return { ok: false, reason: 'not found' };
+        const now = this.clock.now();
+        if (this.leaseLive(exec, now) && exec.lease.owner !== this.owner) {
+            return { ok: false, reason: `held by ${exec.lease.owner} until ${exec.lease.expiresAt}` };
+        }
+        exec.lease = { owner: this.owner, heartbeatAt: now, expiresAt: now + this.expiryMs };
+        this.save(exec);
+        // Confirm we actually won: if another owner's write landed after ours, back off.
+        const confirmed = this.get(id);
+        if (confirmed?.lease?.owner !== this.owner)
+            return { ok: false, reason: 'lost the acquire race' };
+        return { ok: true, execution: confirmed };
+    }
+    /** Write only if we still hold the lease (or it's free/expired) — never clobber a live different owner. */
+    commit(exec) {
+        const disk = this.get(exec.id);
+        if (disk?.lease && disk.lease.owner !== this.owner && disk.lease.expiresAt > this.clock.now())
+            return false;
+        this.save(exec);
+        return true;
+    }
+    /** Renew this owner's lease. Returns false if we no longer hold it. */
+    heartbeat(id) {
+        const exec = this.get(id);
+        if (!exec || exec.lease?.owner !== this.owner)
+            return false;
+        const now = this.clock.now();
+        exec.lease.heartbeatAt = now;
+        exec.lease.expiresAt = now + this.expiryMs;
+        this.save(exec);
+        return true;
+    }
+    release(id) {
+        const exec = this.get(id);
+        if (exec && exec.lease?.owner === this.owner) {
+            delete exec.lease;
+            this.save(exec);
+        }
+    }
+    setStatus(id, status) {
+        const exec = this.get(id);
+        if (exec) {
+            exec.status = status;
+            this.save(exec);
+        }
+    }
+    delete(id) {
+        this.area.remove(id);
+    }
+}

package/dist/generation/generateAdapter.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Dynamic adapter generation. Given an OpenAPI analysis, produce a validated
+ * ProviderConfig that plugs into the existing HttpProvider — so "generating an adapter" means emitting
+ * CONFIG, not code, which keeps it safe: no arbitrary code is created or executed, and the result is
+ * validated before use. The operator still supplies the key via an env var and confirms the mapping.
+ */
+import { type OpenApiAnalysis } from '../discovery/openapi.js';
+import type { ProviderConfig } from '../types.js';
+export interface GenerateOptions {
+    id?: string;
+    apiKeyEnv?: string;
+    models?: string[];
+    privacyClass?: 'cloud' | 'local';
+}
+/** Turn an OpenAPI analysis into a ProviderConfig. Throws if the spec yielded no usable mapping. */
+export declare function generateProviderConfig(analysis: OpenApiAnalysis, overrides?: GenerateOptions): ProviderConfig;
+export declare function generateProviderConfigFromFile(specPath: string, overrides?: GenerateOptions): ProviderConfig;

package/dist/generation/generateAdapter.js

@@ -0,0 +1,30 @@
+/**
+ * Dynamic adapter generation. Given an OpenAPI analysis, produce a validated
+ * ProviderConfig that plugs into the existing HttpProvider — so "generating an adapter" means emitting
+ * CONFIG, not code, which keeps it safe: no arbitrary code is created or executed, and the result is
+ * validated before use. The operator still supplies the key via an env var and confirms the mapping.
+ */
+import { AIError } from '../core/fallback/errors.js';
+import { analyzeOpenApiFile } from '../discovery/openapi.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;
+    if (!base) {
+        throw new AIError('OpenAPI spec did not yield an OpenAI-compatible mapping — a manual adapter config is required', { category: 'CONFIG' });
+    }
+    const config = {
+        ...base,
+        ...(overrides.id ? { id: overrides.id } : {}),
+        ...(overrides.apiKeyEnv ? { apiKeyEnv: overrides.apiKeyEnv } : {}),
+        ...(overrides.privacyClass ? { privacyClass: overrides.privacyClass } : {}),
+        ...(overrides.models ? { models: overrides.models } : {}),
+    };
+    if (config.models === 'auto' && !overrides.models) {
+        // Discovery of the model list is not yet implemented; require an explicit model list to route.
+        delete config.models;
+    }
+    return config;
+}
+export function generateProviderConfigFromFile(specPath, overrides = {}) {
+    return generateProviderConfig(analyzeOpenApiFile(specPath), overrides);
+}