ai-runtime-engine 1.1.1 → 1.2.0

package/CHANGELOG.md

@@ -5,6 +5,31 @@ 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.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 +107,8 @@ 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.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.2.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.
@@ -48,6 +48,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/interactive/repl.js

@@ -15,10 +15,30 @@ 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);
+    // 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).
+    rt.on((e) => {
+        const line = progressLine(e);
+        if (line)
+            print(line);
+    });
     banner(rt);
     const rl = createInterface({ input: process.stdin, output: process.stdout, prompt: '> ' });
     rl.prompt();

package/dist/cli/interactive/session.js

@@ -36,6 +36,8 @@ 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',
@@ -141,6 +143,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':
@@ -165,8 +171,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 +257,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/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,6 +361,19 @@ 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);
         const runResult = await this._ai.run(runRequest);
         this.calibrate(runRequest.system, text, runResult);
@@ -673,16 +687,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/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.2.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",