ai-runtime-engine 1.2.0 → 1.3.0

package/CHANGELOG.md

@@ -5,6 +5,29 @@ All notable changes to `ai-runtime` are documented here. The format follows
 Versioning](https://semver.org/). Development history and rationale live in
 [docs/DECISIONS.md](docs/DECISIONS.md) and [docs/PROGRESS.md](docs/PROGRESS.md).
 
+## [1.3.0] — 2026-09-01
+
+Token-by-token streaming. Additive and backward compatible — every new field is optional and, with
+streaming unconfigured, behavior is identical to 1.2.0.
+
+### Added
+
+- **Streaming responses end-to-end (`response.delta`)** — the reserved streaming event is now emitted for
+  real. Opt in with `stream: true` + `onDelta` on `AI.run()`/`RunRequest`, or `runtime.run({ stream: true })`
+  in chat mode. Text output only (a JSON/structured request never streams). Implemented through the one
+  router: optional `AIProvider.executeStream`, optional wire `buildStreamRequest`/`readDelta` for the
+  OpenAI-compatible and Anthropic shapes, and an SSE reader (`callHttpStream`) that buffers across network
+  boundaries. `AIResponse` is unchanged and remains the full aggregate — deltas ride the event channel.
+- **Live rendering in the terminal** — the interactive REPL renders answers token-by-token (toggle with
+  `/stream`), and one-shot `ai-runtime run --stream` does the same. Streamed text is redacted like every
+  egress and is never reprinted after it streams.
+
+### Reliability
+
+- A provider whose gateway doesn't support SSE **degrades gracefully to a buffered call** before the first
+  token, so enabling streaming never breaks a non-streaming endpoint. A mid-stream drop is categorized and
+  sanitized (never leaks the request URL) and falls back to the next candidate.
+
 ## [1.2.0] — 2026-08-31
 
 Closes the known gaps between what the CLI/REPL exposed and what the Runtime supported. Additive and
@@ -107,6 +130,7 @@ Initial release: the provider-agnostic AI **router** — capability-based routin
 scoring, evidence validation, fallback, health tracking, learning-based scoring, multi-model verification,
 budgets, MCP tools, OpenAPI-based adapter generation, and the `AI` class + CLI.
 
+[1.3.0]: https://github.com/pavankhandelwal21/ai-runtime/releases/tag/v1.3.0
 [1.2.0]: https://github.com/pavankhandelwal21/ai-runtime/releases/tag/v1.2.0
 [1.1.1]: https://github.com/pavankhandelwal21/ai-runtime/releases/tag/v1.1.1
 [1.1.0]: https://github.com/pavankhandelwal21/ai-runtime/releases/tag/v1.1.0

package/dist/cli/cli.js

@@ -20,7 +20,7 @@ import { skillsCommand } from './commands/skills.js';
 import { startRepl } from './interactive/repl.js';
 import { printError } from './render.js';
 const program = new Command();
-program.name('ai-runtime').description('Universal, provider-agnostic AI Runtime & Orchestration Platform').version('1.2.0');
+program.name('ai-runtime').description('Universal, provider-agnostic AI Runtime & Orchestration Platform').version('1.3.0');
 const configOpt = ['-c, --config <path>', 'path to an ai-runtime config file'];
 // Bare `ai-runtime` (no subcommand) opens the interactive terminal. `allowExcessArguments(false)` keeps
 // a mistyped subcommand (e.g. `ai-runtime porviders`) failing fast instead of silently opening the REPL.
@@ -35,6 +35,7 @@ program
     .option(...configOpt)
     .option('--json', 'print the full RuntimeResult as JSON')
     .option('--dry-run', 'plan and report what would happen without making any changes')
+    .option('--stream', 'stream the answer token-by-token (text output only)')
     .action((input, o) => runCommand(input, o));
 program
     .command('executions')

package/dist/cli/commands/run.d.ts

@@ -7,5 +7,6 @@ export interface RunOptions {
     config?: string;
     json?: boolean;
     dryRun?: boolean;
+    stream?: boolean;
 }
 export declare function runCommand(input: string, options: RunOptions): Promise<void>;

package/dist/cli/commands/run.js

@@ -3,13 +3,24 @@
  * the interactive REPL uses. Prints the response (or a structured result with --json).
  */
 import { Runtime } from '../../runtime/runtime.js';
-import { print } from '../render.js';
+import { print, printChunk } from '../render.js';
 import { RUNTIME_MODES } from '../../runtime/types.js';
 export async function runCommand(input, options) {
     const rt = await Runtime.load({ ...(options.config ? { config: options.config } : {}) });
     const req = { input };
     if (options.dryRun)
         req.dryRun = true;
+    // --stream renders tokens live (incompatible with --json, which needs the whole object).
+    let streamedAny = false;
+    if (options.stream && !options.json) {
+        req.stream = true;
+        rt.on((e) => {
+            if (e.type === 'response.delta') {
+                printChunk(e.text);
+                streamedAny = true;
+            }
+        });
+    }
     if (options.mode) {
         if (!RUNTIME_MODES.includes(options.mode)) {
             print(`invalid mode '${options.mode}'. valid: ${RUNTIME_MODES.join(', ')}`);
@@ -19,9 +30,11 @@ export async function runCommand(input, options) {
         req.mode = options.mode;
     }
     const result = await rt.run(req);
+    if (streamedAny)
+        process.stdout.write('\n');
     if (options.json)
         return print(JSON.stringify(result, null, 2));
-    if (result.response?.text)
+    if (result.response?.text && !result.response.streamed)
         print(result.response.text);
     else if (result.response?.json !== undefined)
         print(JSON.stringify(result.response.json, null, 2));

package/dist/cli/interactive/repl.js

@@ -4,7 +4,7 @@
  */
 import { createInterface } from 'node:readline';
 import { Runtime } from '../../runtime/runtime.js';
-import { print, printError } from '../render.js';
+import { print, printChunk, printError } from '../render.js';
 import { summarizeWorkspace } from '../../runtime/workspace/workspace.js';
 import { ReplSession } from './session.js';
 function banner(rt) {
@@ -31,10 +31,16 @@ function progressLine(e) {
 /** Start the interactive session. Resolves when the user exits (or stdin closes). */
 export async function startRepl(configPath) {
     const rt = await Runtime.load({ ...(configPath ? { config: configPath } : {}) });
-    const session = new ReplSession(rt);
-    // Live progress: print concise routing/mode lines as they happen during a run. The events are already
-    // redacted; a throwing observer can never break a run (the emitter swallows sink errors).
+    const session = new ReplSession(rt, { streaming: true });
+    // Tracks whether the CURRENT line produced any streamed output, so we can close the line cleanly.
+    let streamedThisRun = false;
+    // Live progress + token streaming. Events are already redacted; a throwing observer can't break a run.
     rt.on((e) => {
+        if (e.type === 'response.delta') {
+            printChunk(e.text);
+            streamedThisRun = true;
+            return;
+        }
         const line = progressLine(e);
         if (line)
             print(line);
@@ -44,14 +50,19 @@ export async function startRepl(configPath) {
     rl.prompt();
     for await (const line of rl) {
         let result;
+        streamedThisRun = false;
         try {
             result = await session.handle(line);
         }
         catch (err) {
+            if (streamedThisRun)
+                process.stdout.write('\n');
             printError(`error: ${err instanceof Error ? err.message : String(err)}`);
             rl.prompt();
             continue;
         }
+        if (streamedThisRun)
+            process.stdout.write('\n'); // close the streamed line before printing result lines
         if (result.clear)
             process.stdout.write('\x1b[2J\x1b[H');
         for (const l of result.lines)

package/dist/cli/interactive/session.d.ts

@@ -16,7 +16,10 @@ export declare class ReplSession {
     private viewCache?;
     private conversationId?;
     private dryRunMode;
-    constructor(runtime: Runtime);
+    private streaming;
+    constructor(runtime: Runtime, opts?: {
+        streaming?: boolean;
+    });
     currentMode(): RuntimeMode;
     private views;
     handle(raw: string): Promise<HandleResult>;

package/dist/cli/interactive/session.js

@@ -42,6 +42,7 @@ 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',
     '  /clear                      clear the screen',
     '  /exit                       leave the session',
     '',
@@ -53,8 +54,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;
@@ -133,6 +136,9 @@ 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 'memory':
                 return this.memory(args);
             case 'conversations':
@@ -161,9 +167,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));

package/dist/cli/render.d.ts

@@ -4,4 +4,10 @@
  * 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;

package/dist/cli/render.js

@@ -8,6 +8,14 @@ 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));

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

@@ -19,6 +19,9 @@ 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. */

package/dist/core/fallback/fallback.js

@@ -34,7 +34,7 @@ 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 = 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.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,6 +141,7 @@ 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 } : {}),
         });

package/dist/index.d.ts

@@ -20,7 +20,7 @@ export type { FetchLike } from './providers/httpClient.js';
 export { PROVIDER_DEFAULTS } from './config/providerDefaults.js';
 export { resolveModelMetadata } from './discovery/modelCatalog.js';
 export { registerWire } from './providers/wire/registry.js';
-export type { WireModule, WireShape } from './providers/wire/types.js';
+export type { WireDelta, WireModule, WireShape } from './providers/wire/types.js';
 export { AIError, isRetryable, statusToCategory, toAIError } from './core/fallback/errors.js';
 export { capabilitySatisfies, emptyProfile, getCapability, mergeProfiles, profileFromDeclared, rankOf, } from './core/capabilities/evidence.js';
 export { AGENT_CAPABILITIES, INPUT_MODALITIES, INTELLIGENCE_SKILLS, OUTPUT_MODALITIES, } from './core/capabilities/taxonomy.js';

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

package/dist/providers/mock/mockProvider.js

@@ -67,11 +67,45 @@ export class MockProvider {
     }
     async execute(request) {
         this.executeCalls += 1;
+        return this.respond(request);
+    }
+    /** Stream text chunks then resolve with the full aggregate (Phase 13). Failure behaviors still throw. */
+    async executeStream(request, onDelta) {
+        this.executeCalls += 1;
+        const behavior = typeof this.behavior === 'function' ? this.behavior(request) : this.behavior;
+        // JSON output never streams — fall back to the single-shot response (no deltas).
+        const wantsJson = request.output?.format === 'json' || request.output?.format === 'structured_output';
+        if (wantsJson || behavior.kind === 'malformed' || behavior.kind === 'timeout' || behavior.kind === 'rate_limit' || behavior.kind === 'server_error' || behavior.kind === 'auth_fail') {
+            return this.respond(request); // throws for failure kinds, single-shot for json
+        }
+        // Stream some chunks, THEN fail mid-stream (exercises the partial-then-fallback path).
+        if (behavior.kind === 'stream_then_fail') {
+            for (const c of behavior.chunks)
+                onDelta(c);
+            throw new AIError(`${this.id} dropped mid-stream`, { category: 'PROVIDER', status: 503, providerId: this.id, model: request.model });
+        }
+        const full = behavior.kind === 'ok_stream' || behavior.kind === 'ok' || behavior.kind === 'ok_text' ? behavior.text ?? `mock(${this.id}/${request.model}) streamed ${request.taskId}` : '';
+        const chunks = behavior.kind === 'ok_stream' && behavior.chunks ? behavior.chunks : chunkText(full);
+        for (const c of chunks)
+            onDelta(c);
+        return {
+            finishReason: 'stop',
+            providerId: this.id,
+            model: request.model,
+            latencyMs: this.latencyMs,
+            text: chunks.join(''),
+            usage: { inputTokens: Math.ceil((request.input.text?.length ?? 0) / 4), outputTokens: chunks.length },
+        };
+    }
+    respond(request) {
         const behavior = typeof this.behavior === 'function' ? this.behavior(request) : this.behavior;
         const base = { providerId: this.id, model: request.model };
         switch (behavior.kind) {
             case 'timeout':
                 throw new AIError(`${this.id} timed out`, { category: 'TIMEOUT', ...base });
+            case 'stream_then_fail':
+                // Non-streaming caller: no partial output, just the failure.
+                throw new AIError(`${this.id} dropped mid-stream`, { category: 'PROVIDER', status: 503, ...base });
             case 'rate_limit':
                 throw new AIError(`${this.id} rate limited`, { category: 'RATE_LIMIT', status: 429, ...base });
             case 'server_error':
@@ -116,6 +150,26 @@ export class MockProvider {
                     usage: { inputTokens: 4, outputTokens: 8 },
                 };
             }
+            case 'ok_stream': {
+                // Reached only via execute() (non-streaming caller): return the aggregate directly.
+                return {
+                    finishReason: 'stop',
+                    providerId: this.id,
+                    model: request.model,
+                    latencyMs: this.latencyMs,
+                    text: behavior.chunks ? behavior.chunks.join('') : behavior.text ?? `mock(${this.id}/${request.model}) streamed ${request.taskId}`,
+                    usage: { inputTokens: 4, outputTokens: 8 },
+                };
+            }
         }
     }
 }
+/** Split text into small deterministic chunks to simulate token streaming (join(chunks) === text). */
+function chunkText(text, size = 3) {
+    if (!text)
+        return [];
+    const out = [];
+    for (let i = 0; i < text.length; i += size)
+        out.push(text.slice(i, i + size));
+    return out;
+}

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

@@ -12,6 +12,13 @@ export type MockBehavior = {
 } | {
     kind: 'ok_text';
     text?: string;
+} | {
+    kind: 'ok_stream';
+    text?: string;
+    chunks?: string[];
+} | {
+    kind: 'stream_then_fail';
+    chunks: string[];
 } | {
     kind: 'timeout';
 } | {

package/dist/providers/provider.d.ts

@@ -22,5 +22,11 @@ export interface AIProvider {
     /** Resolve capabilities for one model. Providers own capability resolution; core never reads the catalog directly. */
     getCapabilities(model: string): Promise<CapabilityProfile>;
     execute(request: AIRequest): Promise<AIResponse>;
+    /**
+     * OPTIONAL streaming execution (Phase 13). Calls `onDelta` with each text chunk and resolves with the
+     * full aggregated `AIResponse`. A provider that omits it is still valid — the caller falls back to
+     * `execute()`. Text output only; a JSON-mode request should degrade to `execute()`.
+     */
+    executeStream?(request: AIRequest, onDelta: (chunk: string) => void): Promise<AIResponse>;
     estimate(request: AIRequest): Promise<ExecutionEstimate>;
 }

package/dist/providers/wire/anthropicWire.js

@@ -80,4 +80,38 @@ export const anthropicWire = {
         }
         return parsed;
     },
+    buildStreamRequest(req, ctx, jsonMode) {
+        const built = anthropicWire.buildRequest(req, ctx, jsonMode);
+        built.body.stream = true;
+        return built;
+    },
+    readDelta(data) {
+        // Anthropic SSE data payloads are always JSON objects with a `type`. The `event:` lines carry the
+        // same type, so we parse the data alone (the caller skips non-`data:` lines).
+        let j;
+        try {
+            j = JSON.parse(data);
+        }
+        catch {
+            return {};
+        }
+        switch (j.type) {
+            case 'content_block_delta':
+                return j.delta?.text ? { text: j.delta.text } : {};
+            case 'message_start':
+                return j.message?.usage?.input_tokens !== undefined ? { usage: { inputTokens: j.message.usage.input_tokens } } : {};
+            case 'message_delta': {
+                const out = {};
+                if (j.usage?.output_tokens !== undefined)
+                    out.usage = { outputTokens: j.usage.output_tokens };
+                if (j.delta?.stop_reason)
+                    out.finishReason = mapStop(j.delta.stop_reason);
+                return out;
+            }
+            case 'message_stop':
+                return { done: true };
+            default:
+                return {}; // ping / content_block_start / content_block_stop
+        }
+    },
 };

package/dist/providers/wire/openaiWire.js

@@ -78,4 +78,34 @@ export const openaiWire = {
         }
         return parsed;
     },
+    buildStreamRequest(req, ctx, jsonMode) {
+        // Same as buildRequest, plus `stream:true` and `stream_options.include_usage` so the final chunk
+        // carries token usage (supported by OpenAI and most compatible gateways; harmless where ignored).
+        const built = openaiWire.buildRequest(req, ctx, jsonMode);
+        const body = built.body;
+        body.stream = true;
+        body.stream_options = { include_usage: true };
+        return built;
+    },
+    readDelta(data) {
+        if (data.trim() === '[DONE]')
+            return { done: true };
+        let j;
+        try {
+            j = JSON.parse(data);
+        }
+        catch {
+            return {}; // a partial/keep-alive line — ignore
+        }
+        const out = {};
+        const content = j.choices?.[0]?.delta?.content;
+        if (content)
+            out.text = content;
+        const fr = j.choices?.[0]?.finish_reason;
+        if (fr)
+            out.finishReason = mapFinish(fr);
+        if (j.usage)
+            out.usage = { inputTokens: j.usage.prompt_tokens, outputTokens: j.usage.completion_tokens };
+        return out;
+    },
 };

package/dist/providers/wire/types.d.ts

@@ -28,12 +28,28 @@ export interface WireParsed {
     };
     finishReason: FinishReason;
 }
+/** One parsed streaming event (from a single SSE `data:` payload). All fields optional; `done` ends the stream. */
+export interface WireDelta {
+    /** A text chunk to append to the running answer (and surface to the caller). */
+    text?: string;
+    usage?: {
+        inputTokens?: number;
+        outputTokens?: number;
+    };
+    finishReason?: FinishReason;
+    /** The stream is complete (e.g. OpenAI `[DONE]`, Anthropic `message_stop`). */
+    done?: boolean;
+}
 export interface WireModule {
     readonly shape: WireShape;
     /** Pure request builder. `jsonMode` requests a JSON response format where the shape supports it. */
     buildRequest(req: AIRequest, ctx: WireContext, jsonMode: boolean): WireRequest;
     /** Parse a successful response body into normalized pieces. */
     readResponse(json: unknown): WireParsed;
+    /** OPTIONAL: build a streaming request (sets the vendor's `stream` flag). Absence ⇒ no streaming. */
+    buildStreamRequest?(req: AIRequest, ctx: WireContext, jsonMode: boolean): WireRequest;
+    /** OPTIONAL: parse one SSE `data:` payload string into a WireDelta. Pure (no socket). */
+    readDelta?(data: string): WireDelta;
 }
 /** Turn input parts into an OpenAI-style content value (string when text-only, array when multimodal). */
 export declare function toMultimodalContent(text: string | undefined, parts: AIRequest['input']['parts']): unknown;

package/dist/runtime/runtime.js

@@ -375,6 +375,18 @@ export class Runtime {
             return result;
         }
         const runRequest = buildChatRequest(req, strategy, compiled.system || undefined, routing);
+        // Streaming (Phase 13): text-only, chat-mode only, never on a dry run (handled above). Each chunk is
+        // emitted as a `response.delta` lifecycle event (redacted by the emitter). We also accumulate the raw
+        // chunks so we can mark the result `streamed` when the streamed text IS the final answer.
+        const streaming = req.stream === true && req.output?.format !== 'json' && req.output?.format !== 'structured_output';
+        let streamedText = '';
+        if (streaming) {
+            runRequest.stream = true;
+            runRequest.onDelta = (chunk) => {
+                streamedText += chunk;
+                this.emitter.emit({ type: 'response.delta', runId, text: chunk });
+            };
+        }
         const runResult = await this._ai.run(runRequest);
         this.calibrate(runRequest.system, text, runResult);
         const sel = runResult.routing.selected;
@@ -393,6 +405,12 @@ export class Runtime {
         if (memTrace)
             result.memory = memTrace;
         result.context = contextReport;
+        // Mark `streamed` only when the streamed chunks ARE the final answer (a clean single stream). If a
+        // streamed attempt failed and a fallback produced different text, they won't match → not streamed, so
+        // a renderer reprints the authoritative final text.
+        if (streaming && runResult.ok && result.response && streamedText.length > 0 && (result.response.text ?? '') === streamedText) {
+            result.response.streamed = true;
+        }
         return result;
     }
     /** The persistent execution store and its owner-lease machinery. */

package/dist/runtime/types.d.ts

@@ -89,6 +89,9 @@ export interface RuntimeRunInput {
     };
     /** Dry-run: plan + report what WOULD happen, performing zero mutations (plan/execute/orchestrate). */
     dryRun?: boolean;
+    /** Stream the answer token-by-token in chat mode: emits `response.delta` lifecycle events (Phase 13).
+     *  Text output only; ignored for JSON output and for dry runs. */
+    stream?: boolean;
     /** Caller idempotency identity (dedup enforced from Phase 7). */
     requestId?: string;
     /** Per-run exclude/prefer routing (highest precedence; merged with config + env). */
@@ -116,9 +119,12 @@ export interface RuntimeResult {
     runId: string;
     mode: ModeResolution;
     status: RuntimeStatus;
+    /** `streamed` is true when `text` was already delivered via `response.delta` events (Phase 13) — a
+     *  renderer that showed the deltas live should not reprint it. */
     response?: {
         text?: string;
         json?: unknown;
+        streamed?: boolean;
     };
     /** Present when the runtime needs the user to disambiguate. Never a failure. */
     clarification?: Clarification;

package/dist/types.d.ts

@@ -80,6 +80,8 @@ export interface AIRequest {
     signal?: AbortSignal;
     sensitivity: Sensitivity;
     metadata?: Record<string, unknown>;
+    /** Request token-by-token streaming (text output only). A provider without `executeStream` ignores it. */
+    stream?: boolean;
 }
 export type FinishReason = 'stop' | 'length' | 'tool_calls' | 'content_filter' | 'error';
 /** What every provider adapter returns — normalized so callers never parse vendor JSON. */
@@ -335,6 +337,10 @@ export interface RunRequest {
     verification?: boolean;
     /** Attach tools from registered MCP sources to this run (requires a tool-calling model). */
     mcp?: boolean;
+    /** Stream the answer token-by-token (text output only; ignored for JSON output). Needs `onDelta`. */
+    stream?: boolean;
+    /** Called with each text chunk as it streams. The final `AIResponse.text` is still the full aggregate. */
+    onDelta?: (chunk: string) => void;
 }
 /**
  * User exclude/prefer routing (all optional). EXCLUDE is a HARD filter — an excluded candidate is never

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-runtime-engine",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "AI Runtime — a provider-agnostic AI runtime and orchestration platform. Point it at whatever AI providers you have; it routes each task to the best available model. Ships the `ai-runtime` CLI and the `Runtime`/`AI` library API.",
   "type": "module",
   "license": "ISC",