ai-runtime-engine 2.8.0 → 3.0.0

package/CHANGELOG.md

@@ -5,6 +5,97 @@ 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,
+`/agents` lists and stops them, `/status` surfaces work that is unfinished, and the lifecycle events
+they all read from are finally declared rather than cast. Additive: with `runtime.agents` absent no
+agent event is ever emitted, so the lane region never opens and run output is identical to 2.8.0.
+
+### Added
+
+- **Agent lifecycle event arms** — `agent.task.started`, `agent.task.progress`, `agent.task.completed`
+  on `RuntimeEvent`. Metadata only: ids, states and counts. `findings` is a COUNT, because a finding's
+  claim is agent-authored text and an event is the one surface a host may forward anywhere.
+- **`agent.task.progress` per inner wave**, plus one at plan end — bounded at waves + 1 per task, never
+  per inner step.
+- **A multi-lane display** (`src/cli/interactive/lanes.ts`) — one live row per concurrent agent, pure
+  and offline-testable: terminal width, colour and the animation tick are all parameters. Piped output,
+  `NO_COLOR` and dumb terminals get append-only transition lines instead of cursor movement.
+- **`/agents`** — list agent tasks with progress, spend and finding counts; **`/agents stop <id>`**
+  stops one, and reports every outcome including the ones that change nothing.
+- **`/status`** now names unfinished agent work, and says which task is waiting for an answer.
+- **`AgentTaskView`** + `agentTaskView()` — the public read shape. The record's persistence internals
+  (inner plan, inner observations, raw findings, diagnostics) stay internal.
+
+### Changed
+
+- **The event union's evolution contract is now documented**: a new arm is additive at runtime but
+  breaks an exhaustive `switch` at COMPILE time. Consumers must carry a default case. Arms added this
+  way are announced here.
+- `AgentTaskView` (2.8.0) — the read RESULT of `parseAgentTasks` — is renamed `AgentTasksRead`, freeing
+  the name for the per-task view above. 2.8.0 was never published, so no released consumer names it.
+
+### Fixed
+
+- **The agent events were a type lie.** Removing the `as never` cast made them *look* typed, but a
+  single object literal with a union-typed `type` compiles while carrying properties from every
+  constituent — so `agent.task.started` shipped four fields it does not declare. The emit now narrows to
+  one arm per branch, and a key-set test covers what the type system still cannot.
+- **`runId` was missing, then wrong.** The events carried none at all, and the fix left
+  `orchestrateRunners` with a positional tail whose resume call site stamped the execution id instead.
+  It is now a required field of an options object.
+- **`/agents stop` was cosmetic.** `AGENT_RESUMABLE` excludes `cancelled`, so a resume offered no record
+  for the stopped step and simply re-ran the agent — a second paid planning call after a human asked it
+  to stop. It also wedged an execution permanently when the stopped task held the pending slot, and
+  overwrote a concurrent writer's work.
+- `/quit` was reachable but absent from `/help`, alongside `/agents`. A test now asserts every command
+  is documented.
+
 ## [2.8.0] — 2026-09-05
 
 Agent work now **survives a crash**. Until this release an agent's progress existed only in memory: the
@@ -750,6 +841,8 @@ 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
 [2.6.0]: https://github.com/pavankhandelwal21/ai-runtime/releases/tag/v2.6.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/task.d.ts

@@ -92,6 +92,43 @@ export interface AgentTaskRecord {
 export declare const AGENT_TERMINAL: ReadonlySet<AgentTaskState>;
 /** States a persisted task may be resumed from. Exactly the complement of AGENT_TERMINAL. */
 export declare const AGENT_RESUMABLE: ReadonlySet<AgentTaskState>;
+/**
+ * The PUBLIC read shape of an agent task (Phase 3.6) — what a host or a status line needs to render
+ * progress, and nothing else.
+ *
+ * It exists so the record's internals are not frozen into the public API. `innerPlan`,
+ * `innerObservations`, `innerCheckpoint`, raw `findings` and `diagnostics` are all persistence detail:
+ * they change as the phase evolves, they carry agent-authored content, and a host that reached into
+ * them would break on the next schema version. This shape is counts, ids and states — safe to freeze.
+ */
+export interface AgentTaskView {
+    agentTaskId: string;
+    agentId: string;
+    stepId: string;
+    state: AgentTaskState;
+    innerSteps: {
+        total: number;
+        succeeded: number;
+    };
+    /** What the step reserved from the run's call budget, and what it has actually spent. */
+    callsReserved: number;
+    callsUsed: number;
+    toolCallsUsed: number;
+    /** How many findings were ADMITTED — never the findings themselves. */
+    findings: number;
+    /** Why a non-terminal task stopped, when it was stopped by something outside itself. */
+    interruption?: {
+        kind: 'crash' | 'pause' | 'parent-cancel';
+        at: number;
+    };
+    /** The question this task is waiting on, clamped. Present only while it is waiting. */
+    question?: string;
+    startedAt?: number;
+    endedAt?: number;
+    updatedAt: number;
+}
+/** Project a record onto the public view. The ONE place that mapping lives. */
+export declare function agentTaskView(record: AgentTaskRecord): AgentTaskView;
 /** One row per agent-task state. Read this table; never re-derive a projection at a call site. */
 export interface ProjectionRow {
     step: PlanStepStatus;

package/dist/agents/task.js

@@ -9,6 +9,7 @@
  * normal state and records WHY in `interruption`, so the reason is auditable without growing the
  * lifecycle.
  */
+import { flattenClamp } from '../util/flatten.js';
 /** Terminal agent-task states: reached once, never left. A commit may not move a task out of one. */
 export const AGENT_TERMINAL = new Set(['completed', 'failed', 'cancelled']);
 /** States a persisted task may be resumed from. Exactly the complement of AGENT_TERMINAL. */
@@ -20,6 +21,27 @@ export const AGENT_RESUMABLE = new Set([
     'waiting_for_clarification',
     'paused',
 ]);
+/** Project a record onto the public view. The ONE place that mapping lives. */
+export function agentTaskView(record) {
+    return {
+        agentTaskId: record.agentTaskId,
+        agentId: record.agentId,
+        stepId: record.stepId,
+        state: record.state,
+        innerSteps: record.innerSteps,
+        callsReserved: record.callsReserved,
+        callsUsed: record.callsUsed,
+        toolCallsUsed: record.toolCallsUsed,
+        findings: record.findings.length,
+        ...(record.interruption ? { interruption: { kind: record.interruption.kind, at: record.interruption.at } } : {}),
+        // The ONE untrusted string in this shape: model-authored, read back from a file some other
+        // version wrote, and rendered in a terminal. `.slice()` truncates but strips nothing.
+        ...(record.pendingInner ? { question: flattenClamp(record.pendingInner.question, 240) } : {}),
+        ...(record.startedAt !== undefined ? { startedAt: record.startedAt } : {}),
+        ...(record.endedAt !== undefined ? { endedAt: record.endedAt } : {}),
+        updatedAt: record.updatedAt,
+    };
+}
 export const AGENT_TASK_PROJECTION = {
     created: { step: 'pending', exec: 'running', reachableIn34: true },
     queued: { step: 'pending', exec: 'running', reachableIn34: true },

package/dist/agents/worker.d.ts

@@ -55,8 +55,11 @@ export interface AgentWorkerDeps {
         ref?: ArtifactRef;
         unavailable: boolean;
     };
+    /** Lifecycle notifications. `agent.task.progress` fires once per inner WAVE — never per inner step:
+     *  the inner executor runs one step at a time, so per-step would emit one event per step and a chatty
+     *  agent would push every other event out of the emitter's ring buffer. */
     emit?: (event: {
-        type: 'agent.task.started' | 'agent.task.completed';
+        type: 'agent.task.started' | 'agent.task.progress' | 'agent.task.completed';
         record: AgentTaskRecord;
     }) => void;
     parentSignal?: AbortSignal;
@@ -66,11 +69,19 @@ export interface AgentWorkerDeps {
         executionId?: string;
         planVersion: number;
     };
+    /** Phase 3.6: hands the caller a way to stop THIS task specifically, for as long as it is running.
+     *  Without it the only lever is the run's own controller, which stops every agent at once. */
+    registerAbort?: (agentTaskId: string, abort: () => void) => void;
+    /** Phase 3.6: called when the task is no longer running, so the abort handle is not kept forever. */
+    releaseAbort?: (agentTaskId: string) => void;
     /** Phase 3.5: called whenever the record MATERIALLY changes, so inner progress reaches disk while the
      *  agent is still running. Without a seam inside the inner run, everything between `running` and
      *  `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

@@ -120,6 +120,7 @@ export async function runAgentTask(step, envelope, definition, deps) {
     const skillResults = [];
     const finish = (state, failure) => {
         deps.parentSignal?.removeEventListener('abort', onParentAbort);
+        deps.releaseAbort?.(record.agentTaskId);
         record.state = state;
         record.endedAt = deps.clock.now();
         record.updatedAt = record.endedAt;
@@ -165,6 +166,7 @@ export async function runAgentTask(step, envelope, definition, deps) {
     record.state = 'running';
     record.startedAt = deps.clock.now();
     record.updatedAt = record.startedAt;
+    deps.registerAbort?.(record.agentTaskId, () => child.abort());
     deps.emit?.({ type: 'agent.task.started', record });
     deps.onRecord?.(record);
     // (6) THE TOOL SEAM - defense in depth behind narrowEnvelope. Always a structured denial, never a
@@ -261,7 +263,15 @@ export async function runAgentTask(step, envelope, definition, deps) {
                 record.callsUsed = priorCalls + calls;
                 record.toolCallsUsed = priorToolCalls + toolCalls;
                 record.updatedAt = deps.clock.now();
+                record.innerSteps = { total: snap.plan.steps.length, succeeded: record.innerCompletedSteps.length };
                 deps.onRecord?.(record);
+                // One event per WAVE, plus one at the end. `wave-partition` fires BEFORE the wave runs, so on
+                // its own it reports the count from before — for a single-wave inner plan (the common case)
+                // that means the only progress event says 0/N, which is exactly what `started` already said,
+                // and a display would read 0/N until the task simply finished. `plan-end` fires once and is the
+                // only snapshot carrying the final count. Still not per-step: waves + 1 events per task.
+                if (snap.at === 'wave-partition' || snap.at === 'plan-end')
+                    deps.emit?.({ type: 'agent.task.progress', record });
             },
             runSkill: async (id, i) => {
                 const out = await deps.runSkill(id, i, { permissions: envelope.permissions, signal: child.signal, ai: metered });
@@ -362,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.8.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/cli/interactive/repl.js

@@ -13,6 +13,7 @@ import { print, printChunk, printError } from '../render.js';
 import { summarizeWorkspace } from '../../runtime/workspace/workspace.js';
 import { ReplSession, SLASH_COMMANDS } from './session.js';
 import { makeCompleter } from './complete.js';
+import { LaneSet, laneLines, frameDiff, frameRows } from './lanes.js';
 import { colorEnabled, bold, cyan, dim, gray, SPINNER_FRAMES, statusLine, clearLine } from './ansi.js';
 function banner(rt, colors) {
     const ws = rt.workspaceInfo();
@@ -96,6 +97,22 @@ export async function startRepl(configPath) {
     };
     let streamedThisRun = false;
     let spinner;
+    // Phase 3.6: concurrent agent steps render as live lanes. The region opens on the first agent event —
+    // long after the spinner has been stopped by the very first event of the run — so the two never own
+    // the cursor at the same time. With agents disabled no agent event is ever emitted, so the region
+    // never opens and output is byte-identical.
+    const lanes = new LaneSet();
+    let laneRows = 0;
+    let laneTick = 0;
+    // A late event — one arriving after the run has already returned — must not open a region on top of
+    // the prompt and leave `laneRows` set for the NEXT run's cursor arithmetic to walk into.
+    let runInFlight = false;
+    const closeLanes = () => {
+        if (laneRows > 0)
+            printChunk(frameDiff(laneRows, [], colors));
+        laneRows = 0;
+        lanes.clear();
+    };
     // Live progress + token streaming. Events are already redacted; a throwing observer can't break a run.
     rt.on((e) => {
         spinner?.stop(); // any event means work has started producing output — drop the spinner first
@@ -104,6 +121,30 @@ export async function startRepl(configPath) {
             streamedThisRun = true;
             return;
         }
+        const lane = lanes.observe(e);
+        if (lane) {
+            if (!runInFlight)
+                return; // see `runInFlight`
+            laneTick += 1;
+            if (colors) {
+                // The region must fit the viewport: `cursorUp` saturates at row 0, so a frame taller than the
+                // pane can never walk back to its own top and would redraw itself downward forever.
+                const budget = Math.max(1, (process.stdout.rows || 24) - 2);
+                const all = lanes.list();
+                const shown = all.length > budget ? all.slice(0, budget - 1) : all;
+                const lines = laneLines(shown, { cols: process.stdout.columns || 80, colors, tick: laneTick });
+                if (all.length > shown.length)
+                    lines.push(dim(`  … ${all.length - shown.length} more agent task(s)`, colors));
+                printChunk(frameDiff(laneRows, lines, colors));
+                laneRows = frameRows(lines);
+            }
+            else if (e.type !== 'agent.task.progress') {
+                // Piped, NO_COLOR or a dumb terminal: cursor games would be garbage in a log file, so report
+                // the transitions append-only instead. Progress ticks are dropped — in a log they are noise.
+                print(`  · agent ${lane.agentId} @ ${lane.stepId}: ${lane.state}`);
+            }
+            return;
+        }
         const line = progressLine(e, colors);
         if (line)
             print(line);
@@ -125,18 +166,29 @@ export async function startRepl(configPath) {
         let result;
         streamedThisRun = false;
         spinner = startSpinner(colors);
+        runInFlight = true;
+        // Readline keeps echoing keypresses while the handler awaits, and the cursor sits inside the lane
+        // region — so a keystroke mid-run writes into the frame and its clear-to-end-of-screen erases the
+        // rows below it. Pausing buffers the input instead; it is resumed on both exits below.
+        rl.pause();
         try {
             result = await session.handle(line);
         }
         catch (err) {
+            runInFlight = false;
+            rl.resume();
             spinner.stop();
+            closeLanes();
             if (streamedThisRun)
                 process.stdout.write('\n');
             printError(`error: ${err instanceof Error ? err.message : String(err)}`);
             rl.prompt();
             continue;
         }
+        runInFlight = false;
+        rl.resume();
         spinner.stop();
+        closeLanes(); // hand the cursor back before any result line is printed
         if (streamedThisRun)
             process.stdout.write('\n'); // close the streamed line before printing result lines
         if (result.clear)

package/dist/cli/interactive/session.d.ts

@@ -11,7 +11,10 @@ export interface HandleResult {
     clear?: boolean;
 }
 /** Top-level slash commands, for REPL tab-completion (Phase 21b). Kept in sync with the `handle` dispatch. */
-export declare const SLASH_COMMANDS: readonly ["help", "status", "info", "doctor", "cleanup", "mode", "compare", "models", "config", "providers", "tools", "capabilities", "mcp", "skills", "memory", "conversations", "executions", "resume", "resume-execution", "pause", "cancel", "approve", "deny", "learning", "feedback", "permissions", "budget", "stream", "dry-run", "clear", "exit", "quit"];
+export declare const SLASH_COMMANDS: readonly ["help", "status", "info", "doctor", "cleanup", "mode", "compare", "models", "config", "providers", "tools", "capabilities", "mcp", "skills", "memory", "conversations", "executions", "agents", "resume", "resume-execution", "pause", "cancel", "approve", "deny", "learning", "feedback", "permissions", "budget", "stream", "dry-run", "clear", "exit", "quit"];
+/** Exported so a test can prove every reachable command is documented — the three touch points below
+ *  are synced by hand, and `/agents` shipped tab-completable but absent from this list. */
+export declare const HELP: string[];
 export declare class ReplSession {
     private readonly runtime;
     private mode;
@@ -36,6 +39,10 @@ export declare class ReplSession {
     private learning;
     private permissions;
     private conversationsList;
+    /** Agent tasks across this project's executions, newest first. */
+    private agentsList;
+    /** Stop one agent task. Every outcome is reported — a stop that looks like nothing happened is a bug. */
+    private agentStop;
     private executionsList;
     private resumeExecution;
     private resume;