ai-runtime-engine 1.1.0

package/dist/runtime/runtime.js

@@ -0,0 +1,718 @@
+/**
+ * Runtime — the high-level facade OVER the existing `AI` router. It resolves a mode + policy, assembles
+ * a RuntimeContext, executes chat through `AI.run()`, and streams redacted lifecycle events. It never
+ * routes or scores; all model selection stays in the one router. Unimplemented modes degrade to chat.
+ */
+import { resolve } from 'node:path';
+import { AI } from '../plugin/ai.js';
+import { setCredentialResolver } from '../security/credentials.js';
+import { loadRuntimeConfig } from './config.js';
+import { detectWorkspace } from './workspace/workspace.js';
+import { HeuristicIntentClassifier } from './intent/classifier.js';
+import { resolveMode, resolveStrategy } from './modes/modeResolver.js';
+import { resolvePolicy } from './policy.js';
+import { CHAT_TASK, buildChatRequest, toRuntimeResult, inputText } from './modes/chat.js';
+import { RuntimeEmitter } from './events.js';
+import { systemClock } from '../util/clock.js';
+import { RuntimeStore } from '../store/store.js';
+import { ConversationStore } from '../conversations/conversations.js';
+import { MemoryStore } from '../memory/memory.js';
+import { classifyMemory } from '../memory/classifier.js';
+import { summarizeWorkspace } from './workspace/workspace.js';
+import { compileContext } from '../context/compiler.js';
+import { resolveContextBudget } from '../context/budget.js';
+import { TokenEstimator } from '../context/tokens.js';
+import { ToolRegistry } from '../tools/registry.js';
+import { resolvePermissions } from '../tools/permissions.js';
+import { filesystemTool } from '../tools/builtins/filesystem.js';
+import { shellTool } from '../tools/builtins/shell.js';
+import { gitTool } from '../tools/builtins/git.js';
+import { SkillRegistry } from '../skills/registry.js';
+import { fileAnalyzerSkill } from '../skills/builtins/fileAnalyzer.js';
+import { repositoryAnalyzerSkill } from '../skills/builtins/repositoryAnalyzer.js';
+import { discoverSkills, scanRepoForSkills, loadSkillSource, loadSkillPackage } from '../skills/discovery.js';
+import { orchestrate } from '../orchestration/orchestrator.js';
+import { executePlan } from '../orchestration/executor.js';
+import { ExecutionStore } from '../executions/store.js';
+import { RESUMABLE, TERMINAL } from '../executions/execution.js';
+import { captureCheckpoint, reconcile } from '../executions/checkpoint.js';
+import { ArtifactStore } from '../artifacts/artifacts.js';
+import { compare } from '../comparison/comparator.js';
+import { renderComparison } from '../comparison/render.js';
+import { LearningStore } from '../learning/learningStore.js';
+import { resolveRoutingPrefs, withPreferredProviders } from './routing.js';
+import { tokenize } from '../memory/bm25.js';
+let runCounter = 0;
+function nextRunId() {
+    runCounter += 1;
+    return `run_${runCounter.toString(36)}_${Math.random().toString(36).slice(2, 8)}`;
+}
+function numFromEnv(env, key) {
+    const raw = env[key];
+    if (raw === undefined || raw === '')
+        return undefined;
+    const n = Number(raw);
+    return Number.isFinite(n) ? n : undefined;
+}
+export class Runtime {
+    _ai;
+    settingsValue;
+    classifier;
+    env;
+    workspace;
+    emitter;
+    _store;
+    _memory;
+    _conversations;
+    estimator = new TokenEstimator();
+    _tools = new ToolRegistry();
+    _skills = new SkillRegistry();
+    _executions;
+    _artifacts;
+    _learning;
+    workspaceRoot;
+    configPermissions;
+    approval;
+    _configFile;
+    _loadedSkillSources = [];
+    constructor(config = { router: { providers: [] } }, options = {}, workspace) {
+        this._ai = new AI(config.router, options.ai);
+        this.settingsValue = config.runtime ?? {};
+        this.classifier = options.classifier ?? new HeuristicIntentClassifier();
+        this.env = options.ai?.env ?? process.env;
+        if (workspace)
+            this.workspace = workspace;
+        this.configPermissions = config.permissions ?? {};
+        if (options.host?.approval)
+            this.approval = options.host.approval;
+        if (options.configFile)
+            this._configFile = options.configFile;
+        // Local store (conversations + memory). Disabled → NullAreas (stateless mode).
+        const clock = options.ai?.clock ?? systemClock;
+        const root = workspace?.root ?? resolveCwd(options.workspace ?? options.host?.workspace);
+        this.workspaceRoot = root;
+        this._store = new RuntimeStore({ workspaceRoot: root, ...(workspace?.name ? { workspaceName: workspace.name } : {}), env: this.env, clock, enabled: options.persistence !== 'disabled' });
+        this._memory = new MemoryStore(this._store, clock);
+        this._conversations = new ConversationStore(this._store.conversations(), clock);
+        this._executions = new ExecutionStore(this._store.executions(), { clock });
+        this._artifacts = new ArtifactStore(this._store.artifacts(), clock);
+        this._learning = new LearningStore(this._store.learning());
+        // Built-in tools + generic skills (QA-neutral). Users add more via registerTool/registerSkill.
+        this._tools.register(filesystemTool).register(shellTool).register(gitTool);
+        this._skills.register(fileAnalyzerSkill).register(repositoryAnalyzerSkill);
+        // Host integration: attach an event sink and register a credential resolver if supplied.
+        const host = options.host;
+        this.emitter = new RuntimeEmitter({
+            ...(options.ai?.clock ? { clock: options.ai.clock } : {}),
+            ...(host?.eventSink ? { sinks: [host.eventSink] } : {}),
+        });
+        if (host?.credentialResolver)
+            setCredentialResolver(host.credentialResolver);
+        // Register the generic chat task only if the user hasn't defined their own.
+        const hasChat = this._ai.tasksList().some((t) => t.id === 'chat' || t.aliases?.includes('chat'));
+        if (!hasChat)
+            this._ai.registerTask(CHAT_TASK);
+    }
+    /** Build a Runtime from a workspace: load config (.ai-runtime/config.yaml > root fallback), detect workspace. */
+    static async load(options = {}) {
+        const workspaceRoot = resolveCwd(options.workspace ?? options.host?.workspace);
+        const loaded = loadRuntimeConfig({ workspaceRoot, ...(options.config ? { explicitPath: options.config } : {}) });
+        const workspace = options.detectWorkspace === false ? undefined : detectWorkspace(workspaceRoot, options.ai?.clock);
+        const rt = new Runtime(loaded.config, { ...options, ...(loaded.configFile ? { configFile: loaded.configFile } : {}) }, workspace);
+        await rt.autoloadSkills();
+        return rt;
+    }
+    /**
+     * Load consented local skills — the conventional `.ai-runtime/skills/` dir plus any `skills.paths` in
+     * config — and register them. Manifests are data; module skills run the user's own code, which is why
+     * only these consented locations auto-load. Off when `skills.autoload: false`. Resilient: a broken
+     * source is recorded (see `skillSources()`), never fatal. Called by `Runtime.load`.
+     */
+    async autoloadSkills() {
+        const settings = this.settingsValue.skills ?? {};
+        if (settings.autoload === false)
+            return;
+        let sources;
+        try {
+            sources = discoverSkills({ root: this.workspaceRoot, ...(settings.paths ? { paths: settings.paths } : {}) });
+        }
+        catch {
+            return; // discovery must never break construction
+        }
+        const loaded = await Promise.all(sources.map((s) => loadSkillSource(s)));
+        // npm skill packs (trusted dependencies, resolved from node_modules — not workspace-jailed).
+        const pkgLoaded = await Promise.all((settings.packages ?? []).map((p) => loadSkillPackage(p)));
+        const all = [...loaded, ...pkgLoaded];
+        for (const l of all)
+            for (const sk of l.skills)
+                this._skills.register(sk);
+        this._loadedSkillSources = all;
+    }
+    /** What autoloadSkills loaded (or failed to), for `info`/`doctor`/`skills` reporting. */
+    skillSources() {
+        return this._loadedSkillSources;
+    }
+    /** Scan the workspace for skill-looking files elsewhere (report only — nothing is loaded). */
+    discoverSkillCandidates() {
+        return scanRepoForSkills({ root: this.workspaceRoot });
+    }
+    /** Explicitly load chosen skill sources (e.g. candidates the user picked) and register them. */
+    async loadSkillSources(sources) {
+        const loaded = await Promise.all(sources.map((s) => loadSkillSource(s)));
+        for (const l of loaded)
+            for (const sk of l.skills)
+                this._skills.register(sk);
+        this._loadedSkillSources = [...this._loadedSkillSources, ...loaded];
+        return loaded;
+    }
+    /** The config file this runtime resolved (`.ai-runtime/config.yaml` or a fallback), if any. */
+    get configFile() {
+        return this._configFile;
+    }
+    /** The inner router facade — register providers/tasks/MCP sources here. */
+    get ai() {
+        return this._ai;
+    }
+    /** The local runtime store (conversations, memory, indexes, cache). */
+    get store() {
+        return this._store;
+    }
+    /** Durable scoped memory. */
+    get memory() {
+        return this._memory;
+    }
+    /** Persistent conversation history. */
+    get conversations() {
+        return this._conversations;
+    }
+    memoryEnabled() {
+        return this._memory.enabled && this.env.AI_MEMORY_ENABLED !== 'false';
+    }
+    /** Durable cross-run learning (provider/skill/workflow/plan outcomes; feeds soft prefer signals). */
+    get learning() {
+        return this._learning;
+    }
+    learningEnabled() {
+        return this._learning.enabled && this.env.AI_LEARNING_ENABLED !== 'false';
+    }
+    /**
+     * Effective exclude/prefer routing for a run: env + project config + per-run (unioned), then learned
+     * soft-prefer folded in — but never re-admitting an excluded provider. Learning stays subordinate to
+     * every hard gate (exclude/privacy/pin/capability/budget), which the router filter enforces.
+     */
+    effectiveRouting(perRun) {
+        const base = resolveRoutingPrefs({
+            env: this.env,
+            ...(this.settingsValue.routing ? { config: this.settingsValue.routing } : {}),
+            ...(perRun ? { perRun } : {}),
+        });
+        if (!this.learningEnabled())
+            return base;
+        return withPreferredProviders(base, this._learning.preferredProviders());
+    }
+    /** Apply free-text feedback (e.g. "that worked" / "wrong root cause") to the most recent outcome. */
+    feedback(text, opts) {
+        return this._learning.feedback(text, opts ?? {});
+    }
+    /** A coarse goal pattern (first few significant tokens) keying workflow/plan learning. */
+    goalType(text) {
+        const toks = tokenize(text).slice(0, 3);
+        return toks.length ? toks.join('-') : 'general';
+    }
+    /** Resolve exact-version SkillRefs for the skill steps of a plan (for skill/workflow learning). */
+    planSkillRefs(plan) {
+        if (!plan)
+            return [];
+        const refs = [];
+        for (const step of plan.steps) {
+            if (!step.skill)
+                continue;
+            const version = this._skills.get(step.skill)?.version;
+            if (version)
+                refs.push({ id: step.skill, version });
+        }
+        return refs;
+    }
+    /** Register a tool. Chainable. */
+    registerTool(tool) {
+        this._tools.register(tool);
+        return this;
+    }
+    tools() {
+        return this._tools.list();
+    }
+    /** Register a skill. Chainable. */
+    registerSkill(skill) {
+        this._skills.register(skill);
+        return this;
+    }
+    /** Skills whose required tools are all registered. */
+    skills() {
+        return this._skills.match({ tools: this._tools.ids() });
+    }
+    /** The resolved tool permissions for this runtime (config grants over deny-by-default defaults). */
+    permissions() {
+        return resolvePermissions(this.configPermissions);
+    }
+    toolContext(overrides) {
+        return {
+            workspaceRoot: this.workspaceRoot,
+            permissions: resolvePermissions({ ...this.configPermissions, ...(overrides?.permissions ?? {}) }),
+            ...(this.approval ? { approval: this.approval } : {}),
+            ...(overrides?.signal ? { signal: overrides.signal } : {}),
+        };
+    }
+    /** Invoke a registered tool with the runtime's resolved permissions + host approval. */
+    async runTool(id, input, overrides) {
+        const tool = this._tools.get(id);
+        if (!tool)
+            return { ok: false, error: { code: 'NOT_FOUND', message: `no tool '${id}'` } };
+        return tool.execute(input, this.toolContext(overrides));
+    }
+    /** Run a skill end-to-end (plan → execute → validate) with tools bound to the runtime's permissions. */
+    async runSkill(id, input, overrides) {
+        const skill = this._skills.get(id);
+        if (!skill)
+            throw new Error(`no skill '${id}'`);
+        const toolCtx = this.toolContext(overrides);
+        const ctx = {
+            input,
+            ai: this._ai,
+            callTool: async (toolId, toolInput) => {
+                const tool = this._tools.get(toolId);
+                if (!tool)
+                    return { ok: false, error: { code: 'NOT_FOUND', message: `no tool '${toolId}'` } };
+                return tool.execute(toolInput, toolCtx);
+            },
+            ...(overrides?.signal ? { signal: overrides.signal } : {}),
+        };
+        const plan = await skill.plan(ctx);
+        const result = await skill.execute(ctx, plan);
+        const validation = await skill.validate(result, ctx);
+        return { plan, result, validation };
+    }
+    workspaceInfo() {
+        return this.workspace;
+    }
+    settings() {
+        return this.settingsValue;
+    }
+    /** Subscribe to runtime lifecycle events; returns an unsubscribe function. */
+    on(listener) {
+        return this.emitter.on(listener);
+    }
+    /** Recent runtime events (redacted, metadata only). */
+    events() {
+        return this.emitter.recent();
+    }
+    async run(input) {
+        const req = typeof input === 'string' ? { input } : input;
+        const runId = nextRunId();
+        const text = inputText(req.input);
+        this.emitter.emit({ type: 'runtime.started', runId, requested: req.mode ?? 'auto' });
+        const modeResult = await resolveMode({
+            ...(req.mode !== undefined ? { explicit: req.mode } : {}),
+            ...(this.settingsValue.defaultMode !== undefined ? { configDefault: this.settingsValue.defaultMode } : {}),
+            ...(this.env.AI_DEFAULT_MODE !== undefined ? { envDefault: this.env.AI_DEFAULT_MODE } : {}),
+            intent: { text, hasParts: typeof req.input !== 'string' && !!req.input.parts?.length, ...(this.workspace ? { workspace: this.workspace } : {}) },
+            classifier: this.classifier,
+        });
+        const resolution = modeResult.resolution;
+        this.emitter.emit({ type: 'mode.selected', runId, requested: resolution.requested, selected: resolution.selected, executed: resolution.executed, source: resolution.source, confidence: resolution.confidence });
+        const strategy = resolveStrategy({
+            ...(req.strategy !== undefined ? { explicit: req.strategy } : {}),
+            ...(this.settingsValue.defaultStrategy !== undefined ? { configDefault: this.settingsValue.defaultStrategy } : {}),
+            ...(this.env.AI_DEFAULT_STRATEGY !== undefined ? { envDefault: this.env.AI_DEFAULT_STRATEGY } : {}),
+        });
+        const envLimits = { maxCostUsd: numFromEnv(this.env, 'AI_MAX_COST_USD'), maxCalls: numFromEnv(this.env, 'AI_MAX_CALLS') };
+        const overrides = { ...(req.dryRun ? { dryRun: true } : {}), ...(this.configPermissions ? { permissions: this.configPermissions } : {}) };
+        const policy = resolvePolicy({ mode: resolution.executed, overrides, settings: this.settingsValue, env: envLimits });
+        const routing = this.effectiveRouting(req.routing);
+        const context = {
+            runId,
+            ...(req.requestId ? { requestId: req.requestId } : {}),
+            request: req,
+            ...(this.workspace ? { workspace: this.workspace } : {}),
+            policy,
+            ...(envLimits.maxCostUsd !== undefined || envLimits.maxCalls !== undefined ? { budget: { ...(envLimits.maxCostUsd !== undefined ? { maxCostUsd: envLimits.maxCostUsd } : {}), ...(envLimits.maxCalls !== undefined ? { maxCalls: envLimits.maxCalls } : {}) } } : {}),
+        };
+        // Orchestration modes (plan/execute/orchestrate) plan + drive skills/tools; they do not use the
+        // chat memory/context path. Clarification here comes from the planner, not mode ambiguity.
+        if (resolution.executed === 'plan' || resolution.executed === 'execute' || resolution.executed === 'orchestrate' || resolution.executed === 'agent' || resolution.executed === 'debug') {
+            return this.runOrchestration(resolution.executed, text, resolution, runId, policy, req.requestId, routing);
+        }
+        // Compare mode: fan out the same task across pins and analyze — read-only, no approval gate.
+        if (resolution.executed === 'compare') {
+            return this.runCompareMode(req, text, resolution, runId, policy, routing);
+        }
+        // ── chat path ──
+        // Ambiguity: attach non-blocking clarification metadata (a real ask-back UX arrives with the REPL).
+        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);
+        // 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 } : {}),
+            ...(this.settingsValue.context?.maxTokens !== undefined ? { config: this.settingsValue.context.maxTokens } : {}),
+            ...(this.env.AI_CONTEXT_MAX_TOKENS !== undefined ? { env: this.env.AI_CONTEXT_MAX_TOKENS } : {}),
+        });
+        const compiled = compileContext(this.contextBlocks(req, context.workspace, memTrace?.retrieved), { budgetTokens: budget, estimator: this.estimator });
+        const contextReport = { metrics: compiled.metrics, validation: compiled.validation };
+        const runRequest = buildChatRequest(req, strategy, compiled.system || undefined, routing);
+        const runResult = await this._ai.run(runRequest);
+        this.calibrate(runRequest.system, text, runResult);
+        const sel = runResult.routing.selected;
+        if (this.learningEnabled()) {
+            this._learning.record({ goalType: this.goalType(text), mode: 'chat', ok: runResult.ok, ...(sel ? { providerId: sel.providerId, model: sel.model } : {}), latencyMs: attemptsLatency(runResult) });
+        }
+        if (sel)
+            this.emitter.emit({ type: 'provider.selected', runId, providerId: sel.providerId, model: sel.model });
+        else {
+            const lastFail = [...runResult.routing.attempts].reverse().find((a) => a.outcome !== 'success');
+            if (lastFail)
+                this.emitter.emit({ type: 'provider.failed', runId, providerId: lastFail.providerId, model: lastFail.model, ...(lastFail.category ? { category: lastFail.category } : {}) });
+        }
+        this.emitter.emit({ type: 'run.completed', runId, ok: runResult.ok, status: clarification ? 'waiting_for_clarification' : 'completed', confidence: runResult.confidence });
+        const result = toRuntimeResult(runResult, resolution, runId, clarification);
+        if (memTrace)
+            result.memory = memTrace;
+        result.context = contextReport;
+        return result;
+    }
+    /** The persistent execution store and its owner-lease machinery. */
+    get executionStore() {
+        return this._executions;
+    }
+    /** The artifact store (content owner behind ArtifactRef). */
+    get artifacts() {
+        return this._artifacts;
+    }
+    /** Recent persisted executions, newest first. */
+    executions() {
+        return this._executions.list();
+    }
+    /** plan/execute/orchestrate/agent/debug: run the orchestrator and persist a resumable Execution. */
+    async runOrchestration(mode, goal, resolution, runId, policy, requestId, routing) {
+        const effectiveGoal = mode === 'debug' ? `Investigate and diagnose the following, gathering evidence before concluding: ${goal}` : goal;
+        // plan mode and dry-run produce no durable work → run without persisting an execution.
+        if (mode === 'plan' || policy.dryRun || !this._executions.enabled) {
+            const outcome = await orchestrate(this.orchestrateInput(mode, effectiveGoal, policy, routing));
+            this.recordOrchestration(mode, goal, outcome);
+            return this.mapOutcome(outcome, resolution, runId, undefined);
+        }
+        // Reserve the execution BEFORE running (persist-in-progress + claim the requestId under the store
+        // lock so a concurrent retry with the same requestId dedupes to it).
+        const reserved = this._store.withLock(() => {
+            if (requestId) {
+                const ex = this._executions.byRequestId(requestId);
+                if (ex)
+                    return { exec: ex, existed: true };
+            }
+            return { exec: this._executions.create({ ...(requestId ? { requestId } : {}), goal, mode, planVersion: 0, status: 'running' }), existed: false };
+        });
+        if (reserved.existed) {
+            this._executions.release(reserved.exec.id);
+            return this.resultFromExecution(reserved.exec, resolution, runId);
+        }
+        const exec = reserved.exec;
+        try {
+            // Renew the lease while the (possibly long) run is in flight so it can't expire mid-run.
+            const outcome = await this.withHeartbeat(exec.id, () => orchestrate(this.orchestrateInput(mode, effectiveGoal, policy, routing)));
+            exec.status = this.execStatus(outcome.status);
+            exec.observations = outcome.observations;
+            if (outcome.plan) {
+                exec.plan = outcome.plan;
+                exec.planVersion = outcome.plan.version;
+                exec.completedSteps = outcome.plan.steps.filter((s) => s.status === 'succeeded').map((s) => s.id);
+            }
+            if (outcome.status === 'waiting_for_approval')
+                exec.pending = { kind: 'approval', action: goal };
+            else if (outcome.status === 'waiting_for_clarification' && outcome.clarification)
+                exec.pending = { kind: 'clarification', question: outcome.clarification };
+            exec.checkpoints.push(captureCheckpoint({ root: this.workspaceRoot, ...(exec.plan ? { plan: exec.plan } : {}), skills: this.skills(), completedSteps: exec.completedSteps }));
+            this._executions.commit(exec); // ownership-checked: never clobber a newer owner
+            this.recordOrchestration(mode, goal, outcome);
+            return this.mapOutcome(outcome, resolution, runId, exec.id);
+        }
+        finally {
+            this._executions.release(exec.id);
+        }
+    }
+    /** Run `fn` while heartbeating the execution lease so a long run never lets the lease expire. */
+    async withHeartbeat(id, fn) {
+        const timer = setInterval(() => this._executions.heartbeat(id), this._executions.heartbeatMs);
+        if (typeof timer.unref === 'function')
+            timer.unref();
+        try {
+            return await fn();
+        }
+        finally {
+            clearInterval(timer);
+        }
+    }
+    orchestrateInput(mode, goal, policy, routing) {
+        return {
+            goal,
+            mode,
+            ai: this._ai,
+            skills: this.skills(),
+            tools: this._tools.ids(),
+            policy,
+            ...(routing ? { routing } : {}),
+            ...(this.approval ? { approval: this.approval } : {}),
+            runSkill: (id, input) => this.runSkill(id, input).then((o) => ({ result: o.result, validation: o.validation })),
+            runTool: (id, input) => this.runTool(id, input),
+        };
+    }
+    /** Record an EXECUTED orchestration outcome for learning. plan-only, dry-run, and waiting states are
+     * skipped — no skill ran, so there is no success/failure to learn (recording them would teach noise). */
+    recordOrchestration(mode, goal, outcome) {
+        if (!this.learningEnabled())
+            return;
+        if (mode === 'plan' || outcome.status === 'dry-run' || outcome.status.startsWith('waiting'))
+            return;
+        this._learning.record({ goalType: this.goalType(goal), mode, ok: outcome.status === 'completed', skills: this.planSkillRefs(outcome.plan) });
+    }
+    execStatus(s) {
+        if (s === 'completed' || s === 'dry-run')
+            return 'completed';
+        if (s === 'failed')
+            return 'failed';
+        if (s === 'waiting_for_approval')
+            return 'waiting_for_input';
+        return 'waiting_for_clarification';
+    }
+    mapOutcome(outcome, resolution, runId, execId) {
+        const status = outcome.status === 'dry-run' ? 'completed' : outcome.status;
+        const ok = outcome.status === 'completed' || outcome.status === 'dry-run' || outcome.status.startsWith('waiting');
+        this.emitter.emit({ type: 'run.completed', runId, ok, status, confidence: ok ? 1 : 0 });
+        return {
+            ok,
+            runId,
+            mode: resolution,
+            status,
+            response: { text: outcome.summary },
+            ...(outcome.plan ? { plan: outcome.plan } : {}),
+            execution: { ...(execId ? { id: execId } : {}), observations: outcome.observations, planHistory: outcome.planHistory },
+            ...(outcome.clarification ? { clarification: { question: outcome.clarification } } : {}),
+            artifacts: [],
+        };
+    }
+    resultFromExecution(exec, resolution, runId) {
+        const ok = exec.status !== 'failed' && exec.status !== 'cancelled';
+        const status = exec.status === 'completed' ? 'completed' : exec.status === 'failed' || exec.status === 'cancelled' ? 'failed' : exec.status === 'waiting_for_clarification' ? 'waiting_for_clarification' : exec.status === 'waiting_for_input' ? 'waiting_for_approval' : 'completed';
+        return {
+            ok,
+            runId,
+            mode: resolution,
+            status,
+            response: { text: `execution ${exec.id} (${exec.status})` },
+            ...(exec.plan ? { plan: exec.plan } : {}),
+            execution: { id: exec.id, observations: exec.observations, planHistory: exec.plan ? [exec.plan] : [] },
+            ...(exec.pending?.kind === 'clarification' && exec.pending.question ? { clarification: { question: exec.pending.question } } : {}),
+            artifacts: exec.artifacts,
+        };
+    }
+    /**
+     * Compare a task across several models/providers and return a normalized comparison (agreement,
+     * differences, contradictions, missing info, and an EVIDENCE-first ranking). Runs entirely through the
+     * ONE router (`AI.run()` pins) — no second selection engine. Pass a `validate` for evidence-based
+     * ranking (beats any judge), or a `judge` pin for a labeled opinion; with neither it reports only.
+     */
+    async compare(input) {
+        return compare({ ...input, ai: this._ai });
+    }
+    /** compare mode: fan out over pins (default: every enabled, non-excluded provider) and render. Read-only. */
+    async runCompareMode(req, goal, resolution, runId, policy, routing) {
+        const opts = req.compare ?? {};
+        const pins = opts.pins && opts.pins.length ? opts.pins : this.defaultComparePins(routing);
+        if (pins.length < 2) {
+            const msg = `Comparison needs at least two providers/models; ${pins.length} available. Configure more providers or pass compare.pins.`;
+            this.emitter.emit({ type: 'run.completed', runId, ok: false, status: 'failed', confidence: 0 });
+            return { ok: false, runId, mode: resolution, status: 'failed', response: { text: msg }, artifacts: [] };
+        }
+        const result = await this.compare({
+            goal,
+            input: req.input,
+            ...(req.system ? { system: req.system } : {}),
+            ...(req.output ? { output: req.output } : {}),
+            pins,
+            ...(routing ? { routing } : {}),
+            ...(opts.judge ? { judge: opts.judge } : {}),
+            ...(opts.task ? { task: opts.task } : {}),
+            ...(opts.agreementThreshold !== undefined ? { agreementThreshold: opts.agreementThreshold } : {}),
+            policy: {
+                ...(policy.maxCalls !== undefined ? { maxCalls: policy.maxCalls } : {}),
+                ...(policy.maxCostUsd !== undefined ? { maxCostUsd: policy.maxCostUsd } : {}),
+                maxParallelSteps: policy.maxParallelSteps ?? 2,
+            },
+        });
+        if (this.learningEnabled())
+            this._learning.ingestComparisonSignals(result.signals);
+        for (const c of result.candidates)
+            if (c.ok && c.selected)
+                this.emitter.emit({ type: 'provider.selected', runId, providerId: c.selected.providerId, model: c.selected.model });
+        const ok = result.candidates.some((c) => c.ok);
+        const status = ok ? 'completed' : 'failed';
+        this.emitter.emit({ type: 'run.completed', runId, ok, status, confidence: ok ? 1 : 0 });
+        return { ok, runId, mode: resolution, status, response: { text: renderComparison(result).join('\n') }, comparison: result, artifacts: [] };
+    }
+    /** Default compare pins: one per enabled, non-excluded provider (model left to the provider default). */
+    defaultComparePins(routing) {
+        const excluded = new Set(routing?.excludeProviders ?? []);
+        return this._ai.providers().filter((p) => p.enabled && !excluded.has(p.id)).map((p) => ({ provider: p.id, label: p.id }));
+    }
+    /**
+     * Resume a persisted execution: acquire its lease, reconcile the workspace, then continue (if
+     * unchanged) or replan (on drift) — never blindly. Answers a pending clarification/approval.
+     */
+    async resumeExecution(id, opts = {}) {
+        const runId = nextRunId();
+        const resolution = { requested: 'auto', selected: 'orchestrate', executed: 'orchestrate', source: 'explicit', confidence: 1, reason: 'resume' };
+        const acq = this._executions.acquire(id);
+        if (!acq.ok || !acq.execution) {
+            return { ok: false, runId, mode: resolution, status: 'failed', response: { text: `cannot resume ${id}: ${acq.reason ?? 'unavailable'}` }, artifacts: [] };
+        }
+        const exec = acq.execution;
+        try {
+            if (TERMINAL.has(exec.status))
+                return this.resultFromExecution(exec, resolution, runId);
+            if (!RESUMABLE.has(exec.status))
+                return this.resultFromExecution(exec, resolution, runId);
+            // Approval gate is PRESERVED across resume: a pending approval requires an explicit decision.
+            // approve===false cancels; approve===true proceeds; anything else keeps waiting (never auto-runs).
+            if (exec.pending?.kind === 'approval') {
+                if (opts.approve === false) {
+                    exec.status = 'cancelled';
+                    this._executions.commit(exec);
+                    return this.resultFromExecution(exec, resolution, runId);
+                }
+                if (opts.approve !== true) {
+                    // Still waiting — do NOT execute a plan that was never approved.
+                    return this.resultFromExecution(exec, resolution, runId);
+                }
+            }
+            // Reconcile against the checkpoint — drift forces a replan rather than a blind continue.
+            const checkpoint = exec.checkpoints[exec.checkpoints.length - 1];
+            const recon = checkpoint ? reconcile(checkpoint, this.workspaceRoot, this.skills()) : { drifted: true, reasons: ['no checkpoint'] };
+            const goal = exec.pending?.kind === 'clarification' && opts.clarificationAnswer ? `${exec.goal}\n\nClarification: ${opts.clarificationAnswer}` : exec.goal;
+            const policy = resolvePolicy({ mode: 'orchestrate', overrides: { autonomy: 'autonomous', approval: 'none', ...(this.configPermissions ? { permissions: this.configPermissions } : {}) }, settings: this.settingsValue });
+            // We only reach here for an approval-pending execution if it was explicitly approved.
+            const approvedNow = exec.pending?.kind === 'approval';
+            const canContinue = !recon.drifted && !!exec.plan && (approvedNow || (exec.completedSteps.length > 0 && !exec.pending));
+            let outcome;
+            if (canContinue && exec.plan) {
+                // No drift → continue: execute the (approved / partially-done) plan, skipping completed steps.
+                const exe = await this.withHeartbeat(exec.id, () => executePlan(exec.plan, { ...this.orchestrateRunners(), maxParallelSteps: policy.maxParallelSteps ?? 2, skip: new Set(exec.completedSteps), ...(opts.signal ? { signal: opts.signal } : {}) }));
+                outcome = { status: exe.ok ? 'completed' : 'failed', plan: exe.plan, planHistory: [exe.plan], observations: exe.observations, summary: exe.ok ? `resumed and completed "${exec.goal}"` : `resume did not complete "${exec.goal}"` };
+            }
+            else {
+                // Drift, or a pending clarification answer, or no partial progress → replan from the goal.
+                // Re-resolve routing so env/config excludes (and learned prefer) still apply to the replan's
+                // planning-model call — a hard exclude must not be dropped just because we're resuming.
+                outcome = await this.withHeartbeat(exec.id, () => orchestrate(this.orchestrateInput('orchestrate', goal, policy, this.effectiveRouting())));
+            }
+            exec.status = this.execStatus(outcome.status);
+            exec.observations = [...exec.observations, ...outcome.observations];
+            if (outcome.plan) {
+                exec.plan = outcome.plan;
+                exec.planVersion = outcome.plan.version;
+                exec.completedSteps = outcome.plan.steps.filter((s) => s.status === 'succeeded').map((s) => s.id);
+            }
+            delete exec.pending;
+            exec.checkpoints.push(captureCheckpoint({ root: this.workspaceRoot, ...(exec.plan ? { plan: exec.plan } : {}), skills: this.skills(), completedSteps: exec.completedSteps }));
+            this._executions.commit(exec);
+            return this.mapOutcome(outcome, resolution, runId, exec.id);
+        }
+        finally {
+            this._executions.release(id);
+        }
+    }
+    orchestrateRunners() {
+        return {
+            runSkill: (skillId, input) => this.runSkill(skillId, input).then((o) => ({ result: o.result, validation: o.validation })),
+            runTool: (toolId, input) => this.runTool(toolId, input),
+        };
+    }
+    /** Mark an execution paused (it can be resumed later). */
+    pauseExecution(id) {
+        const exec = this._executions.get(id);
+        if (!exec || TERMINAL.has(exec.status))
+            return false;
+        exec.status = 'paused';
+        this._executions.save(exec);
+        this._executions.release(id);
+        return true;
+    }
+    /** Cancel an execution (terminal). */
+    cancelExecution(id) {
+        const exec = this._executions.get(id);
+        if (!exec || TERMINAL.has(exec.status))
+            return false;
+        exec.status = 'cancelled';
+        this._executions.save(exec);
+        this._executions.release(id);
+        return true;
+    }
+    /** Assemble the context blocks for a chat run: user system (critical), workspace (high), memory (normal). */
+    contextBlocks(req, workspace, facts) {
+        const blocks = [];
+        if (req.system)
+            blocks.push({ id: 'user-system', kind: 'system', text: req.system, retention: 'critical' });
+        if (req.workspaceContext !== false && workspace)
+            blocks.push({ id: 'workspace', kind: 'workspace', text: summarizeWorkspace(workspace), retention: 'high' });
+        if (facts && facts.length)
+            blocks.push({ id: 'memory', kind: 'memory', text: `Known facts:\n${facts.map((f) => `- ${f}`).join('\n')}`, retention: 'normal' });
+        return blocks;
+    }
+    /** Best-effort estimator calibration from provider-reported input usage (estimates never claim to be exact). */
+    calibrate(system, inputText, run) {
+        const tokens = run.response?.usage?.inputTokens;
+        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) {
+        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 };
+            }
+            trace.retrieved = this._memory.search(text, { limit: 3 }).map((h) => h.text);
+            if (trace.retrieved.length === 0 && !trace.captured)
+                return undefined;
+            return trace;
+        }
+        catch {
+            // Memory is an enhancement; a store problem must never break the chat itself.
+            return undefined;
+        }
+    }
+}
+/** Build clarification metadata when auto-detection was ambiguous (mode-level ambiguity in Phase 1). */
+function buildClarification(modeResult) {
+    const c = modeResult.classification;
+    if (!c || !c.ambiguous)
+        return undefined;
+    const competitors = Object.entries(c.scores)
+        .sort((a, b) => (b[1] ?? 0) - (a[1] ?? 0))
+        .slice(0, 3)
+        .map(([m]) => m);
+    return {
+        question: `I wasn't sure which mode fits — did you mean one of: ${competitors.join(', ')}? (Answering helps me route; I've answered as chat for now.)`,
+        options: competitors,
+    };
+}
+function resolveCwd(workspace) {
+    return workspace ? resolve(workspace) : process.cwd();
+}
+/** Total latency across a run's attempts (primary + fallbacks), for learning outcomes. */
+function attemptsLatency(run) {
+    return run.routing.attempts.reduce((sum, a) => sum + (a.latencyMs ?? 0), 0);
+}