ai-runtime-engine 1.3.0 → 2.7.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/task.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Agent task state (Phase 3.4) - the record, and THE PROJECTION TABLE.
+ *
+ * The state set is the PRD's; no state is invented here. Every one of them projects onto the EXISTING
+ * PlanStepStatus / ExecutionStatus vocabularies, and that is deliberate: 3.4 adds no new status
+ * anywhere, which is what stops a later phase from needing one.
+ *
+ * An INTERRUPTION IS NOT A STATE. A crash, a parent pause, or a parent cancel leaves the task in a
+ * normal state and records WHY in `interruption`, so the reason is auditable without growing the
+ * lifecycle.
+ */
+import type { PlanStepStatus } from '../orchestration/plan.js';
+import type { StepObservationCode } from '../orchestration/executor.js';
+import type { ExecutionStatus } from '../executions/execution.js';
+import type { AdmissionRejection } from './admit.js';
+import type { Finding } from './finding.js';
+export type AgentTaskState = 'created' | 'queued' | 'running' | 'completed' | 'failed' | 'cancelled' | 'waiting_for_input' | 'waiting_for_clarification' | 'paused';
+export interface AgentTaskRecord {
+    /** `ag_<base36 now>_<counter>`. `agentTaskId`, NEVER `taskId` - that name belongs to the router. */
+    agentTaskId: string;
+    agentId: string;
+    stepId: string;
+    state: AgentTaskState;
+    createdAt: number;
+    startedAt?: number;
+    endedAt?: number;
+    /** Additive, and NOT a state. Carries why a non-terminal task stopped. */
+    interruption?: {
+        kind: 'crash' | 'pause' | 'parent-cancel';
+        at: number;
+        detail?: string;
+    };
+    innerPlanVersion?: number;
+    innerSteps: {
+        total: number;
+        succeeded: number;
+    };
+    callsUsed: number;
+    toolCallsUsed: number;
+    findings: Finding[];
+    /** Candidates the admission pipeline REFUSED. Auditable, and never threaded anywhere. */
+    diagnostics: AdmissionRejection[];
+    failure?: {
+        code: StepObservationCode;
+        message: string;
+    };
+}
+/** One row per agent-task state. Read this table; never re-derive a projection at a call site. */
+export interface ProjectionRow {
+    step: PlanStepStatus;
+    exec: ExecutionStatus;
+    code?: StepObservationCode;
+    /** False for the states only a persisted, resumable task can reach (Phase 3.5). */
+    reachableIn34: boolean;
+}
+export declare const AGENT_TASK_PROJECTION: Readonly<Record<AgentTaskState, ProjectionRow>>;
+/** The states an agent task can actually reach in 3.4. */
+export declare const REACHABLE_IN_34: AgentTaskState[];
+/** Mint an agent task id. Base36 clock + a counter, so ids are stable under a fake clock. */
+export declare function nextAgentTaskId(now: number): string;

package/dist/agents/task.js

@@ -0,0 +1,32 @@
+/**
+ * Agent task state (Phase 3.4) - the record, and THE PROJECTION TABLE.
+ *
+ * The state set is the PRD's; no state is invented here. Every one of them projects onto the EXISTING
+ * PlanStepStatus / ExecutionStatus vocabularies, and that is deliberate: 3.4 adds no new status
+ * anywhere, which is what stops a later phase from needing one.
+ *
+ * An INTERRUPTION IS NOT A STATE. A crash, a parent pause, or a parent cancel leaves the task in a
+ * normal state and records WHY in `interruption`, so the reason is auditable without growing the
+ * lifecycle.
+ */
+export const AGENT_TASK_PROJECTION = {
+    created: { step: 'pending', exec: 'running', reachableIn34: true },
+    queued: { step: 'pending', exec: 'running', reachableIn34: true },
+    running: { step: 'running', exec: 'running', reachableIn34: true },
+    completed: { step: 'succeeded', exec: 'completed', reachableIn34: true },
+    failed: { step: 'failed', exec: 'failed', code: 'agent-failed', reachableIn34: true },
+    cancelled: { step: 'skipped', exec: 'cancelled', code: 'cancelled', reachableIn34: true },
+    // Declared, not reachable in 3.4: nothing persists an AgentTaskRecord yet, so nothing can be resumed
+    // into a waiting state. The rows exist so 3.5 inherits a mapping instead of inventing one.
+    waiting_for_input: { step: 'pending', exec: 'waiting_for_input', reachableIn34: false },
+    waiting_for_clarification: { step: 'pending', exec: 'waiting_for_clarification', reachableIn34: false },
+    paused: { step: 'pending', exec: 'paused', reachableIn34: false },
+};
+/** The states an agent task can actually reach in 3.4. */
+export const REACHABLE_IN_34 = Object.keys(AGENT_TASK_PROJECTION).filter((s) => AGENT_TASK_PROJECTION[s].reachableIn34);
+let counter = 0;
+/** Mint an agent task id. Base36 clock + a counter, so ids are stable under a fake clock. */
+export function nextAgentTaskId(now) {
+    counter += 1;
+    return `ag_${now.toString(36)}_${counter.toString(36)}`;
+}