ai-runtime-engine 1.2.0 → 2.7.0

package/dist/runtime/runtime.js

@@ -3,12 +3,16 @@
  * 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 { resolve, join } from 'node:path';
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { stringify as stringifyYaml } from 'yaml';
+import { generateSkillManifest } from '../generation/generateSkill.js';
 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 { AIIntentClassifier } from './intent/aiClassifier.js';
 import { resolveMode, resolveStrategy } from './modes/modeResolver.js';
 import { resolvePolicy } from './policy.js';
 import { CHAT_TASK, buildChatRequest, toRuntimeResult, inputText } from './modes/chat.js';
@@ -20,10 +24,19 @@ 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 { verifyContextLoss } from '../context/lossVerifier.js';
+import { summarizeOverBudget } from '../context/summarize.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 { resolvePermissions, clampMcpPermissions } from '../tools/permissions.js';
+import { flattenClamp } from '../util/flatten.js';
+import { McpManager } from '../mcp/manager.js';
+import { mcpTool, mcpToolId } from '../mcp/toolAdapter.js';
+import { StaticMcpSource } from '../mcp/mcp.js';
+import { ActionCapabilityRegistry, capabilityReportFrom } from '../capabilities/registry.js';
+import { namespacedId } from '../capabilities/capability.js';
+import { candidatesFrom, deriveCapabilities } from './planning/deriveCapabilities.js';
 import { filesystemTool } from '../tools/builtins/filesystem.js';
 import { shellTool } from '../tools/builtins/shell.js';
 import { gitTool } from '../tools/builtins/git.js';
@@ -32,6 +45,9 @@ 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 { foldCalls } from '../orchestration/budget.js';
+import { narrowEnvelope } from '../agents/envelope.js';
+import { runAgentTask } from '../agents/worker.js';
 import { executePlan } from '../orchestration/executor.js';
 import { ExecutionStore } from '../executions/store.js';
 import { RESUMABLE, TERMINAL } from '../executions/execution.js';
@@ -40,7 +56,13 @@ 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 { resolveRoutingPrefs, withPreferredProviders, mergeRouting } from './routing.js';
+import { loadModelProfile, resolveModelDirective, directiveToOverrides } from './models/modelProfile.js';
+import { HashEmbedder } from '../memory/embedders/hash.js';
+import { HttpEmbedder } from '../memory/embedders/http.js';
+import { Credential } from '../security/credentials.js';
+import { makeCodec, deriveKey } from '../store/crypto.js';
+import { AIError } from '../core/fallback/errors.js';
 import { tokenize } from '../memory/bm25.js';
 let runCounter = 0;
 function nextRunId() {
@@ -54,6 +76,23 @@ function numFromEnv(env, key) {
     const n = Number(raw);
     return Number.isFinite(n) ? n : undefined;
 }
+/**
+ * Clamp a source-controlled string before it is rendered into a MODEL PROMPT (invariant 15/16). Ids,
+ * provider ids, and tool lists come from tools/skills/packs — and from MCP servers in Phase 3.2 — so a
+ * rendered catalog row must never carry newlines, control characters, or unbounded text that could forge
+ * additional rows or smuggle instructions into the planner prompt.
+ */
+function promptSafe(raw, max = 80) {
+    return flattenClamp(raw, max);
+}
+/** Merge gap lists first-wins by capabilityId: pre-pass, then post-plan check, then plan validation. */
+function mergeGapsById(list) {
+    const out = new Map();
+    for (const g of list)
+        if (!out.has(g.capabilityId))
+            out.set(g.capabilityId, g);
+    return [...out.values()];
+}
 export class Runtime {
     _ai;
     settingsValue;
@@ -65,20 +104,46 @@ export class Runtime {
     _memory;
     _conversations;
     estimator = new TokenEstimator();
+    /** ACTION-capability registry (Phase 3.1). Declared BEFORE the tool/skill registries so its
+     *  ingest listeners are attached in time to capture the builtin registrations below. */
+    _capabilities = new ActionCapabilityRegistry();
+    /** MCP server lifecycle (Phase 3.2). Connection is LAZY: nothing is contacted until first use. */
+    _mcp;
+    mcpConnected = false;
+    mcpToolIds = new Set();
+    mcpWarnings = [];
     _tools = new ToolRegistry();
     _skills = new SkillRegistry();
     _executions;
     _artifacts;
     _learning;
     workspaceRoot;
+    _modelProfile;
     configPermissions;
+    /** The INJECTED clock. Agent deadlines are measured against it, never a real timer, so an offline
+     *  test with a fake clock stays deterministic. */
+    clock;
+    /** Multi-agent core (Phase 3.4). False ⇒ every agent path is inert. */
+    agentsEnabled;
+    agentDefs = new Map();
+    /** Live runs, so a pause/cancel can abort the agent tasks actually in flight. Only ever populated
+     *  when agents are enabled, so pause/cancel are unchanged with the flag off. */
+    liveRuns = new Map();
+    /** The config file's `budget:` ceilings, kept only so the 3.3 pre-pass can decline a model call. */
+    _configBudget;
     approval;
     _configFile;
     _loadedSkillSources = [];
     constructor(config = { router: { providers: [] } }, options = {}, workspace) {
-        this._ai = new AI(config.router, options.ai);
+        // Phase 19: fold the config's per-provider concurrency caps into the AI (shared limiter across runs).
+        const perProvider = config.runtime?.concurrency?.perProvider;
+        const aiOptions = { ...options.ai, ...(perProvider ? { concurrency: { ...(options.ai?.concurrency ?? {}), perProvider } } : {}) };
+        this._ai = new AI(config.router, aiOptions);
         this.settingsValue = config.runtime ?? {};
-        this.classifier = options.classifier ?? new HeuristicIntentClassifier();
+        // Base classifier: a caller-supplied one wins, else the deterministic heuristic. When
+        // `runtime.intent.aiFallback` is on, wrap it so an *ambiguous* heuristic result consults one model call.
+        const baseClassifier = options.classifier ?? new HeuristicIntentClassifier();
+        this.classifier = this.settingsValue.intent?.aiFallback ? new AIIntentClassifier(this._ai, baseClassifier) : baseClassifier;
         this.env = options.ai?.env ?? process.env;
         if (workspace)
             this.workspace = workspace;
@@ -87,19 +152,64 @@ export class Runtime {
             this.approval = options.host.approval;
         if (options.configFile)
             this._configFile = options.configFile;
+        const cfgBudget = config.router.budget?.maxCalls ?? config.router.budget?.maxCostUsd;
+        if (cfgBudget !== undefined)
+            this._configBudget = cfgBudget;
         // Local store (conversations + memory). Disabled → NullAreas (stateless mode).
         const clock = options.ai?.clock ?? systemClock;
+        this.clock = clock;
+        this.agentsEnabled = config.runtime?.agents?.enabled === true;
+        for (const [id, def] of Object.entries(config.runtime?.agents?.definitions ?? {}))
+            this.agentDefs.set(id, def);
         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);
+        const persistenceEnabled = options.persistence !== 'disabled';
+        const cipher = persistenceEnabled ? this.buildCipher() : undefined; // throws a hard CONFIG error if encrypt:true but no key
+        this._store = new RuntimeStore({ workspaceRoot: root, ...(workspace?.name ? { workspaceName: workspace.name } : {}), env: this.env, clock, enabled: persistenceEnabled, ...(this.settingsValue.organization ? { organization: this.settingsValue.organization } : {}), ...(cipher ? { cipher } : {}) });
+        // MCP (Phase 3.2): construct always (cheap, connects nothing); a discovered tool becomes an ordinary
+        // Runtime Tool so runTool's permission/approval/signal machinery applies with no parallel path.
+        this._mcp = new McpManager({
+            ...(config.mcp?.servers ? { servers: config.mcp.servers } : {}),
+            ...(persistenceEnabled ? { store: this._store.mcp() } : {}),
+            env: this.env,
+            clock,
+            ...(options.ai?.fetchImpl ? { fetchImpl: options.ai.fetchImpl } : {}),
+            onToolsDiscovered: (serverId, tools) => this.registerMcpTools(serverId, tools),
+            onServerRemoved: (serverId) => this.deregisterMcpTools(serverId),
+        });
+        this._modelProfile = loadModelProfile(root); // models.md (per-mode/task routing); undefined if absent
+        this._memory = new MemoryStore(this._store, clock, this.buildEmbedder(options.ai?.fetchImpl));
         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);
+        // Action capabilities: wire live accessors + ingest listeners BEFORE any registration, then
+        // register the builtins as TRUSTED (the only code allowed to claim bare curated ids).
+        this._capabilities
+            .attachAccessors({
+            toolIds: () => this._tools.ids(),
+            skills: () => this._skills.list().map((s) => ({ id: s.id, ...(s.tools ? { tools: s.tools } : {}) })),
+            mcpAvailability: (serverId) => this.mcpAvailability(serverId),
+        })
+            .configure(this.settingsValue.capabilities ?? {});
+        // An MCP-backed tool ingests under the `mcp:` namespace (its source kind drives the resolution
+        // tie-break and `removeBySourcePrefix`); `mcpToolIds` is populated BEFORE register for exactly this.
+        this._tools.attach({
+            onRegister: (t, trusted) => (this.mcpToolIds.has(t.id) ? this._capabilities.ingestMcpTool(t) : this._capabilities.ingestTool(t, trusted)),
+            onUnregister: (id) => this._capabilities.removeSource(this.mcpToolIds.has(id) ? 'mcp' : 'tool', id),
+        });
+        this._skills.attach({ onRegister: (sk) => this._capabilities.ingestSkill(sk), onUnregister: (id) => this._capabilities.removeSource('skill', id) });
+        this._tools.register(filesystemTool, true).register(shellTool, true).register(gitTool, true);
         this._skills.register(fileAnalyzerSkill).register(repositoryAnalyzerSkill);
+        // Cache-seeded MCP catalog: a previously discovered tool is plan-referenceable BEFORE (or entirely
+        // without) a connection — at availability `unknown`, denying honestly at call time. No I/O beyond
+        // the store read the manager already did, so lazy connect is preserved.
+        for (const serverId of this._mcp.ids()) {
+            const cached = this._mcp.tools(serverId);
+            if (cached.length)
+                this.registerMcpTools(serverId, cached, { cached: true });
+        }
         // Host integration: attach an event sink and register a credential resolver if supplied.
         const host = options.host;
         this.emitter = new RuntimeEmitter({
@@ -113,6 +223,41 @@ export class Runtime {
         if (!hasChat)
             this._ai.registerTask(CHAT_TASK);
     }
+    /**
+     * Build the memory embedder from `runtime.embedding` (Phase 14). Absent → undefined → BM25 keyword
+     * retrieval (the offline default). `local` = the zero-dep deterministic HashEmbedder; `openai-compatible`
+     * = the HTTP adapter (key by env NAME via `Credential`; a missing `baseUrl` yields no embedder → BM25).
+     */
+    buildEmbedder(fetchImpl) {
+        const cfg = this.settingsValue.embedding;
+        if (!cfg)
+            return undefined;
+        if (cfg.provider === 'local')
+            return new HashEmbedder();
+        if (!cfg.baseUrl)
+            return undefined; // openai-compatible needs an endpoint; no URL → stay on BM25
+        return new HttpEmbedder({
+            baseUrl: cfg.baseUrl,
+            model: cfg.model ?? 'text-embedding-3-small',
+            credential: new Credential(cfg.apiKeyEnv, this.env),
+            ...(fetchImpl ? { fetchImpl } : {}),
+        });
+    }
+    /**
+     * Build the store cipher from `runtime.storage` (Phase 18). Absent / `encrypt:false` → undefined → a
+     * plaintext store (the default). `encrypt:true` resolves the key from the env var NAMED by `keyEnv` via
+     * `Credential` (never a value) and derives an AES-256 key; a missing key is a hard CONFIG error (silent
+     * plaintext would be a lie). The key lives only inside the returned codec — never logged or serialized.
+     */
+    buildCipher() {
+        const cfg = this.settingsValue.storage;
+        if (!cfg?.encrypt)
+            return undefined;
+        const key = new Credential(cfg.keyEnv, this.env).use();
+        if (!key)
+            throw new AIError(`storage encryption is enabled but the key env var ${cfg.keyEnv} is not set`, { category: 'CONFIG' });
+        return makeCodec(deriveKey(key));
+    }
     /** 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);
@@ -210,6 +355,36 @@ export class Runtime {
             return base;
         return withPreferredProviders(base, this._learning.preferredProviders());
     }
+    /** The loaded `models.md` routing profile (per-mode/per-task model directives), or undefined if none. */
+    modelProfile() {
+        return this._modelProfile;
+    }
+    /**
+     * Fold the `models.md` directive for this (mode, task) into the run — a soft prefer (universal, merged
+     * into routing), a strategy, or a hard pin (chat path, via the request escape hatch). Precedence is
+     * explicit per-run > models.md: the caller's own strategy/pin win, and prefer is unioned (never
+     * re-admitting an exclusion). No profile / no matching directive ⇒ the request is returned unchanged.
+     */
+    applyModelProfile(req, mode) {
+        if (!this._modelProfile)
+            return req;
+        const directive = resolveModelDirective(this._modelProfile, { mode, ...(mode === 'chat' ? { task: 'chat' } : {}) });
+        if (!directive)
+            return req;
+        const o = directiveToOverrides(directive);
+        const next = { ...req };
+        if (o.strategy && next.strategy === undefined)
+            next.strategy = o.strategy;
+        if ((o.provider || o.model) && next.request?.provider === undefined && next.request?.model === undefined) {
+            next.request = { ...(next.request ?? {}), ...(o.provider ? { provider: o.provider } : {}), ...(o.model ? { model: o.model } : {}) };
+        }
+        if (o.routing) {
+            const merged = mergeRouting(next.routing, o.routing);
+            if (merged)
+                next.routing = merged;
+        }
+        return next;
+    }
     /** 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 ?? {});
@@ -246,18 +421,206 @@ export class Runtime {
         this._skills.register(skill);
         return this;
     }
+    /**
+     * Register an agent definition (Phase 3.4). Chainable, and inert unless `runtime.agents.enabled` is
+     * set — registering a definition grants nothing on its own, exactly like adding an MCP server.
+     */
+    registerAgent(id, def) {
+        if (!/^[a-z0-9][a-z0-9_-]{0,32}$/.test(id))
+            throw new AIError(`invalid agent id '${id}' — use lowercase letters, digits, '_' or '-' (max 33 chars)`, { category: 'CONFIG' });
+        this.agentDefs.set(id, def);
+        return this;
+    }
+    /** The agent definition ids this runtime knows (registered or configured). */
+    agents() {
+        return [...this.agentDefs.keys()].sort();
+    }
+    /**
+     * This run's agent envelopes. THE ONLY call site of `narrowEnvelope` — never re-derive an inner
+     * catalog, a permission clamp, or a reservation anywhere else (see the header of agents/envelope.ts).
+     */
+    agentEnvelopes(policy) {
+        if (!this.agentsEnabled || this.agentDefs.size === 0)
+            return [];
+        const routing = this.effectiveRouting();
+        return [...this.agentDefs].map(([id, definition]) => narrowEnvelope({
+            agentId: id,
+            definition,
+            parentTools: this._tools.ids(),
+            parentSkills: this.skills().map((sk) => ({ id: sk.id, ...(sk.tools ? { tools: sk.tools } : {}) })),
+            parentPermissions: policy.permissions,
+            ...(routing ? { parentRouting: routing } : {}),
+            defaults: {
+                maxToolCalls: this.settingsValue.agents?.maxToolCalls ?? 25,
+                maxDurationMs: this.settingsValue.agents?.maxDurationMs ?? 120_000,
+                maxInnerCalls: this.settingsValue.agents?.maxInnerCalls ?? 3,
+            },
+        }));
+    }
+    // ── MCP (Phase 3.2) ────────────────────────────────────────────────────────
+    /** The MCP server manager: `list()`, `status(id)`, `test(id)`, `addServer`, `removeServer`, `setEnabled`. */
+    mcp() {
+        return this._mcp;
+    }
+    /**
+     * Connect every enabled MCP server, discover their tools, and register them. LAZY BY DESIGN: a one-shot
+     * CLI command that never touches MCP pays nothing, and a failing server records its state instead of
+     * breaking construction. Idempotent — the second call is a no-op.
+     */
+    async connectMcp() {
+        if (this.mcpConnected)
+            return this._mcp.list();
+        this.mcpConnected = true;
+        return this._mcp.connectAll();
+    }
+    /** Whether any MCP server is configured at all (absent ⇒ MCP is entirely inert). */
+    hasMcpServers() {
+        return this._mcp.ids().length > 0;
+    }
+    /**
+     * Register one server's discovered tools as ordinary Runtime Tools (+ their namespaced action
+     * capabilities, via the tool registry's ingest listener). A generated id NEVER shadows an existing
+     * non-MCP tool: the collision is skipped and reported, because silently replacing `filesystem` would be
+     * a privilege swap.
+     */
+    registerMcpTools(serverId, tools, opts = {}) {
+        const fresh = new Set();
+        for (const decl of tools) {
+            const id = mcpToolId(serverId, decl.name);
+            if (this._tools.get(id) && !this.mcpToolIds.has(id)) {
+                this.mcpWarnings.push(`MCP tool '${id}' collides with a registered tool and was skipped`);
+                continue;
+            }
+            // A CACHED annotation must never RELAX a gate: `readOnlyHint` would lower the permission gate, and
+            // `destructiveHint: false` would remove the confirmation. Until a live handshake says otherwise the
+            // tool is write-like AND destructive. (The adapter also re-reads live annotations at call time —
+            // this is the registration-side half of the same rule.)
+            const gated = opts.cached ? { ...decl, readOnly: false, destructive: true } : decl;
+            this.mcpToolIds.add(id); // before register: the capability ingest hook routes on this set
+            this._tools.register(mcpTool({
+                call: (sid, t, a, o) => this._mcp.call(sid, t, a, o),
+                usable: (sid) => this._mcp.usable(sid),
+                liveTool: (sid, t) => this._mcp.liveTool(sid, t),
+            }, serverId, gated));
+            fresh.add(id);
+        }
+        // A live discovery is the AUTHORITY on what this server offers: anything we still have registered
+        // that the server no longer lists (a stale cache entry, a withdrawn tool) must go, or it would keep
+        // reporting itself as available and get planned against.
+        if (!opts.cached) {
+            for (const id of [...this.mcpToolIds]) {
+                if (!id.startsWith(`${serverId}.`) || fresh.has(id))
+                    continue;
+                this._tools.unregister(id);
+                this.mcpToolIds.delete(id);
+                this._capabilities.removeSource('mcp', id);
+            }
+        }
+        this.publishMcpSource(serverId, tools);
+    }
+    /**
+     * The legacy declaration path (`AI.run({ mcp: true })`) — tools DECLARED to a model, never executed
+     * through here. It honors the same read/full split as execution (declaring a tool the executor would
+     * refuse just invites the model to plan around it) and is keyed by server id, so re-publishing with an
+     * empty list REVOKES it.
+     */
+    publishMcpSource(serverId, tools) {
+        const servers = this.permissions().mcp.servers;
+        const grant = Object.prototype.hasOwnProperty.call(servers, serverId) ? servers[serverId] : 'off';
+        const offered = grant === 'full' ? tools : grant === 'read' ? tools.filter((t) => t.readOnly) : [];
+        // Names are emitted ALREADY namespaced: McpRegistry only prefixes a name without a dot, so a server
+        // tool called `other.thing` would otherwise appear to the model inside another source's namespace.
+        const specs = offered.map((t) => ({ name: mcpToolId(serverId, t.name), description: `${t.description} (MCP server: ${serverId})`, ...(t.inputSchema ? { parameters: t.inputSchema } : {}) }));
+        this._ai.registerMcpSource(new StaticMcpSource(serverId, specs));
+    }
+    /** Drop a server's tools (removal / disable). */
+    deregisterMcpTools(serverId) {
+        for (const id of [...this.mcpToolIds]) {
+            if (!id.startsWith(`${serverId}.`))
+                continue;
+            this._tools.unregister(id);
+            this.mcpToolIds.delete(id);
+        }
+        this._capabilities.removeMcpServer(serverId);
+        this.publishMcpSource(serverId, []); // revoke the model-facing declarations too
+    }
+    /** Map a server's lifecycle state onto capability availability (the D7 derivation table). */
+    mcpAvailability(serverId) {
+        const st = this._mcp.status(serverId);
+        if (!st)
+            return 'unavailable';
+        if (!st.enabled || st.state === 'disabled')
+            return 'disabled';
+        if (st.state === 'connected' || st.state === 'degraded')
+            return 'available';
+        if (st.state === 'configured' || st.state === 'connecting')
+            return 'unknown'; // cache-seeded / in flight
+        return 'unavailable'; // auth_failed | unreachable
+    }
+    /** Warnings from MCP wiring (id collisions) plus the manager's own (invalid store files, etc.). */
+    mcpWarningsList() {
+        return [...this.mcpWarnings, ...this._mcp.warningsList()];
+    }
+    /**
+     * Release long-lived resources — today: MCP stdio child processes. A one-shot CLI command and the REPL
+     * both call this on completion/exit; without it a spawned server keeps the event loop alive.
+     */
+    async close() {
+        await this._mcp.close();
+    }
     /** Skills whose required tools are all registered. */
     skills() {
         return this._skills.match({ tools: this._tools.ids() });
     }
+    /**
+     * Scaffold a skill MANIFEST from a natural-language goal (Phase 21a). Drafts a `*.skill.yaml` via the
+     * model, validated by `parseManifest` + tool-membership + a dry compile. **Writes nothing** — pass the
+     * returned manifest to `saveScaffoldedSkill` on explicit confirm.
+     */
+    async scaffoldSkill(goal) {
+        return generateSkillManifest({ goal, tools: this._tools.ids(), ai: this._ai });
+    }
+    /**
+     * Write a scaffolded manifest into the consented `.ai-runtime/skills/` directory (Phase 21a). Only call
+     * this after the user has confirmed the drafted manifest. Returns the written path. The id was validated
+     * as kebab-case at generation; it is re-checked here so a hand-built manifest can't escape the skills dir.
+     */
+    saveScaffoldedSkill(manifest) {
+        if (!/^[a-z0-9][a-z0-9-]{0,63}$/.test(manifest.id))
+            throw new AIError(`unsafe skill id: ${JSON.stringify(manifest.id)}`, { category: 'CONFIG' });
+        const dir = join(this.workspaceRoot, '.ai-runtime', 'skills');
+        mkdirSync(dir, { recursive: true });
+        const path = join(dir, `${manifest.id}.skill.yaml`);
+        writeFileSync(path, stringifyYaml(manifest));
+        return path;
+    }
+    /** The ACTION-capability registry (Phase 3.1): what this runtime can DO, and who provides it. */
+    capabilities() {
+        return this._capabilities;
+    }
     /** The resolved tool permissions for this runtime (config grants over deny-by-default defaults). */
     permissions() {
         return resolvePermissions(this.configPermissions);
     }
+    /**
+     * The ONE resolved-permission view for a run: config grants merged with a per-run override, with `mcp`
+     * merged by per-server MINIMUM so an override can only ever NARROW. Extracted from `toolContext`
+     * (Phase 3.3 / D9) so capability resolution and tool execution can never read different permissions.
+     * Never re-derive this merge at a call site: a plain `resolvePermissions({ ...config, ...override })`
+     * would let an override widen `read` to `full` and drop sibling servers.
+     */
+    resolvedPermissions(overrides) {
+        const permissions = resolvePermissions({ ...this.configPermissions, ...(overrides?.permissions ?? {}) });
+        // `mcp` is the first NESTED permission dimension, so a shallow spread would let an override REPLACE
+        // the configured grants — silently widening `read` to `full` and dropping sibling servers. It merges
+        // by per-server minimum instead: an override can only ever narrow (invariant: permissions never widen).
+        permissions.mcp = { servers: clampMcpPermissions(resolvePermissions(this.configPermissions).mcp.servers, overrides?.permissions?.mcp?.servers) };
+        return permissions;
+    }
     toolContext(overrides) {
         return {
             workspaceRoot: this.workspaceRoot,
-            permissions: resolvePermissions({ ...this.configPermissions, ...(overrides?.permissions ?? {}) }),
+            permissions: this.resolvedPermissions(overrides),
             ...(this.approval ? { approval: this.approval } : {}),
             ...(overrides?.signal ? { signal: overrides.signal } : {}),
         };
@@ -277,7 +640,9 @@ export class Runtime {
         const toolCtx = this.toolContext(overrides);
         const ctx = {
             input,
-            ai: this._ai,
+            // Phase 3.4: an agent worker passes its METERED facade here, so a skill's own model calls are
+            // counted against that agent's reservation. Absent ⇒ the real AI, byte-identical.
+            ai: overrides?.ai ?? this._ai,
             callTool: async (toolId, toolInput) => {
                 const tool = this._tools.get(toolId);
                 if (!tool)
@@ -306,7 +671,7 @@ export class Runtime {
         return this.emitter.recent();
     }
     async run(input) {
-        const req = typeof input === 'string' ? { input } : input;
+        let 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' });
@@ -319,6 +684,9 @@ export class Runtime {
         });
         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 });
+        // models.md (Phase 23): fold the per-mode/per-task model directive into this run's routing/strategy/pin
+        // — but never over an explicit per-run choice. Downstream strategy/routing/dispatch read the result.
+        req = this.applyModelProfile(req, resolution.executed);
         const strategy = resolveStrategy({
             ...(req.strategy !== undefined ? { explicit: req.strategy } : {}),
             ...(this.settingsValue.defaultStrategy !== undefined ? { configDefault: this.settingsValue.defaultStrategy } : {}),
@@ -339,7 +707,7 @@ export class Runtime {
         // 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);
+            return this.runOrchestration(resolution.executed, text, resolution, runId, policy, req.requestId, routing, req.partial);
         }
         // Compare mode: fan out the same task across pins and analyze — read-only, no approval gate.
         if (resolution.executed === 'compare') {
@@ -352,14 +720,23 @@ export class Runtime {
             this.emitter.emit({ type: 'clarification.requested', runId, question: clarification.question });
         // Memory: retrieve relevant facts into context, and (unless this is a dry run) capture an explicit
         // "remember …". A dry run performs zero mutations, so it retrieves but never writes.
-        const memTrace = this.applyMemory(text, !policy.dryRun);
+        const memTrace = await this.applyMemory(text, !policy.dryRun);
         // Compile the model context (workspace summary + memory facts + user system) under a token budget.
         const budget = resolveContextBudget({
             ...(req.context?.maxTokens !== undefined ? { perRun: req.context.maxTokens } : {}),
             ...(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 });
+        // Optional abstractive summarization pre-pass (Phase 16, opt-in) — shrinks over-budget non-critical
+        // blocks before the deterministic compile. Never on a dry run (it makes model calls). Failure → originals.
+        // `originalBlocks` is kept so loss verification can compare against the TRUE originals (pre-summary),
+        // catching loss introduced by summarization as well as by the compiler.
+        const originalBlocks = this.contextBlocks(req, context.workspace, memTrace?.retrieved);
+        let blocks = originalBlocks;
+        if (!policy.dryRun && this.settingsValue.context?.summarize) {
+            blocks = await summarizeOverBudget({ ai: this._ai, blocks, budgetTokens: budget, estimator: this.estimator });
+        }
+        const compiled = compileContext(blocks, { budgetTokens: budget, estimator: this.estimator });
         const contextReport = { metrics: compiled.metrics, validation: compiled.validation };
         // Dry-run: chat's only "action" is the model call itself, so a dry run makes NO call. It reports
         // what it would send (mode, compiled-context size) and performs zero mutations.
@@ -374,7 +751,24 @@ export class Runtime {
                 result.memory = memTrace;
             return result;
         }
+        // Optional model-based context-loss verification (Phase 16, opt-in) — appends one advisory check to
+        // validation.checks; never blocks, never runs on a dry run (returned above). Failure → inconclusive.
+        if (this.settingsValue.context?.verifyLoss) {
+            compiled.validation.checks.push(await verifyContextLoss({ ai: this._ai, blocks: originalBlocks, compiled }));
+        }
         const runRequest = buildChatRequest(req, strategy, compiled.system || undefined, routing);
+        // Streaming (Phase 13): text-only, chat-mode only, never on a dry run (handled above). Each chunk is
+        // emitted as a `response.delta` lifecycle event (redacted by the emitter). We also accumulate the raw
+        // chunks so we can mark the result `streamed` when the streamed text IS the final answer.
+        const streaming = req.stream === true && req.output?.format !== 'json' && req.output?.format !== 'structured_output';
+        let streamedText = '';
+        if (streaming) {
+            runRequest.stream = true;
+            runRequest.onDelta = (chunk) => {
+                streamedText += chunk;
+                this.emitter.emit({ type: 'response.delta', runId, text: chunk });
+            };
+        }
         const runResult = await this._ai.run(runRequest);
         this.calibrate(runRequest.system, text, runResult);
         const sel = runResult.routing.selected;
@@ -393,6 +787,12 @@ export class Runtime {
         if (memTrace)
             result.memory = memTrace;
         result.context = contextReport;
+        // Mark `streamed` only when the streamed chunks ARE the final answer (a clean single stream). If a
+        // streamed attempt failed and a fallback produced different text, they won't match → not streamed, so
+        // a renderer reprints the authoritative final text.
+        if (streaming && runResult.ok && result.response && streamedText.length > 0 && (result.response.text ?? '') === streamedText) {
+            result.response.streamed = true;
+        }
         return result;
     }
     /** The persistent execution store and its owner-lease machinery. */
@@ -408,13 +808,29 @@ export class Runtime {
         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) {
+    async runOrchestration(mode, goal, resolution, runId, policy, requestId, routing, partial) {
         const effectiveGoal = mode === 'debug' ? `Investigate and diagnose the following, gathering evidence before concluding: ${goal}` : goal;
+        // Phase 3.4: ONE controller per run, registered under the run id (and the execution id below) so
+        // pauseExecution/cancelExecution can abort agent work that is actually in flight. With agents
+        // disabled nothing consumes the signal, so this is inert.
+        const controller = new AbortController();
+        if (this.agentsEnabled)
+            this.liveRuns.set(runId, { controller });
         // 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);
+            // Phase 3.3 (opt-in): derive + resolve this goal's capabilities BEFORE planning. Done here rather
+            // than in `orchestrateInput` because this scope has the resolved `policy`, so plan/execute/
+            // orchestrate/agent/debug all behave identically. `undefined` when the flag is off, which is the
+            // entire flag-off delta on this path.
+            const planning = await this.capabilityPlanning(effectiveGoal, policy, routing);
+            try {
+                const outcome = await orchestrate(this.orchestrateInput(mode, effectiveGoal, policy, routing, partial, planning?.block, this.agentsEnabled ? controller.signal : undefined, { planVersion: 1 }));
+                this.recordOrchestration(mode, goal, outcome);
+                return this.mapOutcome(outcome, resolution, runId, undefined, planning);
+            }
+            finally {
+                this.liveRuns.delete(runId);
+            }
         }
         // 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).
@@ -431,9 +847,15 @@ export class Runtime {
             return this.resultFromExecution(reserved.exec, resolution, runId);
         }
         const exec = reserved.exec;
+        // Derive only AFTER the requestId dedup has admitted this as fresh work: an idempotent retry returns
+        // the existing execution above, and paying for a model call whose result is then discarded would
+        // spend budget to answer a question nobody asked.
+        const planning = await this.capabilityPlanning(effectiveGoal, policy, routing);
         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)));
+            if (this.agentsEnabled)
+                this.liveRuns.set(exec.id, { controller });
+            const outcome = await this.withHeartbeat(exec.id, () => orchestrate(this.orchestrateInput(mode, effectiveGoal, policy, routing, partial, planning?.block, this.agentsEnabled ? controller.signal : undefined, { executionId: exec.id, planVersion: exec.planVersion })));
             exec.status = this.execStatus(outcome.status);
             exec.observations = outcome.observations;
             if (outcome.plan) {
@@ -445,12 +867,16 @@ export class Runtime {
                 exec.pending = { kind: 'approval', action: goal };
             else if (outcome.status === 'waiting_for_clarification' && outcome.clarification)
                 exec.pending = { kind: 'clarification', question: outcome.clarification };
+            else if (outcome.status === 'waiting_for_budget' && outcome.budget)
+                exec.pending = { kind: 'budget', budget: outcome.budget };
             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);
+            return this.mapOutcome(outcome, resolution, runId, exec.id, planning);
         }
         finally {
+            this.liveRuns.delete(runId);
+            this.liveRuns.delete(exec.id);
             this._executions.release(exec.id);
         }
     }
@@ -466,7 +892,7 @@ export class Runtime {
             clearInterval(timer);
         }
     }
-    orchestrateInput(mode, goal, policy, routing) {
+    orchestrateInput(mode, goal, policy, routing, partial, requiredCapabilities, signal, provenance) {
         return {
             goal,
             mode,
@@ -475,9 +901,19 @@ export class Runtime {
             tools: this._tools.ids(),
             policy,
             ...(routing ? { routing } : {}),
+            ...(partial ? { partial: true } : {}),
             ...(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),
+            // Phase 3.1: the capability snapshot is opt-in (`runtime.capabilities.catalog`); the gap resolver is
+            // always on but only fires on a validation failure, adding metadata to an unchanged error.
+            ...(this.settingsValue.capabilities?.catalog ? { capabilityCatalog: this.capabilityCatalogText() } : {}),
+            // Phase 3.3: the derived-requirement block (opt-in, pre-rendered + clamped). Absent ⇒ the
+            // OrchestrateInput/PlannerInput objects are key-identical to 2.5.1.
+            ...(requiredCapabilities ? { requiredCapabilities } : {}),
+            resolveGaps: (missing) => this.resolveMissingRefs(missing, policy),
+            // Phase 3.4: ONE runner source. `agents`, `runAgent` and `reserve` ride along only when agents are
+            // enabled AND a definition exists, so with the flag off this object is KEY-identical to 2.6.0.
+            ...this.orchestrateRunners(policy, signal, provenance),
+            ...(signal ? { signal } : {}),
         };
     }
     /** Record an EXECUTED orchestration outcome for learning. plan-only, dry-run, and waiting states are
@@ -489,19 +925,168 @@ export class Runtime {
             return;
         this._learning.record({ goalType: this.goalType(goal), mode, ok: outcome.status === 'completed', skills: this.planSkillRefs(outcome.plan) });
     }
+    /**
+     * A capped, FENCED action-capability snapshot for the planner prompt (Phase 3.1, opt-in). Untrusted
+     * sources (anything not an in-tree builtin) have their descriptions fenced, and the block is bounded so
+     * a large catalog can never dominate the prompt.
+     */
+    capabilityCatalogText(maxEntries = 40) {
+        const caps = this._capabilities.list();
+        if (caps.length === 0)
+            return '';
+        const lines = [];
+        for (const c of caps.slice(0, maxEntries)) {
+            const providers = this._capabilities
+                .providersOf(c.id)
+                .map((p) => `${promptSafe(p.providerId)}${p.availability === 'available' ? '' : ` (${p.availability})`}`)
+                .join(', ');
+            lines.push(`  - capability "${promptSafe(c.id)}" [${c.effects.join('/')}] → ${promptSafe(providers, 200)}`);
+        }
+        const more = caps.length > maxEntries ? `\n  …and ${caps.length - maxEntries} more (see /capabilities)` : '';
+        // Skills hidden by a missing tool — the "why can't you do this" answer the planner needs.
+        const usable = new Set(this.skills().map((sk) => sk.id));
+        const blocked = this._skills
+            .list()
+            .filter((sk) => !usable.has(sk.id))
+            .map((sk) => `  - skill "${promptSafe(sk.id)}" needs tool(s) ${promptSafe((sk.tools ?? []).filter((t) => !this._tools.ids().includes(t)).join(', '), 200)} (not registered)`);
+        const unavailable = blocked.length ? `\nUnavailable (do not use):\n${blocked.join('\n')}` : '';
+        return `Action capabilities:\n${lines.join('\n')}${more}${unavailable}`;
+    }
+    /** Any call/cost ceiling declared in the config file's `budget:` block (router-level, not policy). */
+    configBudget() {
+        return this._configBudget;
+    }
+    /** Deriver candidates: registry ids + one clamped label. Built by the SAME helper the CLI uses. */
+    capabilityCandidates() {
+        return candidatesFrom(this._capabilities.list());
+    }
+    /**
+     * Derive the capabilities this goal needs and resolve them (Phase 3.3, opt-in). Offline BM25 first —
+     * free and deterministic — with ONE model call only when the offline rung finds nothing. ADVISORY: it
+     * never blocks a run and never grants anything; a gap is metadata plus a line in the planner prompt.
+     */
+    async capabilityPlanning(goal, policy, routing) {
+        if (!this.settingsValue.capabilities?.planning)
+            return undefined;
+        const permissions = this.resolvedPermissions({ permissions: policy.permissions });
+        const candidates = this.capabilityCandidates();
+        if (candidates.length === 0)
+            return { derived: [], gaps: [], block: '', permissions };
+        // The model rung is skipped whenever ANY budget is set. `maxCalls` is denominated in plan skill steps
+        // (orchestrator.estimateCalls), so it cannot express a pre-plan call — spending one would exceed a
+        // limit only ExecutionPolicy is meant to author — and a COST ceiling is just as much a budget. The
+        // router-config `budget.maxCalls` is consulted directly because it deliberately does NOT flow into
+        // `policy.maxCalls`: threading it there would newly gate ORCHESTRATION for every existing config,
+        // which is a flag-off behavior change this phase must not make. Skipped on a dry run too. The
+        // offline rung still runs in every one of these cases and costs nothing.
+        const budgeted = policy.maxCalls !== undefined || policy.maxCostUsd !== undefined || this.configBudget() !== undefined;
+        const useModel = !policy.dryRun && !budgeted;
+        const res = await deriveCapabilities({ goal, candidates, ...(useModel ? { ai: this._ai } : {}), ...(routing ? { routing } : {}) });
+        if (res.required.length === 0)
+            return { derived: [], gaps: [], block: '', permissions };
+        const resolution = this._capabilities.resolve(res.required, { permissions });
+        return { derived: res.required, gaps: resolution.gaps, block: this.requiredCapabilitiesText(resolution), permissions };
+    }
+    /** The pre-rendered "Required capabilities" planner block (Phase 3.3) — clamped like the 3.1 catalog. */
+    requiredCapabilitiesText(res) {
+        const rows = [
+            ...res.satisfied.map((sat) => `  - "${promptSafe(sat.capabilityId)}" → use ${promptSafe(sat.chosen.providerId)}`),
+            ...res.gaps.map((g) => `  - "${promptSafe(g.capabilityId)}" → NOT AVAILABLE (${g.reason}) — do not plan a step that needs it`),
+        ];
+        return rows.length ? `Required capabilities for this goal (derived):\n${rows.join('\n')}` : '';
+    }
+    /** A step's capability provider id. An MCP-backed tool ingests under `mcp:` (see the ingest hook). */
+    providerIdForRef(ref) {
+        if (ref.kind === 'skill')
+            return namespacedId('skill', ref.id);
+        return namespacedId(this.mcpToolIds.has(ref.id) ? 'mcp' : 'tool', ref.id);
+    }
+    /**
+     * Resolve the capabilities the plan's OWN steps reference (Phase 3.3). ZERO model calls, purely
+     * additive metadata, and the only path that can surface a real `permission` gap with a concrete
+     * policyKey — the always-on validation path resolves namespaced MISSES, which have no providers and are
+     * therefore always reason 'unknown'. It never blocks: a gap here is advice, and the tool's own
+     * permission check remains the authority.
+     */
+    checkPlanCapabilities(plan, permissions, derived) {
+        try {
+            const ids = new Set();
+            for (const step of plan.steps) {
+                const ref = step.skill ? { kind: 'skill', id: step.skill } : step.tool ? { kind: 'tool', id: step.tool } : undefined;
+                if (!ref)
+                    continue;
+                for (const id of this._capabilities.capabilitiesOf(this.providerIdForRef(ref), ref.id))
+                    ids.add(id);
+            }
+            const all = [...ids].sort();
+            const res = this._capabilities.resolve(all, { permissions });
+            const reasonOf = new Map(res.gaps.map((g) => [g.capabilityId, g.reason]));
+            /**
+             * A provider can do more than the step will. `tool:filesystem` provides read_file AND write_file,
+             * so a read-only step would otherwise be reported as needing write access — and the remedy would
+             * tell the operator to GRANT it. Pushing an over-grant for work that may never happen is worse
+             * than saying nothing, so a `permission` gap survives only when the GOAL derived that capability.
+             * Every other reason (unknown / unavailable / disabled provider) is a fact about the plan whatever
+             * the step does, and is always reported.
+             */
+            const keep = (id) => derived.has(id) || reasonOf.get(id) !== 'permission';
+            return { required: all.filter(keep), gaps: res.gaps.filter((g) => keep(g.capabilityId)) };
+        }
+        catch {
+            return { required: [], gaps: [] }; // a check bug can never fail a run the runtime could complete
+        }
+    }
+    /**
+     * Turn unregistered plan references into structured gaps (Phase 3.1's always-on upgrade), resolved
+     * against the RUN's permissions rather than the raw config (Phase 3.3 / D9) — so what resolution
+     * reports and what the executor will allow can never disagree.
+     */
+    resolveMissingRefs(missing, policy) {
+        const ids = [...new Set(missing.map((m) => namespacedId(m.kind, m.id)))];
+        return this._capabilities.resolve(ids, { permissions: this.resolvedPermissions({ permissions: policy.permissions }) }).gaps;
+    }
+    /**
+     * The user-facing report for a set of required capability ids (Phase 3.1), against the runtime's
+     * CONFIGURED posture. A specific run's gaps use that run's merged permissions instead (see
+     * `resolveMissingRefs` and the capability-planning pre-pass); this entry point has no run in scope.
+     */
+    capabilityReport(required) {
+        return this._capabilities.report(required, { permissions: this.permissions() });
+    }
+    /**
+     * Project an orchestration status onto a persisted execution status. EXHAUSTIVE on purpose (Phase
+     * 3.4): the previous catch-all silently persisted an unrecognized status as
+     * `waiting_for_clarification` — resumable, answerable with a text answer, and wrong. The mapping of
+     * the six existing members is unchanged.
+     */
     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) {
+        switch (s) {
+            case 'completed':
+            case 'dry-run':
+                return 'completed';
+            case 'failed':
+                return 'failed';
+            case 'waiting_for_approval':
+            case 'waiting_for_budget':
+                return 'waiting_for_input';
+            case 'waiting_for_clarification':
+                return 'waiting_for_clarification';
+            default: {
+                const never = s;
+                return never;
+            }
+        }
+    }
+    mapOutcome(outcome, resolution, runId, execId, planning) {
         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 });
+        // One report, three sources: the pre-pass (the goal), the post-plan check (the plan's own steps),
+        // and the always-on validation upgrade (unregistered refs). The post-plan check is free — no model
+        // call — so it runs wherever the flag is on, resumes included.
+        const check = planning && outcome.plan ? this.checkPlanCapabilities(outcome.plan, planning.permissions, new Set(planning.derived)) : undefined;
+        const gaps = mergeGapsById([...(planning?.gaps ?? []), ...(check?.gaps ?? []), ...(outcome.gaps ?? [])]);
+        const required = [...new Set([...(planning?.derived ?? []), ...(check?.required ?? []), ...(outcome.gaps ?? []).map((g) => g.capabilityId)])];
         return {
             ok,
             runId,
@@ -509,20 +1094,25 @@ export class Runtime {
             status,
             response: { text: outcome.summary },
             ...(outcome.plan ? { plan: outcome.plan } : {}),
+            ...(gaps.length ? { capabilityGaps: capabilityReportFrom(required, gaps, (id) => this._capabilities.providersOf(id)) } : {}),
             execution: { ...(execId ? { id: execId } : {}), observations: outcome.observations, planHistory: outcome.planHistory },
             ...(outcome.clarification ? { clarification: { question: outcome.clarification } } : {}),
-            artifacts: [],
+            // Phase 3.4: an agent step's admitted findings carry evidence artifacts. With agents disabled
+            // there are no agent observations, so this is the same empty array as 2.6.0.
+            artifacts: outcome.observations.flatMap((o) => o.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';
+        // waiting_for_input carries a pending kind — a budget pause maps to waiting_for_budget, else approval.
+        const waitingInput = exec.pending?.kind === 'budget' ? 'waiting_for_budget' : 'waiting_for_approval';
+        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' ? waitingInput : 'completed';
         return {
             ok,
             runId,
             mode: resolution,
             status,
-            response: { text: `execution ${exec.id} (${exec.status})` },
+            response: { text: exec.pending?.kind === 'budget' && exec.pending.budget ? `execution ${exec.id}: ${exec.pending.budget.completedSteps}/${exec.pending.budget.totalSteps} step(s) done — raise the budget and resume` : `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 } } : {}),
@@ -612,21 +1202,37 @@ export class Runtime {
             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.
+            // Re-read the budget from env so raising AI_MAX_CALLS before resuming actually takes effect (Phase 22).
+            const policy = resolvePolicy({ mode: 'orchestrate', overrides: { autonomy: 'autonomous', approval: 'none', ...(this.configPermissions ? { permissions: this.configPermissions } : {}) }, settings: this.settingsValue, env: { maxCostUsd: numFromEnv(this.env, 'AI_MAX_COST_USD'), maxCalls: numFromEnv(this.env, 'AI_MAX_CALLS') } });
+            // A resumed run is never re-DERIVED — no surprise second model call on work already approved and
+            // mid-flight — but it does get the FREE post-plan check: a grant may have changed since it started.
+            const planning = this.settingsValue.capabilities?.planning
+                ? { derived: [], gaps: [], block: '', permissions: this.resolvedPermissions({ permissions: policy.permissions }) }
+                : undefined;
+            // Continue (skip completed steps) for an approved plan, a budget pause, or partial progress.
             const approvedNow = exec.pending?.kind === 'approval';
-            const canContinue = !recon.drifted && !!exec.plan && (approvedNow || (exec.completedSteps.length > 0 && !exec.pending));
+            const budgetPaused = exec.pending?.kind === 'budget';
+            const canContinue = !recon.drifted && !!exec.plan && (approvedNow || budgetPaused || (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}"` };
+                // Continue the plan, skipping completed steps. The call budget is ALWAYS enforced on the continue
+                // path (whether the pause was approval, budget, or partial-progress) so an approved-but-over-budget
+                // plan pauses for budget rather than silently exceeding it; a raised budget re-applies here.
+                const exe = await this.withHeartbeat(exec.id, () => executePlan(exec.plan, { ...this.orchestrateRunners(policy, opts.signal, { executionId: exec.id, planVersion: exec.planVersion }), maxParallelSteps: policy.maxParallelSteps ?? 2, ...(policy.limits ? { limits: policy.limits } : {}), skip: new Set(exec.completedSteps), ...(policy.maxCalls !== undefined ? { callBudget: policy.maxCalls } : {}), ...(opts.signal ? { signal: opts.signal } : {}) }));
+                if (exe.stoppedForBudget) {
+                    const done = exe.plan.steps.filter((s) => s.status === 'succeeded').length;
+                    const total = exe.plan.steps.length;
+                    outcome = { status: 'waiting_for_budget', plan: exe.plan, planHistory: [exe.plan], observations: exe.observations, budget: { estCalls: foldCalls(exe.plan.steps, policy.maxCalls), maxCalls: policy.maxCalls, completedSteps: done, totalSteps: total }, summary: `Ran ${done} of ${total} step(s) within the ${policy.maxCalls}-call budget. Raise the budget (AI_MAX_CALLS) and resume to continue.` };
+                }
+                else {
+                    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())));
+                // 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. A budget-paused replan stays
+                // partial so it keeps running-what-fits instead of reverting to notify-and-wait.
+                outcome = await this.withHeartbeat(exec.id, () => orchestrate(this.orchestrateInput('orchestrate', goal, policy, this.effectiveRouting(), budgetPaused)));
             }
             exec.status = this.execStatus(outcome.status);
             exec.observations = [...exec.observations, ...outcome.observations];
@@ -635,27 +1241,92 @@ export class Runtime {
                 exec.planVersion = outcome.plan.version;
                 exec.completedSteps = outcome.plan.steps.filter((s) => s.status === 'succeeded').map((s) => s.id);
             }
-            delete exec.pending;
+            // Preserve a fresh budget pause; otherwise the pending state is resolved.
+            if (outcome.status === 'waiting_for_budget' && outcome.budget)
+                exec.pending = { kind: 'budget', budget: outcome.budget };
+            else
+                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);
+            return this.mapOutcome(outcome, resolution, runId, exec.id, planning);
         }
         finally {
             this._executions.release(id);
         }
     }
-    orchestrateRunners() {
+    /**
+     * THE single source of step runners, used by both the fresh-run path and the resume-continue path.
+     * They used to drift: resume built its own pair with no agent runner, so a persisted plan containing
+     * an agent step would have failed every one of those steps.
+     */
+    orchestrateRunners(policy, signal, provenance) {
+        const envelopes = policy ? this.agentEnvelopes(policy) : [];
+        const byId = new Map(envelopes.map((e) => [e.agentId, e]));
         return {
             runSkill: (skillId, input) => this.runSkill(skillId, input).then((o) => ({ result: o.result, validation: o.validation })),
             runTool: (toolId, input) => this.runTool(toolId, input),
+            ...(envelopes.length
+                ? {
+                    agents: envelopes,
+                    reserve: (step) => (step.agent ? byId.get(step.agent)?.reservation ?? 1 : 0),
+                    runAgent: async (step, ctx) => {
+                        const envelope = byId.get(step.agent ?? '');
+                        const definition = this.agentDefs.get(step.agent ?? '');
+                        if (!envelope || !definition)
+                            return { stepId: step.id, ok: false, code: 'agent-not-enabled', error: `no agent definition '${step.agent ?? ''}'` };
+                        const innerSkills = this._skills.list().filter((sk) => envelope.skills.includes(sk.id));
+                        const out = await runAgentTask(step, envelope, definition, {
+                            ai: this._ai,
+                            clock: this.clock,
+                            skills: innerSkills,
+                            runSkill: (id, i, o) => this.runSkill(id, i, o).then((r) => ({ result: r.result, validation: r.validation })),
+                            runTool: (id, i, o) => this.runTool(id, i, o),
+                            putArtifact: (content, source) => {
+                                // The `enabled` check must precede `put`: in stateless mode `put` still returns a
+                                // well-formed ref with a real checksum whose `resolve()` is permanently undefined —
+                                // a dangling evidence ref threaded as if it were real.
+                                if (!this._artifacts.enabled)
+                                    return { unavailable: true };
+                                try {
+                                    return { ref: this._artifacts.put({ type: 'agent-evidence', source, content }), unavailable: false };
+                                }
+                                catch {
+                                    return { unavailable: true };
+                                }
+                            },
+                            emit: (e) => this.emitter.emit({ type: e.type, agentTaskId: e.record.agentTaskId, agentId: e.record.agentId, stepId: e.record.stepId, state: e.record.state, innerSteps: e.record.innerSteps, callsUsed: e.record.callsUsed, toolCallsUsed: e.record.toolCallsUsed, findings: e.record.findings.length }),
+                            ...(ctx.signal ?? signal ? { parentSignal: ctx.signal ?? signal } : {}),
+                            ...(provenance ? { provenance } : { provenance: { planVersion: 1 } }),
+                            abortReason: () => {
+                                for (const live of this.liveRuns.values())
+                                    if (live.controller.signal.aborted && live.reason)
+                                        return live.reason;
+                                return undefined;
+                            },
+                        });
+                        return out.observation;
+                    },
+                }
+                : {}),
         };
     }
+    /** Abort a run that is in flight, recording WHY so a task can tell a pause from a cancellation. */
+    abortLiveRun(id, reason) {
+        const live = this.liveRuns.get(id);
+        if (!live)
+            return;
+        live.reason = reason;
+        live.controller.abort();
+    }
     /** 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';
+        // Phase 3.4: abort whatever is actually in flight, so a pause stops live agent work instead of only
+        // flipping a stored status. A no-op with agents disabled — `liveRuns` is empty then.
+        this.abortLiveRun(id, 'pause');
         this._executions.save(exec);
         this._executions.release(id);
         return true;
@@ -666,6 +1337,7 @@ export class Runtime {
         if (!exec || TERMINAL.has(exec.status))
             return false;
         exec.status = 'cancelled';
+        this.abortLiveRun(id, 'parent-cancel'); // parent cancelled ⇒ every live agent controller aborted
         this._executions.save(exec);
         this._executions.release(id);
         return true;
@@ -692,7 +1364,7 @@ export class Runtime {
      * `capture` is false on a dry run — retrieval is read-only, but writing a fact is a mutation the dry
      * run must not perform.
      */
-    applyMemory(text, capture = true) {
+    async applyMemory(text, capture = true) {
         if (!this.memoryEnabled())
             return undefined;
         try {
@@ -704,7 +1376,8 @@ export class Runtime {
                     trace.captured = { id: rec.id, scope: rec.scope };
                 }
             }
-            trace.retrieved = this._memory.search(text, { limit: 3 }).map((h) => h.text);
+            // Semantic retrieval when an embedder is configured, else BM25 (searchSemantic degrades internally).
+            trace.retrieved = (await this._memory.searchSemantic(text, { limit: 3 })).map((h) => h.text);
             if (trace.retrieved.length === 0 && !trace.captured)
                 return undefined;
             return trace;