ai-runtime-engine 1.3.0 → 2.8.0

package/dist/agents/admit.d.ts

@@ -0,0 +1,69 @@
+/**
+ * The Finding ADMISSION PIPELINE (Phase 3.4) - the only way a Finding enters persistent or inter-agent
+ * state. Arbitrary agent output NEVER becomes a Finding.
+ *
+ * FOUR STAGES, in order, each with one rejection reason: extract -> output-contract validate ->
+ * Finding validate -> persist. A rejected candidate becomes a DIAGNOSTIC on the task record and is
+ * never threaded: not onto the observation, not into a prompt, not into a RuntimeResult.
+ *
+ * Findings carry no secret by construction: every string is a clamped derivative of tool/skill output.
+ * That clamp is the ONLY defense for a persisted finding - `src/security/redact.ts` covers telemetry and
+ * CLI output, not the execution store.
+ */
+import type { Finding, FindingEvidence } from './finding.js';
+import type { AgentDefinition } from './definition.js';
+import type { ArtifactRef } from '../runtime/types.js';
+/** Clamp bounds. Each is a prompt- and record-facing string. */
+export declare const TYPE_MAX = 40;
+export declare const SUBJECT_MAX = 80;
+export declare const CLAIM_MAX = 240;
+export declare const VERDICT_MAX = 80;
+/** Observations are persisted verbatim onto the Execution, so what rides along is bounded. */
+export declare const FINDING_THREAD_MAX = 5;
+/** The contract default when a definition declares one without a count. */
+export declare const DEFAULT_MAX_FINDINGS = 10;
+export interface AdmissionRejection {
+    index: number;
+    stage: 'extract' | 'output-contract' | 'finding-validate' | 'persist';
+    why: string;
+}
+export interface AdmissionResult {
+    admitted: Finding[];
+    rejected: AdmissionRejection[];
+    /** True when a DECLARED output contract was violated - the input to the task-failure rule. */
+    contractViolated: boolean;
+    /** Whether a contract was declared at all. Recorded HERE so `contractFailed` needs only this result:
+     *  taking the contract twice would let a caller check the rule against a contract the pipeline never
+     *  actually applied, and quietly get the wrong answer. */
+    contractDeclared: boolean;
+}
+export interface AdmitFindingsInput {
+    agentTaskId: string;
+    agentId: string;
+    /** Raw `data.findings` from the final inner step. Untrusted shape: anything at all. */
+    candidates: unknown;
+    contract?: AgentDefinition['outputContract'];
+    /** Deterministic execution coverage, injected - never computed from the candidates. */
+    coverage: number;
+    /** `SkillResult.data.confidence` from the final inner step, if it offered one. */
+    confidenceOverride?: unknown;
+    evidenceFor: (index: number) => FindingEvidence[];
+    artifactsFor: (index: number) => {
+        refs: ArtifactRef[];
+        unavailable: boolean;
+    };
+    sourceSteps: string[];
+    provenance: {
+        executionId?: string;
+        planVersion: number;
+    };
+    now: number;
+}
+export declare function admitFindings(input: AdmitFindingsInput): AdmissionResult;
+/**
+ * THE TASK-FAILURE RULE. An agent task fails on its findings ONLY when the definition declared an
+ * output contract: then a violation, or admitting nothing at all, is a contract failure. With no
+ * declared contract findings are best-effort - rejections are diagnostics and the step's success is
+ * decided by its inner plan alone.
+ */
+export declare function contractFailed(result: AdmissionResult): boolean;

package/dist/agents/admit.js

@@ -0,0 +1,129 @@
+/**
+ * The Finding ADMISSION PIPELINE (Phase 3.4) - the only way a Finding enters persistent or inter-agent
+ * state. Arbitrary agent output NEVER becomes a Finding.
+ *
+ * FOUR STAGES, in order, each with one rejection reason: extract -> output-contract validate ->
+ * Finding validate -> persist. A rejected candidate becomes a DIAGNOSTIC on the task record and is
+ * never threaded: not onto the observation, not into a prompt, not into a RuntimeResult.
+ *
+ * Findings carry no secret by construction: every string is a clamped derivative of tool/skill output.
+ * That clamp is the ONLY defense for a persisted finding - `src/security/redact.ts` covers telemetry and
+ * CLI output, not the execution store.
+ */
+import { flattenClamp } from '../util/flatten.js';
+import { confidenceOf } from './finding.js';
+/** Clamp bounds. Each is a prompt- and record-facing string. */
+export const TYPE_MAX = 40;
+export const SUBJECT_MAX = 80;
+export const CLAIM_MAX = 240;
+export const VERDICT_MAX = 80;
+/** Observations are persisted verbatim onto the Execution, so what rides along is bounded. */
+export const FINDING_THREAD_MAX = 5;
+/** The contract default when a definition declares one without a count. */
+export const DEFAULT_MAX_FINDINGS = 10;
+export function admitFindings(input) {
+    const admitted = [];
+    const rejected = [];
+    let contractViolated = false;
+    // STAGE 1 - EXTRACT. The shape is whatever a skill happened to return.
+    if (!Array.isArray(input.candidates)) {
+        return { admitted, rejected: [{ index: -1, stage: 'extract', why: 'data.findings is not an array' }], contractViolated: input.contract !== undefined, contractDeclared: input.contract !== undefined };
+    }
+    const maxFindings = input.contract ? input.contract.maxFindings ?? DEFAULT_MAX_FINDINGS : Number.POSITIVE_INFINITY;
+    input.candidates.forEach((raw, index) => {
+        if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
+            rejected.push({ index, stage: 'extract', why: 'candidate is not an object' });
+            return;
+        }
+        const c = raw;
+        if (typeof c.type !== 'string' || !c.type.trim()) {
+            rejected.push({ index, stage: 'extract', why: 'missing type' });
+            return;
+        }
+        if (typeof c.claim !== 'string' || !c.claim.trim()) {
+            rejected.push({ index, stage: 'extract', why: 'missing claim' });
+            return;
+        }
+        // STAGE 2 - OUTPUT-CONTRACT VALIDATE. Only when the definition declared one.
+        if (input.contract) {
+            if (!input.contract.types.includes(c.type)) {
+                rejected.push({ index, stage: 'output-contract', why: `type '${flattenClamp(c.type, TYPE_MAX)}' is not in the declared output contract` });
+                contractViolated = true;
+                return;
+            }
+            if (admitted.length >= maxFindings) {
+                rejected.push({ index, stage: 'output-contract', why: 'exceeds maxFindings' });
+                contractViolated = true;
+                return;
+            }
+            if (input.contract.requireSubject && (typeof c.subject !== 'string' || !c.subject.trim())) {
+                rejected.push({ index, stage: 'output-contract', why: 'the contract requires a subject' });
+                contractViolated = true;
+                return;
+            }
+        }
+        // STAGE 3 - FINDING VALIDATE. Build it fully, clamp every string, then assert the invariants.
+        const evidence = input.evidenceFor(index);
+        const artifacts = input.artifactsFor(index);
+        const confidence = confidenceOf(evidence, input.confidenceOverride);
+        const finding = {
+            id: `${input.agentTaskId}_f${admitted.length + 1}`,
+            agentId: input.agentId,
+            agentTaskId: input.agentTaskId,
+            type: flattenClamp(c.type, TYPE_MAX),
+            ...(typeof c.subject === 'string' && c.subject.trim() ? { subject: flattenClamp(c.subject, SUBJECT_MAX) } : {}),
+            claim: flattenClamp(c.claim, CLAIM_MAX),
+            ...(typeof c.verdict === 'string' && c.verdict.trim() ? { verdict: flattenClamp(c.verdict, VERDICT_MAX) } : {}),
+            executionCoverage: input.coverage,
+            confidence,
+            evidence,
+            artifacts: artifacts.refs,
+            sourceSteps: [...input.sourceSteps],
+            provenance: { ...input.provenance },
+            status: 'active',
+            createdAt: input.now,
+        };
+        const invalid = validateFinding(finding);
+        if (invalid) {
+            rejected.push({ index, stage: 'finding-validate', why: invalid });
+            return;
+        }
+        // STAGE 4 - PERSIST/THREAD. Bounded, and an excess is a recorded rejection rather than a silent
+        // truncation: an observation rides on the persisted Execution, so unbounded data would grow the
+        // store without limit.
+        if (admitted.length >= FINDING_THREAD_MAX) {
+            rejected.push({ index, stage: 'persist', why: `exceeds the ${FINDING_THREAD_MAX}-finding thread bound` });
+            return;
+        }
+        admitted.push(finding);
+    });
+    return { admitted, rejected, contractViolated, contractDeclared: input.contract !== undefined };
+}
+/** The Finding-validate assertions. Returns the failing one's name, or undefined when it holds. */
+function validateFinding(f) {
+    if (!(f.confidence >= 0 && f.confidence <= 1))
+        return 'confidence is not in [0,1]';
+    if (!(f.executionCoverage >= 0 && f.executionCoverage <= 1))
+        return 'executionCoverage is not in [0,1]';
+    if (f.sourceSteps.length === 0)
+        return 'sourceSteps is empty';
+    // A claim with no evidence may exist only if it also claims no belief.
+    if (f.evidence.length === 0 && f.confidence !== 0)
+        return 'evidence is empty but confidence is not 0';
+    if (!f.type)
+        return 'type is empty after clamping';
+    if (!f.claim)
+        return 'claim is empty after clamping';
+    return undefined;
+}
+/**
+ * THE TASK-FAILURE RULE. An agent task fails on its findings ONLY when the definition declared an
+ * output contract: then a violation, or admitting nothing at all, is a contract failure. With no
+ * declared contract findings are best-effort - rejections are diagnostics and the step's success is
+ * decided by its inner plan alone.
+ */
+export function contractFailed(result) {
+    if (!result.contractDeclared)
+        return false;
+    return result.contractViolated || result.admitted.length === 0;
+}

package/dist/agents/definition.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Agent definitions (Phase 3.4) — the OPERATOR-authored shape of a delegable unit of work.
+ *
+ * A definition is a CEILING, never a grant: its `tools`/`skills` are intersected with the parent's
+ * catalog, its `permissions` may only narrow, its caps may only lower, and its `routing` may only add
+ * exclusions. Everything that turns a definition into something runnable happens at exactly one place —
+ * `narrowEnvelope` in ./envelope.ts. Nothing else may derive an inner catalog or a permission set.
+ */
+import type { PermissionPolicy } from '../runtime/policy.js';
+import type { CapabilityRequirement, RoutingPreferences } from '../types.js';
+export interface AgentDefinition {
+    /** What this agent is for. Definition-authored, clamped before it reaches a prompt. */
+    objective: string;
+    /** Tool allowlist, INTERSECTED with the parent catalog — it can never add a tool. */
+    tools?: string[];
+    /** Skill allowlist, intersected with the parent catalog (and with what the envelope's tools support). */
+    skills?: string[];
+    /** May only NARROW the parent's permissions (see `clampPermissions`). */
+    permissions?: PermissionPolicy;
+    /** Per-task caps. A definition may only LOWER the configured default. */
+    maxToolCalls?: number;
+    maxDurationMs?: number;
+    /** The wave-gate reservation AND the worker's hard inner-model-call ceiling — one number, both jobs. */
+    maxInnerCalls?: number;
+    /** What the agent must produce for its findings to be admitted (see ./admit.ts). */
+    outputContract?: {
+        types: string[];
+        maxFindings?: number;
+        requireSubject?: boolean;
+    };
+    /** Model constraints. `routing` may only narrow the parent's — never re-admit an excluded provider. */
+    model?: {
+        requirements?: CapabilityRequirement[];
+        routing?: RoutingPreferences;
+    };
+}

package/dist/agents/definition.js

@@ -0,0 +1,9 @@
+/**
+ * Agent definitions (Phase 3.4) — the OPERATOR-authored shape of a delegable unit of work.
+ *
+ * A definition is a CEILING, never a grant: its `tools`/`skills` are intersected with the parent's
+ * catalog, its `permissions` may only narrow, its caps may only lower, and its `routing` may only add
+ * exclusions. Everything that turns a definition into something runnable happens at exactly one place —
+ * `narrowEnvelope` in ./envelope.ts. Nothing else may derive an inner catalog or a permission set.
+ */
+export {};

package/dist/agents/envelope.d.ts

@@ -0,0 +1,53 @@
+/**
+ * THE ONE ENFORCEMENT POINT for agent execution (Phase 3.4).
+ *
+ * `narrowEnvelope` is the single place an inner catalog, a narrowed permission set, the per-task caps,
+ * the budget reservation, and the no-nested-agents rule are derived. NEVER re-derive any of them at
+ * another call site — the same standing discipline as `Runtime.resolvedPermissions` and
+ * `clampMcpPermissions`. It has exactly one caller (`Runtime.agentEnvelopes`) and is deliberately not
+ * exported from the public API, so that property is checkable by grep.
+ *
+ * Everything here NARROWS. A definition is a ceiling: it can remove a tool but never add one, lower a
+ * cap but never raise it, drop a permission but never grant one, and add a routing exclusion but never
+ * re-admit an excluded provider.
+ */
+import type { PermissionPolicy } from '../runtime/policy.js';
+import type { CapabilityRequirement, RoutingPreferences } from '../types.js';
+import type { AgentDefinition } from './definition.js';
+/** The definition-authored objective reaches a model prompt, so it is bounded like any other source text. */
+export declare const OBJECTIVE_MAX = 240;
+export interface AgentEnvelope {
+    agentId: string;
+    /** Definition-authored, already flattened and clamped. */
+    objective: string;
+    /** parent ∩ definition, sorted. Agents are NEVER a member — depth 1 is structural. */
+    tools: string[];
+    /** parent ∩ definition ∩ { skills whose declared tools are all inside `tools` }, sorted. */
+    skills: string[];
+    /** Fully explicit and ≤ the parent on every field, so a later merge cannot widen it. */
+    permissions: PermissionPolicy;
+    maxToolCalls: number;
+    maxDurationMs: number;
+    /** The wave-gate cost AND the worker's hard inner-model-call ceiling. One number, both jobs. */
+    reservation: number;
+    /** Only ever narrower than the parent's: exclusions union, preferences intersect. */
+    routing?: RoutingPreferences;
+    requirements?: CapabilityRequirement[];
+}
+export interface NarrowEnvelopeInput {
+    agentId: string;
+    definition: AgentDefinition;
+    parentTools: string[];
+    parentSkills: Array<{
+        id: string;
+        tools?: string[];
+    }>;
+    parentPermissions: PermissionPolicy;
+    parentRouting?: RoutingPreferences;
+    defaults: {
+        maxToolCalls: number;
+        maxDurationMs: number;
+        maxInnerCalls: number;
+    };
+}
+export declare function narrowEnvelope(input: NarrowEnvelopeInput): AgentEnvelope;

package/dist/agents/envelope.js

@@ -0,0 +1,68 @@
+/**
+ * THE ONE ENFORCEMENT POINT for agent execution (Phase 3.4).
+ *
+ * `narrowEnvelope` is the single place an inner catalog, a narrowed permission set, the per-task caps,
+ * the budget reservation, and the no-nested-agents rule are derived. NEVER re-derive any of them at
+ * another call site — the same standing discipline as `Runtime.resolvedPermissions` and
+ * `clampMcpPermissions`. It has exactly one caller (`Runtime.agentEnvelopes`) and is deliberately not
+ * exported from the public API, so that property is checkable by grep.
+ *
+ * Everything here NARROWS. A definition is a ceiling: it can remove a tool but never add one, lower a
+ * cap but never raise it, drop a permission but never grant one, and add a routing exclusion but never
+ * re-admit an excluded provider.
+ */
+import { clampPermissions } from '../tools/permissions.js';
+import { flattenClamp } from '../util/flatten.js';
+/** The definition-authored objective reaches a model prompt, so it is bounded like any other source text. */
+export const OBJECTIVE_MAX = 240;
+/** A cap a definition may only LOWER, never raise, and never below 1. */
+function lowerOnly(deflt, requested) {
+    return Math.max(1, Math.min(deflt, requested ?? deflt));
+}
+const uniqSorted = (xs) => [...new Set(xs)].sort();
+export function narrowEnvelope(input) {
+    const { definition: def, defaults } = input;
+    // (1) Tools: intersect with the parent. A definition entry naming something the parent does not have
+    // is simply absent — it can never ADD a tool.
+    const parentTools = new Set(input.parentTools);
+    const tools = uniqSorted((def.tools ?? input.parentTools).filter((t) => parentTools.has(t)));
+    // (2) Skills: intersect with the parent, then drop any skill that needs a tool outside the envelope.
+    // That second clause is load-bearing, not tidiness: a skill's own `callTool` resolves straight off the
+    // Runtime's registry with no allowlist check, so admitting a skill whose declared tools escape the
+    // envelope would be a hole. Excluding it is the structural fix; the worker's membership check is
+    // defense in depth.
+    const inner = new Set(tools);
+    const allowedSkills = def.skills ? new Set(def.skills) : undefined;
+    const skills = uniqSorted(input.parentSkills.filter((s) => (!allowedSkills || allowedSkills.has(s.id)) && (s.tools ?? []).every((t) => inner.has(t))).map((s) => s.id));
+    // (3) Permissions: minimum-merged and fully explicit (see `clampPermissions`).
+    const permissions = clampPermissions(input.parentPermissions, def.permissions);
+    // (6) Routing: exclusions only ever GROW, preferences only ever shrink, so an agent can never
+    // re-admit a provider the parent excluded, nor reach past a privacy or policy decision.
+    const pr = input.parentRouting;
+    const dr = def.model?.routing;
+    const routing = pr || dr
+        ? {
+            ...(pr?.excludeProviders || dr?.excludeProviders ? { excludeProviders: uniqSorted([...(pr?.excludeProviders ?? []), ...(dr?.excludeProviders ?? [])]) } : {}),
+            ...(pr?.excludeModels || dr?.excludeModels ? { excludeModels: uniqSorted([...(pr?.excludeModels ?? []), ...(dr?.excludeModels ?? [])]) } : {}),
+            ...(pr?.preferProviders ? { preferProviders: dr?.preferProviders ? pr.preferProviders.filter((x) => dr.preferProviders.includes(x)) : [...pr.preferProviders] } : dr?.preferProviders ? { preferProviders: [...dr.preferProviders] } : {}),
+            ...(pr?.preferModels ? { preferModels: dr?.preferModels ? pr.preferModels.filter((x) => dr.preferModels.includes(x)) : [...pr.preferModels] } : dr?.preferModels ? { preferModels: [...dr.preferModels] } : {}),
+        }
+        : undefined;
+    return {
+        agentId: input.agentId,
+        objective: flattenClamp(def.objective, OBJECTIVE_MAX),
+        tools,
+        skills,
+        permissions,
+        // (4) Caps: a definition may only lower.
+        maxToolCalls: lowerOnly(defaults.maxToolCalls, def.maxToolCalls),
+        maxDurationMs: lowerOnly(defaults.maxDurationMs, def.maxDurationMs),
+        // (5) The reservation is the same shape of number, and doubles as the hard inner-call ceiling.
+        reservation: lowerOnly(defaults.maxInnerCalls, def.maxInnerCalls),
+        ...(routing && Object.keys(routing).length ? { routing } : {}),
+        // Requirements ADD to the parent's — more requirements is a narrower candidate set.
+        ...(def.model?.requirements?.length ? { requirements: [...def.model.requirements] } : {}),
+    };
+    // (7) There is no `agents` field, by construction: depth 1 is structural, not a runtime check. The
+    // worker plans with `agents: []`, so validatePlan rejects any nested agent step as `unknown agent`.
+}

package/dist/agents/finding.d.ts

@@ -0,0 +1,79 @@
+/**
+ * The Finding contract (Phase 3.4) - what an agent is allowed to tell the rest of the system.
+ *
+ * TWO NUMBERS, NEVER CONFLATED:
+ *  - `executionCoverage` is how much of the agent's plan actually ran. Deterministic, read from step
+ *    statuses, and NOT a belief about the claim.
+ *  - `confidence` is evidence-based belief in the claim. Conflict resolution weighs ONLY this;
+ *    coverage may filter or break a tie, never contribute to the weight.
+ *
+ * NAMING: the entry type is `FindingEvidence`, not `Evidence` - that name is already the router's
+ * capability-evidence RANK union (src/types.ts), and `EvidenceResult` belongs to comparison. The same
+ * class of collision as `Tool.provides` and `agentTaskId`.
+ */
+import type { ArtifactRef } from '../runtime/types.js';
+import type { PlanStep } from '../orchestration/plan.js';
+export type FindingStatus = 'active' | 'superseded' | 'contradicted';
+export type FindingEvidenceKind = 'validation' | 'observation' | 'tool-output' | 'artifact';
+export interface FindingEvidence {
+    kind: FindingEvidenceKind;
+    /** The INNER step id this entry came from. */
+    stepId: string;
+    /** Clamped at construction. Fenced again at render; never stored fenced. */
+    detail: string;
+    ok: boolean;
+    /** `validation` only: the check tally that backs the belief. */
+    checks?: {
+        passed: number;
+        total: number;
+    };
+    /** Set when the backing artifact could not be written - the DOWNGRADE marker. */
+    unavailable?: boolean;
+}
+export interface Finding {
+    id: string;
+    agentId: string;
+    /** `agentTaskId`, NEVER `taskId` - that name belongs to the router. */
+    agentTaskId: string;
+    type: string;
+    subject?: string;
+    claim: string;
+    verdict?: string;
+    /** Deterministic plan completion, NOT belief. */
+    executionCoverage: number;
+    /** Evidence-based belief in the claim. */
+    confidence: number;
+    evidence: FindingEvidence[];
+    artifacts: ArtifactRef[];
+    sourceSteps: string[];
+    provenance: {
+        executionId?: string;
+        planVersion: number;
+    };
+    status: FindingStatus;
+    supersededBy?: string;
+    createdAt: number;
+}
+/** Two decimals, so a JSON round-trip is stable and an equality assertion means something. */
+export declare function round2(n: number): number;
+/**
+ * How much of the agent's inner plan succeeded. Reads step STATUSES only - it never consults evidence
+ * and is never derived from confidence.
+ */
+export declare function executionCoverage(steps: PlanStep[]): number;
+/**
+ * Evidence-based belief. The rubric, in order:
+ *  - no evidence => 0, always. This guard precedes the override, so a finding with nothing behind it
+ *    can never claim belief.
+ *  - at least one usable `validation` entry => up to 1.0, scaled by validated/total CHECKS.
+ *  - observation / tool-output only => capped at 0.5.
+ *  - a final inner step MAY supply a structured override (`SkillResult.data.confidence`), clamped
+ *    0..1. That is a skill-authored judgment, still not model prose.
+ */
+export declare function confidenceOf(ev: FindingEvidence[], override?: unknown): number;
+/**
+ * Resolve conflicts among active findings, weighing ONLY `confidence`. Two findings conflict when they
+ * share a `type` + `subject`: a differing verdict makes the loser `contradicted`, and otherwise the
+ * loser is `superseded`. `executionCoverage` breaks a tie and never enters the weight.
+ */
+export declare function resolveConflicts(findings: Finding[]): Finding[];

package/dist/agents/finding.js

@@ -0,0 +1,80 @@
+/**
+ * The Finding contract (Phase 3.4) - what an agent is allowed to tell the rest of the system.
+ *
+ * TWO NUMBERS, NEVER CONFLATED:
+ *  - `executionCoverage` is how much of the agent's plan actually ran. Deterministic, read from step
+ *    statuses, and NOT a belief about the claim.
+ *  - `confidence` is evidence-based belief in the claim. Conflict resolution weighs ONLY this;
+ *    coverage may filter or break a tie, never contribute to the weight.
+ *
+ * NAMING: the entry type is `FindingEvidence`, not `Evidence` - that name is already the router's
+ * capability-evidence RANK union (src/types.ts), and `EvidenceResult` belongs to comparison. The same
+ * class of collision as `Tool.provides` and `agentTaskId`.
+ */
+/** Two decimals, so a JSON round-trip is stable and an equality assertion means something. */
+export function round2(n) {
+    return Math.round(n * 100) / 100;
+}
+/**
+ * How much of the agent's inner plan succeeded. Reads step STATUSES only - it never consults evidence
+ * and is never derived from confidence.
+ */
+export function executionCoverage(steps) {
+    if (steps.length === 0)
+        return 0;
+    return round2(steps.filter((s) => s.status === 'succeeded').length / steps.length);
+}
+/**
+ * Evidence-based belief. The rubric, in order:
+ *  - no evidence => 0, always. This guard precedes the override, so a finding with nothing behind it
+ *    can never claim belief.
+ *  - at least one usable `validation` entry => up to 1.0, scaled by validated/total CHECKS.
+ *  - observation / tool-output only => capped at 0.5.
+ *  - a final inner step MAY supply a structured override (`SkillResult.data.confidence`), clamped
+ *    0..1. That is a skill-authored judgment, still not model prose.
+ */
+export function confidenceOf(ev, override) {
+    if (ev.length === 0)
+        return 0;
+    const validations = ev.filter((e) => e.kind === 'validation' && !e.unavailable && (e.checks?.total ?? 0) > 0);
+    let c;
+    if (validations.length >= 1) {
+        const passed = validations.reduce((n, e) => n + e.checks.passed, 0);
+        const total = validations.reduce((n, e) => n + e.checks.total, 0);
+        c = Math.min(1, passed / total);
+    }
+    else {
+        c = (ev.filter((e) => e.ok && !e.unavailable).length / ev.length) * 0.5;
+    }
+    if (typeof override === 'number' && Number.isFinite(override))
+        c = Math.min(1, Math.max(0, override));
+    return round2(c);
+}
+/**
+ * Resolve conflicts among active findings, weighing ONLY `confidence`. Two findings conflict when they
+ * share a `type` + `subject`: a differing verdict makes the loser `contradicted`, and otherwise the
+ * loser is `superseded`. `executionCoverage` breaks a tie and never enters the weight.
+ */
+export function resolveConflicts(findings) {
+    const groups = new Map();
+    for (const f of findings) {
+        if (!f.subject)
+            continue; // no conflict key => nothing to resolve against
+        const key = `${f.type}\u0000${f.subject}`;
+        groups.set(key, [...(groups.get(key) ?? []), f]);
+    }
+    const out = new Map(findings.map((f) => [f.id, { ...f }]));
+    for (const group of groups.values()) {
+        if (group.length < 2)
+            continue;
+        const ranked = [...group].sort((a, b) => b.confidence - a.confidence || b.executionCoverage - a.executionCoverage || (a.id < b.id ? -1 : 1));
+        const winner = ranked[0];
+        for (const loser of ranked.slice(1)) {
+            const row = out.get(loser.id);
+            const differingVerdict = loser.verdict !== undefined && winner.verdict !== undefined && loser.verdict !== winner.verdict;
+            row.status = differingVerdict ? 'contradicted' : 'superseded';
+            row.supersededBy = winner.id;
+        }
+    }
+    return [...out.values()];
+}

package/dist/agents/roles.d.ts

@@ -0,0 +1,36 @@
+/**
+ * The closed role vocabulary for auto-decomposition (Phase 3.7).
+ *
+ * Auto-decomposition lets a goal produce agent steps with no operator-authored definition. The thing
+ * that makes it safe is what it does NOT do: no model-authored string ever becomes an objective, a tool
+ * id, or a permission. The model's only influence is choosing among the bounded agents offered to it —
+ * the same closed-set discipline `deriveCapabilitiesOffline` uses, applied to roles instead of ids.
+ *
+ * Every objective here is written in-tree by a human, because the objective is the one string that
+ * reaches the inner prompt UNFENCED (the step input beside it is fenced as untrusted). Every role is
+ * read-shaped, and adding a write-shaped one is a decision to record, not a line to slip in: the
+ * permission clamp would still deny it, but the catalog it is offered should not suggest otherwise.
+ */
+import type { AgentDefinition } from './definition.js';
+export interface AgentRole {
+    id: string;
+    /** IN-TREE and human-written. Never derived, never model-authored. */
+    objective: string;
+    /** What the role is for, shown in the plan catalog so the planner can choose between roles. */
+    description: string;
+    /**
+     * An output contract is MANDATORY for a derived role, though optional for an authored definition.
+     * `contractFailed` returns false when no contract is declared and the finding cap becomes infinite —
+     * so an agent nobody wrote would be the one agent whose output could never fail admission, and the
+     * one whose finding count is unbounded.
+     */
+    outputContract: NonNullable<AgentDefinition['outputContract']>;
+}
+/** Three roles ship in 3.0.0. All read-shaped; see the header before adding a fourth. */
+export declare const AGENT_ROLES: readonly AgentRole[];
+/** The id prefix reserved for synthesized agents, so one can never collide with an authored id. */
+export declare const DERIVED_ID_PREFIX = "auto_";
+/** The agent id a role synthesizes to. */
+export declare function roleAgentId(roleId: string): string;
+/** Whether an id belongs to the reserved synthesized namespace. */
+export declare function isDerivedAgentId(id: string): boolean;

package/dist/agents/roles.js

@@ -0,0 +1,44 @@
+/**
+ * The closed role vocabulary for auto-decomposition (Phase 3.7).
+ *
+ * Auto-decomposition lets a goal produce agent steps with no operator-authored definition. The thing
+ * that makes it safe is what it does NOT do: no model-authored string ever becomes an objective, a tool
+ * id, or a permission. The model's only influence is choosing among the bounded agents offered to it —
+ * the same closed-set discipline `deriveCapabilitiesOffline` uses, applied to roles instead of ids.
+ *
+ * Every objective here is written in-tree by a human, because the objective is the one string that
+ * reaches the inner prompt UNFENCED (the step input beside it is fenced as untrusted). Every role is
+ * read-shaped, and adding a write-shaped one is a decision to record, not a line to slip in: the
+ * permission clamp would still deny it, but the catalog it is offered should not suggest otherwise.
+ */
+/** Three roles ship in 3.0.0. All read-shaped; see the header before adding a fourth. */
+export const AGENT_ROLES = [
+    {
+        id: 'investigate',
+        objective: 'Investigate the question you are given by reading the workspace. Report what you found as structured findings, each naming the file or symbol it is about. Do not modify anything.',
+        description: 'reads the workspace to answer a question, and reports findings',
+        outputContract: { types: ['observation'], maxFindings: 5, requireSubject: true },
+    },
+    {
+        id: 'verify',
+        objective: 'Check the specific claim you are given against the workspace. Report whether it holds, as structured findings that name what you checked. Do not modify anything.',
+        description: 'checks a specific claim against the workspace and reports whether it holds',
+        outputContract: { types: ['verification'], maxFindings: 5, requireSubject: true },
+    },
+    {
+        id: 'survey',
+        objective: 'Survey the area you are given and describe what is there: the files, their roles, and how they relate. Report structured findings. Do not modify anything.',
+        description: 'describes the shape of an area of the workspace',
+        outputContract: { types: ['survey'], maxFindings: 5, requireSubject: true },
+    },
+];
+/** The id prefix reserved for synthesized agents, so one can never collide with an authored id. */
+export const DERIVED_ID_PREFIX = 'auto_';
+/** The agent id a role synthesizes to. */
+export function roleAgentId(roleId) {
+    return `${DERIVED_ID_PREFIX}${roleId}`;
+}
+/** Whether an id belongs to the reserved synthesized namespace. */
+export function isDerivedAgentId(id) {
+    return id.startsWith(DERIVED_ID_PREFIX);
+}

package/dist/agents/synthesize.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Synthesizing agents from the registry (Phase 3.7) — auto-decomposition.
+ *
+ * THE TOOL SET IS THE WHOLE PROBLEM. A capability's providers are NAMESPACED ids (`tool:filesystem`)
+ * while the tool registry holds bare ones (`filesystem`), and `narrowEnvelope` intersects against the
+ * bare set. Emitting provider ids directly yields an empty catalog for every derived agent — a feature
+ * that is inert while looking correct, and whose obvious tests ("a derived agent cannot name a tool
+ * outside the registry") pass vacuously on the empty array. So the prefix is stripped here, membership
+ * in the parent catalog is asserted here, and the tests assert a NON-EMPTY result.
+ *
+ * WHAT IS NOT USED: BM25 relevance. It was measured to abstain on exactly the goals these roles exist
+ * for — "review the changed files", "find the bug", "audit the auth module" all derive nothing, because
+ * its thresholds were tuned for a different job (advisory capability hints, where a false positive
+ * merely over-advises). Gating whether an agent EXISTS on that calibration would make decomposition a
+ * silent no-op for the goals it is for. Roles are offered whenever they have tools; which one fits the
+ * goal is the planner's judgment, made from the role descriptions, which is exactly its job.
+ */
+import type { AgentRole } from './roles.js';
+import type { AgentDefinition } from './definition.js';
+export interface DerivedAgent {
+    id: string;
+    roleId: string;
+    definition: AgentDefinition;
+}
+export interface SynthesizeInput {
+    /** Every capability the registry knows, with its effects and providers. */
+    capabilities: Array<{
+        id: string;
+        effects: readonly string[];
+        providers: string[];
+    }>;
+    /** The tool ids the parent actually holds — the set `narrowEnvelope` will intersect against. */
+    parentTools: string[];
+    roles?: readonly AgentRole[];
+}
+/**
+ * Offer one bounded agent per role that has at least one usable tool.
+ *
+ * A role draws the parent's tools that provide at least one READ-effect capability. Effects are
+ * advisory metadata and never authorization (invariant 25) — the permission clamp in `narrowEnvelope`
+ * is what actually denies writing. Using them here only NARROWS what a machine-generated agent is
+ * offered, which fails safe: a tool with no declared effects is inferred write-shaped and excluded.
+ */
+export declare function synthesizeAgents(input: SynthesizeInput): DerivedAgent[];