ai-runtime-engine 1.2.0 → 2.7.0

package/dist/agents/worker.d.ts

@@ -0,0 +1,68 @@
+/**
+ * The agent worker (Phase 3.4) - runs ONE agent step.
+ *
+ * IT NEVER CALLS `orchestrate()`. It composes `generatePlan` + `executePlan` directly, because
+ * re-entering the orchestrator inside a step would re-run the parent's gates per step: re-asking for
+ * approval, re-applying the parent call budget, and re-checking plan/dry-run mode. A useful consequence
+ * of that same structure is that a dry run can never reach a worker at all - `orchestrate` returns
+ * before `executePlan` is ever called.
+ *
+ * IT NEVER CONSTRUCTS AN `AI`. One router: the inner planning call goes through a METERED FACADE over
+ * the parent's AI, so every inner model call is counted against the envelope's reservation - including
+ * the ones a skill makes through `SkillContext.ai`, which the parent budget cannot see today.
+ *
+ * DEPTH 1 IS STRUCTURAL: the inner plan is generated with `agents: []`, so `validatePlan` rejects a
+ * nested agent step as `unknown agent`. There is no runtime depth counter to get wrong.
+ */
+import { AI } from '../plugin/ai.js';
+import type { AgentTaskRecord } from './task.js';
+import type { AgentEnvelope } from './envelope.js';
+import type { AgentDefinition } from './definition.js';
+import type { PlanStep } from '../orchestration/plan.js';
+import type { StepObservation } from '../orchestration/executor.js';
+import type { Skill, SkillResult, SkillValidation } from '../skills/skill.js';
+import type { ToolResult } from '../tools/tool.js';
+import type { ArtifactRef } from '../runtime/types.js';
+import type { PermissionPolicy } from '../runtime/policy.js';
+import type { Clock } from '../util/clock.js';
+/** How much of a step input may reach the inner prompt. It is model-authored, and it is fenced. */
+export declare const AGENT_INPUT_MAX = 1000;
+export interface AgentWorkerDeps {
+    ai: AI;
+    clock: Clock;
+    /** Narrowed to the envelope by the caller; the worker does not re-derive a catalog. */
+    skills: Skill[];
+    runSkill: (id: string, input: unknown, overrides: {
+        permissions: PermissionPolicy;
+        signal?: AbortSignal;
+        ai?: AI;
+    }) => Promise<{
+        result: SkillResult;
+        validation: SkillValidation;
+    }>;
+    runTool: (id: string, input: unknown, overrides: {
+        permissions: PermissionPolicy;
+        signal?: AbortSignal;
+    }) => Promise<ToolResult>;
+    /** Store evidence content. Returns `unavailable` rather than a dangling ref when the store is off. */
+    putArtifact: (content: string, source: string) => {
+        ref?: ArtifactRef;
+        unavailable: boolean;
+    };
+    emit?: (event: {
+        type: 'agent.task.started' | 'agent.task.completed';
+        record: AgentTaskRecord;
+    }) => void;
+    parentSignal?: AbortSignal;
+    /** Why the parent aborted, when it knows. Distinguishes a cancel from a pause on the record. */
+    abortReason?: () => 'pause' | 'parent-cancel' | undefined;
+    provenance: {
+        executionId?: string;
+        planVersion: number;
+    };
+}
+export interface RunAgentTaskResult {
+    observation: StepObservation;
+    record: AgentTaskRecord;
+}
+export declare function runAgentTask(step: PlanStep, envelope: AgentEnvelope, definition: AgentDefinition, deps: AgentWorkerDeps): Promise<RunAgentTaskResult>;

package/dist/agents/worker.js

@@ -0,0 +1,256 @@
+/**
+ * The agent worker (Phase 3.4) - runs ONE agent step.
+ *
+ * IT NEVER CALLS `orchestrate()`. It composes `generatePlan` + `executePlan` directly, because
+ * re-entering the orchestrator inside a step would re-run the parent's gates per step: re-asking for
+ * approval, re-applying the parent call budget, and re-checking plan/dry-run mode. A useful consequence
+ * of that same structure is that a dry run can never reach a worker at all - `orchestrate` returns
+ * before `executePlan` is ever called.
+ *
+ * IT NEVER CONSTRUCTS AN `AI`. One router: the inner planning call goes through a METERED FACADE over
+ * the parent's AI, so every inner model call is counted against the envelope's reservation - including
+ * the ones a skill makes through `SkillContext.ai`, which the parent budget cannot see today.
+ *
+ * DEPTH 1 IS STRUCTURAL: the inner plan is generated with `agents: []`, so `validatePlan` rejects a
+ * nested agent step as `unknown agent`. There is no runtime depth counter to get wrong.
+ */
+import { generatePlan } from '../orchestration/planner.js';
+import { executePlan } from '../orchestration/executor.js';
+import { wrapUntrusted } from '../tools/untrusted.js';
+import { flattenClamp } from '../util/flatten.js';
+import { admitFindings, contractFailed } from './admit.js';
+import { executionCoverage } from './finding.js';
+import { AGENT_TASK_PROJECTION, nextAgentTaskId } from './task.js';
+/** How much of a step input may reach the inner prompt. It is model-authored, and it is fenced. */
+export const AGENT_INPUT_MAX = 1000;
+/** Raised by the metered facade when an agent tries to exceed its reservation. */
+class AgentCallBudgetError extends Error {
+    constructor() {
+        super('agent inner model-call reservation exhausted');
+        this.name = 'AgentCallBudgetError';
+    }
+}
+export async function runAgentTask(step, envelope, definition, deps) {
+    const now = deps.clock.now();
+    const record = {
+        agentTaskId: nextAgentTaskId(now),
+        agentId: envelope.agentId,
+        stepId: step.id,
+        state: 'created',
+        createdAt: now,
+        innerSteps: { total: 0, succeeded: 0 },
+        callsUsed: 0,
+        toolCallsUsed: 0,
+        findings: [],
+        diagnostics: [],
+    };
+    record.state = 'queued';
+    // (2) A child controller, so a parent abort reaches the inner run and nothing else does.
+    const child = new AbortController();
+    const onParentAbort = () => child.abort();
+    if (deps.parentSignal?.aborted)
+        child.abort();
+    else
+        deps.parentSignal?.addEventListener('abort', onParentAbort, { once: true });
+    const deadline = deps.clock.now() + envelope.maxDurationMs;
+    const expired = () => deps.clock.now() > deadline;
+    // (3) THE METERED FACADE. Prototype-delegating, so it IS an AI (assignable to SkillContext.ai) while
+    // owning `run`. The count increments BEFORE the await, so a failed inner call is still charged.
+    let calls = 0;
+    const metered = Object.create(deps.ai);
+    metered.run = async (req) => {
+        if (calls >= envelope.reservation)
+            throw new AgentCallBudgetError();
+        calls += 1;
+        return deps.ai.run(req);
+    };
+    let toolCalls = 0;
+    const toolResults = [];
+    const skillResults = [];
+    const finish = (state, failure) => {
+        deps.parentSignal?.removeEventListener('abort', onParentAbort);
+        record.state = state;
+        record.endedAt = deps.clock.now();
+        record.callsUsed = calls;
+        record.toolCallsUsed = toolCalls;
+        if (failure)
+            record.failure = failure;
+        const row = AGENT_TASK_PROJECTION[state];
+        const observation = {
+            stepId: step.id,
+            agent: envelope.agentId,
+            agentTaskId: record.agentTaskId,
+            ok: state === 'completed',
+            callsUsed: calls,
+            ...(failure ? { code: failure.code, error: failure.message } : row.code ? { code: row.code } : {}),
+            ...(record.findings.length ? { data: { findings: record.findings } } : {}),
+            ...(record.findings.some((f) => f.artifacts.length) ? { artifacts: record.findings.flatMap((f) => f.artifacts) } : {}),
+            ...(state === 'completed' ? { output: `${envelope.agentId}: ${record.innerSteps.succeeded}/${record.innerSteps.total} inner step(s), ${record.findings.length} finding(s)` } : {}),
+        };
+        deps.emit?.({ type: 'agent.task.completed', record });
+        return { observation, record };
+    };
+    // (12) A parent abort is a cancel or a pause; both project to the same observation, and the record
+    // carries which so a later phase can re-queue a paused task rather than treat it as cancelled.
+    const abortedNow = () => {
+        if (!child.signal.aborted)
+            return undefined;
+        const kind = deps.abortReason?.() ?? 'parent-cancel';
+        if (kind === 'pause') {
+            record.interruption = { kind: 'pause', at: deps.clock.now() };
+            return finish('queued', { code: 'cancelled', message: 'cancelled: the run was paused' });
+        }
+        record.interruption = { kind: 'parent-cancel', at: deps.clock.now() };
+        return finish('cancelled', { code: 'cancelled', message: 'cancelled: the run was aborted' });
+    };
+    const preempted = abortedNow();
+    if (preempted)
+        return preempted;
+    record.state = 'running';
+    record.startedAt = deps.clock.now();
+    deps.emit?.({ type: 'agent.task.started', record });
+    // (6) THE TOOL SEAM - defense in depth behind narrowEnvelope. Always a structured denial, never a
+    // throw: the tool contract is that a refusal is visible.
+    const innerCallTool = async (id, input) => {
+        if (!envelope.tools.includes(id))
+            return { ok: false, error: { code: 'PERMISSION', message: `'${flattenClamp(id, 40)}' is not in this agent's catalog` } };
+        if (toolCalls + 1 > envelope.maxToolCalls)
+            return { ok: false, error: { code: 'PERMISSION', message: `agent tool-call budget exhausted (${envelope.maxToolCalls})` } };
+        if (expired())
+            return { ok: false, error: { code: 'TIMEOUT', message: 'agent time budget exhausted' } };
+        toolCalls += 1;
+        const result = await deps.runTool(id, input, { permissions: envelope.permissions, signal: child.signal });
+        return result;
+    };
+    // (4) PROMPT BOUNDARY #1: the objective is definition-authored and clamped; the step input is
+    // MODEL-authored and therefore fenced as untrusted data.
+    const innerGoal = [
+        envelope.objective,
+        wrapUntrusted(`agent-input:${envelope.agentId}`, flattenClamp(JSON.stringify(step.input ?? null), AGENT_INPUT_MAX)),
+    ].join('\n\n');
+    let planned;
+    try {
+        planned = await generatePlan({ goal: innerGoal, ai: metered, skills: deps.skills, tools: envelope.tools, agents: [], version: 1, ...(envelope.routing ? { routing: envelope.routing } : {}) });
+    }
+    catch (err) {
+        if (err instanceof AgentCallBudgetError)
+            return finish('failed', { code: 'agent-call-budget', message: err.message });
+        return finish('failed', { code: 'agent-failed', message: flattenClamp(err instanceof Error ? err.message : String(err), 160) });
+    }
+    if (!planned.plan) {
+        return finish('failed', { code: 'agent-failed', message: flattenClamp(planned.error ?? planned.clarification ?? 'the agent could not form a plan', 160) });
+    }
+    record.innerPlanVersion = planned.plan.version;
+    const aborted = abortedNow();
+    if (aborted)
+        return aborted;
+    if (expired())
+        return finish('failed', { code: 'agent-timeout', message: `agent exceeded ${envelope.maxDurationMs}ms` });
+    // (5) Inner execution. NO callBudget: the facade in (3) is a strictly tighter ceiling and also covers
+    // a skill's own model calls, which a wave gate cannot see.
+    let inner;
+    try {
+        inner = await executePlan(planned.plan, {
+            runSkill: async (id, i) => {
+                const out = await deps.runSkill(id, i, { permissions: envelope.permissions, signal: child.signal, ai: metered });
+                skillResults.push({ stepId: id, result: out.result, validation: out.validation });
+                return out;
+            },
+            runTool: async (id, i) => {
+                const result = await innerCallTool(id, i);
+                toolResults.push({ stepId: id, result });
+                return result;
+            },
+            maxParallelSteps: 1,
+            signal: child.signal,
+        });
+    }
+    catch (err) {
+        if (err instanceof AgentCallBudgetError)
+            return finish('failed', { code: 'agent-call-budget', message: err.message });
+        return finish('failed', { code: 'agent-failed', message: flattenClamp(err instanceof Error ? err.message : String(err), 160) });
+    }
+    record.innerSteps = { total: inner.plan.steps.length, succeeded: inner.plan.steps.filter((s) => s.status === 'succeeded').length };
+    const afterRun = abortedNow();
+    if (afterRun)
+        return afterRun;
+    // (8) Deterministic coverage, from statuses only.
+    const coverage = executionCoverage(inner.plan.steps);
+    // (10) Evidence: one entry per inner step, keyed STRUCTURALLY by what the step produced. A skill's
+    // validation checks are free-form names, so there is nothing to parse - the kind comes from the fact
+    // that a SkillValidation exists at all.
+    const evidence = [
+        ...skillResults.map((s) => ({
+            kind: 'validation',
+            stepId: s.stepId,
+            detail: flattenClamp(s.result.output ?? s.result.error?.message ?? 'skill completed', 160),
+            ok: s.result.ok && s.validation.ok,
+            checks: { passed: s.validation.checks.filter((c) => c.ok).length, total: s.validation.checks.length },
+        })),
+        ...toolResults.map((t) => ({
+            kind: 'tool-output',
+            stepId: t.stepId,
+            detail: flattenClamp(t.result.output ?? t.result.error?.message ?? 'tool completed', 160),
+            ok: t.result.ok,
+        })),
+    ];
+    // (11) HEADLESS DENIAL => FINDING + FAIL-BRANCH. There is no inner approval wait at 3.0: a denial is
+    // reported as a first-class finding and the branch fails. The worker can see `error.code` because it
+    // holds the ToolResult directly; the executor flattens it away.
+    const denials = toolResults
+        .filter((t) => !t.result.ok && t.result.error?.code === 'PERMISSION')
+        .map((t, i) => ({
+        id: `${record.agentTaskId}_d${i + 1}`,
+        agentId: envelope.agentId,
+        agentTaskId: record.agentTaskId,
+        type: 'permission-denied',
+        subject: flattenClamp(t.stepId, 80),
+        claim: flattenClamp(`the agent was denied a permitted action: ${t.result.error?.message ?? 'permission denied'}`, 240),
+        executionCoverage: coverage,
+        confidence: 0.5,
+        evidence: [{ kind: 'tool-output', stepId: t.stepId, detail: flattenClamp(t.result.error?.message ?? 'permission denied', 160), ok: false }],
+        artifacts: [],
+        sourceSteps: [t.stepId],
+        provenance: { ...deps.provenance },
+        status: 'active',
+        createdAt: deps.clock.now(),
+    }));
+    // (9) Candidates come from the FINAL inner step's structured data - never from model prose.
+    const last = [...skillResults].pop();
+    const lastTool = [...toolResults].pop();
+    const finalData = (last?.result.data ?? lastTool?.result.data);
+    const admission = admitFindings({
+        agentTaskId: record.agentTaskId,
+        agentId: envelope.agentId,
+        candidates: finalData?.findings ?? [],
+        ...(definition.outputContract ? { contract: definition.outputContract } : {}),
+        coverage,
+        ...(finalData?.confidence !== undefined ? { confidenceOverride: finalData.confidence } : {}),
+        evidenceFor: () => evidence,
+        artifactsFor: (index) => {
+            const source = `agent:${envelope.agentId}#${index}`;
+            const content = evidence.map((e) => `${e.kind} ${e.stepId}: ${e.detail}`).join('\n');
+            if (!content)
+                return { refs: [], unavailable: false };
+            const put = deps.putArtifact(content, source);
+            return put.ref ? { refs: [put.ref], unavailable: false } : { refs: [], unavailable: true };
+        },
+        sourceSteps: inner.plan.steps.map((s) => s.id),
+        provenance: deps.provenance,
+        now: deps.clock.now(),
+    });
+    record.findings = [...denials, ...admission.admitted];
+    record.diagnostics = admission.rejected;
+    if (contractFailed(admission)) {
+        return finish('failed', { code: 'finding-contract', message: 'the agent did not satisfy its declared output contract' });
+    }
+    if (expired())
+        return finish('failed', { code: 'agent-timeout', message: `agent exceeded ${envelope.maxDurationMs}ms` });
+    if (toolCalls > envelope.maxToolCalls)
+        return finish('failed', { code: 'agent-tool-budget', message: `agent exceeded ${envelope.maxToolCalls} tool call(s)` });
+    if (!inner.ok) {
+        const why = inner.observations.filter((o) => !o.ok).map((o) => `${o.stepId}: ${o.error ?? 'failed'}`).join('; ');
+        return finish('failed', { code: 'agent-failed', message: flattenClamp(why || 'the agent plan did not complete', 160) });
+    }
+    return finish('completed');
+}

package/dist/capabilities/capability.d.ts

@@ -0,0 +1,117 @@
+/**
+ * ACTION capabilities (Phase 3.1) — what the system can DO (`read_file`, `run_tests`, `read_issue`),
+ * independent of which tool / skill / MCP server provides it. Deliberately distinct from the router's
+ * MODEL-capability system (`src/core/capabilities/**`, `CapabilityProfile`/`CapabilityRequirement`):
+ * every type here is `Action*`-prefixed, nothing under `src/core/` imports this module, and the router
+ * never sees an action capability.
+ *
+ * SECURITY: `effects` is advisory metadata only and NEVER authorization. It orders resolution, drives
+ * permission-gap suggestions, and labels the catalog; the actual operation permission is always enforced
+ * by the selected Tool/Skill execution path (`runTool`/`runSkill` → `ToolContext.permissions`).
+ */
+import type { Evidence } from '../types.js';
+/** Side-effect class. Two values only: anything not provably read-only is `write` (fail-closed). */
+export type ActionCapabilityEffect = 'read' | 'write';
+/** Where a provider came from. `plugin` is reserved for a future plugin system. */
+export type ActionCapabilitySource = 'native' | 'skill' | 'mcp' | 'openapi' | 'plugin';
+/** Whether a provider can be used right now. `disabled` is operator-driven (MCP, Phase 3.2). */
+export type ProviderAvailability = 'available' | 'unavailable' | 'disabled' | 'unknown';
+/** What a tool / skill / manifest declares it provides. Effects absent ⇒ ['write'] (fail-closed). */
+export interface ActionCapabilityDecl {
+    id: string;
+    effects?: ActionCapabilityEffect[];
+    description?: string;
+}
+/** A capability entity — a DERIVED view keyed by id (curated metadata wins; see vocabulary.ts). */
+export interface ActionCapability {
+    id: string;
+    name: string;
+    description: string;
+    effects: ActionCapabilityEffect[];
+    /** True when the id belongs to the shipped curated vocabulary. */
+    curated: boolean;
+}
+/** One concrete provider of one capability. Bindings always execute through an EXISTING registry. */
+export interface ActionCapabilityProvider {
+    capabilityId: string;
+    /** `tool:<id>` | `skill:<id>` | `mcp:<server>.<tool>` — the one grammar pins/aliases/tie-breaks use. */
+    providerId: string;
+    source: ActionCapabilitySource;
+    binding: {
+        kind: 'tool';
+        toolId: string;
+    } | {
+        kind: 'skill';
+        skillId: string;
+    };
+    effects: ActionCapabilityEffect[];
+    /** `inferred` (undeclared), `documented` (declared or config-aliased), `verified` (future probes). */
+    verification: Evidence;
+    availability: ProviderAvailability;
+    note?: string;
+}
+/** Why a required capability could not be satisfied. */
+export type CapabilityGapReason = 'unknown' | 'unavailable' | 'disabled' | 'permission';
+export type GapSuggestion = {
+    kind: 'register';
+    hint: string;
+} | {
+    kind: 'enable-server';
+    serverId: string;
+} | {
+    kind: 'install-skill';
+    hint: string;
+} | {
+    kind: 'grant-permission';
+    policyKey: string;
+};
+export interface CapabilityGap {
+    capabilityId: string;
+    reason: CapabilityGapReason;
+    /** Every known provider (may be unavailable/disabled/denied); empty ⇒ reason 'unknown'. */
+    providers: ActionCapabilityProvider[];
+    suggestions: GapSuggestion[];
+}
+/** The user-facing report: what a goal needed, what is available, and what to do about the rest. */
+export interface MissingCapabilityReport {
+    required: Array<{
+        capabilityId: string;
+        status: 'available' | CapabilityGapReason;
+        providers: string[];
+    }>;
+    gaps: CapabilityGap[];
+    suggestions: GapSuggestion[];
+}
+export interface CapabilityResolution {
+    ok: boolean;
+    satisfied: Array<{
+        capabilityId: string;
+        chosen: ActionCapabilityProvider;
+        alternates: ActionCapabilityProvider[];
+    }>;
+    gaps: CapabilityGap[];
+}
+/** A bare curated id: `^[a-z][a-z0-9_]*$`. */
+export declare const CURATED_ID_RE: RegExp;
+/** A namespaced id: `tool:`/`skill:`/`mcp:` + a segment containing no further colon. */
+export declare const NAMESPACED_ID_RE: RegExp;
+/** Sanitize an arbitrary source id into a namespace segment (never rejects — existing callers keep working). */
+export declare function sanitizeSegment(raw: string): string;
+/** Build the namespaced id for a source-owned capability: `tool:filesystem`, `skill:code-review`. */
+export declare function namespacedId(kind: 'tool' | 'skill' | 'mcp', segment: string): string;
+/**
+ * Resolve the id a declaration actually registers under (the claiming rule, D2). A declared bare id is
+ * kept ONLY when the declaration is trusted (in-tree builtins) and the id is curated; a declared
+ * NAMESPACED id is kept only when it is the declarer's OWN id (`tool:<own-segment>`) — otherwise the
+ * declaration is namespaced to its source, so no source can ever claim a curated name or impersonate
+ * another provider's namespaced capability.
+ */
+export declare function effectiveDeclId(decl: ActionCapabilityDecl, kind: 'tool' | 'skill' | 'mcp', segment: string, trusted: boolean): string;
+/** Effects for a declaration: declared values, else fail-closed `['write']`. Curated ids use vocabulary. */
+export declare function effectsOf(decl: ActionCapabilityDecl | undefined, id: string): ActionCapabilityEffect[];
+/** Build the derived entity view for an id (curated metadata wins; else the declaring source's text). */
+export declare function entityFor(id: string, fallback: {
+    name?: string;
+    description?: string;
+    effects?: ActionCapabilityEffect[];
+}): ActionCapability;

package/dist/capabilities/capability.js

@@ -0,0 +1,66 @@
+/**
+ * ACTION capabilities (Phase 3.1) — what the system can DO (`read_file`, `run_tests`, `read_issue`),
+ * independent of which tool / skill / MCP server provides it. Deliberately distinct from the router's
+ * MODEL-capability system (`src/core/capabilities/**`, `CapabilityProfile`/`CapabilityRequirement`):
+ * every type here is `Action*`-prefixed, nothing under `src/core/` imports this module, and the router
+ * never sees an action capability.
+ *
+ * SECURITY: `effects` is advisory metadata only and NEVER authorization. It orders resolution, drives
+ * permission-gap suggestions, and labels the catalog; the actual operation permission is always enforced
+ * by the selected Tool/Skill execution path (`runTool`/`runSkill` → `ToolContext.permissions`).
+ */
+import { curated, isCurated } from './vocabulary.js';
+// ── id grammar (D2/D3) ───────────────────────────────────────────────────────
+/** A bare curated id: `^[a-z][a-z0-9_]*$`. */
+export const CURATED_ID_RE = /^[a-z][a-z0-9_]*$/;
+/** A namespaced id: `tool:`/`skill:`/`mcp:` + a segment containing no further colon. */
+export const NAMESPACED_ID_RE = /^(tool|skill|mcp):[^:\s][^:]*$/;
+/** Sanitize an arbitrary source id into a namespace segment (never rejects — existing callers keep working). */
+export function sanitizeSegment(raw) {
+    const s = String(raw).trim().toLowerCase().replace(/:/g, '-').replace(/\s+/g, '-').replace(/[^a-z0-9._/-]/g, '');
+    return s || 'unnamed';
+}
+/** Build the namespaced id for a source-owned capability: `tool:filesystem`, `skill:code-review`. */
+export function namespacedId(kind, segment) {
+    return `${kind}:${sanitizeSegment(segment)}`;
+}
+/**
+ * Resolve the id a declaration actually registers under (the claiming rule, D2). A declared bare id is
+ * kept ONLY when the declaration is trusted (in-tree builtins) and the id is curated; a declared
+ * NAMESPACED id is kept only when it is the declarer's OWN id (`tool:<own-segment>`) — otherwise the
+ * declaration is namespaced to its source, so no source can ever claim a curated name or impersonate
+ * another provider's namespaced capability.
+ */
+export function effectiveDeclId(decl, kind, segment, trusted) {
+    const id = String(decl.id ?? '').trim();
+    const own = namespacedId(kind, segment);
+    // The declarer's own id, or a sub-namespace of it (`tool:acme.fetch_issue`) — expressive but unforgeable.
+    if (NAMESPACED_ID_RE.test(id) && (id === own || id.startsWith(`${own}.`)))
+        return id;
+    if (trusted && isCurated(id))
+        return id; // builtin claiming a curated id
+    return own;
+}
+/** Effects for a declaration: declared values, else fail-closed `['write']`. Curated ids use vocabulary. */
+export function effectsOf(decl, id) {
+    const c = curated(id);
+    if (c)
+        return [...c.effects]; // curated metadata is canonical
+    const declared = decl?.effects;
+    if (Array.isArray(declared) && declared.length > 0 && declared.every((e) => e === 'read' || e === 'write'))
+        return [...declared];
+    return ['write']; // absent or unrecognized ⇒ fail-closed
+}
+/** Build the derived entity view for an id (curated metadata wins; else the declaring source's text). */
+export function entityFor(id, fallback) {
+    const c = curated(id);
+    if (c)
+        return { id, name: c.name, description: c.description, effects: [...c.effects], curated: true };
+    return {
+        id,
+        name: fallback.name ?? id,
+        description: fallback.description ?? id,
+        effects: fallback.effects && fallback.effects.length ? [...fallback.effects] : ['write'],
+        curated: false,
+    };
+}

package/dist/capabilities/registry.d.ts

@@ -0,0 +1,139 @@
+/**
+ * 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 type { ResolvedPermissions } from '../tools/permissions.js';
+import { type ActionCapability, type ActionCapabilityDecl, type ActionCapabilityEffect, type ActionCapabilityProvider, type ActionCapabilitySource, type CapabilityGap, type CapabilityResolution, type MissingCapabilityReport, type ProviderAvailability } from './capability.js';
+export interface ActionCapabilityQuery {
+    text?: string;
+    source?: ActionCapabilitySource;
+    effects?: ActionCapabilityEffect;
+    availableOnly?: boolean;
+}
+/** Read-only views the registry needs to derive availability (lifts SkillRegistry.match one level). */
+export interface RegistryAccessors {
+    toolIds?: () => string[];
+    skills?: () => Array<{
+        id: string;
+        tools?: string[];
+    }>;
+    /**
+     * MCP availability, DRIVEN by the McpManager (registration alone cannot answer this): connected ⇒
+     * available, disabled ⇒ disabled, unreachable/auth-failed ⇒ unavailable, cache-only ⇒ unknown.
+     */
+    mcpAvailability?: (serverId: string) => ProviderAvailability;
+}
+export interface CapabilityConfig {
+    /** `aliases.<curatedId> = <providerId>` — CLAIMS: injects that provider into the curated id's set. */
+    aliases?: Record<string, string>;
+    /** `pins.<capabilityId> = <providerId>` — SELECTS among already-eligible providers. */
+    pins?: Record<string, string>;
+}
+export declare class ActionCapabilityRegistry {
+    /** providerId → its entries (so a re-registration can drop exactly that provider's contributions). */
+    private readonly byProvider;
+    private accessors;
+    private config;
+    /** Warnings recorded during ingestion (sanitized ids, unknown alias/pin targets). */
+    private readonly warnings;
+    /** Wire the live registries (call once, before any registration). */
+    attachAccessors(a: RegistryAccessors): this;
+    /** Apply `runtime.capabilities` config (aliases claim; pins select). */
+    configure(config: CapabilityConfig): this;
+    configWarnings(): string[];
+    /**
+     * 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: {
+        id: string;
+        description?: string;
+        provides?: ActionCapabilityDecl[];
+    }, trusted?: boolean): void;
+    /**
+     * 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: {
+        id: string;
+        description?: string;
+        provides?: ActionCapabilityDecl[];
+    }): void;
+    /** Ingest a skill's declarations (or infer one). Skills are never trusted to claim curated ids. */
+    ingestSkill(skill: {
+        id: string;
+        description?: string;
+        provides?: ActionCapabilityDecl[];
+    }): void;
+    /**
+     * 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.
+     */
+    private claimProviderId;
+    /** Remove everything a provider contributed (tool/skill unregistration, MCP server removal). */
+    removeProvider(providerId: string): void;
+    /**
+     * 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: 'tool' | 'skill' | 'mcp', rawId: string): void;
+    /**
+     * 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: string): void;
+    /**
+     * 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: string): void;
+    private replaceProvider;
+    private declsToEntries;
+    /** Every provider entry, including alias-claimed ones, with availability derived. */
+    private allProviders;
+    private findEntry;
+    private toProvider;
+    /** Availability is DERIVED: a skill whose tools are not all registered is unavailable. */
+    private availabilityOf;
+    /**
+     * 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: string, rawId?: string): string[];
+    /** All capability entities (derived views), sorted by id for stable output. */
+    list(): ActionCapability[];
+    get(id: string): ActionCapability | undefined;
+    providersOf(capabilityId: string): ActionCapabilityProvider[];
+    query(q?: ActionCapabilityQuery): ActionCapability[];
+    resolve(required: string[], opts?: {
+        permissions?: ResolvedPermissions;
+    }): CapabilityResolution;
+    /** Build the user-facing report from a resolution (one shape; gaps carry the actionable suggestions). */
+    report(required: string[], opts?: {
+        permissions?: ResolvedPermissions;
+    }): MissingCapabilityReport;
+}
+/**
+ * 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 declare function capabilityReportFrom(required: string[], gaps: CapabilityGap[], providersOf: (id: string) => ActionCapabilityProvider[]): MissingCapabilityReport;