ai-runtime-engine 1.1.1 → 1.3.0

package/CHANGELOG.md

@@ -5,6 +5,54 @@ 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
+backward compatible, with three small behavior corrections noted under Changed.
+
+### Added
+
+- **Approve / deny from the terminal** — `resume-execution --approve` / `--deny`, and REPL `/approve <id>`
+  / `/deny <id>`. A plan that stops at `waiting_for_approval` can now be advanced or cancelled from the
+  CLI or interactive terminal (previously reachable only programmatically or via a host `ApprovalProvider`).
+- **Live progress in the interactive terminal** — the REPL now prints concise mode/routing/fallback lines
+  during a run by subscribing to lifecycle events (it always claimed to, but never did).
+
+### Changed
+
+- **`chat` mode now honors `--dry-run` / `dryRun`** — a chat dry run makes **no** model call and captures
+  **no** memory; it reports what it would send. (Orchestration modes already did; chat used to run live.)
+- **`ai-runtime config`** now resolves `.ai-runtime/config.yaml` through the runtime loader, matching
+  every other command. It previously used the legacy root-only loader and reported "no config file found"
+  even when the canonical file was in use.
+- **`ai-runtime init`** now scaffolds the canonical `.ai-runtime/config.yaml` (same location as `setup`)
+  instead of a root `ai-runtime.yaml`. A root `ai-runtime.yaml` still works as a fallback if present.
+- **`ai-runtime telemetry`** empty-state message now explains that telemetry is buffered in-process and
+  points to `telemetry: { sink: file }` for history that survives across CLI invocations.
+
 ## [1.1.1] — 2026-08-31
 
 Documentation only — no code changes.
@@ -82,6 +130,9 @@ 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
 [1.0.0]: https://github.com/pavankhandelwal21/ai-runtime/releases/tag/v1.0.0
 [0.1.0]: https://github.com/pavankhandelwal21/ai-runtime/releases/tag/v0.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.1.1');
+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')
@@ -48,6 +49,8 @@ program
     .description('Resume a persisted execution (reconciles the workspace first)')
     .option(...configOpt)
     .option('--answer <text>', 'answer a pending clarification')
+    .option('--approve', 'approve a plan that is waiting for approval, then continue')
+    .option('--deny', 'deny a plan waiting for approval (cancels the execution)')
     .action((id, o) => resumeExecutionCommand(id, o));
 program.command('init').description('Scaffold ai-runtime.yaml, .env.example, and .gitignore entries').action(() => initCommand());
 program

package/dist/cli/commands/config.js

@@ -3,16 +3,18 @@
  * defaults). Shows weights, strategy, policy posture, and timeouts. No secrets are read or printed.
  */
 import { resolveConfig } from '../../config/defaults.js';
-import { loadConfig, findConfigFile } from '../../config/load.js';
+import { loadRuntimeConfig } from '../../runtime/config.js';
 import { print } from '../render.js';
 export function configCommand(options) {
-    const file = options.config ?? findConfigFile();
-    const resolved = resolveConfig(loadConfig(options.config));
+    // Use the runtime loader so `.ai-runtime/config.yaml` is honored (root `ai-runtime.yaml` still works
+    // as a fallback) — matching every other command, instead of the legacy root-only loader.
+    const loaded = loadRuntimeConfig({ workspaceRoot: process.cwd(), ...(options.config ? { explicitPath: options.config } : {}) });
+    const resolved = resolveConfig(loaded.config.router);
     if (options.json) {
         print(JSON.stringify(resolved, null, 2));
         return;
     }
-    print(file ? `Resolved config (${file}):` : 'Resolved defaults (no config file found):');
+    print(loaded.configFile ? `Resolved config (${loaded.configFile}):` : 'Resolved defaults (no config file found):');
     print(`  providers:      ${resolved.providers.length}`);
     print(`  strategy:       ${resolved.strategy}`);
     print(`  timeoutMs:      ${resolved.timeoutMs}`);

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

@@ -6,4 +6,6 @@ export declare function executionsCommand(options: {
 export declare function resumeExecutionCommand(id: string, options: {
     config?: string;
     answer?: string;
+    approve?: boolean;
+    deny?: boolean;
 }): Promise<void>;

package/dist/cli/commands/executions.js

@@ -14,10 +14,17 @@ export async function executionsCommand(options) {
 }
 export async function resumeExecutionCommand(id, options) {
     const rt = await Runtime.load({ ...(options.config ? { config: options.config } : {}) });
-    const r = await rt.resumeExecution(id, { ...(options.answer ? { clarificationAnswer: options.answer } : {}) });
+    // --approve proceeds past a waiting-for-approval gate; --deny cancels it. Neither → leave the decision.
+    const approve = options.approve ? true : options.deny ? false : undefined;
+    const r = await rt.resumeExecution(id, {
+        ...(options.answer ? { clarificationAnswer: options.answer } : {}),
+        ...(approve !== undefined ? { approve } : {}),
+    });
     if (r.response?.text)
         print(r.response.text);
     print(`status: ${r.status}`);
+    if (r.status === 'waiting_for_approval')
+        print('(waiting for approval — re-run with --approve to proceed or --deny to cancel)');
     if (r.clarification)
         print(`? ${r.clarification.question}`);
     if (!r.ok)

package/dist/cli/commands/init.js

@@ -2,8 +2,8 @@
  * `ai-runtime init` — scaffold a config, an env template, and gitignore entries. Never writes secrets;
  * the config carries only env-var NAMES, and `.env` is added to .gitignore.
  */
-import { existsSync, readFileSync, writeFileSync } from 'node:fs';
-import { resolve } from 'node:path';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
 import { print } from '../render.js';
 const EXAMPLE_YAML = `# ai-runtime configuration. Secret VALUES live in .env (gitignored); this file names env vars only.
 strategy: best
@@ -48,6 +48,7 @@ function writeIfAbsent(file, contents) {
         print(`  • ${file} already exists — left unchanged`);
         return;
     }
+    mkdirSync(dirname(full), { recursive: true });
     writeFileSync(full, contents);
     print(`  ✓ wrote ${file}`);
 }
@@ -65,11 +66,13 @@ function ensureGitignore() {
 }
 export function initCommand() {
     print('Initializing ai-runtime...');
-    writeIfAbsent('ai-runtime.yaml', EXAMPLE_YAML);
+    // Write the canonical `.ai-runtime/config.yaml` (the location the runtime loader prefers) so `init`
+    // and `setup` scaffold the same file. A root `ai-runtime.yaml` still works as a fallback if present.
+    writeIfAbsent('.ai-runtime/config.yaml', EXAMPLE_YAML);
     writeIfAbsent('.env.example', EXAMPLE_ENV);
     ensureGitignore();
     print('\nNext steps:');
     print('  1. Copy .env.example to .env and fill in the keys you have');
     print('  2. Run `ai-runtime doctor` to verify configuration');
-    print('  3. Run `ai-runtime route <task>` to route a task');
+    print('  3. Run `ai-runtime` to open the interactive terminal (or `ai-runtime run "<task>"`)');
 }

package/dist/cli/commands/phase2.js

@@ -65,8 +65,12 @@ export function telemetryCommand(opts) {
     const events = ai.telemetryEvents();
     const limit = opts.limit ? Number(opts.limit) : 20;
     const recent = events.slice(-limit);
-    if (recent.length === 0)
-        return print('No telemetry recorded in this session.');
+    if (recent.length === 0) {
+        print('No telemetry recorded in this session.');
+        print('(Telemetry is buffered in-process, so a fresh CLI invocation starts empty. For telemetry that');
+        print(' persists across processes, set `telemetry: { sink: file }` in your config.)');
+        return;
+    }
     for (const e of recent)
         print(JSON.stringify(e));
 }

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) {
@@ -15,23 +15,54 @@ function banner(rt) {
     print(`mode: auto  ·  ${rt.ai.providers().length} providers  ·  type /help or a request, /exit to quit`);
     print('');
 }
+/** A concise, redacted progress line for a lifecycle event — the REPL's live feedback during a run. */
+function progressLine(e) {
+    switch (e.type) {
+        case 'mode.selected':
+            return e.source === 'auto' ? `  · mode: ${e.selected} (auto, ${Math.round(e.confidence * 100)}%)` : `  · mode: ${e.selected}`;
+        case 'provider.selected':
+            return `  · routed → ${e.providerId}/${e.model}`;
+        case 'provider.failed':
+            return `  · ${e.providerId}/${e.model} failed${e.category ? ` (${e.category})` : ''} — falling back`;
+        default:
+            return undefined; // runtime.started / clarification.requested / run.completed are covered by the result block
+    }
+}
 /** 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);
+    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);
+    });
     banner(rt);
     const rl = createInterface({ input: process.stdin, output: process.stdout, prompt: '> ' });
     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

@@ -36,10 +36,13 @@ const HELP = [
     '  /resume <id>                resume a conversation',
     '  /executions                 list persisted executions',
     '  /resume-execution <id>      resume an execution',
+    '  /approve <id>               approve an execution waiting for approval, then continue',
+    '  /deny <id>                  deny an execution waiting for approval (cancels it)',
     '  /pause <id>                 pause an execution',
     '  /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',
     '',
@@ -51,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;
@@ -131,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':
@@ -141,6 +149,10 @@ export class ReplSession {
                 return this.executionsList();
             case 'resume-execution':
                 return this.resumeExecution(args[0]);
+            case 'approve':
+                return this.resumeExecution(args[0], true);
+            case 'deny':
+                return this.resumeExecution(args[0], false);
             case 'pause':
                 return args[0] ? { lines: [this.runtime.pauseExecution(args[0]) ? `paused ${args[0]}` : `cannot pause '${args[0]}'`] } : { lines: ['usage: /pause <execution-id>'] };
             case 'cancel':
@@ -155,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));
@@ -165,8 +178,10 @@ export class ReplSession {
             lines.push(`[${result.error.category}] ${result.error.message}`);
         if (result.mode.executed !== result.mode.selected)
             lines.push(`(mode: ${result.mode.selected} → ${result.mode.executed})`);
-        if (result.status === 'waiting_for_approval')
-            lines.push('(approval required before execution — resume the execution to approve)');
+        if (result.status === 'waiting_for_approval') {
+            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 === 'failed')
             lines.push('(did not complete)');
         if (result.clarification)
@@ -249,14 +264,16 @@ export class ReplSession {
             return { lines: ['no executions yet.'] };
         return { lines: ['Executions:', ...list.map((e) => `  ${e.id}  [${e.status}]  ${e.mode}: ${e.goal.slice(0, 50)}`)] };
     }
-    async resumeExecution(id) {
+    async resumeExecution(id, approve) {
         if (!id)
-            return { lines: ['usage: /resume-execution <execution-id>'] };
-        const r = await this.runtime.resumeExecution(id);
+            return { lines: [`usage: /${approve === undefined ? 'resume-execution' : approve ? 'approve' : 'deny'} <execution-id>`] };
+        const r = await this.runtime.resumeExecution(id, approve !== undefined ? { approve } : {});
         const lines = [];
         if (r.response?.text)
             lines.push(r.response.text);
         lines.push(`status: ${r.status}`);
+        if (r.status === 'waiting_for_approval')
+            lines.push('(waiting for approval — /approve ' + id + ' to proceed, /deny ' + id + ' to cancel)');
         if (r.clarification)
             lines.push(`? ${r.clarification.question}`);
         return { lines };

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.d.ts

@@ -186,6 +186,10 @@ export declare class Runtime {
     private contextBlocks;
     /** Best-effort estimator calibration from provider-reported input usage (estimates never claim to be exact). */
     private calibrate;
-    /** Capture an explicit "remember …" fact and retrieve relevant facts for context. Off when disabled. */
+    /**
+     * Capture an explicit "remember …" fact and retrieve relevant facts for context. Off when disabled.
+     * `capture` is false on a dry run — retrieval is read-only, but writing a fact is a mutation the dry
+     * run must not perform.
+     */
     private applyMemory;
 }

package/dist/runtime/runtime.js

@@ -350,8 +350,9 @@ export class Runtime {
         const clarification = buildClarification(modeResult);
         if (clarification)
             this.emitter.emit({ type: 'clarification.requested', runId, question: clarification.question });
-        // Memory: capture an explicit "remember …" and retrieve relevant facts into context.
-        const memTrace = this.applyMemory(text);
+        // Memory: retrieve relevant facts into context, and (unless this is a dry run) capture an explicit
+        // "remember …". A dry run performs zero mutations, so it retrieves but never writes.
+        const memTrace = this.applyMemory(text, !policy.dryRun);
         // Compile the model context (workspace summary + memory facts + user system) under a token budget.
         const budget = resolveContextBudget({
             ...(req.context?.maxTokens !== undefined ? { perRun: req.context.maxTokens } : {}),
@@ -360,7 +361,32 @@ export class Runtime {
         });
         const compiled = compileContext(this.contextBlocks(req, context.workspace, memTrace?.retrieved), { budgetTokens: budget, estimator: this.estimator });
         const contextReport = { metrics: compiled.metrics, validation: compiled.validation };
+        // Dry-run: chat's only "action" is the model call itself, so a dry run makes NO call. It reports
+        // what it would send (mode, compiled-context size) and performs zero mutations.
+        if (policy.dryRun) {
+            const status = clarification ? 'waiting_for_clarification' : 'completed';
+            this.emitter.emit({ type: 'run.completed', runId, ok: true, status, confidence: 1 });
+            const preview = `[dry-run] chat — no model call made. Would compile ${compiled.metrics.compiledTokens} context token(s) (budget ${budget}) and send one request to the best-matching provider. Run without --dry-run to execute.`;
+            const result = { ok: true, runId, mode: resolution, status, response: { text: preview }, context: contextReport, artifacts: [] };
+            if (clarification)
+                result.clarification = clarification;
+            if (memTrace)
+                result.memory = memTrace;
+            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;
@@ -379,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. */
@@ -673,16 +705,22 @@ export class Runtime {
         if (tokens && tokens > 0)
             this.estimator.calibrate((system?.length ?? 0) + inputText.length, tokens);
     }
-    /** Capture an explicit "remember …" fact and retrieve relevant facts for context. Off when disabled. */
-    applyMemory(text) {
+    /**
+     * Capture an explicit "remember …" fact and retrieve relevant facts for context. Off when disabled.
+     * `capture` is false on a dry run — retrieval is read-only, but writing a fact is a mutation the dry
+     * run must not perform.
+     */
+    applyMemory(text, capture = true) {
         if (!this.memoryEnabled())
             return undefined;
         try {
             const trace = { retrieved: [] };
-            const candidate = classifyMemory(text);
-            if (candidate) {
-                const rec = this._memory.remember(candidate);
-                trace.captured = { id: rec.id, scope: rec.scope };
+            if (capture) {
+                const candidate = classifyMemory(text);
+                if (candidate) {
+                    const rec = this._memory.remember(candidate);
+                    trace.captured = { id: rec.id, scope: rec.scope };
+                }
             }
             trace.retrieved = this._memory.search(text, { limit: 3 }).map((h) => h.text);
             if (trace.retrieved.length === 0 && !trace.captured)

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/docs/GUIDE.md

@@ -66,8 +66,9 @@ You can run the whole pipeline with a **mock provider** — no credentials, no n
 ```js
 import { Runtime, MockProvider, makeModel } from 'ai-runtime-engine';
 
-// A fresh runtime with no persistence (nothing written to disk).
-const runtime = new Runtime();
+// A fresh runtime in stateless mode, so this demo writes nothing to disk.
+// (Persistence is ON by default; pass { persistence: 'disabled' } to turn it off.)
+const runtime = new Runtime(undefined, { persistence: 'disabled' });
 
 // Register one fake provider with one fake model that can "reason" and output "text".
 runtime.ai.registerProvider(new MockProvider({

package/docs/README.md

@@ -13,8 +13,15 @@ with the `ai-runtime-engine` package:
   permissions, credentials, and the learning safety rail.
 
 Additional development records — the append-only decision log (`DECISIONS.md`), the phase-by-phase build
-log (`PROGRESS.md`), and the release checklist (`NPM_PUBLISHING.md`) — live in the (private) source
-repository and are not part of the published package.
+log (`PROGRESS.md`), the release checklist (`NPM_PUBLISHING.md`), and the complete project **handbook**
+(`handbook/00-index.md` and its chapters) — live in the (private) source repository and are not part of
+the published package. The handbook is the deepest reference: architecture, a file-by-file source tour,
+the CLI/REPL, the npm story, testing, and maintenance.
+
+> Note: this index file (`docs/README.md`) itself *does* end up in the npm tarball, because npm always
+> includes any `README*` file regardless of the `files` allowlist. It only links to shipped docs, so that
+> is harmless — but keep anything private out of `README*`-named files. (The handbook index is named
+> `00-index.md`, not `README.md`, for exactly this reason.)
 
 Per-subsystem detail is documented at the source: each module under `src/**` opens with a doc comment
 describing its contract and invariants, and the README's [How to use it](../README.md#how-to-use-it)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-runtime-engine",
-  "version": "1.1.1",
+  "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",