ai-runtime-engine 1.3.0 → 2.8.0

package/dist/runtime/runtime.d.ts

@@ -3,6 +3,8 @@
  * 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 type { GenerateSkillResult } from '../generation/generateSkill.js';
+import type { SkillManifest } from '../skills/manifest.js';
 import { AI } from '../plugin/ai.js';
 import type { AIOptions } from '../plugin/ai.js';
 import type { WorkspaceInfo } from './workspace/workspace.js';
@@ -14,8 +16,13 @@ import { ConversationStore } from '../conversations/conversations.js';
 import { MemoryStore } from '../memory/memory.js';
 import type { Tool, ToolResult } from '../tools/tool.js';
 import { resolvePermissions } from '../tools/permissions.js';
+import { McpManager } from '../mcp/manager.js';
+import type { McpServerStatus } from '../mcp/manager.js';
+import { ActionCapabilityRegistry } from '../capabilities/registry.js';
+import type { MissingCapabilityReport } from '../capabilities/capability.js';
 import type { Skill, SkillResult, SkillValidation, SkillPlan } from '../skills/skill.js';
 import type { SkillSource, LoadedSource } from '../skills/discovery.js';
+import type { AgentDefinition } from '../agents/definition.js';
 import { ExecutionStore } from '../executions/store.js';
 import type { Execution } from '../executions/execution.js';
 import { ArtifactStore } from '../artifacts/artifacts.js';
@@ -23,6 +30,7 @@ import type { CompareInput } from '../comparison/comparator.js';
 import type { ComparisonResult } from '../comparison/comparison.js';
 import { LearningStore } from '../learning/learningStore.js';
 import type { FeedbackSignal } from '../learning/feedback.js';
+import type { ModelProfile } from './models/modelProfile.js';
 import type { PermissionPolicy } from './policy.js';
 import type { RuntimeConfig, RuntimeResult, RuntimeRunInput, RuntimeSettings } from './types.js';
 export interface RuntimeOptions {
@@ -54,17 +62,50 @@ export declare class Runtime {
     private readonly _memory;
     private readonly _conversations;
     private readonly estimator;
+    /** 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. */
+    private readonly _capabilities;
+    /** MCP server lifecycle (Phase 3.2). Connection is LAZY: nothing is contacted until first use. */
+    private readonly _mcp;
+    private mcpConnected;
+    private readonly mcpToolIds;
+    private readonly mcpWarnings;
     private readonly _tools;
     private readonly _skills;
     private readonly _executions;
     private readonly _artifacts;
     private readonly _learning;
     private readonly workspaceRoot;
+    private readonly _modelProfile?;
     private readonly configPermissions;
+    /** The INJECTED clock. Agent deadlines are measured against it, never a real timer, so an offline
+     *  test with a fake clock stays deterministic. */
+    private readonly clock;
+    /** Multi-agent core (Phase 3.4). False ⇒ every agent path is inert. */
+    private readonly agentsEnabled;
+    private readonly agentDefs;
+    /** 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. */
+    private readonly liveRuns;
+    /** The config file's `budget:` ceilings, kept only so the 3.3 pre-pass can decline a model call. */
+    private readonly _configBudget?;
     private readonly approval?;
     private readonly _configFile?;
     private _loadedSkillSources;
     constructor(config?: RuntimeConfig, options?: RuntimeOptions, workspace?: WorkspaceInfo);
+    /**
+     * 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).
+     */
+    private buildEmbedder;
+    /**
+     * 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.
+     */
+    private buildCipher;
     /** Build a Runtime from a workspace: load config (.ai-runtime/config.yaml > root fallback), detect workspace. */
     static load(options?: RuntimeOptions): Promise<Runtime>;
     /**
@@ -100,6 +141,15 @@ export declare class Runtime {
      * every hard gate (exclude/privacy/pin/capability/budget), which the router filter enforces.
      */
     private effectiveRouting;
+    /** The loaded `models.md` routing profile (per-mode/per-task model directives), or undefined if none. */
+    modelProfile(): ModelProfile | undefined;
+    /**
+     * 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.
+     */
+    private applyModelProfile;
     /** Apply free-text feedback (e.g. "that worked" / "wrong root cause") to the most recent outcome. */
     feedback(text: string, opts?: {
         providerId?: string;
@@ -114,10 +164,79 @@ export declare class Runtime {
     tools(): Tool[];
     /** Register a skill. Chainable. */
     registerSkill(skill: Skill): 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: string, def: AgentDefinition): this;
+    /** The agent definition ids this runtime knows (registered or configured). */
+    agents(): string[];
+    /**
+     * 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).
+     */
+    private agentEnvelopes;
+    /** The MCP server manager: `list()`, `status(id)`, `test(id)`, `addServer`, `removeServer`, `setEnabled`. */
+    mcp(): McpManager;
+    /**
+     * 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.
+     */
+    connectMcp(): Promise<McpServerStatus[]>;
+    /** Whether any MCP server is configured at all (absent ⇒ MCP is entirely inert). */
+    hasMcpServers(): boolean;
+    /**
+     * 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.
+     */
+    private registerMcpTools;
+    /**
+     * 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.
+     */
+    private publishMcpSource;
+    /** Drop a server's tools (removal / disable). */
+    private deregisterMcpTools;
+    /** Map a server's lifecycle state onto capability availability (the D7 derivation table). */
+    private mcpAvailability;
+    /** Warnings from MCP wiring (id collisions) plus the manager's own (invalid store files, etc.). */
+    mcpWarningsList(): string[];
+    /**
+     * 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.
+     */
+    close(): Promise<void>;
     /** Skills whose required tools are all registered. */
     skills(): Skill[];
+    /**
+     * 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.
+     */
+    scaffoldSkill(goal: string): Promise<GenerateSkillResult>;
+    /**
+     * 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: SkillManifest): string;
+    /** The ACTION-capability registry (Phase 3.1): what this runtime can DO, and who provides it. */
+    capabilities(): ActionCapabilityRegistry;
     /** The resolved tool permissions for this runtime (config grants over deny-by-default defaults). */
     permissions(): ReturnType<typeof resolvePermissions>;
+    /**
+     * 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.
+     */
+    private resolvedPermissions;
     private toolContext;
     /** Invoke a registered tool with the runtime's resolved permissions + host approval. */
     runTool(id: string, input: unknown, overrides?: {
@@ -128,6 +247,7 @@ export declare class Runtime {
     runSkill(id: string, input: unknown, overrides?: {
         permissions?: PermissionPolicy;
         signal?: AbortSignal;
+        ai?: AI;
     }): Promise<{
         plan: SkillPlan;
         result: SkillResult;
@@ -148,12 +268,73 @@ export declare class Runtime {
     executions(): Execution[];
     /** plan/execute/orchestrate/agent/debug: run the orchestrator and persist a resumable Execution. */
     private runOrchestration;
+    /**
+     * THE mid-run persistence sink (Phase 3.5) — the only thing that writes an execution while it runs.
+     *
+     * Invariant 18 says everything needed for resume is on disk before the next wave starts, and the
+     * non-obvious part is WHAT that includes. Committing the plan, the completed steps and the agent
+     * records is not enough: the resume gate is `!recon.drifted && !!exec.plan`, and `recon` defaults to
+     * DRIFTED whenever `checkpoints` is empty. Since checkpoints were captured only after orchestration
+     * returned, a crash mid-run always drifted, always replanned, and re-ran every completed agent task —
+     * the exact thing this phase exists to prevent. So the sink captures a checkpoint too.
+     *
+     * Every refusal from the funnel ABORTS the run. A refused commit means another owner now owns this
+     * execution's fate; carrying on would call the same tools and burn the same model calls twice while
+     * that owner re-runs the identical steps, and every result would be discarded at the end anyway.
+     */
+    private runPersistence;
     /** Run `fn` while heartbeating the execution lease so a long run never lets the lease expire. */
     private withHeartbeat;
     private orchestrateInput;
     /** Record an EXECUTED orchestration outcome for learning. plan-only, dry-run, and waiting states are
      * skipped — no skill ran, so there is no success/failure to learn (recording them would teach noise). */
     private recordOrchestration;
+    /**
+     * 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.
+     */
+    private capabilityCatalogText;
+    /** Any call/cost ceiling declared in the config file's `budget:` block (router-level, not policy). */
+    private configBudget;
+    /** Deriver candidates: registry ids + one clamped label. Built by the SAME helper the CLI uses. */
+    private capabilityCandidates;
+    /**
+     * 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.
+     */
+    private capabilityPlanning;
+    /** The pre-rendered "Required capabilities" planner block (Phase 3.3) — clamped like the 3.1 catalog. */
+    private requiredCapabilitiesText;
+    /** A step's capability provider id. An MCP-backed tool ingests under `mcp:` (see the ingest hook). */
+    private providerIdForRef;
+    /**
+     * 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.
+     */
+    private checkPlanCapabilities;
+    /**
+     * 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.
+     */
+    private resolveMissingRefs;
+    /**
+     * 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: string[]): MissingCapabilityReport;
+    /**
+     * 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.
+     */
     private execStatus;
     private mapOutcome;
     private resultFromExecution;
@@ -177,7 +358,59 @@ export declare class Runtime {
         approve?: boolean;
         signal?: AbortSignal;
     }): Promise<RuntimeResult>;
+    /**
+     * 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.
+     */
     private orchestrateRunners;
+    /**
+     * A bounded, fenced brief of what the agents have already established (Phase 3.5).
+     *
+     * On drift the plan is thrown away and the goal is replanned — but validated findings are facts about
+     * the WORKSPACE, not about the plan's structure, so discarding them silently would make the run redo
+     * work it had already proved. They are agent-authored text, so they cross a prompt boundary fenced,
+     * exactly like every other untrusted string.
+     */
+    private findingsBrief;
+    /**
+     * Fingerprint the MCP tools a plan actually references (Phase 3.5). An MCP server is remote and
+     * mutable: while a plan sits paused it can change a tool's input schema, change what it does, or drop
+     * it entirely — and the plan would then be resumed against a tool that is no longer the tool it was
+     * planned for. Hashing the live declaration makes that visible as ordinary drift.
+     *
+     * Non-MCP tools are deliberately absent: they are in-tree code covered by the config/skill hashes.
+     */
+    private mcpToolHashes;
+    /**
+     * Crash / pause / cancel reconciliation (Phase 3.5). A record left `running` or `created` describes a
+     * worker that no longer exists — the process died, or the parent stopped it — so it goes back to
+     * `queued` with an auditable reason. An interruption is deliberately NOT a state: the lifecycle does
+     * not grow, only the explanation does.
+     *
+     * This runs on the RESUME path and inside pause/cancel. Resume alone is not enough: `cancelExecution`
+     * writes a terminal status and resume early-returns on terminal, so a cancelled execution's `running`
+     * records would stay `running` on disk forever, unstamped and unexplained.
+     *
+     * Records that fail validation are preserved in place, never dropped — reconciling is not a licence to
+     * delete what this version could not parse.
+     */
+    private reconcileAgentTasks;
+    /**
+     * FIRST-WINS PENDING. `Execution.pending` is a single slot but two agents can be waiting at once, so
+     * the earliest-created waiting task claims it. The others are not lost: once this one is answered and
+     * the run continues, the next resume re-elects whichever task is still waiting — rediscovery, rather
+     * than a queue that has to be kept in sync with the records that are already the source of truth.
+     */
+    private electWaitingAgent;
+    /**
+     * Which persisted task, if any, a plan step should CONTINUE. Bound by step-input hash, never by step
+     * id: plan step ids (`s1`, `auto1`) are model-authored and recur across replans, so an id match would
+     * hand one step's completed inner work to a different step with the same id and a different input.
+     */
+    private agentResumeLookup;
+    /** Abort a run that is in flight, recording WHY so a task can tell a pause from a cancellation. */
+    private abortLiveRun;
     /** Mark an execution paused (it can be resumed later). */
     pauseExecution(id: string): boolean;
     /** Cancel an execution (terminal). */