ai-runtime-engine 1.2.0 → 2.7.0

package/dist/capabilities/registry.js

@@ -0,0 +1,413 @@
+/**
+ * The ACTION-capability registry (Phase 3.1) — capability → provider(s), with a fully deterministic
+ * resolution algorithm and structured gaps for what cannot be satisfied.
+ *
+ * Population is driven by the tool/skill registries (their optional change listeners), so builtins,
+ * autoloaded manifest skills, and npm skill packs are all covered by one funnel. Availability is
+ * DERIVED at query time from injected read-only accessors, so it is never a stale snapshot.
+ *
+ * SECURITY: resolution NEVER grants permission. It drops policy-denied providers (so it doesn't propose
+ * something the run cannot do) and returns bindings that still execute through `runTool`/`runSkill`,
+ * where the real permission check lives.
+ */
+import { rankOf } from '../core/capabilities/evidence.js';
+import { curated, isCurated } from './vocabulary.js';
+import { effectiveDeclId, effectsOf, entityFor, namespacedId, } from './capability.js';
+const SOURCE_ORDER = ['native', 'skill', 'mcp', 'openapi', 'plugin'];
+export class ActionCapabilityRegistry {
+    /** providerId → its entries (so a re-registration can drop exactly that provider's contributions). */
+    byProvider = new Map();
+    accessors = {};
+    config = {};
+    /** Warnings recorded during ingestion (sanitized ids, unknown alias/pin targets). */
+    warnings = [];
+    /** Wire the live registries (call once, before any registration). */
+    attachAccessors(a) {
+        this.accessors = { ...this.accessors, ...a };
+        return this;
+    }
+    /** Apply `runtime.capabilities` config (aliases claim; pins select). */
+    configure(config) {
+        this.config = config ?? {};
+        return this;
+    }
+    configWarnings() {
+        return [...this.warnings];
+    }
+    // ── ingestion ──────────────────────────────────────────────────────────────
+    /**
+     * Ingest a tool's declarations (or infer one). `trusted` marks in-tree builtins, the only code allowed
+     * to claim a bare curated id. Idempotent: prior entries for this provider are replaced.
+     */
+    ingestTool(tool, trusted = false) {
+        const providerId = namespacedId('tool', tool.id);
+        if (!this.claimProviderId(providerId, tool.id))
+            return;
+        this.replaceProvider(providerId, this.declsToEntries(tool.provides, providerId, 'native', { kind: 'tool', toolId: tool.id }, 'tool', tool.id, trusted, tool.description));
+    }
+    /**
+     * Ingest an MCP-backed Tool. Its OWN namespace is derived from the Runtime-generated tool id
+     * (`<serverId>.<toolName>`) — never from the server's own declaration — so a server can claim a
+     * capability inside its own `mcp:` namespace and nowhere else. MCP is never a trusted claimant, so a
+     * curated id in its declaration is namespaced away like any other untrusted source.
+     */
+    ingestMcpTool(tool) {
+        const providerId = namespacedId('mcp', tool.id);
+        if (!this.claimProviderId(providerId, tool.id))
+            return;
+        this.replaceProvider(providerId, this.declsToEntries(tool.provides, providerId, 'mcp', { kind: 'tool', toolId: tool.id }, 'mcp', tool.id, false, tool.description));
+    }
+    /** Ingest a skill's declarations (or infer one). Skills are never trusted to claim curated ids. */
+    ingestSkill(skill) {
+        const providerId = namespacedId('skill', skill.id);
+        if (!this.claimProviderId(providerId, skill.id))
+            return;
+        this.replaceProvider(providerId, this.declsToEntries(skill.provides, providerId, 'skill', { kind: 'skill', skillId: skill.id }, 'skill', skill.id, false, skill.description));
+    }
+    /**
+     * Ownership guard: `providerId` is a SANITIZED view of a source id, and sanitization is not injective
+     * (`Filesystem`, `FILESYSTEM`, `file@system` all fold to `filesystem`). Re-registering the SAME raw id
+     * replaces its entries (idempotent, matching the tool/skill registries); a DIFFERENT raw id that folds
+     * onto an already-owned providerId is refused with a warning — it can neither erase the incumbent's
+     * capabilities nor inherit an operator alias/pin that names that providerId.
+     */
+    claimProviderId(providerId, rawId) {
+        const owner = this.byProvider.get(providerId)?.[0]?.rawId;
+        if (owner !== undefined && owner !== rawId) {
+            this.warnings.push(`'${rawId}' maps to provider id '${providerId}', already held by '${owner}' — its action capabilities were not registered (rename the source to a distinct id)`);
+            return false;
+        }
+        return true;
+    }
+    /** Remove everything a provider contributed (tool/skill unregistration, MCP server removal). */
+    removeProvider(providerId) {
+        this.byProvider.delete(providerId);
+    }
+    /**
+     * Remove a source's entries by its EXACT id (what the tool/skill registries emit on unregister).
+     * Sanitization is applied here, and only the owning raw id may remove — so a colliding id can never
+     * unregister the incumbent's capabilities.
+     */
+    removeSource(kind, rawId) {
+        const providerId = namespacedId(kind, rawId);
+        if (this.byProvider.get(providerId)?.[0]?.rawId === rawId)
+            this.byProvider.delete(providerId);
+    }
+    /**
+     * Drop every capability contributed by one MCP server's tools. Scoped by the `mcp:<server>.` prefix
+     * INCLUDING the dot — without it, removing `demo` would also strip `demo2`.
+     */
+    removeMcpServer(serverId) {
+        this.removeBySourcePrefix(`${namespacedId('mcp', serverId)}.`);
+    }
+    /**
+     * Remove every provider whose providerId starts with the given LITERAL prefix. A low-level primitive:
+     * prefer `removeSource`/`removeMcpServer`, which scope correctly — a bare `mcp:demo` prefix also
+     * matches `mcp:demo2.x`.
+     */
+    removeBySourcePrefix(prefix) {
+        for (const id of [...this.byProvider.keys()])
+            if (id.startsWith(prefix))
+                this.byProvider.delete(id);
+    }
+    replaceProvider(providerId, entries) {
+        this.byProvider.set(providerId, entries);
+    }
+    declsToEntries(provides, providerId, source, binding, kind, segment, trusted, description) {
+        // Undeclared ⇒ one inferred, namespaced capability so nothing is ever invisible.
+        if (!Array.isArray(provides) || provides.length === 0) {
+            return [{ capabilityId: namespacedId(kind, segment), providerId, rawId: segment, source, binding, effects: ['write'], verification: 'inferred', ...(description ? { description } : {}) }];
+        }
+        // One entry per RESOLVED capability id: several declarations collapsing onto the same id (e.g. two
+        // bare non-curated ids both namespaced to the source) must not produce duplicate providers.
+        const byId = new Map();
+        for (const decl of provides) {
+            const raw = String(decl?.id ?? '').trim();
+            const id = effectiveDeclId(decl, kind, segment, trusted);
+            if (raw && id !== raw) {
+                this.warnings.push(isCurated(raw)
+                    ? `${providerId} declared curated capability '${raw}' — registered as '${id}' (only builtins and config aliases may claim curated ids)`
+                    : `${providerId} declared capability '${raw}' — registered as '${id}' (a declaration may only use its own namespaced id)`);
+            }
+            byId.set(id, {
+                capabilityId: id,
+                providerId,
+                rawId: segment,
+                source,
+                binding,
+                effects: effectsOf(decl, id),
+                verification: 'documented',
+                ...(decl?.description ? { description: decl.description } : description ? { description } : {}),
+            });
+        }
+        return [...byId.values()];
+    }
+    // ── derived views ──────────────────────────────────────────────────────────
+    /** Every provider entry, including alias-claimed ones, with availability derived. */
+    allProviders() {
+        // Keyed by (capabilityId, providerId) so one provider can never appear twice for one capability —
+        // an alias pointing at a provider that already declares the id collapses onto a single entry.
+        const out = new Map();
+        const add = (p) => {
+            const key = `${p.capabilityId}\u0000${p.providerId}`;
+            if (!out.has(key))
+                out.set(key, p);
+        };
+        for (const entries of this.byProvider.values()) {
+            for (const e of entries)
+                add(this.toProvider(e, e.capabilityId));
+        }
+        // Config aliases: claim a curated id for an existing provider (its effects merge fail-closed).
+        for (const [curatedId, providerId] of Object.entries(this.config.aliases ?? {})) {
+            const src = this.findEntry(providerId);
+            if (!src)
+                continue; // unknown target — reported by configWarnings/gaps, never a silent grant
+            add(this.toProvider({ ...src, capabilityId: curatedId, verification: 'documented' }, curatedId));
+        }
+        return [...out.values()];
+    }
+    findEntry(providerId) {
+        return this.byProvider.get(providerId)?.[0];
+    }
+    toProvider(e, capabilityId) {
+        return {
+            capabilityId,
+            providerId: e.providerId,
+            source: e.source,
+            binding: e.binding,
+            effects: effectsOf({ id: capabilityId, effects: e.effects }, capabilityId),
+            verification: e.verification,
+            availability: this.availabilityOf(e),
+            ...(e.note ? { note: e.note } : {}),
+        };
+    }
+    /** Availability is DERIVED: a skill whose tools are not all registered is unavailable. */
+    availabilityOf(e) {
+        // An MCP provider's availability is the SERVER's, not merely "is the tool object registered" — a
+        // cache-seeded tool is registered and plan-referenceable while its server is only `unknown`.
+        if (e.source === 'mcp') {
+            const server = e.providerId.slice('mcp:'.length).split('.')[0] ?? '';
+            const a = this.accessors.mcpAvailability?.(server);
+            if (a)
+                return a;
+        }
+        if (e.binding.kind === 'tool') {
+            const ids = this.accessors.toolIds?.();
+            if (!ids)
+                return 'unknown';
+            return ids.includes(e.binding.toolId) ? 'available' : 'unavailable';
+        }
+        const skills = this.accessors.skills?.();
+        const toolIds = this.accessors.toolIds?.();
+        if (!skills || !toolIds)
+            return 'unknown';
+        const skill = skills.find((s) => s.id === e.binding.skillId);
+        if (!skill)
+            return 'unavailable';
+        return (skill.tools ?? []).every((t) => toolIds.includes(t)) ? 'available' : 'unavailable';
+    }
+    /**
+     * The capability ids ONE provider contributes: its own stored entries plus any config alias that
+     * CLAIMS a curated id for it. A pure lookup over `byProvider` — no inference — so the registry stays
+     * offline and property-testable. Phase 3.3's post-plan check uses it to ask "what does this step's
+     * provider actually do?" instead of guessing from the step input.
+     */
+    capabilitiesOf(providerId, rawId) {
+        const entries = this.byProvider.get(providerId) ?? [];
+        // Ownership check: `providerId` is a SANITIZED view of a source id, so `Filesystem` and `filesystem`
+        // fold together. `claimProviderId` refuses the second registration, which means a lookup by the
+        // loser's id would otherwise be answered with the INCUMBENT's capabilities — charging a step with
+        // permissions and effects belonging to a different provider. Given the caller's exact id, refuse.
+        if (rawId !== undefined && entries.length > 0 && entries[0].rawId !== rawId)
+            return [];
+        const own = entries.map((e) => e.capabilityId);
+        const aliased = Object.entries(this.config.aliases ?? {})
+            .filter(([, target]) => target === providerId && this.findEntry(target) !== undefined)
+            .map(([curatedId]) => curatedId);
+        return [...new Set([...own, ...aliased])].sort();
+    }
+    /** All capability entities (derived views), sorted by id for stable output. */
+    list() {
+        const ids = new Map();
+        for (const p of this.allProviders()) {
+            const arr = ids.get(p.capabilityId) ?? [];
+            arr.push(p);
+            ids.set(p.capabilityId, arr);
+        }
+        return [...ids.entries()]
+            .map(([id, providers]) => {
+            // The winning provider by the same total order resolve() uses — never Map insertion order.
+            const top = [...providers].sort(compareProviders)[0];
+            return entityFor(id, { description: this.byProvider.get(top.providerId)?.find((e) => e.capabilityId === id)?.description, effects: top.effects });
+        })
+            .sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+    }
+    get(id) {
+        return this.list().find((c) => c.id === id);
+    }
+    providersOf(capabilityId) {
+        return this.allProviders().filter((p) => p.capabilityId === capabilityId);
+    }
+    query(q = {}) {
+        const text = q.text?.toLowerCase();
+        return this.list().filter((c) => {
+            if (text && !`${c.id} ${c.name} ${c.description}`.toLowerCase().includes(text))
+                return false;
+            if (q.effects && !c.effects.includes(q.effects))
+                return false;
+            const providers = this.providersOf(c.id);
+            if (q.source && !providers.some((p) => p.source === q.source))
+                return false;
+            if (q.availableOnly && !providers.some((p) => p.availability === 'available'))
+                return false;
+            return true;
+        });
+    }
+    // ── resolution (D9: the deterministic 8-step algorithm) ────────────────────
+    resolve(required, opts = {}) {
+        const satisfied = [];
+        const gaps = [];
+        for (const capabilityId of required) {
+            // (1) collect
+            const all = this.providersOf(capabilityId);
+            if (all.length === 0) {
+                gaps.push({ capabilityId, reason: 'unknown', providers: [], suggestions: [{ kind: 'register', hint: `no tool or skill provides '${capabilityId}' — register one, install a skill pack, or check the id` }] });
+                continue;
+            }
+            // (2) disabled
+            let pool = all.filter((p) => p.availability !== 'disabled');
+            if (pool.length === 0) {
+                gaps.push({ capabilityId, reason: 'disabled', providers: all, suggestions: all.filter((p) => p.source === 'mcp').map((p) => ({ kind: 'enable-server', serverId: p.providerId.replace(/^mcp:/, '').split('.')[0] ?? p.providerId })) });
+                continue;
+            }
+            // (3) policy-denied. Two predicates, and only these two: the curated vocabulary's `permissionHint`
+            // for a curated id, and — for an `mcp:` provider — the run's per-server grant. An MCP provider whose
+            // server is not granted is NOT eligible: reporting it as available would have the planner build a
+            // plan around a tool the executor then refuses.
+            const hint = curated(capabilityId)?.permissionHint;
+            const perms = opts.permissions;
+            if (hint !== undefined && perms !== undefined && !permitted(hint, perms)) {
+                gaps.push({ capabilityId, reason: 'permission', providers: pool, suggestions: [{ kind: 'grant-permission', policyKey: hintToPolicyKey(hint) }] });
+                continue;
+            }
+            if (perms !== undefined) {
+                const granted = pool.filter((p) => p.source !== 'mcp' || mcpGranted(p, perms));
+                if (granted.length === 0) {
+                    const server = mcpServerOf(pool[0]);
+                    gaps.push({ capabilityId, reason: 'permission', providers: pool, suggestions: [{ kind: 'grant-permission', policyKey: `permissions.mcp.servers.${server}` }] });
+                    continue;
+                }
+                pool = granted;
+            }
+            // (4) unavailable
+            const usable = pool.filter((p) => p.availability === 'available' || p.availability === 'unknown');
+            if (usable.length === 0) {
+                gaps.push({ capabilityId, reason: 'unavailable', providers: pool, suggestions: [{ kind: 'register', hint: `'${capabilityId}' has provider(s) that are not usable right now (a required tool is not registered, or a server is unreachable)` }] });
+                continue;
+            }
+            pool = usable;
+            // (5) user pin → (6) evidence rank → (7) source order → (8) lexicographic providerId
+            const pinned = this.config.pins?.[capabilityId];
+            const pin = pinned ? pool.find((p) => p.providerId === pinned) : undefined;
+            const ordered = [...pool].sort(compareProviders);
+            const chosen = pin ?? ordered[0];
+            satisfied.push({ capabilityId, chosen, alternates: ordered.filter((p) => p !== chosen) });
+        }
+        return { ok: gaps.length === 0, satisfied, gaps };
+    }
+    /** Build the user-facing report from a resolution (one shape; gaps carry the actionable suggestions). */
+    report(required, opts = {}) {
+        return capabilityReportFrom(required, this.resolve(required, opts).gaps, (id) => this.providersOf(id));
+    }
+}
+// ── helpers ──────────────────────────────────────────────────────────────────
+/** The MCP server a provider belongs to: `mcp:<server>.<tool>` → `<server>`. */
+function mcpServerOf(p) {
+    return p.providerId.replace(/^mcp:/, '').split('.')[0] ?? p.providerId;
+}
+/**
+ * Whether the run's permissions admit this MCP provider at all. A write-like tool needs `full`, a
+ * read-only one needs `read` — the same split the tool adapter enforces at execution, so resolution and
+ * execution agree. Own-property checked, so an unconfigured server cannot inherit a grant.
+ */
+function mcpGranted(p, perms) {
+    const servers = perms.mcp.servers;
+    const server = mcpServerOf(p);
+    const grant = Object.prototype.hasOwnProperty.call(servers, server) ? servers[server] : 'off';
+    if (grant === 'full')
+        return true;
+    if (grant !== 'read')
+        return false;
+    return !p.effects.includes('write');
+}
+/**
+ * Build the ONE `MissingCapabilityReport` shape from an already-resolved gap set. Factored out of
+ * `report()` (Phase 3.3) so the run path and the public reporter cannot diverge: before this, the
+ * Runtime hand-built the same shape without `dedupeSuggestions` and listed only gapped ids in
+ * `required`. Every construction of this type now goes through here.
+ */
+export function capabilityReportFrom(required, gaps, providersOf) {
+    const gapById = new Map(gaps.map((g) => [g.capabilityId, g]));
+    return {
+        required: required.map((id) => {
+            const gap = gapById.get(id);
+            return {
+                capabilityId: id,
+                status: gap ? gap.reason : 'available',
+                providers: (gap ? gap.providers : providersOf(id)).map((p) => p.providerId),
+            };
+        }),
+        gaps,
+        suggestions: dedupeSuggestions(gaps.flatMap((g) => g.suggestions)),
+    };
+}
+function permitted(hint, p) {
+    switch (hint) {
+        case 'filesystem.read':
+            return p.filesystem.read;
+        case 'filesystem.write':
+            return p.filesystem.write;
+        case 'shell.enabled':
+            return p.shell.enabled;
+        case 'git.commit':
+            return p.git.commit;
+        case 'git.push':
+            return p.git.push;
+    }
+}
+function hintToPolicyKey(hint) {
+    switch (hint) {
+        case 'filesystem.read':
+            return 'permissions.fsRead';
+        case 'filesystem.write':
+            return 'permissions.fsWrite';
+        case 'shell.enabled':
+            return 'permissions.shell';
+        case 'git.commit':
+            return 'permissions.gitCommit';
+        case 'git.push':
+            return 'permissions.gitPush';
+    }
+}
+/** Total order: evidence rank desc → source order → providerId lexicographic (fully deterministic). */
+function compareProviders(a, b) {
+    const ev = rankOf(b.verification) - rankOf(a.verification);
+    if (ev !== 0)
+        return ev;
+    const src = SOURCE_ORDER.indexOf(a.source) - SOURCE_ORDER.indexOf(b.source);
+    if (src !== 0)
+        return src;
+    return a.providerId < b.providerId ? -1 : a.providerId > b.providerId ? 1 : 0;
+}
+function dedupeSuggestions(list) {
+    const seen = new Set();
+    const out = [];
+    for (const s of list) {
+        const key = JSON.stringify(s);
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        out.push(s);
+    }
+    return out;
+}

package/dist/capabilities/vocabulary.d.ts

@@ -0,0 +1,32 @@
+/**
+ * The curated ACTION-capability vocabulary (Phase 3.1). These are the canonical, cross-provider ids a
+ * goal can require — `read_file`, `run_tests`, `read_repository` — independent of which tool, skill, or
+ * MCP server provides them.
+ *
+ * Curated metadata is CANONICAL: a declaration may add itself as a provider of a curated id, but can
+ * never override the id's name/description/effects. Bare curated ids are claimable only by (a) the
+ * in-tree builtin declarations registered at Runtime construction and (b) operator config aliases —
+ * every other declared bare id is auto-namespaced to its source, so third-party code can never squat a
+ * curated name (see `namespacedId` in ./capability.ts).
+ *
+ * `permissionHint` names the ResolvedPermissions predicate a provider of this capability will need. It
+ * is used ONLY to drop policy-denied providers during resolution and to render an actionable "grant
+ * this" suggestion — it is never authorization: the selected tool's own permission check is what
+ * actually gates execution.
+ */
+import type { ActionCapabilityEffect } from './capability.js';
+/** The permission predicates a curated capability can depend on (keys into ResolvedPermissions). */
+export type PermissionHint = 'filesystem.read' | 'filesystem.write' | 'shell.enabled' | 'git.commit' | 'git.push';
+export interface CuratedCapability {
+    id: string;
+    name: string;
+    description: string;
+    effects: ActionCapabilityEffect[];
+    permissionHint?: PermissionHint;
+}
+/** The shipped vocabulary. Adding an entry is an additive, documented decision (see DECISIONS.md). */
+export declare const CURATED_VOCABULARY: readonly CuratedCapability[];
+/** The curated entry for an id, or undefined when the id is not curated. */
+export declare function curated(id: string): CuratedCapability | undefined;
+/** Whether an id belongs to the curated vocabulary (the membership oracle — "curated" is never a guess). */
+export declare function isCurated(id: string): boolean;

package/dist/capabilities/vocabulary.js

@@ -0,0 +1,34 @@
+/**
+ * The curated ACTION-capability vocabulary (Phase 3.1). These are the canonical, cross-provider ids a
+ * goal can require — `read_file`, `run_tests`, `read_repository` — independent of which tool, skill, or
+ * MCP server provides them.
+ *
+ * Curated metadata is CANONICAL: a declaration may add itself as a provider of a curated id, but can
+ * never override the id's name/description/effects. Bare curated ids are claimable only by (a) the
+ * in-tree builtin declarations registered at Runtime construction and (b) operator config aliases —
+ * every other declared bare id is auto-namespaced to its source, so third-party code can never squat a
+ * curated name (see `namespacedId` in ./capability.ts).
+ *
+ * `permissionHint` names the ResolvedPermissions predicate a provider of this capability will need. It
+ * is used ONLY to drop policy-denied providers during resolution and to render an actionable "grant
+ * this" suggestion — it is never authorization: the selected tool's own permission check is what
+ * actually gates execution.
+ */
+/** The shipped vocabulary. Adding an entry is an additive, documented decision (see DECISIONS.md). */
+export const CURATED_VOCABULARY = [
+    { id: 'read_file', name: 'Read a file', description: 'Read the contents of a workspace file.', effects: ['read'], permissionHint: 'filesystem.read' },
+    { id: 'write_file', name: 'Write a file', description: 'Create or modify a workspace file.', effects: ['write'], permissionHint: 'filesystem.write' },
+    { id: 'read_repository', name: 'Read the repository', description: 'Inspect repository structure, history, or metadata.', effects: ['read'], permissionHint: 'filesystem.read' },
+    { id: 'run_command', name: 'Run a command', description: 'Execute a shell command in the workspace.', effects: ['write'], permissionHint: 'shell.enabled' },
+    { id: 'run_tests', name: 'Run tests', description: 'Execute the project test suite or a subset of it.', effects: ['write'], permissionHint: 'shell.enabled' },
+    { id: 'commit_changes', name: 'Commit changes', description: 'Record changes to the repository history.', effects: ['write'], permissionHint: 'git.commit' },
+];
+const BY_ID = new Map(CURATED_VOCABULARY.map((c) => [c.id, c]));
+/** The curated entry for an id, or undefined when the id is not curated. */
+export function curated(id) {
+    return BY_ID.get(id);
+}
+/** Whether an id belongs to the curated vocabulary (the membership oracle — "curated" is never a guess). */
+export function isCurated(id) {
+    return BY_ID.has(id);
+}

package/dist/cli/cli.js

@@ -17,10 +17,11 @@ import { setupCommand } from './commands/setup.js';
 import { infoCommand } from './commands/info.js';
 import { cleanupCommand } from './commands/cleanup.js';
 import { skillsCommand } from './commands/skills.js';
+import { mcpCommand, mcpAddCommand, mcpRemoveCommand, mcpEnableCommand, mcpTestCommand } from './commands/mcp.js';
 import { startRepl } from './interactive/repl.js';
 import { printError } from './render.js';
 const program = new Command();
-program.name('ai-runtime').description('Universal, provider-agnostic AI Runtime & Orchestration Platform').version('1.2.0');
+program.name('ai-runtime').description('Universal, provider-agnostic AI Runtime & Orchestration Platform').version('2.7.0');
 const configOpt = ['-c, --config <path>', 'path to an ai-runtime config file'];
 // Bare `ai-runtime` (no subcommand) opens the interactive terminal. `allowExcessArguments(false)` keeps
 // a mistyped subcommand (e.g. `ai-runtime porviders`) failing fast instead of silently opening the REPL.
@@ -35,6 +36,8 @@ program
     .option(...configOpt)
     .option('--json', 'print the full RuntimeResult as JSON')
     .option('--dry-run', 'plan and report what would happen without making any changes')
+    .option('--stream', 'stream the answer token-by-token (text output only)')
+    .option('--partial', 'if over the call budget, run the phases that fit and pause (vs. notify-and-wait)')
     .action((input, o) => runCommand(input, o));
 program
     .command('executions')
@@ -59,11 +62,57 @@ program
     .action((o) => setupCommand(o));
 program
     .command('skills')
-    .description('List available skills; --discover scans the workspace for more (reported, not loaded)')
+    .description('List available skills; --discover scans the workspace for more; --scaffold drafts a new one')
     .option(...configOpt)
     .option('--discover', 'scan the workspace for skill files elsewhere and report them')
+    .option('--scaffold <goal>', 'draft a *.skill.yaml manifest for a goal (asks before saving)')
+    .option('-y, --yes', 'with --scaffold, save the drafted skill without prompting')
     .option('--json', 'print as JSON')
     .action((o) => skillsCommand(o));
+// `mcp` — MCP servers. A subcommand-bearing group whose bare form lists, and `mcp <id>` details one.
+// Every path releases stdio children on completion (Runtime.close), so a one-shot command never orphans.
+const mcp = program.command('mcp').description('Inspect and manage MCP servers (tools from external servers)');
+mcp
+    .argument('[id]', 'a server id to show in detail')
+    .option(...configOpt)
+    .option('--json', 'print as JSON')
+    .action((id, o) => mcpCommand(id, o));
+mcp
+    .command('add')
+    .argument('<id>', 'a short id for the server (lowercase, kebab/snake)')
+    .description('Add a server (stored locally — your config file is never modified)')
+    .option('--command <argv>', 'stdio server command line, e.g. "npx -y some-mcp-server"')
+    .option('--url <url>', 'streamable-HTTP endpoint')
+    .option('--token-env <NAME>', 'env-var NAME holding the credential (never the value itself)')
+    .option('--timeout <ms>', 'per-call timeout override')
+    .option(...configOpt)
+    .option('--json', 'print as JSON')
+    .action((id, o) => mcpAddCommand(id, o));
+mcp
+    .command('remove')
+    .argument('<id>', 'server id')
+    .description('Remove a server that was added with `mcp add`')
+    .option(...configOpt)
+    .action((id, o) => mcpRemoveCommand(id, o));
+mcp
+    .command('enable')
+    .argument('<id>', 'server id')
+    .description('Enable a disabled server')
+    .option(...configOpt)
+    .action((id, o) => mcpEnableCommand(id, true, o));
+mcp
+    .command('disable')
+    .argument('<id>', 'server id')
+    .description('Disable a server without removing it')
+    .option(...configOpt)
+    .action((id, o) => mcpEnableCommand(id, false, o));
+mcp
+    .command('test')
+    .argument('<id>', 'server id')
+    .description('Connect, handshake, list tools, and ping — reporting exactly what happened')
+    .option(...configOpt)
+    .option('--json', 'print as JSON')
+    .action((id, o) => mcpTestCommand(id, o));
 program
     .command('info')
     .description('Summarize the runtime: workspace, providers, skills, tools, memory, learning, storage')
@@ -89,13 +138,16 @@ program
     .description('List known models across providers')
     .option(...configOpt)
     .option('--json', 'print as JSON')
+    .option('--profile', 'show the models.md per-mode/per-task routing profile instead')
     .action((o) => modelsCommand(o));
 program
     .command('capabilities')
-    .description('Show the capability matrix by model')
+    .argument('[goal]', 'with --actions: which action capabilities this goal needs (offline — no model call)')
+    .description('Show the model capability matrix; --actions shows action capabilities (read_file, run_tests, …)')
     .option(...configOpt)
+    .option('--actions', 'show ACTION capabilities (what the runtime can do) instead of the model matrix')
     .option('--json', 'print as JSON')
-    .action((o) => capabilitiesCommand(o));
+    .action((goal, o) => capabilitiesCommand(goal, o));
 program
     .command('doctor')
     .description('Diagnose the runtime: config, .env, providers, models, store, skills, tools, permissions, git')

package/dist/cli/commands/cleanup.js

@@ -4,9 +4,9 @@
  * Nothing is deleted without confirmation unless `--yes`; `--dry-run` only reports the plan. Integrity
  * issues are reported, never auto-"repaired" destructively.
  */
-import { Runtime } from '../../runtime/runtime.js';
 import { TERMINAL } from '../../executions/execution.js';
 import { confirm } from '../prompt.js';
+import { withRuntime } from '../runtimeSession.js';
 import { print } from '../render.js';
 const DAY_MS = 86_400_000;
 function numEnv(v) {
@@ -67,30 +67,32 @@ function renderPlan(plan) {
     return lines;
 }
 export async function cleanupCommand(opts) {
-    const rt = await Runtime.load({ ...(opts.config ? { config: opts.config } : {}) });
-    if (!rt.store.enabled) {
-        print('storage is disabled (stateless mode) — nothing to clean.');
-        return;
-    }
-    const plan = planCleanup(rt, Date.now());
-    if (opts.json)
-        return print(JSON.stringify(plan, null, 2));
-    for (const line of renderPlan(plan))
-        print(line);
-    const removable = toRemove(plan);
-    if (removable === 0) {
-        print('\nNothing to remove.');
-        return;
-    }
-    if (opts.dryRun) {
-        print('\n(dry run — nothing was removed)');
-        return;
-    }
-    const ok = opts.yes || (await confirm(`\nRemove ${removable} item(s)?`));
-    if (!ok) {
-        print('cancelled — nothing was removed.');
-        return;
-    }
-    const done = applyCleanup(rt, plan);
-    print(`\nremoved: ${done.conversations} conversation(s), ${done.executions} execution(s), ${done.artifacts} artifact(s), ${done.cache} cache entr${done.cache === 1 ? 'y' : 'ies'}.`);
+    // Every Runtime-based command releases its Runtime (MCP children included) on every path.
+    return withRuntime(opts, async (rt) => {
+        if (!rt.store.enabled) {
+            print('storage is disabled (stateless mode) — nothing to clean.');
+            return;
+        }
+        const plan = planCleanup(rt, Date.now());
+        if (opts.json)
+            return print(JSON.stringify(plan, null, 2));
+        for (const line of renderPlan(plan))
+            print(line);
+        const removable = toRemove(plan);
+        if (removable === 0) {
+            print('\nNothing to remove.');
+            return;
+        }
+        if (opts.dryRun) {
+            print('\n(dry run — nothing was removed)');
+            return;
+        }
+        const ok = opts.yes || (await confirm(`\nRemove ${removable} item(s)?`));
+        if (!ok) {
+            print('cancelled — nothing was removed.');
+            return;
+        }
+        const done = applyCleanup(rt, plan);
+        print(`\nremoved: ${done.conversations} conversation(s), ${done.executions} execution(s), ${done.artifacts} artifact(s), ${done.cache} cache entr${done.cache === 1 ? 'y' : 'ies'}.`);
+    });
 }