ai-runtime-engine 1.2.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")',
@@ -42,6 +56,8 @@ const HELP = [
     '  /cancel <id>                cancel an execution',
     '  /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',
     '',
@@ -53,8 +69,10 @@ export class ReplSession {
     viewCache;
     conversationId;
     dryRunMode = false;
-    constructor(runtime) {
+    streaming;
+    constructor(runtime, opts = {}) {
         this.runtime = runtime;
+        this.streaming = opts.streaming ?? false;
     }
     currentMode() {
         return this.mode;
@@ -64,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)
@@ -106,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': {
@@ -133,6 +190,17 @@ export class ReplSession {
             case 'dryrun':
                 this.dryRunMode = !this.dryRunMode;
                 return { lines: [`dry-run ${this.dryRunMode ? 'ON — plans will be shown, nothing executed' : 'OFF'}`] };
+            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':
@@ -161,9 +229,10 @@ export class ReplSession {
                 this.conversationId = this.runtime.conversations.start();
             this.runtime.conversations.append(this.conversationId, 'user', input);
         }
-        const result = await this.runtime.run({ input, mode: forceMode ?? this.mode, ...(this.dryRunMode ? { dryRun: true } : {}) });
+        const result = await this.runtime.run({ input, mode: forceMode ?? this.mode, ...(this.dryRunMode ? { dryRun: true } : {}), ...(this.streaming ? { stream: true } : {}) });
         const lines = [];
-        if (result.response?.text)
+        // When the answer already streamed live (response.streamed), don't reprint it.
+        if (result.response?.text && !result.response.streamed)
             lines.push(result.response.text);
         else if (result.response?.json !== undefined)
             lines.push(JSON.stringify(result.response.json, null, 2));
@@ -175,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];
@@ -193,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

@@ -4,4 +4,17 @@
  * directly from a command.
  */
 export declare function print(line: string): void;
+/**
+ * Write a streamed chunk WITHOUT a trailing newline, redacted like every other egress. (Redaction is
+ * per-chunk, matching the lifecycle emitter; a secret split across chunk boundaries is the known limit of
+ * any token stream — but model output never contains the env-var secrets the redactor tracks.)
+ */
+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,11 +4,29 @@
  * 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));
 }
+/**
+ * Write a streamed chunk WITHOUT a trailing newline, redacted like every other egress. (Redaction is
+ * per-chunk, matching the lifecycle emitter; a secret split across chunk boundaries is the known limit of
+ * any token stream — but model output never contains the env-var secrets the redactor tracks.)
+ */
+export function printChunk(chunk) {
+    process.stdout.write(redactString(chunk));
+}
 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;
@@ -19,12 +20,19 @@ export interface FallbackInput {
     signal?: AbortSignal;
     clock?: Clock;
     onAttempt?: (record: AttemptRecord) => void;
+    /** Phase-13 streaming: forwarded to each attempt's `executeOnce`; deltas ride this callback, the final
+     *  aggregate rides the return value. Only meaningful when `template.stream` is set. */
+    onDelta?: (chunk: string) => void;
     /** Optional Phase-6 validation. A failing report drops this candidate and continues (no poisoning). */
     validate?: (response: AIResponse, model: string) => ValidationReport;
     /** Optional spend guardrail. When it cannot afford the next call, the run STOPS with BUDGET. */
     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);
+        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/executor.d.ts

@@ -13,4 +13,9 @@ export type ExecOutcome = {
     ok: false;
     error: AIError;
 };
-export declare function executeOnce(provider: AIProvider, request: AIRequest): Promise<ExecOutcome>;
+/**
+ * Run one attempt. When `onDelta` is supplied AND the request asked to stream AND the provider supports
+ * `executeStream`, the answer streams token-by-token; otherwise the normal single-shot `execute()` runs.
+ * Either way the resolved `AIResponse` is the full aggregate.
+ */
+export declare function executeOnce(provider: AIProvider, request: AIRequest, onDelta?: (chunk: string) => void): Promise<ExecOutcome>;

package/dist/core/router/executor.js

@@ -4,9 +4,16 @@
  * raw vendor error.
  */
 import { AIError, toAIError } from '../fallback/errors.js';
-export async function executeOnce(provider, request) {
+/**
+ * Run one attempt. When `onDelta` is supplied AND the request asked to stream AND the provider supports
+ * `executeStream`, the answer streams token-by-token; otherwise the normal single-shot `execute()` runs.
+ * Either way the resolved `AIResponse` is the full aggregate.
+ */
+export async function executeOnce(provider, request, onDelta) {
     try {
-        const response = await provider.execute(request);
+        const response = onDelta && request.stream && provider.executeStream
+            ? await provider.executeStream(request, onDelta)
+            : await provider.execute(request);
         return { ok: true, response };
     }
     catch (e) {

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

@@ -22,6 +22,8 @@ export interface RequestTemplate {
     params?: AIRequest['params'];
     timeoutMs: number;
     sensitivity: Sensitivity;
+    /** Stream the answer token-by-token (Phase 13). Set only for text output; never for JSON. */
+    stream?: boolean;
 }
 export interface NormalizeResult {
     task: NormalizedTask;

package/dist/core/router/request.js

@@ -15,6 +15,8 @@ export function buildRequest(template, model, signal) {
         req.tools = template.tools;
     if (template.params !== undefined)
         req.params = template.params;
+    if (template.stream)
+        req.stream = true;
     if (signal !== undefined)
         req.signal = signal;
     return req;

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

@@ -31,6 +31,11 @@ export class Router {
         // Phase 1 — normalize
         const { task, template } = normalize(req, tasks, config);
         const pin = { provider: req.provider, model: req.model };
+        // Phase 13 — streaming is opt-in and TEXT-ONLY: a JSON/structured request never streams (partial
+        // JSON is useless). The delta callback rides `req.onDelta`; the final aggregate rides the return value.
+        const wantsJsonOut = template.output?.format === 'json' || template.output?.format === 'structured_output';
+        if (req.stream && req.onDelta && !wantsJsonOut)
+            template.stream = true;
         // Team policy (org-level guardrails) merged over per-run constraints.
         const policy = config.policy;
         if (policy.requireLocal)
@@ -136,8 +141,10 @@ export class Router {
             maxFallbacks: config.maxFallbacks,
             clock: this.clock,
             onAttempt,
+            ...(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>;