ai-runtime-engine 1.3.0 → 2.7.0

package/dist/cli/interactive/session.js

@@ -9,6 +9,16 @@ import { SETUP_CANDIDATES } from '../commands/setup.js';
 import { gatherInfo, renderInfo } from '../commands/info.js';
 import { gatherDoctor, renderDoctor } from '../commands/doctor.js';
 import { planCleanup } from '../commands/cleanup.js';
+import { actionCapabilityRows, renderActionCapabilities, renderCapabilityGaps } from '../commands/inspect.js';
+import { renderMcpList, renderMcpDetail } from '../commands/mcp.js';
+import { candidatesFrom, deriveCapabilitiesOffline } from '../../runtime/planning/deriveCapabilities.js';
+import { displaySafe } from '../render.js';
+/** Top-level slash commands, for REPL tab-completion (Phase 21b). Kept in sync with the `handle` dispatch. */
+export const SLASH_COMMANDS = [
+    'help', 'status', 'info', 'doctor', 'cleanup', 'mode', 'compare', 'models', 'config', 'providers', 'tools', 'capabilities', 'mcp',
+    'skills', 'memory', 'conversations', 'executions', 'resume', 'resume-execution', 'pause', 'cancel', 'approve',
+    'deny', 'learning', 'feedback', 'permissions', 'budget', 'stream', 'dry-run', 'clear', 'exit', 'quit',
+];
 const HELP = [
     'Commands:',
     '  /help                       show this help',
@@ -24,6 +34,10 @@ const HELP = [
     '  /providers/<id> [models|capabilities|health]   inspect one provider',
     '  /models                     list all known models',
     '  /tools                      list registered tools',
+    '  /capabilities               list action capabilities (what the runtime can DO) + providers',
+    '  /capabilities <goal>        which capabilities a goal needs, and what is missing (offline)',
+    '  /mcp                        list MCP servers (state, tools, grant)',
+    '  /mcp/<id>                   inspect one MCP server (protocol, tools, diagnostics)',
     '  /skills [discover]          list available skills; discover scans the workspace',
     '  /permissions                show the current tool permissions',
     '  /feedback <text>            record feedback on the last result (e.g. "that worked")',
@@ -43,6 +57,7 @@ const HELP = [
     '  /config                     show the resolved configuration',
     '  /dry-run                    toggle dry-run (plan only, no changes)',
     '  /stream                     toggle token-by-token streaming of answers',
+    '  /budget                     show the call/cost budget (AI_MAX_CALLS / AI_MAX_COST_USD)',
     '  /clear                      clear the screen',
     '  /exit                       leave the session',
     '',
@@ -67,6 +82,27 @@ export class ReplSession {
             this.viewCache = new ProviderViewCache(this.runtime.ai);
         return this.viewCache;
     }
+    /**
+     * MCP servers in the REPL. The session's Runtime is already connected (the REPL connects eagerly at
+     * start), so this NEVER opens a second Runtime — that would spawn duplicate stdio children and give
+     * `close()` the wrong one to tear down. It reuses the exact formatters the `mcp` command prints.
+     */
+    mcpView(target) {
+        if (!this.runtime.hasMcpServers())
+            return { lines: renderMcpList({}, []) };
+        const grants = this.runtime.permissions().mcp.servers;
+        if (!target) {
+            const lines = renderMcpList(grants, this.runtime.mcp().list());
+            const warnings = this.runtime.mcpWarningsList();
+            if (warnings.length)
+                lines.push('', 'Warnings:', ...warnings.map((w) => `  ! ${w}`));
+            return { lines };
+        }
+        const status = this.runtime.mcp().status(target);
+        if (!status)
+            return { lines: [`no MCP server '${displaySafe(target, 40)}' — /mcp lists them`] };
+        return { lines: renderMcpDetail(grants, status, this.runtime.mcp().diagnostics(target), this.runtime.mcp().tools(target)) };
+    }
     async handle(raw) {
         const line = raw.trim();
         if (!line)
@@ -109,6 +145,24 @@ export class ReplSession {
                 return this.config();
             case 'providers':
                 return this.providers(parts[1], args[0]);
+            case 'capabilities': {
+                // `capabilities --actions` connects (inspect.ts); without this the same question reported
+                // different MCP availability on the two surfaces. connectMcp is idempotent.
+                if (this.runtime.hasMcpServers())
+                    await this.runtime.connectMcp();
+                // Both forms, and never a truncated goal: `/capabilities run the tests` and
+                // `/capabilities/run the tests` must mean the same thing.
+                const goal = [...parts.slice(1), ...args].join(' ').trim();
+                if (!goal)
+                    return { lines: renderActionCapabilities(actionCapabilityRows(this.runtime)) };
+                const required = deriveCapabilitiesOffline(goal, candidatesFrom(this.runtime.capabilities().list()));
+                if (!required.length)
+                    return { lines: [`no action capability matched "${displaySafe(goal, 80)}" — /capabilities lists everything this runtime can do.`] };
+                return { lines: renderCapabilityGaps(this.runtime.capabilityReport(required)) };
+            }
+            case 'mcp':
+                // `/mcp/<id>` and `/mcp <id>` both address one server.
+                return this.mcpView(parts[1] ?? args[0]);
             case 'tools':
                 return { lines: ['Tools:', ...this.runtime.tools().map((t) => `  ${t.id.padEnd(14)} ${t.description}`)] };
             case 'skills': {
@@ -139,6 +193,14 @@ export class ReplSession {
             case 'stream':
                 this.streaming = !this.streaming;
                 return { lines: [`streaming ${this.streaming ? 'ON — answers render token-by-token' : 'OFF'}`] };
+            case 'budget':
+                return {
+                    lines: [
+                        `call budget (AI_MAX_CALLS):    ${process.env.AI_MAX_CALLS ?? '(unset — no limit)'}`,
+                        `cost budget (AI_MAX_COST_USD): ${process.env.AI_MAX_COST_USD ?? '(unset — no limit)'}`,
+                        'over budget: notify-and-wait by default; add --partial (one-shot) to run the phases that fit and pause.',
+                    ],
+                };
             case 'memory':
                 return this.memory(args);
             case 'conversations':
@@ -182,17 +244,25 @@ export class ReplSession {
             const execId = result.execution?.id;
             lines.push(execId ? `(approval required — /approve ${execId} to proceed, or /deny ${execId})` : '(approval required — approve the execution via /executions then /approve <id>)');
         }
+        if (result.status === 'waiting_for_budget') {
+            const execId = result.execution?.id;
+            lines.push(execId ? `(over budget — raise AI_MAX_CALLS and /resume-execution ${execId}, or re-run with more budget)` : '(over budget — raise the call budget and re-run, or add --partial)');
+        }
         if (result.status === 'failed')
             lines.push('(did not complete)');
         if (result.clarification)
             lines.push(`? ${result.clarification.question}`);
         if (result.memory?.captured)
             lines.push('(remembered)');
+        // Phase 3.3: the ONE gap renderer, shared with `ai-runtime run` and both capabilities surfaces.
+        // Appended AFTER the existing advisory tail so every positional assertion above is untouched.
+        if (result.capabilityGaps)
+            lines.push(...renderCapabilityGaps(result.capabilityGaps));
         if (this.conversationId && result.response?.text)
             this.runtime.conversations.append(this.conversationId, 'assistant', result.response.text, result.runId);
         return { lines };
     }
-    memory(args) {
+    async memory(args) {
         if (!this.runtime.memory.enabled)
             return { lines: ['memory is disabled (stateless mode).'] };
         const sub = args[0];
@@ -200,7 +270,8 @@ export class ReplSession {
             const q = args.slice(1).join(' ');
             if (!q)
                 return { lines: ['usage: /memory search <query>'] };
-            const hits = this.runtime.memory.search(q, { limit: 10 });
+            // Semantic ranking when an embedder is configured; degrades to BM25 internally.
+            const hits = await this.runtime.memory.searchSemantic(q, { limit: 10 });
             return { lines: hits.length ? hits.map((r) => `  ${r.id}  [${r.scope}]  ${r.text}`) : ['no matches.'] };
         }
         if (sub === 'delete') {

package/dist/cli/render.d.ts

@@ -11,3 +11,10 @@ export declare function print(line: string): void;
  */
 export declare function printChunk(chunk: string): void;
 export declare function printError(line: string): void;
+/**
+ * Clamp a source- or MODEL-controlled string before it reaches the terminal — the terminal twin of
+ * `promptSafe`. LOAD-BEARING: `print` redacts secrets but strips no control characters and bounds no
+ * length, and a gap's `capabilityId` originates in the model's plan JSON — `sanitizeSegment` restricts
+ * its charset but sets no maximum, and the `register` gap hint interpolates it.
+ */
+export declare function displaySafe(raw: string, max?: number): string;

package/dist/cli/render.js

@@ -4,6 +4,7 @@
  * directly from a command.
  */
 import { redactString } from '../security/redact.js';
+import { flattenClamp } from '../util/flatten.js';
 export function print(line) {
     // eslint-disable-next-line no-console
     console.log(redactString(line));
@@ -20,3 +21,12 @@ export function printError(line) {
     // eslint-disable-next-line no-console
     console.error(redactString(line));
 }
+/**
+ * Clamp a source- or MODEL-controlled string before it reaches the terminal — the terminal twin of
+ * `promptSafe`. LOAD-BEARING: `print` redacts secrets but strips no control characters and bounds no
+ * length, and a gap's `capabilityId` originates in the model's plan JSON — `sanitizeSegment` restricts
+ * its charset but sets no maximum, and the `register` gap hint interpolates it.
+ */
+export function displaySafe(raw, max = 80) {
+    return flattenClamp(raw, max);
+}

package/dist/cli/runtimeSession.d.ts

@@ -0,0 +1,11 @@
+/**
+ * One place where a CLI command borrows a Runtime and gives it back.
+ *
+ * A `Runtime` can own OS resources — today MCP stdio child processes. A one-shot command that returns
+ * without releasing them does not merely leak: a live child keeps the event loop alive, so the CLI never
+ * exits. `withRuntime` guarantees the release on every path, including a thrown error.
+ */
+import { Runtime } from '../runtime/runtime.js';
+export declare function withRuntime<T>(opts: {
+    config?: string;
+}, fn: (rt: Runtime) => Promise<T>): Promise<T>;

package/dist/cli/runtimeSession.js

@@ -0,0 +1,17 @@
+/**
+ * One place where a CLI command borrows a Runtime and gives it back.
+ *
+ * A `Runtime` can own OS resources — today MCP stdio child processes. A one-shot command that returns
+ * without releasing them does not merely leak: a live child keeps the event loop alive, so the CLI never
+ * exits. `withRuntime` guarantees the release on every path, including a thrown error.
+ */
+import { Runtime } from '../runtime/runtime.js';
+export async function withRuntime(opts, fn) {
+    const rt = await Runtime.load({ ...(opts.config ? { config: opts.config } : {}) });
+    try {
+        return await fn(rt);
+    }
+    finally {
+        await rt.close();
+    }
+}

package/dist/config/defaults.d.ts

@@ -24,9 +24,11 @@ export interface ResolvedConfig {
     privacy: ResolvedPrivacy;
     telemetry: {
         enabled: boolean;
-        sink: 'memory' | 'file';
+        sink: 'memory' | 'file' | 'otlp';
         storePrompts: false;
         path?: string;
+        endpoint?: string;
+        headersEnv?: string;
     };
     learning: {
         enabled: boolean;

package/dist/config/defaults.js

@@ -33,6 +33,8 @@ export function resolveConfig(cfg) {
         sink: cfg.telemetry?.sink ?? 'memory',
         storePrompts: false,
         ...(cfg.telemetry?.path !== undefined ? { path: cfg.telemetry.path } : {}),
+        ...(cfg.telemetry?.endpoint !== undefined ? { endpoint: cfg.telemetry.endpoint } : {}),
+        ...(cfg.telemetry?.headersEnv !== undefined ? { headersEnv: cfg.telemetry.headersEnv } : {}),
     };
     return {
         providers: cfg.providers,

package/dist/config/schema.d.ts

@@ -6,4 +6,5 @@
 import type { RouterConfig } from '../types.js';
 /** Canonical strategy names. Exported for reuse by the runtime-config layer (no duplication). */
 export declare const STRATEGIES: readonly ["best", "fastest", "cheapest", "highest-quality", "local-only", "cloud-only", "privacy-first", "provider-specific", "fallback-only"];
+export declare const KEY_LIKE: RegExp;
 export declare function parseConfig(raw: unknown): RouterConfig;

package/dist/config/schema.js

@@ -10,7 +10,7 @@ export const STRATEGIES = ['best', 'fastest', 'cheapest', 'highest-quality', 'lo
 const EVIDENCE = ['unsupported', 'unknown', 'inferred', 'documented', 'verified'];
 const GROUPS = ['input', 'output', 'intelligence', 'agent'];
 const KINDS = ['openai-compatible', 'gemini', 'groq', 'anthropic', 'ollama', 'custom', 'mock'];
-const KEY_LIKE = /^(sk-|gsk_|Bearer\s|[A-Za-z0-9_-]{40,}$)/;
+export const KEY_LIKE = /^(sk-|gsk_|Bearer\s|[A-Za-z0-9_-]{40,}$)/;
 const capabilityRequirement = z.object({
     group: z.enum(GROUPS),
     key: z.string().min(1),
@@ -64,7 +64,7 @@ const routerConfig = z
         .object({ allowCloud: z.boolean().optional(), allowLocal: z.boolean().optional(), sensitiveDataAllowedOnCloud: z.boolean().optional(), treatUnknownAsSensitive: z.boolean().optional(), defaultSensitivity: z.enum(['low', 'high', 'unknown']).optional() })
         .strict()
         .optional(),
-    telemetry: z.object({ enabled: z.boolean().optional(), sink: z.enum(['memory', 'file']).optional(), storePrompts: z.literal(false).optional(), path: z.string().optional() }).strict().optional(),
+    telemetry: z.object({ enabled: z.boolean().optional(), sink: z.enum(['memory', 'file', 'otlp']).optional(), storePrompts: z.literal(false).optional(), path: z.string().optional(), endpoint: z.string().optional(), headersEnv: z.string().refine((v) => v === undefined || !KEY_LIKE.test(v), { message: 'headersEnv must be an env-var NAME, not a header/token value' }).optional() }).strict().optional(),
     tasks: z.array(taskDefinition).optional(),
 })
     .strict();

package/dist/context/lossVerifier.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Model-based context-loss verification (Phase 16) — an OPT-IN rung ON TOP OF the deterministic
+ * `validate()` in the compiler. After the sync `compileContext` runs, this asks a model "does the compiled
+ * context drop anything task-critical that was in the originals?" and returns a single check that the caller
+ * APPENDS to `validation.checks`. It NEVER blocks: any budget/parse/model problem yields an `ok:true`
+ * `inconclusive` check, and the deterministic `validation.ok` is untouched. Both the originals and the
+ * compiled text are `wrapUntrusted`-fenced — they are data to inspect, never instructions.
+ */
+import type { AI } from '../plugin/ai.js';
+import type { ContextBlock, CompiledContext } from './compiler.js';
+export interface VerifyLossInput {
+    ai: AI;
+    /** The ORIGINAL blocks handed to the compiler (pre-compression). */
+    blocks: ContextBlock[];
+    /** The compiler's output (its `system` string is what will actually be sent). */
+    compiled: CompiledContext;
+}
+/** The check appended to `ContextValidation.checks`. `ok:false` means the model flagged task-critical loss. */
+export type LossCheck = {
+    name: 'model-loss-verify';
+    ok: boolean;
+    why?: string;
+};
+export declare function verifyContextLoss(input: VerifyLossInput): Promise<LossCheck>;

package/dist/context/lossVerifier.js

@@ -0,0 +1,45 @@
+/**
+ * Model-based context-loss verification (Phase 16) — an OPT-IN rung ON TOP OF the deterministic
+ * `validate()` in the compiler. After the sync `compileContext` runs, this asks a model "does the compiled
+ * context drop anything task-critical that was in the originals?" and returns a single check that the caller
+ * APPENDS to `validation.checks`. It NEVER blocks: any budget/parse/model problem yields an `ok:true`
+ * `inconclusive` check, and the deterministic `validation.ok` is untouched. Both the originals and the
+ * compiled text are `wrapUntrusted`-fenced — they are data to inspect, never instructions.
+ */
+import { wrapUntrusted } from '../tools/untrusted.js';
+import { extractJson } from '../util/extractJson.js';
+export async function verifyContextLoss(input) {
+    const inconclusive = (why) => ({ name: 'model-loss-verify', ok: true, why: `inconclusive: ${why}` });
+    try {
+        // Only critical/high blocks carry task-critical information worth verifying.
+        const important = input.blocks.filter((b) => b.retention === 'critical' || b.retention === 'high');
+        if (important.length === 0)
+            return inconclusive('no task-critical blocks to verify');
+        const originals = important.map((b) => `[${b.retention}:${b.id}] ${b.resolveContent ? b.resolveContent() : b.text}`).join('\n');
+        const prompt = `You verify whether a COMPILED model context dropped anything task-critical from the ORIGINAL blocks.\n\n` +
+            `ORIGINAL task-critical blocks:\n${wrapUntrusted('context-originals', originals)}\n\n` +
+            `COMPILED context that will be sent:\n${wrapUntrusted('context-compiled', input.compiled.system)}\n\n` +
+            `Reply ONLY with JSON: {"lost": true|false, "items": ["<short phrase>", ...]}. Set "lost" true ONLY if ` +
+            `something task-critical present in the originals is ABSENT or corrupted in the compiled context.`;
+        const result = await input.ai.run({
+            task: 'chat',
+            input: { text: prompt },
+            system: 'You are a context-loss verifier. Respond only with the requested JSON.',
+            output: { format: 'json' },
+            requirements: { intelligence: ['reasoning'], output: ['json'] },
+        });
+        if (!result.ok || !result.response)
+            return inconclusive('verifier run did not complete');
+        const verdict = (result.response.json ?? extractJson(result.response.text ?? ''));
+        if (typeof verdict?.lost !== 'boolean')
+            return inconclusive('verifier response was not parseable JSON');
+        if (!verdict.lost)
+            return { name: 'model-loss-verify', ok: true, why: 'model found no task-critical loss' };
+        const items = Array.isArray(verdict.items) ? verdict.items.filter((x) => typeof x === 'string').slice(0, 5) : [];
+        return { name: 'model-loss-verify', ok: false, why: items.length ? `model flagged omissions: ${items.join('; ')}` : 'model flagged task-critical loss' };
+    }
+    catch {
+        // A verifier problem must never break a run — report it as inconclusive, leave validation.ok alone.
+        return inconclusive('verifier error');
+    }
+}

package/dist/context/summarize.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Opt-in abstractive summarization pre-pass (Phase 16) — runs BEFORE `compileContext`. For non-critical
+ * blocks (`high`/`normal`) whose estimate exceeds their fair share of the budget, it asks a model for a
+ * shorter text and swaps it in. `critical` and `discardable` blocks are NEVER summarized (critical must stay
+ * verbatim; discardable is dropped by the compiler anyway). Originals are never mutated — a new block array
+ * is returned. Any model failure, or a "summary" that does not actually shrink the block, keeps the original
+ * (the compiler's deterministic truncation then handles it, exactly as before). Content is `wrapUntrusted`-
+ * fenced. Absent config ⇒ this never runs and the compiler sees the original blocks.
+ */
+import type { AI } from '../plugin/ai.js';
+import type { ContextBlock } from './compiler.js';
+import { TokenEstimator } from './tokens.js';
+export interface SummarizeInput {
+    ai: AI;
+    blocks: ContextBlock[];
+    budgetTokens: number;
+    estimator?: TokenEstimator;
+}
+export declare function summarizeOverBudget(input: SummarizeInput): Promise<ContextBlock[]>;

package/dist/context/summarize.js

@@ -0,0 +1,53 @@
+/**
+ * Opt-in abstractive summarization pre-pass (Phase 16) — runs BEFORE `compileContext`. For non-critical
+ * blocks (`high`/`normal`) whose estimate exceeds their fair share of the budget, it asks a model for a
+ * shorter text and swaps it in. `critical` and `discardable` blocks are NEVER summarized (critical must stay
+ * verbatim; discardable is dropped by the compiler anyway). Originals are never mutated — a new block array
+ * is returned. Any model failure, or a "summary" that does not actually shrink the block, keeps the original
+ * (the compiler's deterministic truncation then handles it, exactly as before). Content is `wrapUntrusted`-
+ * fenced. Absent config ⇒ this never runs and the compiler sees the original blocks.
+ */
+import { TokenEstimator } from './tokens.js';
+import { wrapUntrusted } from '../tools/untrusted.js';
+export async function summarizeOverBudget(input) {
+    const estimator = input.estimator ?? new TokenEstimator();
+    const compressible = input.blocks.filter((b) => b.retention === 'high' || b.retention === 'normal');
+    if (compressible.length === 0)
+        return input.blocks;
+    // Fair share: the budget split across the compressible blocks. Only those exceeding it are summarized.
+    const share = Math.max(1, Math.floor(Math.max(0, input.budgetTokens) / compressible.length));
+    const out = [];
+    for (const b of input.blocks) {
+        if (b.retention !== 'high' && b.retention !== 'normal') {
+            out.push(b); // critical stays verbatim; discardable is the compiler's to drop
+            continue;
+        }
+        const full = b.resolveContent ? b.resolveContent() : b.text;
+        if (estimator.estimate(full) <= share) {
+            out.push(b); // already within its share — nothing to gain
+            continue;
+        }
+        try {
+            const prompt = `Summarize the following content to about ${share} tokens or fewer, preserving EVERY identifier, ` +
+                `file path, number, and task-critical fact. Output ONLY the summary text.\n\n${wrapUntrusted(`block:${b.id}`, full)}`;
+            const result = await input.ai.run({
+                task: 'chat',
+                input: { text: prompt },
+                system: 'You compress context while preserving task-critical facts and identifiers. Output only the summary text.',
+                requirements: { intelligence: ['reasoning'], output: ['text'] },
+            });
+            const summary = result.ok ? (result.response?.text ?? '').trim() : '';
+            // Accept only a summary that genuinely shrinks the block; otherwise keep the original.
+            if (summary && estimator.estimate(summary) < estimator.estimate(full)) {
+                out.push({ ...b, text: summary, ...(b.resolveContent ? { resolveContent: () => summary } : {}) });
+            }
+            else {
+                out.push(b);
+            }
+        }
+        catch {
+            out.push(b); // model failure → keep the original; the compiler truncates deterministically as before
+        }
+    }
+    return out;
+}

package/dist/core/fallback/fallback.d.ts

@@ -11,6 +11,7 @@ import type { RequestTemplate } from '../router/normalize.js';
 import { AIError } from './errors.js';
 import type { BudgetTracker } from '../policies/budget.js';
 import type { Clock } from '../../util/clock.js';
+import type { KeyedSemaphore } from '../../util/semaphore.js';
 export interface FallbackInput {
     ranked: ScoredCandidate[];
     template: RequestTemplate;
@@ -28,6 +29,10 @@ export interface FallbackInput {
     budget?: BudgetTracker;
     /** Estimated USD cost of a candidate call, consulted before spending (used with `budget`). */
     costOf?: (providerId: string, model: string) => Promise<number>;
+    /** Phase 19: optional per-provider in-flight limiter, SHARED across concurrent router calls. Bounds how
+     *  many calls to a given provider run at once (this fallback walks candidates sequentially, so it only
+     *  bites under fan-out). Absent / unlimited ⇒ a zero-overhead pass-through. */
+    providerLimiter?: KeyedSemaphore;
 }
 export type FallbackResult = {
     ok: true;

package/dist/core/fallback/fallback.js

@@ -34,7 +34,9 @@ export async function runWithFallback(input) {
         tried += 1;
         const started = clock.now();
         const request = buildRequest(input.template, model.id, input.signal);
-        const outcome = await executeOnce(provider, request, input.onDelta);
+        const outcome = input.providerLimiter
+            ? await input.providerLimiter.run(providerId, () => executeOnce(provider, request, input.onDelta))
+            : await executeOnce(provider, request, input.onDelta);
         const latencyMs = clock.now() - started;
         input.budget?.recordCall(estCost);
         if (outcome.ok) {

package/dist/core/router/router.d.ts

@@ -14,6 +14,7 @@ import type { PerformanceStore } from '../../learning/performanceStore.js';
 import type { CapabilityOverlay } from '../capabilities/overlay.js';
 import type { Clock } from '../../util/clock.js';
 import type { RunRequest, RunResult } from '../../types.js';
+import type { KeyedSemaphore } from '../../util/semaphore.js';
 export interface RouterDeps {
     registry: ProviderRegistry;
     tasks: TaskRegistry;
@@ -23,6 +24,8 @@ export interface RouterDeps {
     performance?: PerformanceStore;
     overlay?: CapabilityOverlay;
     clock?: Clock;
+    /** Phase 19: shared per-provider in-flight limiter, forwarded to fallback (bounds concurrent calls to a provider). */
+    providerLimiter?: KeyedSemaphore;
 }
 export declare class Router {
     private readonly deps;

package/dist/core/router/router.js

@@ -144,6 +144,7 @@ export class Router {
             ...(template.stream && req.onDelta ? { onDelta: req.onDelta } : {}),
             validate: (response) => validateResponse({ response, ...(template.output ? { output: template.output } : {}), ...(template.tools ? { tools: template.tools } : {}) }),
             ...(budget ? { budget, costOf } : {}),
+            ...(this.deps.providerLimiter ? { providerLimiter: this.deps.providerLimiter } : {}),
         });
         baseReport.attempts = fb.attempts;
         const fallbackCount = Math.max(0, fb.attempts.length - 1);

package/dist/executions/execution.d.ts

@@ -24,11 +24,22 @@ export interface Checkpoint {
     skillVersions: Record<string, string>;
     completedSteps: string[];
 }
-/** What an execution is waiting for (approval or clarification), persisted so a restart can resume it. */
+/** A plan's estimated vs available model-call budget (Phase 22), carried on a budget-paused execution. */
+export interface BudgetInfo {
+    /** Estimated model calls the plan needs (its skill steps). */
+    estCalls: number;
+    /** The call budget in force (`policy.maxCalls`). */
+    maxCalls: number;
+    /** Steps already completed (0 on a notify-before-start pause). */
+    completedSteps: number;
+    totalSteps: number;
+}
+/** What an execution is waiting for (approval / clarification / budget), persisted so a restart resumes it. */
 export interface PendingInput {
-    kind: 'approval' | 'clarification';
+    kind: 'approval' | 'clarification' | 'budget';
     question?: string;
     action?: string;
+    budget?: BudgetInfo;
 }
 export interface Execution {
     id: string;

package/dist/generation/generateAdapter.d.ts

@@ -6,6 +6,7 @@
  */
 import { type OpenApiAnalysis } from '../discovery/openapi.js';
 import type { ProviderConfig } from '../types.js';
+import type { AI } from '../plugin/ai.js';
 export interface GenerateOptions {
     id?: string;
     apiKeyEnv?: string;
@@ -15,3 +16,16 @@ export interface GenerateOptions {
 /** 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;
+export interface SuggestResult {
+    ok: boolean;
+    config?: ProviderConfig;
+    error?: string;
+}
+/**
+ * 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 declare function suggestProviderConfig(analysis: OpenApiAnalysis, ai: AI, overrides?: GenerateOptions): Promise<SuggestResult>;

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