ai-runtime-engine 2.9.0 → 3.0.0

package/CHANGELOG.md

@@ -5,6 +5,50 @@ All notable changes to `ai-runtime` are documented here. The format follows
 Versioning](https://semver.org/). Development history and rationale live in
 [docs/DECISIONS.md](docs/DECISIONS.md) and [docs/PROGRESS.md](docs/PROGRESS.md).
 
+## [3.0.0] — 2026-09-05
+
+**AI Runtime 3.0.** The 3.x arc set out to make the runtime reason about *what it can do*, talk to tools
+it did not ship with, delegate bounded work to agents, and survive being killed in the middle of it.
+That is now true end to end, and `tests/integration/runtime-3-demo.test.ts` runs the whole of it —
+derive, decompose, delegate, crash, resume — offline, inside a call budget, with a leak scan.
+
+Upgrading from 2.9.0 requires no config change. One documented default changes; see below.
+
+### Added
+
+- **Auto-decomposition** (`runtime.agents.decompose`, default OFF) — a goal can delegate to a bounded,
+  read-shaped agent with no operator-authored definition. Three roles ship in-tree; no model-authored
+  string ever becomes an objective, a tool id, or a permission, and `auto_` is a reserved config
+  namespace so a derived id can never shadow an authored one.
+- **Conflict supersession is wired.** `resolveConflicts` shipped in 3.4 with no caller, so two agents
+  reaching opposite conclusions about the same subject both stayed active and both reached the next
+  planning prompt. Resolution now runs when a task finishes, weighs evidence-based confidence, and
+  persists — and it is order-independent, so the answer does not depend on which agent happens to
+  finish first.
+
+### Changed
+
+- **`runtime.capabilities.catalog` now defaults to ON.** Set `catalog: false` to remove the block.
+  Before flipping it, the block was made to match its own documentation: three comments across three
+  files described it as fenced when nothing fenced it, and its blocked-skill half had no cap at all
+  (~24k characters with 300 blocked skills, silently, in every prompt). Both are fixed.
+
+### Fixed
+
+- **A throwing agent took down the whole run.** `executor.ts` returned the agent runner's promise from
+  inside a `try` — and an async function *adopts* a returned promise rather than awaiting it, so the
+  rejection escaped the executor's own catch. The plan failed instead of the step, and wave-mates were
+  left running unawaited. Present since 2.7.0.
+- Derived permissions are a ceiling rather than a default, so a synthesized definition cannot request
+  write access even when the parent has it.
+
+### Notes for consumers
+
+- The `RuntimeEvent` union gained agent arms in 2.9.0 and may gain more. New arms are additive at
+  runtime but break an exhaustive `switch` at compile time — carry a default case.
+- `capabilities.planning` is skipped whenever any call or cost budget is set, and a resumed run is
+  never re-derived. Both are deliberate and now asserted by tests rather than only documented.
+
 ## [2.9.0] — 2026-09-05
 
 Agent work becomes VISIBLE. Concurrent agent steps render as live lanes in the interactive terminal,
@@ -797,6 +841,7 @@ Initial release: the provider-agnostic AI **router** — capability-based routin
 scoring, evidence validation, fallback, health tracking, learning-based scoring, multi-model verification,
 budgets, MCP tools, OpenAPI-based adapter generation, and the `AI` class + CLI.
 
+[3.0.0]: https://github.com/pavankhandelwal21/ai-runtime/releases/tag/v3.0.0
 [2.9.0]: https://github.com/pavankhandelwal21/ai-runtime/releases/tag/v2.9.0
 [2.8.0]: https://github.com/pavankhandelwal21/ai-runtime/releases/tag/v2.8.0
 [2.7.0]: https://github.com/pavankhandelwal21/ai-runtime/releases/tag/v2.7.0

package/README.md

@@ -80,10 +80,40 @@ You describe *what you want*; the runtime picks *which model* runs it. A few ide
   stateless mode).
 - **Add your own skills** — drop a manifest into `.ai-runtime/skills/`, or install a skill pack from npm.
 - **Steer routing** — hard-`exclude` or soft-`prefer` providers/models via config, per-run, or env vars.
+- **Connect MCP servers** — `mcp:` in the config brings a server's tools in as ordinary permission-gated
+  tools, deny-by-default per server. `ai-runtime mcp` and `/mcp` show what is connected.
+- **Delegate to agents** — a plan step can hand bounded work to an agent with its own narrowed catalog,
+  permissions and budget, which reports back structured findings. `/agents` lists them; `/agents stop`
+  stops one. Turn it on with `runtime.agents.enabled`.
+- **Survive a crash mid-run** — agent progress is committed as it happens, so resuming finishes the job
+  instead of redoing it. `ai-runtime resume-execution <id>`.
 - Everything that acts is **permission-gated and workspace-jailed** (see [Safety](#safety)).
 
 ---
 
+## What's new in 3.0
+
+The 3.x arc made the runtime reason about *what it can do*, work with tools it didn't ship with, delegate
+bounded work, and survive being killed in the middle of it.
+
+- **Action capabilities** — the runtime knows it can `read_file` or `run_tests` independently of which
+  tool or skill provides it, and tells you what's missing when a goal needs something it hasn't got.
+- **MCP** — a zero-dependency client over stdio and streamable HTTP. Server tools become ordinary tools,
+  with per-server grants that are off until you say otherwise.
+- **Agents** — a third kind of plan step. An agent gets an envelope narrowed from the parent's catalog and
+  permissions, a call budget it cannot exceed, and an output contract its findings must satisfy. Approving
+  a plan shows you that envelope, because approving a delegation blind is approving a blank cheque.
+- **Durable agent work** — plan, inner steps, findings and spend are on disk before the next wave starts,
+  so a `kill -9` costs you the step in flight and nothing else.
+- **Auto-decomposition** (opt-in) — a goal can delegate to read-shaped agents nobody configured. The roles
+  and their objectives ship in-tree; nothing the model writes becomes an objective, a tool, or a
+  permission.
+
+Upgrading from 2.x needs no config change. One default moved: the capability catalog is now included in
+planning prompts — set `runtime.capabilities.catalog: false` to remove it.
+
+---
+
 ## Configuration
 
 Three places, and only these:

package/dist/agents/admit.d.ts

@@ -65,5 +65,13 @@ export declare function admitFindings(input: AdmitFindingsInput): AdmissionResul
  * 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.
+ *
+ * `emptyIsFailure: false` keeps the contract's SHAPE rules (types, cap, subject) while making "found
+ * nothing worth reporting" an ordinary outcome rather than a failure. Derived agents pass it: their
+ * contract is mandatory precisely so their output stays bounded, but none of the shipped tools emit
+ * `data.findings`, so requiring at least one finding would fail every derived task against the
+ * runtime's own toolset — a feature that cannot succeed out of the box.
  */
-export declare function contractFailed(result: AdmissionResult): boolean;
+export declare function contractFailed(result: AdmissionResult, opts?: {
+    emptyIsFailure?: boolean;
+}): boolean;

package/dist/agents/admit.js

@@ -121,9 +121,17 @@ function validateFinding(f) {
  * 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.
+ *
+ * `emptyIsFailure: false` keeps the contract's SHAPE rules (types, cap, subject) while making "found
+ * nothing worth reporting" an ordinary outcome rather than a failure. Derived agents pass it: their
+ * contract is mandatory precisely so their output stays bounded, but none of the shipped tools emit
+ * `data.findings`, so requiring at least one finding would fail every derived task against the
+ * runtime's own toolset — a feature that cannot succeed out of the box.
  */
-export function contractFailed(result) {
+export function contractFailed(result, opts = {}) {
     if (!result.contractDeclared)
         return false;
-    return result.contractViolated || result.admitted.length === 0;
+    if (result.contractViolated)
+        return true;
+    return opts.emptyIsFailure !== false && result.admitted.length === 0;
 }

package/dist/agents/envelope.d.ts

@@ -49,5 +49,26 @@ export interface NarrowEnvelopeInput {
         maxDurationMs: number;
         maxInnerCalls: number;
     };
+    /**
+     * Where the definition came from (Phase 3.7). `authored` keeps the 3.4 rule that an omitted field
+     * INHERITS the parent's reach — an operator wrote that definition, and omission is their choice.
+     * `derived` INVERTS it: an omitted field means nothing at all.
+     *
+     * The inversion lives here rather than in the synthesizer on purpose. If the synthesizer did the
+     * bounding, a forgotten field there would silently hand a machine-generated agent the parent's whole
+     * catalog and every permission — it would fail OPEN. Here, a synthesizer bug produces an agent that
+     * can do nothing: loud, and safe. There is still exactly one enforcement point.
+     */
+    provenance?: 'authored' | 'derived';
 }
+/**
+ * What a DERIVED agent may do: read, and reason about what it read. Every other dimension is explicitly
+ * `false` rather than absent, because `clampPermissions` treats an absent field as "inherit" — so an
+ * explicit denial is the only thing that actually denies. Writes remain the province of a definition a
+ * human wrote and an operator configured.
+ */
+export declare const DERIVED_PERMISSIONS: PermissionPolicy;
+/** Tighter ceilings for an agent nobody authored. A definition may still only lower them. */
+export declare const DERIVED_MAX_TOOL_CALLS = 8;
+export declare const DERIVED_MAX_INNER_CALLS = 2;
 export declare function narrowEnvelope(input: NarrowEnvelopeInput): AgentEnvelope;

package/dist/agents/envelope.js

@@ -15,6 +15,26 @@ 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;
+/**
+ * What a DERIVED agent may do: read, and reason about what it read. Every other dimension is explicitly
+ * `false` rather than absent, because `clampPermissions` treats an absent field as "inherit" — so an
+ * explicit denial is the only thing that actually denies. Writes remain the province of a definition a
+ * human wrote and an operator configured.
+ */
+export const DERIVED_PERMISSIONS = {
+    fsRead: true,
+    fsWrite: false,
+    shell: false,
+    shellAllowedCommands: [],
+    gitWrite: false,
+    gitCommit: false,
+    gitPush: false,
+    network: false,
+    mcp: { servers: {} },
+};
+/** Tighter ceilings for an agent nobody authored. A definition may still only lower them. */
+export const DERIVED_MAX_TOOL_CALLS = 8;
+export const DERIVED_MAX_INNER_CALLS = 2;
 /** 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));
@@ -25,17 +45,31 @@ export function narrowEnvelope(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)));
+    const derived = input.provenance === 'derived';
+    // A derived definition that names no tools gets NONE. An authored one inherits the parent's, which is
+    // the 3.4 behaviour and stays unchanged.
+    const tools = uniqSorted((def.tools ?? (derived ? [] : 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 allowedSkills = def.skills ? new Set(def.skills) : derived ? new Set() : 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);
+    // For a derived agent DERIVED_PERMISSIONS is a CEILING, not a default: the definition is clamped
+    // against it first, so even an explicit `fsWrite: true` in a synthesized definition cannot grant
+    // writing. Using it as a mere default would leave the guarantee resting on the synthesizer never
+    // setting the field — which is true today, and is exactly the kind of thing that stops being true.
+    const permissions = derived
+        ? clampPermissions(input.parentPermissions, clampPermissions(DERIVED_PERMISSIONS, def.permissions))
+        : clampPermissions(input.parentPermissions, def.permissions);
+    // MCP is the one non-boolean permission dimension, and its clamp is a PER-KEY minimum: an empty
+    // override map means "no opinion", i.e. inherit every server grant — the opposite of what an empty
+    // map reads like. So a derived agent's MCP access is set explicitly rather than clamped to nothing.
+    if (derived)
+        permissions.mcp = { servers: {} };
     // (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;
@@ -55,10 +89,10 @@ export function narrowEnvelope(input) {
         skills,
         permissions,
         // (4) Caps: a definition may only lower.
-        maxToolCalls: lowerOnly(defaults.maxToolCalls, def.maxToolCalls),
+        maxToolCalls: lowerOnly(derived ? Math.min(defaults.maxToolCalls, DERIVED_MAX_TOOL_CALLS) : 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),
+        reservation: lowerOnly(derived ? Math.min(defaults.maxInnerCalls, DERIVED_MAX_INNER_CALLS) : 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] } : {}),

package/dist/agents/finding.d.ts

@@ -72,8 +72,14 @@ export declare function executionCoverage(steps: PlanStep[]): number;
  */
 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.
+ * Resolve conflicts among 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.
+ *
+ * IDEMPOTENT AND TOTAL: pass the whole set every time, including findings already marked. The winner of
+ * each group is restored to `active`, so re-running over a set whose membership grew produces the same
+ * answer as running once over the final set. Resolving only the currently-`active` subset instead makes
+ * the outcome depend on the order results ARRIVE — and leaves `supersededBy` pointing at a finding that
+ * was itself later superseded, a chain nothing heals.
  */
 export declare function resolveConflicts(findings: Finding[]): Finding[];

package/dist/agents/finding.js

@@ -51,9 +51,15 @@ export function confidenceOf(ev, 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.
+ * Resolve conflicts among 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.
+ *
+ * IDEMPOTENT AND TOTAL: pass the whole set every time, including findings already marked. The winner of
+ * each group is restored to `active`, so re-running over a set whose membership grew produces the same
+ * answer as running once over the final set. Resolving only the currently-`active` subset instead makes
+ * the outcome depend on the order results ARRIVE — and leaves `supersededBy` pointing at a finding that
+ * was itself later superseded, a chain nothing heals.
  */
 export function resolveConflicts(findings) {
     const groups = new Map();
@@ -69,6 +75,11 @@ export function resolveConflicts(findings) {
             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];
+        // The winner is `active` by definition of having won — even if an earlier, smaller round had
+        // marked it a loser. This is what makes the function idempotent.
+        const top = out.get(winner.id);
+        top.status = 'active';
+        delete top.supersededBy;
         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;

package/dist/agents/worker.d.ts

@@ -79,6 +79,9 @@ export interface AgentWorkerDeps {
      *  `finish()` — the inner plan, every completed inner step, every inner model call — is lost to a
      *  crash, and the resume has nothing to skip. Synchronous; must not throw. */
     onRecord?: (record: AgentTaskRecord) => void;
+    /** Phase 3.7: this agent was SYNTHESIZED, not authored. Its output contract bounds what it may
+     *  report without obliging it to report anything. */
+    derived?: boolean;
     /** Phase 3.5: a persisted record to CONTINUE instead of minting a fresh one. The caller proves it
      *  belongs to THIS step by step-input hash before passing it. */
     resume?: AgentTaskRecord;

package/dist/agents/worker.js

@@ -372,7 +372,10 @@ export async function runAgentTask(step, envelope, definition, deps) {
     // 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)) {
+    // A DERIVED agent's contract bounds what it may report; it does not oblige it to report. Nothing in
+    // the shipped toolset emits `data.findings`, so demanding at least one would fail every derived task
+    // against the runtime's own tools — the feature would be unusable without a bespoke tool.
+    if (contractFailed(admission, { emptyIsFailure: !deps.derived })) {
         return finish('failed', { code: 'finding-contract', message: 'the agent did not satisfy its declared output contract' });
     }
     if (expired())

package/dist/cli/cli.js

@@ -21,7 +21,7 @@ import { mcpCommand, mcpAddCommand, mcpRemoveCommand, mcpEnableCommand, mcpTestC
 import { startRepl } from './interactive/repl.js';
 import { printError } from './render.js';
 const program = new Command();
-program.name('ai-runtime').description('Universal, provider-agnostic AI Runtime & Orchestration Platform').version('2.9.0');
+program.name('ai-runtime').description('Universal, provider-agnostic AI Runtime & Orchestration Platform').version('3.0.0');
 const configOpt = ['-c, --config <path>', 'path to an ai-runtime config file'];
 // Bare `ai-runtime` (no subcommand) opens the interactive terminal. `allowExcessArguments(false)` keeps
 // a mistyped subcommand (e.g. `ai-runtime porviders`) failing fast instead of silently opening the REPL.

package/dist/orchestration/orchestrator.d.ts

@@ -43,7 +43,8 @@ export interface OrchestrateInput {
     routing?: RoutingPreferences;
     /** Phase 22: run the phases that fit the call budget and pause resumably (vs. the default notify-and-wait). */
     partial?: boolean;
-    /** Phase 3.1: pre-rendered action-capability snapshot for the planner prompt (opt-in). */
+    /** Phase 3.1: pre-rendered, fenced action-capability snapshot for the planner prompt. Present by
+     *  default from 3.0.0; `runtime.capabilities.catalog: false` removes it. */
     capabilityCatalog?: string;
     /** Phase 3.3: pre-rendered "Required capabilities" block for the planner prompt (opt-in). */
     requiredCapabilities?: string;

package/dist/orchestration/planner.d.ts

@@ -18,7 +18,8 @@ export interface PlannerInput {
     reason?: string;
     /** Observations from a prior attempt, to inform a replan. */
     priorObservations?: string[];
-    /** Phase 3.1: a pre-rendered, capped, fenced action-capability snapshot. Absent ⇒ the prompt is
+    /** Phase 3.1: a pre-rendered, capped, fenced action-capability snapshot (fenced for real as of
+     *  3.0.0, and present by default from it). Absent ⇒ the prompt is
      *  byte-identical to 2.3.0 (the catalog flag is off by default). */
     capabilityCatalog?: string;
     /** Phase 3.3: a pre-rendered, clamped block naming the capabilities the goal was derived to need and

package/dist/runtime/config.js

@@ -40,7 +40,7 @@ const agentDefinition = z
     .strict();
 /** An agent definition id: the same prompt-safe shape an MCP server id must have. */
 const AGENT_ID_RE = /^[a-z0-9][a-z0-9_-]{0,32}$/;
-const runtimeSettings = z.object({ defaultMode: z.enum(RUNTIME_MODES).optional(), defaultStrategy: z.enum(STRATEGIES).optional(), context: z.object({ maxTokens: z.number().optional(), verifyLoss: z.boolean().optional(), summarize: z.boolean().optional() }).strict().optional(), skills: z.object({ paths: z.array(z.string()).optional(), packages: z.array(z.string()).optional(), autoload: z.boolean().optional() }).strict().optional(), embedding: z.object({ provider: z.enum(['local', 'openai-compatible']), baseUrl: z.string().optional(), apiKeyEnv: z.string().optional(), model: z.string().optional() }).strict().optional(), intent: z.object({ aiFallback: z.boolean().optional() }).strict().optional(), organization: z.string().optional(), storage: z.object({ encrypt: z.boolean(), keyEnv: z.string() }).strict().optional(), capabilities: z.object({ catalog: z.boolean().optional(), planning: z.boolean().optional(), aliases: z.record(z.string(), z.string()).optional(), pins: z.record(z.string(), z.string()).optional() }).strict().optional(), concurrency: z.object({ maxParallelSteps: z.number().optional(), perTool: z.record(z.string(), z.number()).optional(), perSkill: z.record(z.string(), z.number()).optional(), perProvider: z.record(z.string(), z.number()).optional(), perAgent: z.record(z.string(), z.number()).optional() }).strict().optional(), agents: z.object({ enabled: z.boolean().optional(), maxToolCalls: z.number().optional(), maxDurationMs: z.number().optional(), maxInnerCalls: z.number().optional(), definitions: z.record(z.string().regex(AGENT_ID_RE, 'an agent definition id must be lowercase kebab/snake (max 33 chars)'), agentDefinition).optional() }).strict().optional() }).strict();
+const runtimeSettings = z.object({ defaultMode: z.enum(RUNTIME_MODES).optional(), defaultStrategy: z.enum(STRATEGIES).optional(), context: z.object({ maxTokens: z.number().optional(), verifyLoss: z.boolean().optional(), summarize: z.boolean().optional() }).strict().optional(), skills: z.object({ paths: z.array(z.string()).optional(), packages: z.array(z.string()).optional(), autoload: z.boolean().optional() }).strict().optional(), embedding: z.object({ provider: z.enum(['local', 'openai-compatible']), baseUrl: z.string().optional(), apiKeyEnv: z.string().optional(), model: z.string().optional() }).strict().optional(), intent: z.object({ aiFallback: z.boolean().optional() }).strict().optional(), organization: z.string().optional(), storage: z.object({ encrypt: z.boolean(), keyEnv: z.string() }).strict().optional(), capabilities: z.object({ catalog: z.boolean().optional(), planning: z.boolean().optional(), aliases: z.record(z.string(), z.string()).optional(), pins: z.record(z.string(), z.string()).optional() }).strict().optional(), concurrency: z.object({ maxParallelSteps: z.number().optional(), perTool: z.record(z.string(), z.number()).optional(), perSkill: z.record(z.string(), z.number()).optional(), perProvider: z.record(z.string(), z.number()).optional(), perAgent: z.record(z.string(), z.number()).optional() }).strict().optional(), agents: z.object({ enabled: z.boolean().optional(), decompose: z.boolean().optional(), maxToolCalls: z.number().optional(), maxDurationMs: z.number().optional(), maxInnerCalls: z.number().optional(), definitions: z.record(z.string().regex(AGENT_ID_RE, 'an agent definition id must be lowercase kebab/snake (max 33 chars)').refine((id) => !id.startsWith('auto_'), 'the `auto_` prefix is reserved for agents the runtime derives — pick another id'), agentDefinition).optional() }).strict().optional() }).strict();
 const learning = z.object({ enabled: z.boolean().optional() }).strict();
 const verification = z.object({ enabled: z.boolean().optional() }).strict();
 const budget = z.object({ maxCostUsd: z.number().optional(), maxCalls: z.number().optional() }).strict();

package/dist/runtime/runtime.d.ts

@@ -178,6 +178,15 @@ export declare class Runtime {
      * This run's agent envelopes. THE ONLY call site of `narrowEnvelope` — never re-derive an inner
      * catalog, a permission clamp, or a reservation anywhere else (see the header of agents/envelope.ts).
      */
+    /**
+     * Agents synthesized from the registry for this goal (Phase 3.7). Empty unless
+     * `runtime.agents.decompose` is on — so with the flag off nothing about planning changes.
+     *
+     * Deterministic and offline: no model call, no clock, no randomness. That is a requirement, not a
+     * preference — a derived definition is hashed into `agentDefHash`, and a resume that synthesized
+     * even slightly differently would discard every persisted inner plan as stale.
+     */
+    private derivedAgents;
     private agentEnvelopes;
     /** The MCP server manager: `list()`, `status(id)`, `test(id)`, `addServer`, `removeServer`, `setEnabled`. */
     mcp(): McpManager;
@@ -299,9 +308,17 @@ export declare class Runtime {
      * skipped — no skill ran, so there is no success/failure to learn (recording them would teach noise). */
     private recordOrchestration;
     /**
-     * A capped, FENCED action-capability snapshot for the planner prompt (Phase 3.1, opt-in). Untrusted
-     * sources (anything not an in-tree builtin) have their descriptions fenced, and the block is bounded so
-     * a large catalog can never dominate the prompt.
+     * A capped, FENCED action-capability snapshot for the planner prompt (Phase 3.1; ON by default from
+     * 3.0.0 — set `runtime.capabilities.catalog: false` to remove it).
+     *
+     * The fence is real as of 3.0.0 and was not before: this block carries ids that come from MCP servers
+     * and third-party skills, and it renders them as trusted-looking prompt structure on every planning
+     * iteration of every run. Flattening (`promptSafe`) bounds their shape but says nothing about their
+     * provenance, so the whole block is wrapped as untrusted data. Three comments claimed "fenced" while
+     * no fence existed; shipping that ON by default would have made a false safety claim load-bearing.
+     *
+     * Both halves are bounded. The blocked-skill list had no cap at all — measured at ~24k characters
+     * with 300 blocked skills, silently, in every prompt.
      */
     private capabilityCatalogText;
     /** Any call/cost ceiling declared in the config file's `budget:` block (router-level, not policy). */
@@ -373,6 +390,26 @@ export declare class Runtime {
      * an agent step would have failed every one of those steps.
      */
     private orchestrateRunners;
+    /**
+     * Reconcile findings that contradict each other, across ALL of this execution's agent tasks
+     * (Phase 3.7).
+     *
+     * `resolveConflicts` has existed since 3.4 with no caller, so two agents reaching opposite
+     * conclusions about the same subject both stayed `active` — and both were rendered into the next
+     * planning prompt, as if the runtime had no opinion about which was better supported. It does: it
+     * weighs evidence-based `confidence`, with `executionCoverage` only as a tiebreak.
+     *
+     * Runs at the ONE point new findings can appear — a task reaching a terminal state — and writes the
+     * outcome back onto the owning records, so a supersession survives a restart rather than being
+     * recomputed (and possibly recomputed differently) on every read.
+     *
+     * EVERY finding is passed in, not just the active ones. Resolving over the active subset makes the
+     * result depend on the order tasks happen to finish: a finding that beat a weak rival in wave 1 can
+     * itself lose in wave 2, and the wave-1 loser is then left pointing at a superseded finding — a
+     * broken chain nothing heals. Re-resolving the whole set each round is order-independent and gives
+     * the same answer as one pass over the final set.
+     */
+    private resolveFindingConflicts;
     /**
      * A bounded, fenced brief of what the agents have already established (Phase 3.5).
      *

package/dist/runtime/runtime.js

@@ -55,6 +55,9 @@ import { ExecutionStore } from '../executions/store.js';
 import { RESUMABLE, TERMINAL } from '../executions/execution.js';
 import { captureCheckpoint, reconcile } from '../executions/checkpoint.js';
 import { AGENT_TERMINAL, AGENT_RESUMABLE, agentTaskView } from '../agents/task.js';
+import { synthesizeAgents } from '../agents/synthesize.js';
+import { isDerivedAgentId } from '../agents/roles.js';
+import { resolveConflicts } from '../agents/finding.js';
 import { parseAgentTasks } from '../executions/agentTasks.js';
 import { stepIdentity } from '../agents/worker.js';
 import { hashOf } from '../util/hash.js';
@@ -460,6 +463,12 @@ export class Runtime {
     registerAgent(id, def) {
         if (!/^[a-z0-9][a-z0-9_-]{0,32}$/.test(id))
             throw new AIError(`invalid agent id '${id}' — use lowercase letters, digits, '_' or '-' (max 33 chars)`, { category: 'CONFIG' });
+        // The same reservation the config schema enforces. Without it here, a host could register
+        // `auto_investigate` and — with decompose on — produce two catalog rows with one id, where the
+        // derived one wins both lookups and the SAME step resolves to a different envelope depending on a
+        // flag. Reserving a namespace in only one of its two doors reserves nothing.
+        if (isDerivedAgentId(id))
+            throw new AIError(`agent id '${id}' uses the reserved 'auto_' prefix — that namespace belongs to agents the runtime derives`, { category: 'CONFIG' });
         this.agentDefs.set(id, def);
         return this;
     }
@@ -471,13 +480,34 @@ export class Runtime {
      * This run's agent envelopes. THE ONLY call site of `narrowEnvelope` — never re-derive an inner
      * catalog, a permission clamp, or a reservation anywhere else (see the header of agents/envelope.ts).
      */
-    agentEnvelopes(policy) {
-        if (!this.agentsEnabled || this.agentDefs.size === 0)
+    /**
+     * Agents synthesized from the registry for this goal (Phase 3.7). Empty unless
+     * `runtime.agents.decompose` is on — so with the flag off nothing about planning changes.
+     *
+     * Deterministic and offline: no model call, no clock, no randomness. That is a requirement, not a
+     * preference — a derived definition is hashed into `agentDefHash`, and a resume that synthesized
+     * even slightly differently would discard every persisted inner plan as stale.
+     */
+    derivedAgents() {
+        if (!this.agentsEnabled || this.settingsValue.agents?.decompose !== true)
+            return [];
+        const capabilities = this._capabilities.list().map((c) => ({ id: c.id, effects: c.effects, providers: this._capabilities.providersOf(c.id).map((p) => p.providerId) }));
+        return synthesizeAgents({ capabilities, parentTools: this._tools.ids() });
+    }
+    agentEnvelopes(policy, derived = []) {
+        // Derived definitions are passed IN and never stored: `agentDefs` lives for the process, so writing
+        // a per-goal agent into it would leak that agent into every later run on this Runtime.
+        const entries = [
+            ...[...this.agentDefs].map(([id, d]) => [id, d, 'authored']),
+            ...derived.map((d) => [d.id, d.definition, 'derived']),
+        ];
+        if (!this.agentsEnabled || entries.length === 0)
             return [];
         const routing = this.effectiveRouting();
-        return [...this.agentDefs].map(([id, definition]) => narrowEnvelope({
+        return entries.map(([id, definition, provenance]) => narrowEnvelope({
             agentId: id,
             definition,
+            provenance,
             parentTools: this._tools.ids(),
             parentSkills: this.skills().map((sk) => ({ id: sk.id, ...(sk.tools ? { tools: sk.tools } : {}) })),
             parentPermissions: policy.permissions,
@@ -1028,6 +1058,10 @@ export class Runtime {
                     exec.completedSteps = [...exec.completedSteps, record.stepId];
                     checkpointIfMoved();
                 }
+                // A finished task is the only moment new findings can appear, so it is the only moment two of
+                // them can start disagreeing.
+                if (AGENT_TERMINAL.has(record.state))
+                    this.resolveFindingConflicts(exec);
                 commit();
             },
             /**
@@ -1070,9 +1104,10 @@ export class Runtime {
             ...(routing ? { routing } : {}),
             ...(partial ? { partial: true } : {}),
             ...(this.approval ? { approval: this.approval } : {}),
-            // Phase 3.1: the capability snapshot is opt-in (`runtime.capabilities.catalog`); the gap resolver is
-            // always on but only fires on a validation failure, adding metadata to an unchanged error.
-            ...(this.settingsValue.capabilities?.catalog ? { capabilityCatalog: this.capabilityCatalogText() } : {}),
+            // Phase 3.1, ON by default from 3.0.0 (`runtime.capabilities.catalog: false` removes it); the gap
+            // resolver is always on but only fires on a validation failure, adding metadata to an unchanged error.
+            // 3.0.0: ON by default. `catalog: false` removes it — the only way to get the 2.9.0 prompt back.
+            ...(this.settingsValue.capabilities?.catalog !== false ? { capabilityCatalog: this.capabilityCatalogText() } : {}),
             // Phase 3.3: the derived-requirement block (opt-in, pre-rendered + clamped). Absent ⇒ the
             // OrchestrateInput/PlannerInput objects are key-identical to 2.5.1.
             ...(requiredCapabilities ? { requiredCapabilities } : {}),
@@ -1102,11 +1137,19 @@ export class Runtime {
         this._learning.record({ goalType: this.goalType(goal), mode, ok: outcome.status === 'completed', skills: this.planSkillRefs(outcome.plan) });
     }
     /**
-     * A capped, FENCED action-capability snapshot for the planner prompt (Phase 3.1, opt-in). Untrusted
-     * sources (anything not an in-tree builtin) have their descriptions fenced, and the block is bounded so
-     * a large catalog can never dominate the prompt.
+     * A capped, FENCED action-capability snapshot for the planner prompt (Phase 3.1; ON by default from
+     * 3.0.0 — set `runtime.capabilities.catalog: false` to remove it).
+     *
+     * The fence is real as of 3.0.0 and was not before: this block carries ids that come from MCP servers
+     * and third-party skills, and it renders them as trusted-looking prompt structure on every planning
+     * iteration of every run. Flattening (`promptSafe`) bounds their shape but says nothing about their
+     * provenance, so the whole block is wrapped as untrusted data. Three comments claimed "fenced" while
+     * no fence existed; shipping that ON by default would have made a false safety claim load-bearing.
+     *
+     * Both halves are bounded. The blocked-skill list had no cap at all — measured at ~24k characters
+     * with 300 blocked skills, silently, in every prompt.
      */
-    capabilityCatalogText(maxEntries = 40) {
+    capabilityCatalogText(maxEntries = 40, maxBlocked = 15) {
         const caps = this._capabilities.list();
         if (caps.length === 0)
             return '';
@@ -1116,17 +1159,21 @@ export class Runtime {
                 .providersOf(c.id)
                 .map((p) => `${promptSafe(p.providerId)}${p.availability === 'available' ? '' : ` (${p.availability})`}`)
                 .join(', ');
-            lines.push(`  - capability "${promptSafe(c.id)}" [${c.effects.join('/')}] → ${promptSafe(providers, 200)}`);
+            // Every segment is clamped, `effects` included: it is an array off a declaration, so a hostile or
+            // simply careless source can make one row arbitrarily long.
+            lines.push(`  - capability "${promptSafe(c.id)}" [${promptSafe(c.effects.join('/'), 40)}] → ${promptSafe(providers, 200)}`);
         }
         const more = caps.length > maxEntries ? `\n  …and ${caps.length - maxEntries} more (see /capabilities)` : '';
         // Skills hidden by a missing tool — the "why can't you do this" answer the planner needs.
         const usable = new Set(this.skills().map((sk) => sk.id));
-        const blocked = this._skills
-            .list()
-            .filter((sk) => !usable.has(sk.id))
+        const blockedAll = this._skills.list().filter((sk) => !usable.has(sk.id));
+        const blocked = blockedAll
+            .slice(0, maxBlocked)
             .map((sk) => `  - skill "${promptSafe(sk.id)}" needs tool(s) ${promptSafe((sk.tools ?? []).filter((t) => !this._tools.ids().includes(t)).join(', '), 200)} (not registered)`);
-        const unavailable = blocked.length ? `\nUnavailable (do not use):\n${blocked.join('\n')}` : '';
-        return `Action capabilities:\n${lines.join('\n')}${more}${unavailable}`;
+        const blockedMore = blockedAll.length > maxBlocked ? `\n  …and ${blockedAll.length - maxBlocked} more` : '';
+        const unavailable = blocked.length ? `\nUnavailable (do not use):\n${blocked.join('\n')}${blockedMore}` : '';
+        // The ids inside come from MCP servers and third-party skills. Fenced as data, not structure.
+        return wrapUntrusted('capability-catalog', `Action capabilities:\n${lines.join('\n')}${more}${unavailable}`);
     }
     /** Any call/cost ceiling declared in the config file's `budget:` block (router-level, not policy). */
     configBudget() {
@@ -1503,8 +1550,12 @@ export class Runtime {
      */
     orchestrateRunners(policy, opts) {
         const { runId, signal, provenance, onRecord, agentResume } = opts;
-        const envelopes = policy ? this.agentEnvelopes(policy) : [];
+        const derived = this.derivedAgents();
+        const envelopes = policy ? this.agentEnvelopes(policy, derived) : [];
         const byId = new Map(envelopes.map((e) => [e.agentId, e]));
+        // Definitions come from a LOCAL map, not the process-lifetime field: a derived agent exists for
+        // this run only, and must not be findable by any later one.
+        const defsById = new Map([...this.agentDefs, ...derived.map((d) => [d.id, d.definition])]);
         return {
             runSkill: (skillId, input) => this.runSkill(skillId, input).then((o) => ({ result: o.result, validation: o.validation })),
             runTool: (toolId, input) => this.runTool(toolId, input),
@@ -1514,13 +1565,14 @@ export class Runtime {
                     reserve: (step) => (step.agent ? byId.get(step.agent)?.reservation ?? 1 : 0),
                     runAgent: async (step, ctx) => {
                         const envelope = byId.get(step.agent ?? '');
-                        const definition = this.agentDefs.get(step.agent ?? '');
+                        const definition = defsById.get(step.agent ?? '');
                         if (!envelope || !definition)
                             return { stepId: step.id, ok: false, code: 'agent-not-enabled', error: `no agent definition '${step.agent ?? ''}'` };
                         const innerSkills = this._skills.list().filter((sk) => envelope.skills.includes(sk.id));
                         // Phase 3.5: continue a persisted task for THIS step, if one exists.
                         const prior = agentResume?.(step);
                         const out = await runAgentTask(step, envelope, definition, {
+                            ...(derived.some((d) => d.id === step.agent) ? { derived: true } : {}),
                             ...(prior?.record ? { resume: prior.record } : {}),
                             ...(prior?.answer ? { resumeAnswer: prior.answer } : {}),
                             ai: this._ai,
@@ -1579,6 +1631,52 @@ export class Runtime {
                 : {}),
         };
     }
+    /**
+     * Reconcile findings that contradict each other, across ALL of this execution's agent tasks
+     * (Phase 3.7).
+     *
+     * `resolveConflicts` has existed since 3.4 with no caller, so two agents reaching opposite
+     * conclusions about the same subject both stayed `active` — and both were rendered into the next
+     * planning prompt, as if the runtime had no opinion about which was better supported. It does: it
+     * weighs evidence-based `confidence`, with `executionCoverage` only as a tiebreak.
+     *
+     * Runs at the ONE point new findings can appear — a task reaching a terminal state — and writes the
+     * outcome back onto the owning records, so a supersession survives a restart rather than being
+     * recomputed (and possibly recomputed differently) on every read.
+     *
+     * EVERY finding is passed in, not just the active ones. Resolving over the active subset makes the
+     * result depend on the order tasks happen to finish: a finding that beat a weak rival in wave 1 can
+     * itself lose in wave 2, and the wave-1 loser is then left pointing at a superseded finding — a
+     * broken chain nothing heals. Re-resolving the whole set each round is order-independent and gives
+     * the same answer as one pass over the final set.
+     */
+    resolveFindingConflicts(exec) {
+        const { tasks } = parseAgentTasks(exec);
+        const all = tasks.flatMap((t) => t.findings);
+        if (all.length < 2)
+            return;
+        const resolved = new Map(resolveConflicts(all).map((f) => [f.id, f]));
+        let changed = false;
+        const next = tasks.map((t) => {
+            const findings = t.findings.map((f) => {
+                const r = resolved.get(f.id);
+                if (!r || (r.status === f.status && r.supersededBy === f.supersededBy))
+                    return f;
+                changed = true;
+                const next = { ...f, status: r.status };
+                if (r.supersededBy)
+                    next.supersededBy = r.supersededBy;
+                else
+                    delete next.supersededBy;
+                return next;
+            });
+            return changed ? { ...t, findings } : t;
+        });
+        if (!changed)
+            return;
+        const byId = new Map(next.map((t) => [t.agentTaskId, t]));
+        exec.agentTasks = (exec.agentTasks ?? []).map((entry) => byId.get(entry.agentTaskId ?? '') ?? entry);
+    }
     /**
      * A bounded, fenced brief of what the agents have already established (Phase 3.5).
      *

package/dist/runtime/types.d.ts

@@ -120,6 +120,12 @@ export interface RuntimeSettings {
      *  the worker's hard inner-model-call ceiling. */
     agents?: {
         enabled?: boolean;
+        /** Phase 3.7, default OFF: offer the goal a bounded, read-shaped agent per shipped ROLE, with no
+         *  operator-authored definition. The roles and their objectives are in-tree; nothing the model
+         *  writes becomes an objective, a tool id or a permission.
+         *
+         *  REQUIRES `enabled: true` — on its own this does nothing, because agent execution is off. */
+        decompose?: boolean;
         maxToolCalls?: number;
         maxDurationMs?: number;
         maxInnerCalls?: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-runtime-engine",
-  "version": "2.9.0",
+  "version": "3.0.0",
   "description": "AI Runtime \u2014 a provider-agnostic AI runtime and orchestration platform. Point it at whatever AI providers you have; it routes each task to the best available model. Ships the `ai-runtime` CLI and the `Runtime`/`AI` library API.",
   "type": "module",
   "license": "ISC",