ai-runtime-engine 1.2.0 → 2.7.0

package/dist/orchestration/orchestrator.js

@@ -5,9 +5,53 @@
  * the iteration limit. Dry-run performs ZERO mutations. Missing information surfaces as clarification.
  */
 import { generatePlan } from './planner.js';
+import { foldCalls } from './budget.js';
+import { flattenClamp } from '../util/flatten.js';
 import { executePlan } from './executor.js';
-function planSummary(plan) {
-    const lines = plan.steps.map((s) => `  ${s.id}. ${s.description} [${s.skill ? 'skill:' + s.skill : 'tool:' + s.tool}]`);
+/** Model calls a plan needs = its skill steps (tool steps make no model call). */
+/** Pre-flight model-call estimate. One rule, shared with the executor's wave gate (see ./budget.ts). */
+function estimateCalls(plan, maxCalls, reserve) {
+    return foldCalls(plan.steps, maxCalls, reserve);
+}
+/** Render the granted dimensions of a clamped policy compactly, for the approval disclosure. */
+function permissionSummary(p) {
+    const on = [];
+    if (p.fsRead)
+        on.push('fsRead');
+    if (p.fsWrite)
+        on.push('fsWrite');
+    if (p.shell)
+        on.push(`shell${p.shellAllowedCommands?.length ? `(${p.shellAllowedCommands.join(',')})` : ''}`);
+    if (p.gitCommit)
+        on.push('gitCommit');
+    if (p.gitPush)
+        on.push('gitPush');
+    if (p.network)
+        on.push('network');
+    const mcp = Object.entries(p.mcp?.servers ?? {}).filter(([, g]) => g !== 'off' && g !== false);
+    if (mcp.length)
+        on.push(`mcp(${mcp.map(([id, g]) => `${id}:${String(g)}`).join(',')})`);
+    return on.length ? on.join(', ') : 'none';
+}
+/**
+ * The plan a human is asked to approve. An AGENT step discloses its ENVELOPE — what it may spend, what
+ * it may touch, and what it is allowed to do — because approving a delegation blind is approving a
+ * blank cheque. The skill/tool line is unchanged.
+ *
+ * Every source-controlled segment on the agent line is clamped: a long tool list or permission summary
+ * must not be able to forge a second envelope line in the very text a human is reading to decide.
+ */
+function planSummary(plan, envelopes) {
+    const lines = plan.steps.map((s) => {
+        if (s.agent) {
+            const e = envelopes?.find((x) => x.agentId === s.agent);
+            const env = e
+                ? ` (reserves ${e.reservation} model call(s), max ${e.maxToolCalls} tool call(s), ${e.maxDurationMs}ms; tools: ${flattenClamp(e.tools.join(', '), 160) || 'none'}; permissions: ${flattenClamp(permissionSummary(e.permissions), 120)})`
+                : ' (envelope unavailable)';
+            return `  ${s.id}. ${s.description} [agent:${flattenClamp(s.agent, 40)}]${env}`;
+        }
+        return `  ${s.id}. ${s.description} [${s.skill ? 'skill:' + s.skill : 'tool:' + s.tool}]`;
+    });
     return `Plan v${plan.version} for "${plan.goal}" (${plan.steps.length} steps):\n${lines.join('\n')}`;
 }
 export async function orchestrate(input) {
@@ -15,6 +59,12 @@ export async function orchestrate(input) {
     const loops = input.mode === 'orchestrate' || input.mode === 'agent' || input.mode === 'debug';
     const maxIterations = loops ? Math.max(1, input.policy.maxIterations ?? (input.mode === 'agent' ? 10 : 5)) : 1;
     const needsApproval = input.policy.approval !== 'none' && input.policy.autonomy !== 'chat';
+    // ONE reserve function per run, shared by the pre-flight estimate and the executor's wave gate — so
+    // the two can never disagree about what an agent step costs. It deliberately IGNORES `remaining`:
+    // clamping a reservation to what is left would make `callsUsed + waveCalls` equal the budget instead
+    // of exceeding it, so the gate could never fire and the agent would overrun at run time.
+    const envelopeById = new Map((input.agents ?? []).map((e) => [e.agentId, e]));
+    const reserve = input.agents ? (step) => (step.agent ? envelopeById.get(step.agent)?.reservation ?? 1 : 0) : undefined;
     let priorObservations = [];
     // Accumulate observations across replan iterations so an early return never discards the trace of
     // prior iterations that already executed (and may have mutated the workspace).
@@ -27,30 +77,61 @@ export async function orchestrate(input) {
             tools: input.tools,
             version,
             ...(input.routing ? { routing: input.routing } : {}),
+            ...(input.capabilityCatalog ? { capabilityCatalog: input.capabilityCatalog } : {}),
+            ...(input.requiredCapabilities ? { requiredCapabilities: input.requiredCapabilities } : {}),
+            ...(input.agents ? { agents: input.agents } : {}),
+            ...(input.resolveGaps ? { resolveGaps: input.resolveGaps } : {}),
             ...(version > 1 ? { reason: 'previous attempt did not complete', priorObservations } : {}),
         });
         if (planResult.clarification)
             return { status: 'waiting_for_clarification', planHistory, observations: [...allObservations], clarification: planResult.clarification, summary: planResult.clarification };
         if (!planResult.plan)
-            return { status: 'failed', planHistory, observations: [...allObservations], summary: planResult.error ?? 'planning failed' };
+            return { status: 'failed', planHistory, observations: [...allObservations], summary: planResult.error ?? 'planning failed', ...(planResult.gaps?.length ? { gaps: planResult.gaps } : {}) };
         const plan = planResult.plan;
         planHistory.push(plan);
         if (input.mode === 'plan')
-            return { status: 'completed', plan, planHistory, observations: [...allObservations], summary: `${planSummary(plan)}\n(plan only — not executed)` };
+            return { status: 'completed', plan, planHistory, observations: [...allObservations], summary: `${planSummary(plan, input.agents)}\n(plan only — not executed)` };
         // Dry-run: report, never execute. Checked BEFORE approval — a dry run changes nothing, so it never
         // needs approval.
         if (input.policy.dryRun)
-            return { status: 'dry-run', plan, planHistory, observations: [...allObservations], summary: `${planSummary(plan)}\n(dry run — no changes were made)` };
+            return { status: 'dry-run', plan, planHistory, observations: [...allObservations], summary: `${planSummary(plan, input.agents)}\n(dry run — no changes were made)` };
         // Approval gate (assisted/autonomous with an approval level).
         if (needsApproval) {
             if (!input.approval)
-                return { status: 'waiting_for_approval', plan, planHistory, observations: [...allObservations], summary: `${planSummary(plan)}\nApproval required before execution.` };
-            const approved = await input.approval.requestApproval({ action: `execute plan v${plan.version} for "${plan.goal}"`, reason: planSummary(plan), risk: 'medium' });
+                return { status: 'waiting_for_approval', plan, planHistory, observations: [...allObservations], summary: `${planSummary(plan, input.agents)}\nApproval required before execution.` };
+            const approved = await input.approval.requestApproval({ action: `execute plan v${plan.version} for "${plan.goal}"`, reason: planSummary(plan, input.agents), risk: 'medium' });
             if (!approved)
                 return { status: 'failed', plan, planHistory, observations: [...allObservations], summary: 'plan was not approved' };
         }
-        const exec = await executePlan(plan, { runSkill: input.runSkill, runTool: input.runTool, ...(input.policy.maxParallelSteps ? { maxParallelSteps: input.policy.maxParallelSteps } : {}), ...(input.signal ? { signal: input.signal } : {}) });
+        // Phase 22 — budget check. Model calls needed = skill steps. When a call budget is set and the plan
+        // won't fit, either NOTIFY (default: refuse to start, report the estimate) or run PARTIAL (execute the
+        // phases that fit, then pause resumably). `input.partial` (the --partial flag / req.partial) opts in.
+        const maxCalls = input.policy.maxCalls;
+        const partial = input.partial === true;
+        const estCalls = estimateCalls(plan, maxCalls, reserve);
+        if (maxCalls !== undefined && !partial && estCalls > maxCalls) {
+            return {
+                status: 'waiting_for_budget',
+                plan,
+                planHistory,
+                observations: [...allObservations],
+                budget: { estCalls, maxCalls, completedSteps: 0, totalSteps: plan.steps.length },
+                summary: `This task looks like ~${estCalls} model call(s), but the budget is ${maxCalls}. Raise the budget (AI_MAX_CALLS or maxCalls) and re-run, or run the phases that fit with --partial (then resume as you raise it).`,
+            };
+        }
+        const exec = await executePlan(plan, { runSkill: input.runSkill, runTool: input.runTool, ...(input.runAgent ? { runAgent: input.runAgent } : {}), ...(reserve ? { reserve } : {}), ...(input.policy.maxParallelSteps ? { maxParallelSteps: input.policy.maxParallelSteps } : {}), ...(input.policy.limits ? { limits: input.policy.limits } : {}), ...(input.signal ? { signal: input.signal } : {}), ...(maxCalls !== undefined ? { callBudget: maxCalls } : {}) });
         allObservations.push(...exec.observations);
+        if (exec.stoppedForBudget) {
+            const done = plan.steps.filter((s) => s.status === 'succeeded').length;
+            return {
+                status: 'waiting_for_budget',
+                plan,
+                planHistory,
+                observations: [...allObservations],
+                budget: { estCalls, maxCalls: maxCalls, completedSteps: done, totalSteps: plan.steps.length },
+                summary: `Ran ${done} of ${plan.steps.length} step(s) within the ${maxCalls}-call budget. Raise the budget (AI_MAX_CALLS) and resume to continue.`,
+            };
+        }
         if (exec.ok)
             return { status: 'completed', plan, planHistory, observations: [...allObservations], summary: `completed "${plan.goal}" in ${plan.steps.length} step(s)` };
         // Failed: gather evidence and replan (orchestrate only) or stop.

package/dist/orchestration/plan.d.ts

@@ -3,7 +3,9 @@
  * REGISTERED skill or tool; a plan referencing anything unregistered is invalid (never executed). Plans
  * are data: the model proposes them, the Runtime owns execution and permission enforcement.
  */
-export type PlanStepStatus = 'pending' | 'running' | 'succeeded' | 'failed' | 'skipped';
+/** The five step statuses. A const array as well as a type, so a projection table can be checked. */
+export declare const PLAN_STEP_STATUSES: readonly ["pending", "running", "succeeded", "failed", "skipped"];
+export type PlanStepStatus = (typeof PLAN_STEP_STATUSES)[number];
 export interface PlanStep {
     id: string;
     description: string;
@@ -11,6 +13,10 @@ export interface PlanStep {
     skill?: string;
     /** A registered tool id. */
     tool?: string;
+    /** A registered AGENT DEFINITION id (Phase 3.4). skill/tool/agent are mutually exclusive per step. */
+    agent?: string;
+    /** Finding ids this step was created to address (Phase 3.4). Additive; persisted with the plan. */
+    motivatedBy?: string[];
     input?: unknown;
     /** Ids of steps that must succeed first. */
     dependsOn?: string[];
@@ -27,11 +33,19 @@ export interface ExecutionPlan {
 export interface PlanValidation {
     ok: boolean;
     errors: string[];
+    /** Phase 3.1: the unregistered references behind the `unknown skill/tool` errors, as structured data.
+     *  Additive — `errors` is unchanged and remains the source of truth for messages. */
+    missing?: Array<{
+        stepId: string;
+        kind: 'skill' | 'tool';
+        id: string;
+    }>;
 }
 /** Validate that every step references a registered skill/tool and dependencies/DAG are sound. */
 export declare function validatePlan(plan: ExecutionPlan, available: {
     skills: string[];
     tools: string[];
+    agents?: string[];
 }): PlanValidation;
 /** A topological execution order → array of "waves" (each wave's steps can run in parallel). */
 export declare function executionWaves(steps: PlanStep[]): PlanStep[][];

package/dist/orchestration/plan.js

@@ -3,25 +3,44 @@
  * REGISTERED skill or tool; a plan referencing anything unregistered is invalid (never executed). Plans
  * are data: the model proposes them, the Runtime owns execution and permission enforcement.
  */
+/** The five step statuses. A const array as well as a type, so a projection table can be checked. */
+export const PLAN_STEP_STATUSES = ['pending', 'running', 'succeeded', 'failed', 'skipped'];
 /** Validate that every step references a registered skill/tool and dependencies/DAG are sound. */
 export function validatePlan(plan, available) {
     const errors = [];
+    const missing = [];
     const skills = new Set(available.skills);
     const tools = new Set(available.tools);
+    // Phase 3.4: `agents` is OPTIONAL. Absent ⇒ agent execution is not enabled, and every check below
+    // that mentions an agent is unreachable, so validation is byte-identical to 2.6.0.
+    const agents = new Set(available.agents ?? []);
     const ids = new Set(plan.steps.map((s) => s.id));
     if (plan.steps.length === 0)
         errors.push('plan has no steps');
     if (ids.size !== plan.steps.length)
         errors.push('plan has duplicate step ids'); // dupes would silently drop a step
     for (const step of plan.steps) {
-        if (!step.skill && !step.tool)
+        // With no step naming an agent, `named === 0` is exactly `!step.skill && !step.tool`, so this is the
+        // 2.6.0 condition and the 2.6.0 message, verbatim.
+        const named = [step.skill, step.tool, step.agent].filter((v) => v !== undefined && v !== '').length;
+        if (named === 0)
             errors.push(`step ${step.id}: names neither a skill nor a tool`);
         if (step.skill && step.tool)
             errors.push(`step ${step.id}: names both a skill and a tool`);
-        if (step.skill && !skills.has(step.skill))
+        if (step.agent && (step.skill || step.tool))
+            errors.push(`step ${step.id}: names both an agent and a skill/tool`);
+        if (step.agent && !available.agents)
+            errors.push(`step ${step.id}: agent execution is not enabled`);
+        else if (step.agent && !agents.has(step.agent))
+            errors.push(`step ${step.id}: unknown agent '${step.agent}'`);
+        if (step.skill && !skills.has(step.skill)) {
             errors.push(`step ${step.id}: unknown skill '${step.skill}'`);
-        if (step.tool && !tools.has(step.tool))
+            missing.push({ stepId: step.id, kind: 'skill', id: step.skill });
+        }
+        if (step.tool && !tools.has(step.tool)) {
             errors.push(`step ${step.id}: unknown tool '${step.tool}'`);
+            missing.push({ stepId: step.id, kind: 'tool', id: step.tool });
+        }
         for (const dep of step.dependsOn ?? []) {
             if (!ids.has(dep))
                 errors.push(`step ${step.id}: depends on unknown step '${dep}'`);
@@ -31,7 +50,7 @@ export function validatePlan(plan, available) {
     }
     if (hasCycle(plan.steps))
         errors.push('plan has a dependency cycle');
-    return { ok: errors.length === 0, errors };
+    return { ok: errors.length === 0, errors, ...(missing.length ? { missing } : {}) };
 }
 function hasCycle(steps) {
     const deps = new Map(steps.map((s) => [s.id, s.dependsOn ?? []]));

package/dist/orchestration/planner.d.ts

@@ -6,7 +6,9 @@
 import type { AI } from '../plugin/ai.js';
 import type { RoutingPreferences } from '../types.js';
 import type { Skill } from '../skills/skill.js';
-import type { ExecutionPlan } from './plan.js';
+import type { ExecutionPlan, PlanValidation } from './plan.js';
+import type { CapabilityGap } from '../capabilities/capability.js';
+import type { AgentEnvelope } from '../agents/envelope.js';
 export interface PlannerInput {
     goal: string;
     ai: AI;
@@ -16,6 +18,19 @@ export interface PlannerInput {
     reason?: string;
     /** Observations from a prior attempt, to inform a replan. */
     priorObservations?: string[];
+    /** Phase 3.1: a pre-rendered, capped, fenced action-capability snapshot. Absent ⇒ the prompt is
+     *  byte-identical to 2.3.0 (the catalog flag is off by default). */
+    capabilityCatalog?: string;
+    /** Phase 3.3: a pre-rendered, clamped block naming the capabilities the goal was derived to need and
+     *  the provider chosen for each. Absent ⇒ the prompt is byte-identical (the flag is off by default). */
+    requiredCapabilities?: string;
+    /** Phase 3.4: the narrowed agent envelopes available to this plan. Absent ⇒ the prompt carries no
+     *  agent rows and no agent schema line, and `validatePlan` rejects any agent step. */
+    agents?: AgentEnvelope[];
+    /** Phase 3.4: a pre-rendered, FENCED, bounded block of active findings from completed agent steps. */
+    findings?: string;
+    /** Phase 3.1: resolves unregistered references into structured gaps for the failure result. */
+    resolveGaps?: (missing: NonNullable<PlanValidation['missing']>) => CapabilityGap[];
     /** User exclude/prefer routing applied to the planning model call. */
     routing?: RoutingPreferences;
 }
@@ -24,6 +39,9 @@ export interface PlannerResult {
     /** Set when the planner needs the user to disambiguate or enable a capability. */
     clarification?: string;
     error?: string;
+    /** Phase 3.1: structured capability gaps behind an `unknown skill/tool` failure (additive metadata —
+     *  `error` and `clarification` strings are unchanged). */
+    gaps?: CapabilityGap[];
 }
 /** Generate and validate a plan for a goal. */
 export declare function generatePlan(input: PlannerInput): Promise<PlannerResult>;

package/dist/orchestration/planner.js

@@ -4,10 +4,16 @@
  * execute. When nothing maps to the goal, the planner surfaces a clarification rather than guessing.
  */
 import { validatePlan } from './plan.js';
-function catalog(skills, tools) {
+function catalog(skills, tools, agents) {
     const skillLines = skills.map((s) => `  - skill "${s.id}": ${s.description}`).join('\n') || '  (none)';
     const toolLines = tools.map((t) => `  - tool "${t}"`).join('\n') || '  (none)';
-    return `Available skills:\n${skillLines}\nAvailable tools:\n${toolLines}`;
+    const base = `Available skills:\n${skillLines}\nAvailable tools:\n${toolLines}`;
+    // Phase 3.4: agent rows appear ONLY when envelopes were supplied, so the block above is byte-identical
+    // whenever agents are disabled. The objective is already clamped by `narrowEnvelope`.
+    if (!agents?.length)
+        return base;
+    const agentLines = agents.map((a) => `  - agent "${a.agentId}": ${a.objective}`).join('\n');
+    return `${base}\nAvailable agents (delegate a bounded sub-task):\n${agentLines}`;
 }
 /** Generate and validate a plan for a goal. */
 export async function generatePlan(input) {
@@ -17,8 +23,19 @@ export async function generatePlan(input) {
     const prompt = [
         `Goal: ${input.goal}`,
         input.priorObservations?.length ? `Prior attempt observations:\n${input.priorObservations.map((o) => `  - ${o}`).join('\n')}` : '',
-        catalog(input.skills, input.tools),
+        catalog(input.skills, input.tools, input.agents),
+        // Phase 3.1: opt-in capability snapshot (pre-rendered, capped, fenced by the caller). Absent by
+        // default, so the prompt above stays byte-identical to 2.3.0.
+        input.capabilityCatalog ? input.capabilityCatalog : '',
+        // Phase 3.3: opt-in derived-requirement block (pre-rendered + clamped by the caller). Falsy when
+        // absent, so `.filter(Boolean)` leaves the prompt above byte-identical.
+        input.requiredCapabilities ? input.requiredCapabilities : '',
+        // Phase 3.4: the findings block is pre-rendered, fenced, and bounded by the caller. Falsy when
+        // absent, so `.filter(Boolean)` leaves the prompt above unchanged.
+        input.findings ? input.findings : '',
         'Produce a minimal JSON plan: {"steps":[{"id","description","skill" OR "tool","input","dependsOn":[ids]}]}.',
+        // Phase 3.4: only mentioned when agents are actually available.
+        input.agents?.length ? 'A step may instead delegate to an agent: {"id","description","agent":"<id>","input","dependsOn":[ids]}. Use an agent for a bounded sub-task that needs its own plan.' : '',
         'Use ONLY the skills/tools listed above. If nothing fits, return {"steps":[],"clarification":"<question>"}.',
     ]
         .filter(Boolean)
@@ -47,6 +64,8 @@ export async function generatePlan(input) {
         description: s.description ?? '',
         ...(s.skill ? { skill: s.skill } : {}),
         ...(s.tool ? { tool: s.tool } : {}),
+        ...(s.agent ? { agent: s.agent } : {}),
+        ...(Array.isArray(s.motivatedBy) ? { motivatedBy: s.motivatedBy.filter((x) => typeof x === 'string') } : {}),
         ...(s.input !== undefined ? { input: s.input } : {}),
         ...(Array.isArray(s.dependsOn) ? { dependsOn: s.dependsOn } : {}),
         status: 'pending',
@@ -58,12 +77,13 @@ export async function generatePlan(input) {
         steps,
         ...(input.reason ? { reason: input.reason } : {}),
     };
-    const validation = validatePlan(plan, { skills: input.skills.map((s) => s.id), tools: input.tools });
+    const validation = validatePlan(plan, { skills: input.skills.map((s) => s.id), tools: input.tools, ...(input.agents ? { agents: input.agents.map((a) => a.agentId) } : {}) });
     if (!validation.ok) {
         // Empty plan with no steps → treat as "nothing to do / needs clarification" rather than a hard error.
         if (steps.length === 0)
             return { clarification: 'I could not form a plan for this goal. Can you clarify what you want done?' };
-        return { error: `invalid plan: ${validation.errors.join('; ')}` };
+        const gaps = validation.missing && input.resolveGaps ? input.resolveGaps(validation.missing) : undefined;
+        return { error: `invalid plan: ${validation.errors.join('; ')}`, ...(gaps && gaps.length ? { gaps } : {}) };
     }
     return { plan };
 }

package/dist/plugin/ai.d.ts

@@ -23,6 +23,10 @@ export interface AIOptions {
     env?: NodeJS.ProcessEnv;
     /** Extra telemetry sinks for centralized observability (e.g. a collector exporter). */
     sinks?: TelemetrySink[];
+    /** Phase 19: per-provider in-flight concurrency caps (id → max concurrent calls). Shared across all runs. */
+    concurrency?: {
+        perProvider?: Record<string, number>;
+    };
 }
 /** A key-free view of a registered provider — safe to return from the public API. */
 export interface ProviderInfo {

package/dist/plugin/ai.js

@@ -10,6 +10,7 @@ import { resolveConfig } from '../config/defaults.js';
 import { loadConfigAsync } from '../config/load.js';
 import { MemorySink, MultiSink } from '../telemetry/telemetry.js';
 import { FileSink } from '../telemetry/sinks/file.js';
+import { OtlpSink } from '../telemetry/sinks/otlp.js';
 import { HealthMonitor } from '../core/health/monitor.js';
 import { PerformanceStore } from '../learning/performanceStore.js';
 import { CapabilityOverlay } from '../core/capabilities/overlay.js';
@@ -18,6 +19,7 @@ import { buildProvider } from '../providers/factory.js';
 import { McpRegistry } from '../mcp/mcp.js';
 import { presetToConfig } from '../marketplace/presets.js';
 import { generateProviderConfig, generateProviderConfigFromFile } from '../generation/generateAdapter.js';
+import { KeyedSemaphore } from '../util/semaphore.js';
 export class AI {
     config;
     registry = new ProviderRegistry();
@@ -36,12 +38,18 @@ export class AI {
         const sinks = [memory];
         if (this.config.telemetry.enabled && this.config.telemetry.sink === 'file' && this.config.telemetry.path)
             sinks.push(new FileSink(this.config.telemetry.path));
+        if (this.config.telemetry.enabled && this.config.telemetry.sink === 'otlp' && this.config.telemetry.endpoint) {
+            const authEnv = this.config.telemetry.headersEnv;
+            const authHeader = authEnv ? (options.env ?? process.env)[authEnv] : undefined;
+            sinks.push(new OtlpSink({ endpoint: this.config.telemetry.endpoint, ...(options.fetchImpl ? { fetchImpl: options.fetchImpl } : {}), ...(authHeader ? { authHeader } : {}) }));
+        }
         if (options.sinks)
             sinks.push(...options.sinks);
         this.telemetry = sinks.length > 1 ? new MultiSink(sinks) : memory;
         this.health = new HealthMonitor(this.telemetry, options.clock);
         if (this.config.learning.enabled)
             this.performance = new PerformanceStore();
+        const providerLimiter = options.concurrency?.perProvider ? new KeyedSemaphore(options.concurrency.perProvider) : undefined;
         this.router = new Router({
             registry: this.registry,
             tasks: this.tasks,
@@ -51,6 +59,7 @@ export class AI {
             overlay: this.overlay,
             ...(this.performance ? { performance: this.performance } : {}),
             ...(options.clock ? { clock: options.clock } : {}),
+            ...(providerLimiter?.active ? { providerLimiter } : {}),
         });
         // Build concrete adapters from config (credential resolved from the env-var NAME). Providers of
         // kind 'mock' are registered programmatically instead.

package/dist/providers/httpClient.d.ts

@@ -11,7 +11,8 @@
  * caller built, never in anything this function stores or throws.
  */
 import type { Clock } from '../util/clock.js';
-import type { WireRequest } from './wire/types.js';
+import type { FinishReason } from '../types.js';
+import type { WireDelta, WireRequest } from './wire/types.js';
 export type FetchLike = typeof fetch;
 export interface CallHttpInput {
     build: (jsonMode: boolean) => WireRequest;
@@ -32,3 +33,26 @@ export interface CallHttpResult {
     jsonModeUsed: boolean;
 }
 export declare function callHttp(input: CallHttpInput): Promise<CallHttpResult>;
+export interface CallHttpStreamInput {
+    build: (jsonMode: boolean) => WireRequest;
+    readDelta: (data: string) => WireDelta;
+    onDelta: (text: string) => void;
+    providerId: string;
+    model: string;
+    timeoutMs: number;
+    jsonMode: boolean;
+    fetchImpl?: FetchLike;
+    clock?: Clock;
+    signal?: AbortSignal;
+}
+export interface CallHttpStreamResult {
+    status: number;
+    text: string;
+    usage?: {
+        inputTokens?: number;
+        outputTokens?: number;
+    };
+    finishReason: FinishReason;
+    durationMs: number;
+}
+export declare function callHttpStream(input: CallHttpStreamInput): Promise<CallHttpStreamResult>;

package/dist/providers/httpClient.js

@@ -78,3 +78,96 @@ export async function callHttp(input) {
     }
     throw lastError ?? new AIError(`${providerId} request failed`, { category: 'NETWORK', retryable: true, providerId, model });
 }
+export async function callHttpStream(input) {
+    const fetchImpl = input.fetchImpl ?? fetch;
+    const clock = input.clock ?? systemClock;
+    const { providerId, model } = input;
+    const started = clock.now();
+    const req = input.build(input.jsonMode);
+    // Combine the per-request timeout with any caller abort signal (cancellation).
+    const signals = [AbortSignal.timeout(input.timeoutMs)];
+    if (input.signal)
+        signals.push(input.signal);
+    const signal = signals.length > 1 ? AbortSignal.any(signals) : signals[0];
+    let res;
+    try {
+        res = await fetchImpl(req.url, { method: 'POST', headers: req.headers, body: JSON.stringify(req.body), signal });
+    }
+    catch (e) {
+        // undici embeds the full URL in the message — use only the error NAME, never the message.
+        const name = e instanceof Error ? e.name : 'Error';
+        const isTimeout = name === 'TimeoutError' || name === 'AbortError';
+        throw new AIError(`${providerId} stream request failed (${name})`, { category: isTimeout ? 'TIMEOUT' : 'NETWORK', retryable: true, providerId, model });
+    }
+    if (!res.ok || !res.body) {
+        const text = await res.text().catch(() => '');
+        const excerpt = redactString(text.slice(0, 300));
+        const category = statusToCategory(res.status);
+        throw new AIError(`${providerId} stream returned HTTP ${res.status}: ${excerpt}`, { category, status: res.status, retryable: isRetryable(category), providerId, model });
+    }
+    const reader = res.body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = '';
+    let text = '';
+    let usage;
+    let finishReason = 'stop';
+    let done = false;
+    const handleData = (payload) => {
+        if (!payload)
+            return;
+        const delta = input.readDelta(payload);
+        if (delta.text) {
+            text += delta.text;
+            input.onDelta(delta.text);
+        }
+        if (delta.usage)
+            usage = { ...usage, ...delta.usage };
+        if (delta.finishReason)
+            finishReason = delta.finishReason;
+        if (delta.done)
+            done = true;
+    };
+    try {
+        try {
+            while (!done) {
+                const { value, done: streamDone } = await reader.read();
+                if (streamDone)
+                    break;
+                buffer += decoder.decode(value, { stream: true });
+                // Process complete lines; keep the trailing partial in the buffer.
+                let nl;
+                while ((nl = buffer.indexOf('\n')) >= 0) {
+                    const line = buffer.slice(0, nl).replace(/\r$/, '');
+                    buffer = buffer.slice(nl + 1);
+                    if (line.startsWith('data:'))
+                        handleData(line.slice(5).trim());
+                    // `event:` / blank / comment (`:`) lines are ignored — the type is in the data JSON.
+                    if (done)
+                        break;
+                }
+            }
+            // Flush a final line that had no trailing newline.
+            if (!done && buffer.startsWith('data:'))
+                handleData(buffer.slice(5).trim());
+        }
+        finally {
+            try {
+                await reader.cancel();
+            }
+            catch {
+                /* nothing to do */
+            }
+        }
+    }
+    catch (e) {
+        // A mid-stream drop/timeout after 200 OK: categorize and sanitize like the initial-fetch path (undici
+        // embeds the full URL in the message — use only the error NAME, never the message).
+        const name = e instanceof Error ? e.name : 'Error';
+        const isTimeout = name === 'TimeoutError' || name === 'AbortError';
+        throw new AIError(`${providerId} stream interrupted (${name})`, { category: isTimeout ? 'TIMEOUT' : 'NETWORK', retryable: true, providerId, model });
+    }
+    const result = { status: res.status, text, finishReason, durationMs: clock.now() - started };
+    if (usage)
+        result.usage = usage;
+    return result;
+}

package/dist/providers/httpProvider.d.ts

@@ -46,4 +46,5 @@ export declare class HttpProvider implements AIProvider {
     getCapabilities(model: string): Promise<CapabilityProfile>;
     estimate(request: AIRequest): Promise<ExecutionEstimate>;
     execute(request: AIRequest): Promise<AIResponse>;
+    executeStream(request: AIRequest, onDelta: (chunk: string) => void): Promise<AIResponse>;
 }

package/dist/providers/httpProvider.js

@@ -12,7 +12,7 @@ import { AIError } from '../core/fallback/errors.js';
 import { emptyProfile } from '../core/capabilities/evidence.js';
 import { extractJson } from '../util/extractJson.js';
 import { getWire } from './wire/registry.js';
-import { callHttp } from './httpClient.js';
+import { callHttp, callHttpStream } from './httpClient.js';
 function originOf(url) {
     try {
         return new URL(url).origin;
@@ -132,4 +132,70 @@ export class HttpProvider {
         }
         return response;
     }
+    async executeStream(request, onDelta) {
+        const wire = getWire(this.cfg.wireShape);
+        const wantsJson = request.output?.format === 'json' || request.output?.format === 'structured_output';
+        // JSON output, or a wire without streaming support, degrades to the normal single-shot path.
+        if (wantsJson || !wire.buildStreamRequest || !wire.readDelta)
+            return this.execute(request);
+        const needsKey = this.cfg.requiresKey !== false;
+        const apiKey = this.cfg.credential.use();
+        if (needsKey && !apiKey) {
+            throw new AIError(`no ${this.cfg.credential.envName ?? 'API key'} in the environment`, { category: 'AUTHENTICATION', retryable: false, providerId: this.id, model: request.model });
+        }
+        const maxTokens = request.params?.maxTokens ?? 2000;
+        const ctx = {
+            baseUrl: this.cfg.baseUrl,
+            model: request.model,
+            maxTokens,
+            ...(apiKey ? { apiKey } : {}),
+            ...(this.cfg.headers ? { headers: this.cfg.headers } : {}),
+        };
+        // Graceful degrade: if the stream fails BEFORE any token (a gateway that doesn't do SSE, or 400s on
+        // the streaming body), fall back to buffered execute() so a non-streaming endpoint still works — the
+        // caller just doesn't get live tokens. Once tokens have flowed we can't degrade (would double-emit),
+        // so we rethrow and let the router fall back to a different candidate.
+        let emitted = 0;
+        let result;
+        try {
+            result = await callHttpStream({
+                build: (jsonMode) => wire.buildStreamRequest(request, ctx, jsonMode),
+                readDelta: (data) => wire.readDelta(data),
+                onDelta: (chunk) => {
+                    emitted += 1;
+                    onDelta(chunk);
+                },
+                providerId: this.id,
+                model: request.model,
+                timeoutMs: request.timeoutMs || this.cfg.timeoutMs || 90_000,
+                jsonMode: this.jsonMode,
+                ...(this.cfg.fetchImpl ? { fetchImpl: this.cfg.fetchImpl } : {}),
+                ...(this.cfg.clock ? { clock: this.cfg.clock } : {}),
+                ...(request.signal ? { signal: request.signal } : {}),
+            });
+        }
+        catch (e) {
+            if (emitted === 0)
+                return this.execute(request);
+            throw e;
+        }
+        const response = {
+            finishReason: result.finishReason,
+            providerId: this.id,
+            model: request.model,
+            latencyMs: result.durationMs,
+        };
+        if (result.text)
+            response.text = result.text;
+        if (result.usage) {
+            const inTok = result.usage.inputTokens;
+            const outTok = result.usage.outputTokens;
+            response.usage = {
+                ...(inTok !== undefined ? { inputTokens: inTok } : {}),
+                ...(outTok !== undefined ? { outputTokens: outTok } : {}),
+                ...(inTok !== undefined && outTok !== undefined ? { totalTokens: inTok + outTok } : {}),
+            };
+        }
+        return response;
+    }
 }

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

@@ -32,4 +32,7 @@ export declare class MockProvider implements AIProvider {
     getCapabilities(model: string): Promise<CapabilityProfile>;
     estimate(request: AIRequest): Promise<ExecutionEstimate>;
     execute(request: AIRequest): Promise<AIResponse>;
+    /** Stream text chunks then resolve with the full aggregate (Phase 13). Failure behaviors still throw. */
+    executeStream(request: AIRequest, onDelta: (chunk: string) => void): Promise<AIResponse>;
+    private respond;
 }