ai-runtime-engine 1.1.0

package/dist/benchmark/benchmark.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Benchmarking. Runs representative tasks against each configured provider and reports
+ * success rate, latency, and a cost indicator so a user can compare providers on THEIR tasks. It pins
+ * each provider in turn (bypassing selection) so the comparison is apples-to-apples. Makes real calls
+ * when keys are present; against MockProvider it is fully offline.
+ */
+import type { AI } from '../plugin/ai.js';
+export interface BenchTaskSpec {
+    task: string;
+    input: string;
+}
+export interface BenchResult {
+    providerId: string;
+    model?: string;
+    runs: number;
+    successRate: number;
+    avgLatencyMs: number;
+    failures: number;
+}
+export interface BenchmarkOptions {
+    samples?: number;
+}
+export declare function benchmark(ai: AI, tasks: BenchTaskSpec[], options?: BenchmarkOptions): Promise<BenchResult[]>;

package/dist/benchmark/benchmark.js

@@ -0,0 +1,40 @@
+/**
+ * Benchmarking. Runs representative tasks against each configured provider and reports
+ * success rate, latency, and a cost indicator so a user can compare providers on THEIR tasks. It pins
+ * each provider in turn (bypassing selection) so the comparison is apples-to-apples. Makes real calls
+ * when keys are present; against MockProvider it is fully offline.
+ */
+export async function benchmark(ai, tasks, options = {}) {
+    const samples = Math.max(1, options.samples ?? 3);
+    const results = [];
+    for (const provider of ai.providers()) {
+        if (!provider.enabled)
+            continue;
+        let ok = 0;
+        let runs = 0;
+        let latencyTotal = 0;
+        let lastModel;
+        for (const spec of tasks) {
+            for (let i = 0; i < samples; i += 1) {
+                runs += 1;
+                const result = await ai.run({ task: spec.task, input: spec.input, provider: provider.id });
+                if (result.ok) {
+                    ok += 1;
+                    const last = result.routing.attempts[result.routing.attempts.length - 1];
+                    latencyTotal += last?.latencyMs ?? 0;
+                    lastModel = result.routing.selected?.model ?? lastModel;
+                }
+            }
+        }
+        results.push({
+            providerId: provider.id,
+            ...(lastModel ? { model: lastModel } : {}),
+            runs,
+            successRate: runs > 0 ? ok / runs : 0,
+            avgLatencyMs: ok > 0 ? latencyTotal / ok : 0,
+            failures: runs - ok,
+        });
+    }
+    results.sort((a, b) => b.successRate - a.successRate || a.avgLatencyMs - b.avgLatencyMs);
+    return results;
+}

package/dist/cli/cli.d.ts

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+/**
+ * ai-runtime CLI. Bare `ai-runtime` opens the interactive terminal.
+ *   run <input> | init | providers | models | capabilities | doctor | test | route | config | …
+ */
+export {};

package/dist/cli/cli.js

@@ -0,0 +1,161 @@
+#!/usr/bin/env node
+/**
+ * ai-runtime CLI. Bare `ai-runtime` opens the interactive terminal.
+ *   run <input> | init | providers | models | capabilities | doctor | test | route | config | …
+ */
+import { Command } from 'commander';
+import { routeCommand } from './commands/route.js';
+import { configCommand } from './commands/config.js';
+import { doctorCommand } from './commands/doctor.js';
+import { providersCommand, modelsCommand, capabilitiesCommand } from './commands/inspect.js';
+import { testCommand } from './commands/test.js';
+import { initCommand } from './commands/init.js';
+import { probeCommand, discoverCommand, benchmarkCommand, telemetryCommand, presetsCommand } from './commands/phase2.js';
+import { runCommand } from './commands/run.js';
+import { executionsCommand, resumeExecutionCommand } from './commands/executions.js';
+import { setupCommand } from './commands/setup.js';
+import { infoCommand } from './commands/info.js';
+import { cleanupCommand } from './commands/cleanup.js';
+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.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.
+program.allowExcessArguments(false).action(async () => {
+    await startRepl();
+});
+program
+    .command('run')
+    .argument('<input>', 'natural-language request')
+    .description('Run one request through the runtime (one-shot; shares the interactive Runtime)')
+    .option('-m, --mode <mode>', 'force a mode (auto|chat|plan|execute|orchestrate|agent|compare|debug)')
+    .option(...configOpt)
+    .option('--json', 'print the full RuntimeResult as JSON')
+    .option('--dry-run', 'plan and report what would happen without making any changes')
+    .action((input, o) => runCommand(input, o));
+program
+    .command('executions')
+    .description('List persisted executions')
+    .option(...configOpt)
+    .option('--json', 'print as JSON')
+    .action((o) => executionsCommand(o));
+program
+    .command('resume-execution')
+    .argument('<id>', 'execution id')
+    .description('Resume a persisted execution (reconciles the workspace first)')
+    .option(...configOpt)
+    .option('--answer <text>', 'answer a pending clarification')
+    .action((id, o) => resumeExecutionCommand(id, o));
+program.command('init').description('Scaffold ai-runtime.yaml, .env.example, and .gitignore entries').action(() => initCommand());
+program
+    .command('setup')
+    .description('Guided bootstrap: detect workspace + provider keys, generate config (asks before each write)')
+    .option('-y, --yes', 'accept every write without prompting')
+    .action((o) => setupCommand(o));
+program
+    .command('skills')
+    .description('List available skills; --discover scans the workspace for more (reported, not loaded)')
+    .option(...configOpt)
+    .option('--discover', 'scan the workspace for skill files elsewhere and report them')
+    .option('--json', 'print as JSON')
+    .action((o) => skillsCommand(o));
+program
+    .command('info')
+    .description('Summarize the runtime: workspace, providers, skills, tools, memory, learning, storage')
+    .option(...configOpt)
+    .option('--json', 'print as JSON')
+    .action((o) => infoCommand(o));
+program
+    .command('cleanup')
+    .description('Enforce retention, drop the cache, and validate the store (confirms before deleting)')
+    .option(...configOpt)
+    .option('--dry-run', 'report what would be removed without removing anything')
+    .option('-y, --yes', 'remove without prompting')
+    .option('--json', 'print the cleanup plan as JSON')
+    .action((o) => cleanupCommand(o));
+program
+    .command('providers')
+    .description('List configured providers and their health')
+    .option(...configOpt)
+    .option('--json', 'print as JSON')
+    .action((o) => providersCommand(o));
+program
+    .command('models')
+    .description('List known models across providers')
+    .option(...configOpt)
+    .option('--json', 'print as JSON')
+    .action((o) => modelsCommand(o));
+program
+    .command('capabilities')
+    .description('Show the capability matrix by model')
+    .option(...configOpt)
+    .option('--json', 'print as JSON')
+    .action((o) => capabilitiesCommand(o));
+program
+    .command('doctor')
+    .description('Diagnose the runtime: config, .env, providers, models, store, skills, tools, permissions, git')
+    .option(...configOpt)
+    .option('--json', 'print the full report as JSON')
+    .action((o) => doctorCommand(o));
+program
+    .command('test')
+    .argument('<provider>', 'provider id to test with one live call')
+    .description('Make a minimal live call to a provider (skipped if no key)')
+    .option(...configOpt)
+    .action((provider, o) => testCommand(provider, o));
+program
+    .command('route')
+    .argument('<task>', 'task name, e.g. generate-playwright-tests')
+    .description('Route a task through the router')
+    .option('-i, --input <text>', 'input text for the task')
+    .option('-s, --strategy <strategy>', 'routing strategy (best|fastest|cheapest|highest-quality|...)')
+    .option('-p, --provider <id>', 'pin a provider')
+    .option('-m, --model <id>', 'pin a model')
+    .option(...configOpt)
+    .option('--json', 'print the full RunResult as JSON')
+    .action((task, o) => routeCommand(task, o));
+program
+    .command('config')
+    .description('Print the resolved configuration')
+    .option(...configOpt)
+    .option('--json', 'print as JSON')
+    .action((o) => configCommand(o));
+// ── Learning, discovery & benchmarking ──
+program
+    .command('probe')
+    .argument('<provider>', 'provider id')
+    .argument('<model>', 'model id')
+    .description('Verify a model\'s capabilities with minimal live probes (opt-in, costs tokens)')
+    .option(...configOpt)
+    .action((provider, model, o) => probeCommand(provider, model, o));
+program
+    .command('discover')
+    .argument('<spec>', 'path to an OpenAPI 3.x spec (yaml/json)')
+    .description('Analyze an OpenAPI spec and suggest a provider config')
+    .option('--json', 'print as JSON')
+    .action((spec, o) => discoverCommand(spec, o));
+program
+    .command('benchmark')
+    .description('Compare configured providers on representative tasks')
+    .option(...configOpt)
+    .option('-n, --samples <n>', 'samples per task per provider', '3')
+    .option('--json', 'print as JSON')
+    .action((o) => benchmarkCommand(o));
+program
+    .command('telemetry')
+    .description('Print recent routing telemetry events (metadata only)')
+    .option(...configOpt)
+    .option('-n, --limit <n>', 'number of recent events', '20')
+    .action((o) => telemetryCommand(o));
+program
+    .command('presets')
+    .description('List provider marketplace presets you can add')
+    .option('--json', 'print as JSON')
+    .action((o) => presetsCommand(o));
+program.parseAsync(process.argv).catch((err) => {
+    printError(`ai-runtime error: ${err instanceof Error ? err.message : String(err)}`);
+    process.exitCode = 1;
+});

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

@@ -0,0 +1,47 @@
+/**
+ * `ai-runtime cleanup` — enforce retention, drop the disposable cache, and validate the local store.
+ * Retention is OPT-IN via `AI_CONVERSATION/EXECUTION/ARTIFACT_RETENTION_DAYS` (unset = keep everything).
+ * Nothing is deleted without confirmation unless `--yes`; `--dry-run` only reports the plan. Integrity
+ * issues are reported, never auto-"repaired" destructively.
+ */
+import { Runtime } from '../../runtime/runtime.js';
+import type { IntegrityIssue } from '../../store/area.js';
+export interface CleanupPlan {
+    retention: {
+        conversationDays?: number;
+        executionDays?: number;
+        artifactDays?: number;
+    };
+    conversations: {
+        total: number;
+        expired: string[];
+    };
+    executions: {
+        total: number;
+        expired: string[];
+    };
+    artifacts: {
+        total: number;
+        expired: string[];
+    };
+    cache: {
+        entries: number;
+    };
+    integrity: IntegrityIssue[];
+}
+/** Compute what cleanup WOULD remove, given the current time. Pure aside from reading the store. */
+export declare function planCleanup(rt: Runtime, now: number, env?: NodeJS.ProcessEnv): CleanupPlan;
+export interface CleanupResult {
+    conversations: number;
+    executions: number;
+    artifacts: number;
+    cache: number;
+}
+/** Apply a cleanup plan: delete expired records and clear the cache. Returns the counts actually removed. */
+export declare function applyCleanup(rt: Runtime, plan: CleanupPlan): CleanupResult;
+export declare function cleanupCommand(opts: {
+    config?: string;
+    dryRun?: boolean;
+    yes?: boolean;
+    json?: boolean;
+}): Promise<void>;

package/dist/cli/commands/cleanup.js

@@ -0,0 +1,96 @@
+/**
+ * `ai-runtime cleanup` — enforce retention, drop the disposable cache, and validate the local store.
+ * Retention is OPT-IN via `AI_CONVERSATION/EXECUTION/ARTIFACT_RETENTION_DAYS` (unset = keep everything).
+ * Nothing is deleted without confirmation unless `--yes`; `--dry-run` only reports the plan. Integrity
+ * issues are reported, never auto-"repaired" destructively.
+ */
+import { Runtime } from '../../runtime/runtime.js';
+import { TERMINAL } from '../../executions/execution.js';
+import { confirm } from '../prompt.js';
+import { print } from '../render.js';
+const DAY_MS = 86_400_000;
+function numEnv(v) {
+    if (v === undefined || v === '')
+        return undefined;
+    const n = Number(v);
+    return Number.isFinite(n) && n >= 0 ? n : undefined;
+}
+/** Parse the creation time base36-encoded in an artifact id ("art_<time36>_<counter>"). */
+function artifactTime(id) {
+    const part = id.split('_')[1];
+    if (!part)
+        return undefined;
+    const t = parseInt(part, 36);
+    return Number.isFinite(t) ? t : undefined;
+}
+/** Compute what cleanup WOULD remove, given the current time. Pure aside from reading the store. */
+export function planCleanup(rt, now, env = process.env) {
+    const convDays = numEnv(env.AI_CONVERSATION_RETENTION_DAYS);
+    const execDays = numEnv(env.AI_EXECUTION_RETENTION_DAYS);
+    const artDays = numEnv(env.AI_ARTIFACT_RETENTION_DAYS);
+    const convs = rt.conversations.enabled ? rt.conversations.list() : [];
+    const expiredConvs = convDays !== undefined ? convs.filter((c) => now - c.updatedAt > convDays * DAY_MS).map((c) => c.id) : [];
+    const execs = rt.executionStore.enabled ? rt.executions() : [];
+    // Only TERMINAL executions are eligible for retention deletion — never a live/waiting one.
+    const expiredExecs = execDays !== undefined ? execs.filter((e) => TERMINAL.has(e.status) && now - e.updatedAt > execDays * DAY_MS).map((e) => e.id) : [];
+    const artifacts = rt.artifacts.enabled ? rt.artifacts.list() : [];
+    const expiredArtifacts = artDays !== undefined ? artifacts.filter((id) => { const t = artifactTime(id); return t !== undefined && now - t > artDays * DAY_MS; }) : [];
+    return {
+        retention: { ...(convDays !== undefined ? { conversationDays: convDays } : {}), ...(execDays !== undefined ? { executionDays: execDays } : {}), ...(artDays !== undefined ? { artifactDays: artDays } : {}) },
+        conversations: { total: convs.length, expired: expiredConvs },
+        executions: { total: execs.length, expired: expiredExecs },
+        artifacts: { total: artifacts.length, expired: expiredArtifacts },
+        cache: { entries: rt.store.cache().listIds().length },
+        integrity: rt.store.check(),
+    };
+}
+/** Apply a cleanup plan: delete expired records and clear the cache. Returns the counts actually removed. */
+export function applyCleanup(rt, plan) {
+    for (const id of plan.conversations.expired)
+        rt.conversations.delete(id);
+    for (const id of plan.executions.expired)
+        rt.store.executions().remove(id);
+    for (const id of plan.artifacts.expired)
+        rt.artifacts.delete(id);
+    const cacheIds = rt.store.cache().listIds();
+    for (const id of cacheIds)
+        rt.store.cache().remove(id);
+    return { conversations: plan.conversations.expired.length, executions: plan.executions.expired.length, artifacts: plan.artifacts.expired.length, cache: cacheIds.length };
+}
+function toRemove(plan) {
+    return plan.conversations.expired.length + plan.executions.expired.length + plan.artifacts.expired.length + plan.cache.entries;
+}
+function renderPlan(plan) {
+    const lines = ['ai-runtime cleanup', ''];
+    const ret = plan.retention;
+    lines.push(`conversations: ${plan.conversations.expired.length} expired of ${plan.conversations.total}${ret.conversationDays === undefined ? '  (retention off)' : `  (> ${ret.conversationDays}d)`}`, `executions:    ${plan.executions.expired.length} expired of ${plan.executions.total}${ret.executionDays === undefined ? '  (retention off)' : `  (terminal, > ${ret.executionDays}d)`}`, `artifacts:     ${plan.artifacts.expired.length} expired of ${plan.artifacts.total}${ret.artifactDays === undefined ? '  (retention off)' : `  (> ${ret.artifactDays}d)`}`, `cache:         ${plan.cache.entries} entr${plan.cache.entries === 1 ? 'y' : 'ies'} to drop (disposable)`, `integrity:     ${plan.integrity.length ? `${plan.integrity.length} issue(s) — ${plan.integrity.map((i) => `${i.file} (${i.problem})`).join(', ')}` : 'ok'}`);
+    return lines;
+}
+export async function cleanupCommand(opts) {
+    const rt = await Runtime.load({ ...(opts.config ? { config: opts.config } : {}) });
+    if (!rt.store.enabled) {
+        print('storage is disabled (stateless mode) — nothing to clean.');
+        return;
+    }
+    const plan = planCleanup(rt, Date.now());
+    if (opts.json)
+        return print(JSON.stringify(plan, null, 2));
+    for (const line of renderPlan(plan))
+        print(line);
+    const removable = toRemove(plan);
+    if (removable === 0) {
+        print('\nNothing to remove.');
+        return;
+    }
+    if (opts.dryRun) {
+        print('\n(dry run — nothing was removed)');
+        return;
+    }
+    const ok = opts.yes || (await confirm(`\nRemove ${removable} item(s)?`));
+    if (!ok) {
+        print('cancelled — nothing was removed.');
+        return;
+    }
+    const done = applyCleanup(rt, plan);
+    print(`\nremoved: ${done.conversations} conversation(s), ${done.executions} execution(s), ${done.artifacts} artifact(s), ${done.cache} cache entr${done.cache === 1 ? 'y' : 'ies'}.`);
+}

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

@@ -0,0 +1,8 @@
+/**
+ * `ai-runtime config` — print the resolved configuration (from the config file if present, else
+ * defaults). Shows weights, strategy, policy posture, and timeouts. No secrets are read or printed.
+ */
+export declare function configCommand(options: {
+    config?: string;
+    json?: boolean;
+}): void;

package/dist/cli/commands/config.js

@@ -0,0 +1,28 @@
+/**
+ * `ai-runtime config` — print the resolved configuration (from the config file if present, else
+ * 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 { print } from '../render.js';
+export function configCommand(options) {
+    const file = options.config ?? findConfigFile();
+    const resolved = resolveConfig(loadConfig(options.config));
+    if (options.json) {
+        print(JSON.stringify(resolved, null, 2));
+        return;
+    }
+    print(file ? `Resolved config (${file}):` : 'Resolved defaults (no config file found):');
+    print(`  providers:      ${resolved.providers.length}`);
+    print(`  strategy:       ${resolved.strategy}`);
+    print(`  timeoutMs:      ${resolved.timeoutMs}`);
+    print(`  maxFallbacks:   ${resolved.maxFallbacks}`);
+    print(`  minEvidence:    ${resolved.minEvidence}`);
+    print(`  minConfidence:  ${resolved.minConfidence}`);
+    print('  weights:');
+    for (const [k, v] of Object.entries(resolved.weights))
+        print(`    ${k}: ${v}`);
+    print('  privacy:');
+    for (const [k, v] of Object.entries(resolved.privacy))
+        print(`    ${k}: ${String(v)}`);
+}

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

@@ -0,0 +1,57 @@
+/**
+ * `ai-runtime doctor` — diagnose the whole runtime: config, .env (by env-var NAME only), provider auth +
+ * health, accessible models, the local store (integrity + counts), skills, tools, permissions, and git.
+ * Never prints a secret VALUE; all output is redacted. `--json` emits the structured report.
+ */
+import { Runtime } from '../../runtime/runtime.js';
+import type { IntegrityIssue } from '../../store/area.js';
+export interface DoctorReport {
+    configFile?: string;
+    workspace?: {
+        name: string;
+        branch?: string;
+    };
+    env: {
+        present: string[];
+        absent: string[];
+    };
+    providers: Array<{
+        id: string;
+        state: string;
+        authenticated: boolean;
+        models: number;
+    }>;
+    models: {
+        total: number;
+        usableProviders: number;
+    };
+    store: {
+        enabled: boolean;
+        project: string;
+        integrity: IntegrityIssue[];
+        conversations: number;
+        executions: number;
+        memory: number;
+        artifacts: number;
+    };
+    skills: string[];
+    tools: string[];
+    permissions: {
+        fsRead: boolean;
+        fsWrite: boolean;
+        shell: boolean;
+        gitCommit: boolean;
+        gitPush: boolean;
+        network: boolean;
+    };
+    git: {
+        repo: boolean;
+        branch?: string;
+    };
+}
+export declare function gatherDoctor(rt: Runtime, configFile: string | undefined, env: NodeJS.ProcessEnv): Promise<DoctorReport>;
+export declare function renderDoctor(r: DoctorReport): string[];
+export declare function doctorCommand(opts: {
+    config?: string;
+    json?: boolean;
+}): Promise<void>;

package/dist/cli/commands/doctor.js

@@ -0,0 +1,86 @@
+/**
+ * `ai-runtime doctor` — diagnose the whole runtime: config, .env (by env-var NAME only), provider auth +
+ * health, accessible models, the local store (integrity + counts), skills, tools, permissions, and git.
+ * Never prints a secret VALUE; all output is redacted. `--json` emits the structured report.
+ */
+import { Runtime } from '../../runtime/runtime.js';
+import { loadRuntimeConfig } from '../../runtime/config.js';
+import { print } from '../render.js';
+/** The credential env-var NAMES ai-runtime knows about (§16). Presence is reported, never the value. */
+const KNOWN_KEY_ENVS = [
+    'GEMINI_API_KEY', 'GROQ_API_KEY', 'ANTHROPIC_API_KEY', 'OPENROUTER_API_KEY', 'MISTRAL_API_KEY',
+    'CEREBRAS_API_KEY', 'COHERE_API_KEY', 'HUGGINGFACE_API_KEY', 'CLOUDFLARE_API_TOKEN', 'CUSTOM_AI_API_KEY',
+];
+export async function gatherDoctor(rt, configFile, env) {
+    const health = await rt.ai.checkHealth().catch(() => []);
+    const metas = await rt.ai.discover().catch(() => []);
+    const byId = new Map(metas.map((m) => [m.id, m]));
+    let usableProviders = 0;
+    const providers = health.map((h) => {
+        const authenticated = h.state !== 'NOT_CONFIGURED';
+        if (authenticated)
+            usableProviders += 1;
+        return { id: h.providerId, state: h.state, authenticated, models: byId.get(h.providerId)?.models.length ?? 0 };
+    });
+    const ws = rt.workspaceInfo();
+    const perms = rt.permissions();
+    const storeEnabled = rt.store.enabled;
+    return {
+        ...(configFile ? { configFile } : {}),
+        ...(ws ? { workspace: { name: ws.name ?? ws.root.split(/[\\/]/).pop() ?? 'workspace', ...(ws.git.branch ? { branch: ws.git.branch } : {}) } } : {}),
+        env: {
+            present: KNOWN_KEY_ENVS.filter((k) => (env[k] ?? '') !== ''),
+            absent: KNOWN_KEY_ENVS.filter((k) => (env[k] ?? '') === ''),
+        },
+        providers,
+        models: { total: metas.reduce((n, m) => n + m.models.length, 0), usableProviders },
+        store: {
+            enabled: storeEnabled,
+            project: rt.store.paths().project,
+            integrity: storeEnabled ? rt.store.check() : [],
+            conversations: rt.conversations.enabled ? rt.conversations.list().length : 0,
+            executions: rt.executionStore.enabled ? rt.executions().length : 0,
+            memory: rt.memory.enabled ? rt.memory.all().length : 0,
+            artifacts: rt.artifacts.enabled ? rt.artifacts.list().length : 0,
+        },
+        skills: rt.skills().map((s) => `${s.id}@${s.version}`),
+        tools: rt.tools().map((t) => t.id),
+        permissions: { fsRead: perms.filesystem.read, fsWrite: perms.filesystem.write, shell: perms.shell.enabled, gitCommit: perms.git.commit, gitPush: perms.git.push, network: perms.network.enabled },
+        git: { repo: !!ws?.git.isRepo, ...(ws?.git.branch ? { branch: ws.git.branch } : {}) },
+    };
+}
+export function renderDoctor(r) {
+    const lines = ['ai-runtime Doctor', ''];
+    lines.push(`config:   ${r.configFile ?? '(none — run `ai-runtime setup`)'}`);
+    lines.push(`workspace:${r.workspace ? ` ${r.workspace.name}${r.workspace.branch ? ` @ ${r.workspace.branch}` : ''}` : ' (none)'}`);
+    lines.push('', `.env keys present: ${r.env.present.length ? r.env.present.join(', ') : '(none)'}`);
+    lines.push(`.env keys absent:  ${r.env.absent.join(', ')}`);
+    lines.push('', 'Providers:');
+    if (!r.providers.length)
+        lines.push('  (none configured — run `ai-runtime setup`)');
+    for (const p of r.providers)
+        lines.push(`  ${p.authenticated ? '✓' : '✗'} ${p.id.padEnd(14)} ${p.authenticated ? 'authenticated' : 'not configured'}  [${p.state}]  ${p.models} models`);
+    lines.push(`Models:   ${r.models.total} known, ${r.models.usableProviders} provider(s) usable`);
+    lines.push('', 'Store:');
+    if (!r.store.enabled)
+        lines.push('  disabled (stateless mode)');
+    else {
+        lines.push(`  path: ${r.store.project}`);
+        lines.push(`  ${r.store.conversations} conversation(s), ${r.store.executions} execution(s), ${r.store.memory} memory record(s), ${r.store.artifacts} artifact(s)`);
+        lines.push(`  integrity: ${r.store.integrity.length ? `${r.store.integrity.length} issue(s) — ${r.store.integrity.map((i) => `${i.file} (${i.problem})`).join(', ')}` : 'ok'}`);
+    }
+    lines.push('', `Skills:   ${r.skills.length ? r.skills.join(', ') : '(none)'}`);
+    lines.push(`Tools:    ${r.tools.join(', ')}`);
+    lines.push(`Perms:    fsRead=${r.permissions.fsRead} fsWrite=${r.permissions.fsWrite} shell=${r.permissions.shell} gitCommit=${r.permissions.gitCommit} gitPush=${r.permissions.gitPush} network=${r.permissions.network}`);
+    lines.push(`Git:      ${r.git.repo ? `repository${r.git.branch ? ` @ ${r.git.branch}` : ''}` : 'not a git repository'}`);
+    return lines;
+}
+export async function doctorCommand(opts) {
+    const loaded = loadRuntimeConfig({ workspaceRoot: process.cwd(), ...(opts.config ? { explicitPath: opts.config } : {}) });
+    const rt = await Runtime.load({ ...(opts.config ? { config: opts.config } : {}) });
+    const report = await gatherDoctor(rt, loaded.configFile, process.env);
+    if (opts.json)
+        return print(JSON.stringify(report, null, 2));
+    for (const line of renderDoctor(report))
+        print(line);
+}

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

@@ -0,0 +1,9 @@
+/** `ai-runtime executions` (list) and `resume-execution <id>` — inspect and resume persisted work. */
+export declare function executionsCommand(options: {
+    config?: string;
+    json?: boolean;
+}): Promise<void>;
+export declare function resumeExecutionCommand(id: string, options: {
+    config?: string;
+    answer?: string;
+}): Promise<void>;

package/dist/cli/commands/executions.js

@@ -0,0 +1,25 @@
+/** `ai-runtime executions` (list) and `resume-execution <id>` — inspect and resume persisted work. */
+import { Runtime } from '../../runtime/runtime.js';
+import { print } from '../render.js';
+export async function executionsCommand(options) {
+    const rt = await Runtime.load({ ...(options.config ? { config: options.config } : {}) });
+    const list = rt.executions();
+    if (options.json)
+        return print(JSON.stringify(list, null, 2));
+    if (!list.length)
+        return print('No executions.');
+    print('Executions:');
+    for (const e of list)
+        print(`  ${e.id}  [${e.status}]  ${e.mode}: ${e.goal.slice(0, 60)}`);
+}
+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 } : {}) });
+    if (r.response?.text)
+        print(r.response.text);
+    print(`status: ${r.status}`);
+    if (r.clarification)
+        print(`? ${r.clarification.question}`);
+    if (!r.ok)
+        process.exitCode = 1;
+}

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

@@ -0,0 +1,43 @@
+/**
+ * `ai-runtime info` — a read-only summary of the runtime: workspace, default mode, context budget,
+ * providers/models, skills, tools, memory + learning stats, and storage paths. Makes NO live calls and
+ * mutates nothing. `--json` prints the structured report.
+ */
+import { Runtime } from '../../runtime/runtime.js';
+export interface InfoReport {
+    workspace?: {
+        name: string;
+        summary: string;
+        branch?: string;
+    };
+    defaultMode: string;
+    contextBudgetTokens: number;
+    providers: {
+        total: number;
+        enabled: number;
+    };
+    models: number;
+    skills: string[];
+    tools: string[];
+    memory: {
+        enabled: boolean;
+        facts: number;
+    };
+    learning: {
+        enabled: boolean;
+        entries: number;
+        preferredProviders: string[];
+    };
+    storage: {
+        home: string;
+        project: string;
+        enabled: boolean;
+    };
+}
+/** Gather the read-only info report from a loaded runtime. Pure aside from reading the local store. */
+export declare function gatherInfo(rt: Runtime): Promise<InfoReport>;
+export declare function renderInfo(r: InfoReport): string[];
+export declare function infoCommand(opts: {
+    config?: string;
+    json?: boolean;
+}): Promise<void>;