ai-runtime-engine 1.3.0 → 2.8.0

package/dist/agents/worker.js

@@ -0,0 +1,377 @@
+/**
+ * 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';
+import { hashOf } from '../util/hash.js';
+import { validatePlan } from '../orchestration/plan.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;
+/** Inner observations persisted per task. The record lives in a JSON file that is rewritten every
+ *  commit, so this is a durability bound, not a display one. Beyond it, the count is kept and the
+ *  content dropped — an honest "there was more" rather than a silently short list. */
+export const INNER_OBS_MAX = 20;
+/** Admission rejections kept per task. They accumulate across attempts and are rewritten every commit. */
+export const DIAGNOSTICS_KEPT = 50;
+/**
+ * What makes a step THIS step. Plan step ids (`s1`, `auto1`) are model-authored and recur across
+ * replans, so binding a persisted record by id alone would hand one step's completed inner work to a
+ * different step that happens to share its id — same agent, different input, silently wrong findings.
+ */
+export function stepIdentity(step) {
+    return hashOf({ agent: step.agent, description: step.description, input: step.input ?? null });
+}
+/** 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();
+    // Computed from what is TRUE NOW, so a persisted record can be compared against the run it is about
+    // to be reused in. Reading them off the resumed record instead would compare a value with itself.
+    const defHash = hashOf(definition);
+    const envHash = hashOf(envelope);
+    const record = deps.resume ?? {
+        v: 1,
+        agentTaskId: nextAgentTaskId(now),
+        agentId: envelope.agentId,
+        stepId: step.id,
+        state: 'created',
+        createdAt: now,
+        updatedAt: now,
+        provenance: deps.provenance,
+        // The three identity hashes. They are computed HERE, at the only place a task is minted, so a
+        // resumed record can be compared against the run it is about to be reused in (Phase 3.5).
+        agentDefHash: defHash,
+        envelopeHash: envHash,
+        stepInputHash: stepIdentity(step),
+        attempt: 1,
+        innerCompletedSteps: [],
+        innerObservations: [],
+        innerObservationsOmitted: 0,
+        innerSteps: { total: 0, succeeded: 0 },
+        callsReserved: envelope.reservation,
+        callsUsed: 0,
+        callsRefunded: 0,
+        toolCallsUsed: 0,
+        findings: [],
+        diagnostics: [],
+    };
+    if (deps.resume) {
+        // A resumed record starts a NEW attempt: findings it mints are namespaced by the attempt number, so
+        // they can never collide with findings already on the record from the attempt that was interrupted.
+        record.attempt += 1;
+        // The stamp must describe the LATEST interruption, so it is cleared on promotion, not left to age.
+        delete record.interruption;
+        // The question has been answered (or the task is being retried); either way it is no longer pending,
+        // and leaving it set would re-elect this task as the run's wait on the very next commit.
+        delete record.pendingInner;
+    }
+    record.state = 'queued';
+    record.updatedAt = deps.clock.now();
+    deps.onRecord?.(record);
+    // (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.
+    // Prior spend carries across a resume: the reservation is the ceiling for the TASK, not per attempt,
+    // so a task that already burned 2 of 3 calls before a crash gets 1 more, not 3.
+    const priorCalls = deps.resume?.callsUsed ?? 0;
+    const priorToolCalls = deps.resume?.toolCallsUsed ?? 0;
+    let calls = 0;
+    const spent = () => priorCalls + calls;
+    const metered = Object.create(deps.ai);
+    metered.run = async (req) => {
+        if (spent() >= 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.updatedAt = record.endedAt;
+        record.callsUsed = priorCalls + calls;
+        record.toolCallsUsed = priorToolCalls + toolCalls;
+        // Derived, for reporting only. The real refund is that the executor charges what was SPENT, so the
+        // unspent part of the reservation is simply never charged — there is no ledger to get wrong.
+        record.callsRefunded = Math.max(0, record.callsReserved - record.callsUsed);
+        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 });
+        deps.onRecord?.(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();
+    record.updatedAt = record.startedAt;
+    deps.emit?.({ type: 'agent.task.started', record });
+    deps.onRecord?.(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 (priorToolCalls + 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)),
+        // The answer to THIS task's own question, routed here rather than appended to the outer goal —
+        // appending it there would replan the outer plan and discard every sibling agent's work.
+        ...(deps.resumeAnswer ? [wrapUntrusted(`agent-answer:${envelope.agentId}`, flattenClamp(deps.resumeAnswer, AGENT_INPUT_MAX))] : []),
+    ].join('\n\n');
+    // A persisted inner plan is REUSED rather than regenerated — that is what makes a resume cheap and
+    // what stops completed inner work being redone. It is still re-validated against the envelope's
+    // catalog first: the plan came off disk, and `validatePlan` is the membership gate for every plan,
+    // resumed or fresh. A plan that no longer validates is discarded, not repaired.
+    let innerPlan;
+    const identical = deps.resume ? deps.resume.envelopeHash === envHash && deps.resume.agentDefHash === defHash : false;
+    // An ANSWER changes what the plan should be — that is the entire point of having asked — so a task
+    // being resumed with one always re-plans rather than replaying the plan made before the question.
+    if (deps.resume?.innerPlan && identical && !deps.resumeAnswer) {
+        const check = validatePlan(deps.resume.innerPlan, { skills: envelope.skills, tools: envelope.tools, agents: [] });
+        if (check.ok)
+            innerPlan = deps.resume.innerPlan;
+    }
+    // The record now belongs to THIS run: an edited definition or a re-narrowed envelope invalidates the
+    // old plan (handled above) but not the task, so the hashes move forward with it.
+    record.agentDefHash = defHash;
+    record.envelopeHash = envHash;
+    if (!innerPlan) {
+        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.clarification) {
+            // The one inner wait that exists: the planner needs an answer. The task stays RESUMABLE and the
+            // step stays pending — this is not a failure, and it must not fail the branch.
+            record.pendingInner = { kind: 'clarification', question: flattenClamp(planned.clarification, 240), at: deps.clock.now() };
+            return finish('waiting_for_clarification', { code: 'agent-waiting', message: record.pendingInner.question });
+        }
+        if (!planned.plan) {
+            return finish('failed', { code: 'agent-failed', message: flattenClamp(planned.error ?? 'the agent could not form a plan', 160) });
+        }
+        innerPlan = planned.plan;
+        // A REGENERATED plan has new step ids. Carrying the discarded plan's completed ids into its skip
+        // set would mark steps `succeeded` that never ran — the dangerous direction of a resume, since the
+        // work is silently not done rather than merely done twice.
+        record.innerCompletedSteps = [];
+        record.innerObservations = [];
+        record.innerObservationsOmitted = 0;
+    }
+    record.innerPlan = innerPlan;
+    record.innerPlanVersion = innerPlan.version;
+    // The plan exists and nothing has run: a crash from here on resumes against a real inner plan.
+    record.updatedAt = deps.clock.now();
+    deps.onRecord?.(record);
+    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(innerPlan, {
+            skip: new Set(record.innerCompletedSteps),
+            // THE seam that makes inner work survive a crash. Everything between `running` and `finish()` was
+            // otherwise invisible to disk, so a resumed task had nothing to skip and re-ran the whole inner plan.
+            onProgress: (snap) => {
+                record.innerPlan = snap.plan;
+                record.innerCompletedSteps = snap.plan.steps.filter((st) => st.status === 'succeeded').map((st) => st.id);
+                const room = INNER_OBS_MAX - record.innerObservations.length;
+                if (room > 0)
+                    record.innerObservations.push(...snap.observations.slice(0, room));
+                record.innerObservationsOmitted += Math.max(0, snap.observations.length - Math.max(0, room));
+                record.callsUsed = priorCalls + calls;
+                record.toolCallsUsed = priorToolCalls + toolCalls;
+                record.updatedAt = deps.clock.now();
+                deps.onRecord?.(record);
+            },
+            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 };
+    record.innerCompletedSteps = inner.plan.steps.filter((s) => s.status === 'succeeded').map((s) => s.id);
+    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(),
+    });
+    // MERGE, never assign. A resumed attempt that admits fewer findings than the interrupted one would
+    // otherwise drop the earlier ones on the floor — and observations already committed to disk reference
+    // them by id. Attempt >1 namespaces its ids so the two attempts can never collide.
+    const mint = (f) => (record.attempt > 1 ? { ...f, id: `${f.id}@a${record.attempt}` } : f);
+    const fresh = [...denials, ...admission.admitted].map(mint);
+    const seenFinding = new Set(record.findings.map((f) => f.id));
+    record.findings = [...record.findings, ...fresh.filter((f) => !seenFinding.has(f.id))];
+    // Bounded: diagnostics accumulate across attempts, and every one of them is rewritten to disk on
+    // every commit. Keeping the most recent is the useful half.
+    record.diagnostics = [...record.diagnostics, ...admission.rejected].slice(-DIAGNOSTICS_KEPT);
+    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,
+    };
+}