ai-runtime-engine 1.1.0

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

@@ -0,0 +1,7 @@
+/**
+ * `ai-runtime test <provider>` — one minimal LIVE call to confirm a provider works. Skipped with a
+ * clear message when the provider has no configured key (so it is safe to run without secrets).
+ */
+export declare function testCommand(providerId: string, opts: {
+    config?: string;
+}): Promise<void>;

package/dist/cli/commands/test.js

@@ -0,0 +1,29 @@
+/**
+ * `ai-runtime test <provider>` — one minimal LIVE call to confirm a provider works. Skipped with a
+ * clear message when the provider has no configured key (so it is safe to run without secrets).
+ */
+import { loadAI } from '../context.js';
+import { print, printError } from '../render.js';
+export async function testCommand(providerId, opts) {
+    const { ai, hasProviders } = loadAI(opts.config);
+    if (!hasProviders)
+        return print('No providers configured.');
+    const provider = ai.providers().find((p) => p.id === providerId);
+    if (!provider)
+        return printError(`unknown provider '${providerId}'`);
+    const health = await ai.checkHealth();
+    const h = health.find((x) => x.providerId === providerId);
+    if (h?.state === 'NOT_CONFIGURED') {
+        return print(`⚠ ${providerId}: not configured${h.detail ? ` — ${h.detail}` : ''} (skipped)`);
+    }
+    print(`Testing ${providerId} with a live call...`);
+    const result = await ai.run({ task: 'smoke-test', input: 'Reply with the single word: ok', provider: providerId });
+    if (result.ok) {
+        const last = result.routing.attempts[result.routing.attempts.length - 1];
+        print(`✓ ${providerId}: ${result.routing.selected?.model} responded in ${last?.latencyMs ?? '?'}ms`);
+    }
+    else {
+        printError(`✗ ${providerId} [${result.error?.category}]: ${result.error?.message}`);
+        process.exitCode = 1;
+    }
+}

package/dist/cli/context.d.ts

@@ -0,0 +1,12 @@
+/** Shared CLI helper: build an AI instance from the runtime config (or an empty config). */
+import { AI } from '../plugin/ai.js';
+import type { AIOptions } from '../plugin/ai.js';
+/**
+ * Load an AI for the CLI. Now sits on the runtime config layer, so `.ai-runtime/config.yaml` is honored
+ * (root `ai-runtime.yaml` still works as a fallback). The return shape is unchanged for callers.
+ */
+export declare function loadAI(configPath?: string, options?: AIOptions): {
+    ai: AI;
+    hasProviders: boolean;
+    configFile?: string;
+};

package/dist/cli/context.js

@@ -0,0 +1,16 @@
+/** Shared CLI helper: build an AI instance from the runtime config (or an empty config). */
+import { AI } from '../plugin/ai.js';
+import { loadRuntimeConfig } from '../runtime/config.js';
+/**
+ * Load an AI for the CLI. Now sits on the runtime config layer, so `.ai-runtime/config.yaml` is honored
+ * (root `ai-runtime.yaml` still works as a fallback). The return shape is unchanged for callers.
+ */
+export function loadAI(configPath, options) {
+    const loaded = loadRuntimeConfig({ workspaceRoot: process.cwd(), ...(configPath ? { explicitPath: configPath } : {}) });
+    const ai = new AI(loaded.config.router, options);
+    return {
+        ai,
+        hasProviders: loaded.config.router.providers.length > 0,
+        ...(loaded.configFile ? { configFile: loaded.configFile } : {}),
+    };
+}

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

@@ -0,0 +1,6 @@
+/**
+ * The interactive REPL — a thin node:readline wrapper around ReplSession. All output goes through the
+ * redacted `print`. Progress is shown by subscribing to the runtime's lifecycle events. Zero new deps.
+ */
+/** Start the interactive session. Resolves when the user exits (or stdin closes). */
+export declare function startRepl(configPath?: string): Promise<void>;

package/dist/cli/interactive/repl.js

@@ -0,0 +1,45 @@
+/**
+ * The interactive REPL — a thin node:readline wrapper around ReplSession. All output goes through the
+ * redacted `print`. Progress is shown by subscribing to the runtime's lifecycle events. Zero new deps.
+ */
+import { createInterface } from 'node:readline';
+import { Runtime } from '../../runtime/runtime.js';
+import { print, printError } from '../render.js';
+import { summarizeWorkspace } from '../../runtime/workspace/workspace.js';
+import { ReplSession } from './session.js';
+function banner(rt) {
+    const ws = rt.workspaceInfo();
+    print('ai-runtime');
+    if (ws)
+        print(summarizeWorkspace(ws));
+    print(`mode: auto  ·  ${rt.ai.providers().length} providers  ·  type /help or a request, /exit to quit`);
+    print('');
+}
+/** 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);
+    banner(rt);
+    const rl = createInterface({ input: process.stdin, output: process.stdout, prompt: '> ' });
+    rl.prompt();
+    for await (const line of rl) {
+        let result;
+        try {
+            result = await session.handle(line);
+        }
+        catch (err) {
+            printError(`error: ${err instanceof Error ? err.message : String(err)}`);
+            rl.prompt();
+            continue;
+        }
+        if (result.clear)
+            process.stdout.write('\x1b[2J\x1b[H');
+        for (const l of result.lines)
+            print(l);
+        if (result.exit) {
+            rl.close();
+            return;
+        }
+        rl.prompt();
+    }
+}

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

@@ -0,0 +1,36 @@
+/**
+ * ReplSession — the interactive command router, decoupled from readline so it is unit-testable without
+ * a TTY. `handle(line)` returns the lines to print (and control flags). Natural language goes to
+ * Runtime.run(); slash commands inspect providers/models/config/status/mode.
+ */
+import { Runtime } from '../../runtime/runtime.js';
+import type { RuntimeMode } from '../../runtime/types.js';
+export interface HandleResult {
+    lines: string[];
+    exit?: boolean;
+    clear?: boolean;
+}
+export declare class ReplSession {
+    private readonly runtime;
+    private mode;
+    private viewCache?;
+    private conversationId?;
+    private dryRunMode;
+    constructor(runtime: Runtime);
+    currentMode(): RuntimeMode;
+    private views;
+    handle(raw: string): Promise<HandleResult>;
+    private runInput;
+    private memory;
+    private learning;
+    private permissions;
+    private conversationsList;
+    private executionsList;
+    private resumeExecution;
+    private resume;
+    private status;
+    private setOrShowMode;
+    private config;
+    private models;
+    private providers;
+}

package/dist/cli/interactive/session.js

@@ -0,0 +1,356 @@
+/**
+ * ReplSession — the interactive command router, decoupled from readline so it is unit-testable without
+ * a TTY. `handle(line)` returns the lines to print (and control flags). Natural language goes to
+ * Runtime.run(); slash commands inspect providers/models/config/status/mode.
+ */
+import { RUNTIME_MODES } from '../../runtime/types.js';
+import { ProviderViewCache } from '../../runtime/providerView.js';
+import { SETUP_CANDIDATES } from '../commands/setup.js';
+import { gatherInfo, renderInfo } from '../commands/info.js';
+import { gatherDoctor, renderDoctor } from '../commands/doctor.js';
+import { planCleanup } from '../commands/cleanup.js';
+const HELP = [
+    'Commands:',
+    '  /help                       show this help',
+    '  /status                     workspace, mode, provider count',
+    '  /info                       full runtime summary',
+    '  /providers/setup            how to add a provider (keys / Ollama)',
+    '  /doctor                     diagnose config, providers, store, permissions',
+    '  /cleanup                    preview retention/cache cleanup (apply via CLI)',
+    '  /mode [name]                show or set the mode (auto|chat|plan|compare|…)',
+    '  /compare <request>          compare the request across all enabled providers',
+    '  /providers                  list providers + access state',
+    '  /providers/all models       list every provider’s models',
+    '  /providers/<id> [models|capabilities|health]   inspect one provider',
+    '  /models                     list all known models',
+    '  /tools                      list registered tools',
+    '  /skills [discover]          list available skills; discover scans the workspace',
+    '  /permissions                show the current tool permissions',
+    '  /feedback <text>            record feedback on the last result (e.g. "that worked")',
+    '  /learning                   show what the learning store has observed',
+    '  /memory [list]              list stored facts',
+    '  /memory search <query>      search memory',
+    '  /memory delete <id>         delete a fact (with cascade)',
+    '  /memory clear               clear project-scope facts',
+    '  /conversations              list recent conversations',
+    '  /resume <id>                resume a conversation',
+    '  /executions                 list persisted executions',
+    '  /resume-execution <id>      resume an execution',
+    '  /pause <id>                 pause an execution',
+    '  /cancel <id>                cancel an execution',
+    '  /config                     show the resolved configuration',
+    '  /dry-run                    toggle dry-run (plan only, no changes)',
+    '  /clear                      clear the screen',
+    '  /exit                       leave the session',
+    '',
+    'Anything else is sent to the runtime as a request.',
+];
+export class ReplSession {
+    runtime;
+    mode = 'auto';
+    viewCache;
+    conversationId;
+    dryRunMode = false;
+    constructor(runtime) {
+        this.runtime = runtime;
+    }
+    currentMode() {
+        return this.mode;
+    }
+    views() {
+        if (!this.viewCache)
+            this.viewCache = new ProviderViewCache(this.runtime.ai);
+        return this.viewCache;
+    }
+    async handle(raw) {
+        const line = raw.trim();
+        if (!line)
+            return { lines: [] };
+        if (!line.startsWith('/'))
+            return this.runInput(line);
+        const [token, ...args] = line.split(/\s+/);
+        const parts = token.slice(1).split('/'); // "/providers/all" → ["providers","all"]
+        const cmd = parts[0].toLowerCase();
+        switch (cmd) {
+            case 'help':
+                return { lines: HELP };
+            case 'exit':
+            case 'quit':
+                return { lines: ['bye.'], exit: true };
+            case 'clear':
+                return { lines: [], clear: true };
+            case 'status':
+                return this.status();
+            case 'info':
+                return { lines: renderInfo(await gatherInfo(this.runtime)) };
+            case 'doctor':
+                return { lines: renderDoctor(await gatherDoctor(this.runtime, this.runtime.configFile, process.env)) };
+            case 'cleanup': {
+                if (!this.runtime.store.enabled)
+                    return { lines: ['storage is disabled (stateless mode).'] };
+                const plan = planCleanup(this.runtime, Date.now());
+                const n = plan.conversations.expired.length + plan.executions.expired.length + plan.artifacts.expired.length + plan.cache.entries;
+                return { lines: [`cleanup preview: ${plan.conversations.expired.length} conversation(s), ${plan.executions.expired.length} execution(s), ${plan.artifacts.expired.length} artifact(s), ${plan.cache.entries} cache entr${plan.cache.entries === 1 ? 'y' : 'ies'}`, `integrity: ${plan.integrity.length ? plan.integrity.length + ' issue(s)' : 'ok'}`, n ? 'run `ai-runtime cleanup` to apply.' : 'nothing to remove.'] };
+            }
+            case 'mode':
+                return this.setOrShowMode(args[0]);
+            case 'compare': {
+                const request = args.join(' ');
+                return request ? this.runInput(request, 'compare') : { lines: ['usage: /compare <request>'] };
+            }
+            case 'models':
+                return this.models();
+            case 'config':
+                return this.config();
+            case 'providers':
+                return this.providers(parts[1], args[0]);
+            case 'tools':
+                return { lines: ['Tools:', ...this.runtime.tools().map((t) => `  ${t.id.padEnd(14)} ${t.description}`)] };
+            case 'skills': {
+                if (args[0] === 'discover') {
+                    const candidates = this.runtime.discoverSkillCandidates();
+                    if (!candidates.length)
+                        return { lines: ['no other skill files found in the workspace.'] };
+                    return { lines: [`Discovered ${candidates.length} candidate(s) (not loaded):`, ...candidates.map((c) => `  • ${c.relative}  [${c.kind}]`), 'Enable one: move it into .ai-runtime/skills/ or add it to `skills.paths` in config.'] };
+                }
+                const skills = this.runtime.skills();
+                return { lines: skills.length ? ['Skills:', ...skills.map((s) => `  ${s.id.padEnd(20)} v${s.version}  ${s.description}`)] : ['no skills available (a skill needs its tools registered).'] };
+            }
+            case 'permissions':
+                return this.permissions();
+            case 'feedback': {
+                const text = args.join(' ');
+                if (!text)
+                    return { lines: ['usage: /feedback <text>  (e.g. "that worked" / "wrong root cause")'] };
+                const sig = this.runtime.feedback(text);
+                return { lines: [sig === 'neutral' ? 'noted — no clear positive/negative signal, so nothing was recorded.' : `recorded ${sig} feedback on the last result.`] };
+            }
+            case 'learning':
+                return this.learning();
+            case 'dry-run':
+            case 'dryrun':
+                this.dryRunMode = !this.dryRunMode;
+                return { lines: [`dry-run ${this.dryRunMode ? 'ON — plans will be shown, nothing executed' : 'OFF'}`] };
+            case 'memory':
+                return this.memory(args);
+            case 'conversations':
+                return this.conversationsList();
+            case 'resume':
+                return this.resume(args[0]);
+            case 'executions':
+                return this.executionsList();
+            case 'resume-execution':
+                return this.resumeExecution(args[0]);
+            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':
+                return args[0] ? { lines: [this.runtime.cancelExecution(args[0]) ? `cancelled ${args[0]}` : `cannot cancel '${args[0]}'`] } : { lines: ['usage: /cancel <execution-id>'] };
+            default:
+                return { lines: [`unknown command: ${token}. Try /help.`] };
+        }
+    }
+    async runInput(input, forceMode) {
+        if (this.runtime.conversations.enabled) {
+            if (!this.conversationId)
+                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 lines = [];
+        if (result.response?.text)
+            lines.push(result.response.text);
+        else if (result.response?.json !== undefined)
+            lines.push(JSON.stringify(result.response.json, null, 2));
+        else if (result.error)
+            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 === 'failed')
+            lines.push('(did not complete)');
+        if (result.clarification)
+            lines.push(`? ${result.clarification.question}`);
+        if (result.memory?.captured)
+            lines.push('(remembered)');
+        if (this.conversationId && result.response?.text)
+            this.runtime.conversations.append(this.conversationId, 'assistant', result.response.text, result.runId);
+        return { lines };
+    }
+    memory(args) {
+        if (!this.runtime.memory.enabled)
+            return { lines: ['memory is disabled (stateless mode).'] };
+        const sub = args[0];
+        if (sub === 'search') {
+            const q = args.slice(1).join(' ');
+            if (!q)
+                return { lines: ['usage: /memory search <query>'] };
+            const hits = this.runtime.memory.search(q, { limit: 10 });
+            return { lines: hits.length ? hits.map((r) => `  ${r.id}  [${r.scope}]  ${r.text}`) : ['no matches.'] };
+        }
+        if (sub === 'delete') {
+            if (!args[1])
+                return { lines: ['usage: /memory delete <id>'] };
+            const audit = this.runtime.memory.delete(args[1]);
+            if (!audit.primary)
+                return { lines: [`no memory '${args[1]}'.`] };
+            return { lines: [`Deleted ${audit.id}`, '  ✓ primary record', '  ✓ indexes', `  ✓ relationships (${audit.relationships} updated)`, '  ✓ cache'] };
+        }
+        if (sub === 'clear') {
+            const removed = this.runtime.memory.all().filter((r) => r.scope === 'project');
+            for (const r of removed)
+                this.runtime.memory.delete(r.id);
+            return { lines: [`cleared ${removed.length} project-scope facts.`] };
+        }
+        // default: list
+        const all = this.runtime.memory.all().filter((r) => !r.supersededBy);
+        return { lines: all.length ? all.map((r) => `  ${r.id}  [${r.scope}]  ${r.text}`) : ['no memories stored.'] };
+    }
+    learning() {
+        if (!this.runtime.learning.enabled)
+            return { lines: ['learning is disabled (stateless mode).'] };
+        const snap = this.runtime.learning.snapshot();
+        if (!snap.length)
+            return { lines: ['no learning recorded yet.'] };
+        const lines = ['Learning (observed outcomes):'];
+        for (const s of snap.slice(0, 15))
+            lines.push(`  ${s.key.padEnd(28)} ${s.successes}/${s.attempts} ok  +${s.positive}/-${s.negative}`);
+        const preferred = this.runtime.learning.preferredProviders();
+        if (preferred.length)
+            lines.push(`soft-preferred providers: ${preferred.join(', ')}`);
+        return { lines };
+    }
+    permissions() {
+        const p = this.runtime.permissions();
+        return {
+            lines: [
+                'Tool permissions:',
+                `  filesystem   read=${p.filesystem.read}  write=${p.filesystem.write}`,
+                `  shell        enabled=${p.shell.enabled}  allowed=[${p.shell.allowedCommands.join(', ')}]`,
+                `  git          commit=${p.git.commit}  push=${p.git.push}`,
+                `  network      enabled=${p.network.enabled}`,
+                '(write/exec are off unless granted in .ai-runtime/config.yaml; destructive shell always needs approval)',
+            ],
+        };
+    }
+    conversationsList() {
+        if (!this.runtime.conversations.enabled)
+            return { lines: ['conversations are disabled (stateless mode).'] };
+        const list = this.runtime.conversations.list().slice(0, 10);
+        if (!list.length)
+            return { lines: ['no conversations yet.'] };
+        return { lines: ['Recent conversations:', ...list.map((c, i) => `  ${i + 1}. ${c.id}  ${c.title} (${c.turns} turns)`)] };
+    }
+    executionsList() {
+        if (!this.runtime.executionStore.enabled)
+            return { lines: ['executions are disabled (stateless mode).'] };
+        const list = this.runtime.executions().slice(0, 10);
+        if (!list.length)
+            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) {
+        if (!id)
+            return { lines: ['usage: /resume-execution <execution-id>'] };
+        const r = await this.runtime.resumeExecution(id);
+        const lines = [];
+        if (r.response?.text)
+            lines.push(r.response.text);
+        lines.push(`status: ${r.status}`);
+        if (r.clarification)
+            lines.push(`? ${r.clarification.question}`);
+        return { lines };
+    }
+    resume(id) {
+        if (!id)
+            return { lines: ['usage: /resume <conversation-id>'] };
+        const meta = this.runtime.conversations.meta(id);
+        if (!meta)
+            return { lines: [`no conversation '${id}'.`] };
+        this.conversationId = id;
+        const turns = this.runtime.conversations.turns(id).slice(-6);
+        return { lines: [`resumed ${id} — ${meta.title}`, ...turns.map((t) => `  ${t.role}: ${t.text.length > 80 ? t.text.slice(0, 77) + '…' : t.text}`)] };
+    }
+    status() {
+        const ws = this.runtime.workspaceInfo();
+        const providers = this.runtime.ai.providers();
+        return {
+            lines: [
+                `workspace: ${ws?.name ?? '(none)'}${ws?.git.branch ? ` @ ${ws.git.branch}` : ''}`,
+                `mode:      ${this.mode}`,
+                `providers: ${providers.length} configured (${providers.filter((p) => p.enabled).length} enabled)`,
+            ],
+        };
+    }
+    setOrShowMode(next) {
+        if (!next)
+            return { lines: [`mode: ${this.mode}`] };
+        if (!RUNTIME_MODES.includes(next))
+            return { lines: [`invalid mode '${next}'. valid: ${RUNTIME_MODES.join(', ')}`] };
+        this.mode = next;
+        return { lines: [`mode set to ${this.mode}`] };
+    }
+    config() {
+        const s = this.runtime.settings();
+        const providers = this.runtime.ai.providers();
+        const lines = [`default mode: ${s.defaultMode ?? 'auto'}`, `default strategy: ${s.defaultStrategy ?? '(router default)'}`, 'providers:'];
+        if (providers.length === 0)
+            lines.push('  (none configured)');
+        for (const p of providers)
+            lines.push(`  ${p.enabled ? '●' : '○'} ${p.id} (${p.kind}, ${p.privacyClass})`);
+        return { lines };
+    }
+    async models() {
+        const views = await this.views().get();
+        const lines = ['Models:'];
+        for (const v of views)
+            for (const m of v.models)
+                lines.push(`  ${v.id}/${m.id}  ctx=${m.contextWindow ? Math.round(m.contextWindow / 1000) + 'k' : '?'}  ${m.verified ? 'verified' : m.cataloged ? 'cataloged' : 'unknown'}`);
+        if (lines.length === 1)
+            lines.push('  (no providers configured)');
+        return { lines };
+    }
+    async providers(target, detail) {
+        if (target === 'setup') {
+            const lines = ['Add a provider by setting its API key env var (or install Ollama for a local, no-key option):'];
+            for (const c of SETUP_CANDIDATES)
+                lines.push(`  • ${c.id.padEnd(11)} ${c.apiKeyEnv ? `${c.apiKeyEnv}  →  ` : 'local, no key      →  '}${c.link}`);
+            lines.push('Then run `ai-runtime setup` (or add them to .ai-runtime/config.yaml).');
+            return { lines };
+        }
+        const views = await this.views().get();
+        if (views.length === 0)
+            return { lines: ['No providers configured. Run `ai-runtime setup` or add a provider to .ai-runtime/config.yaml.'] };
+        if (!target || target === 'all') {
+            const lines = ['Providers:'];
+            for (const v of views) {
+                lines.push(`  ${v.enabled ? '●' : '○'} ${v.id.padEnd(14)} ${v.accessState.padEnd(15)} ${v.models.length} models${v.stale ? '  (stale)' : ''}`);
+                if (detail === 'models')
+                    for (const m of v.models)
+                        lines.push(`      ${m.id}  ${m.verified ? 'verified' : m.cataloged ? 'cataloged' : 'unknown'}`);
+            }
+            return { lines };
+        }
+        const v = views.find((x) => x.id.toLowerCase() === target.toLowerCase());
+        if (!v)
+            return { lines: [`unknown provider '${target}'.`] };
+        return { lines: providerDetail(v, detail) };
+    }
+}
+function providerDetail(v, detail) {
+    if (detail === 'health')
+        return [`${v.id}: ${v.accessState} (health ${v.healthState}${v.stale ? ', stale' : ''}${v.ageMs !== undefined ? `, checked ${Math.round(v.ageMs / 1000)}s ago` : ''})`];
+    if (detail === 'capabilities') {
+        const lines = [`${v.id} model capabilities:`];
+        for (const m of v.models)
+            lines.push(`  ${m.id}: ${m.verified ? 'verified' : m.cataloged ? 'cataloged' : 'unknown'} (source ${m.source})`);
+        return lines;
+    }
+    // default or "models"
+    const lines = [`${v.id} [${v.accessState}] — ${v.kind}, ${v.enabled ? 'enabled' : 'disabled'}`, 'models:'];
+    for (const m of v.models)
+        lines.push(`  ${m.id}  ctx=${m.contextWindow ? Math.round(m.contextWindow / 1000) + 'k' : '?'}  ${m.verified ? 'verified' : m.cataloged ? 'cataloged' : 'unknown'}`);
+    if (v.models.length === 0)
+        lines.push('  (none discovered)');
+    return lines;
+}

package/dist/cli/prompt.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Minimal yes/no terminal prompt (node:readline, zero deps). Used by mutating commands (setup, cleanup)
+ * so nothing on disk changes without an explicit confirmation. Defaults to NO on an empty answer or a
+ * non-interactive stdin — the safe default is never to mutate.
+ */
+export declare function confirm(question: string): Promise<boolean>;

package/dist/cli/prompt.js

@@ -0,0 +1,18 @@
+/**
+ * Minimal yes/no terminal prompt (node:readline, zero deps). Used by mutating commands (setup, cleanup)
+ * so nothing on disk changes without an explicit confirmation. Defaults to NO on an empty answer or a
+ * non-interactive stdin — the safe default is never to mutate.
+ */
+import { createInterface } from 'node:readline';
+export async function confirm(question) {
+    if (!process.stdin.isTTY)
+        return false; // non-interactive (CI/pipe) → never mutate implicitly
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        const answer = await new Promise((resolve) => rl.question(`${question} [y/N] `, resolve));
+        return /^y(es)?$/i.test(answer.trim());
+    }
+    finally {
+        rl.close();
+    }
+}

package/dist/cli/render.d.ts

@@ -0,0 +1,7 @@
+/**
+ * CLI output helpers. EVERY line printed by the CLI goes through here so it is redacted — the terminal
+ * and CI logs are first-class egress sinks (see the security hardening notes). Never `console.log`
+ * directly from a command.
+ */
+export declare function print(line: string): void;
+export declare function printError(line: string): void;

package/dist/cli/render.js

@@ -0,0 +1,14 @@
+/**
+ * CLI output helpers. EVERY line printed by the CLI goes through here so it is redacted — the terminal
+ * and CI logs are first-class egress sinks (see the security hardening notes). Never `console.log`
+ * directly from a command.
+ */
+import { redactString } from '../security/redact.js';
+export function print(line) {
+    // eslint-disable-next-line no-console
+    console.log(redactString(line));
+}
+export function printError(line) {
+    // eslint-disable-next-line no-console
+    console.error(redactString(line));
+}

package/dist/comparison/analysis.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Deterministic comparison analysis — no model calls, no randomness. Outputs are compared by token-set
+ * similarity (reusing the memory tokenizer), clustered into agreement groups, diffed pairwise, checked
+ * for unique ("missing from others") sentences, and — for structured (JSON) outputs — checked for direct
+ * field-level contradictions. Everything here is a pure function of the candidates, so it is fully unit
+ * testable and never fabricates a contradiction it cannot ground (free-text contradictions are left to a
+ * judge; only structured fields are asserted as contradictions).
+ */
+import type { AgreementCluster, ComparisonAnalysis, ComparisonCandidate, ComparisonDifference, Contradiction, MissingPoint } from './comparison.js';
+/** Token-set Jaccard similarity of two token bags, 0..1. Two empty bags count as identical (1). */
+export declare function jaccard(a: string[], b: string[]): number;
+/**
+ * Similarity of two output texts, 0..1 (Jaccard over their tokenized bags). When either side tokenizes
+ * to nothing (e.g. all stopwords/punctuation), tokens carry no signal — fall back to exact normalized
+ * text equality so two DIFFERENT all-stopword outputs are not reported as identical.
+ */
+export declare function similarity(a: string, b: string): number;
+/** Deterministic key-sorted JSON stringification (so field order never affects comparison). */
+export declare function stableStringify(value: unknown): string;
+/** The text used to compare a candidate: its text, or a stable stringification of its JSON. */
+export declare function comparableText(c: ComparisonCandidate): string;
+/** Candidates that both ran successfully and produced comparable output. */
+export declare function comparable(candidates: ComparisonCandidate[]): ComparisonCandidate[];
+/**
+ * Greedy agreement clustering: each candidate joins the first cluster whose representative it is at
+ * least `threshold`-similar to, else starts its own. Deterministic in input order.
+ */
+export declare function clusterByAgreement(candidates: ComparisonCandidate[], threshold: number): AgreementCluster[];
+/** Every pair of candidates whose outputs are below the agreement threshold, most-different first. */
+export declare function pairwiseDifferences(candidates: ComparisonCandidate[], threshold: number): ComparisonDifference[];
+/** Split text into trimmed sentence-ish units on sentence terminators and newlines. */
+export declare function splitSentences(text: string): string[];
+/**
+ * For each candidate, sentences that no OTHER candidate expresses (similarity < 0.6 to every sentence of
+ * every other candidate). This surfaces information one model included and others omitted. Skipped when
+ * fewer than two candidates. Capped to keep output readable.
+ */
+export declare function missingPoints(candidates: ComparisonCandidate[], perCandidateCap?: number): MissingPoint[];
+/**
+ * Direct contradictions across STRUCTURED outputs only: for each top-level scalar field present in ≥2
+ * candidates' JSON, if the candidates disagree on its value it is a contradiction. Objects/arrays are not
+ * asserted as contradictions here (that needs semantic judgment, not a deterministic diff).
+ */
+export declare function structuredContradictions(candidates: ComparisonCandidate[]): Contradiction[];
+/** Full deterministic analysis of a set of candidates at the given agreement threshold. */
+export declare function analyze(candidates: ComparisonCandidate[], threshold: number): ComparisonAnalysis;