ai-runtime-engine 2.8.0 → 3.0.0

package/dist/cli/interactive/session.js

@@ -13,13 +13,17 @@ import { actionCapabilityRows, renderActionCapabilities, renderCapabilityGaps }
 import { renderMcpList, renderMcpDetail } from '../commands/mcp.js';
 import { candidatesFrom, deriveCapabilitiesOffline } from '../../runtime/planning/deriveCapabilities.js';
 import { displaySafe } from '../render.js';
+import { AGENT_TERMINAL } from '../../agents/task.js';
+import { TERMINAL as EXEC_TERMINAL } from '../../executions/execution.js';
 /** Top-level slash commands, for REPL tab-completion (Phase 21b). Kept in sync with the `handle` dispatch. */
 export const SLASH_COMMANDS = [
     'help', 'status', 'info', 'doctor', 'cleanup', 'mode', 'compare', 'models', 'config', 'providers', 'tools', 'capabilities', 'mcp',
-    'skills', 'memory', 'conversations', 'executions', 'resume', 'resume-execution', 'pause', 'cancel', 'approve',
+    'skills', 'memory', 'conversations', 'executions', 'agents', 'resume', 'resume-execution', 'pause', 'cancel', 'approve',
     'deny', 'learning', 'feedback', 'permissions', 'budget', 'stream', 'dry-run', 'clear', 'exit', 'quit',
 ];
-const HELP = [
+/** 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 const HELP = [
     'Commands:',
     '  /help                       show this help',
     '  /status                     workspace, mode, provider count',
@@ -49,6 +53,8 @@ const HELP = [
     '  /conversations              list recent conversations',
     '  /resume <id>                resume a conversation',
     '  /executions                 list persisted executions',
+    '  /agents                     list agent tasks (state, progress, spend, findings)',
+    '  /agents stop <id>           stop one agent task',
     '  /resume-execution <id>      resume an execution',
     '  /approve <id>               approve an execution waiting for approval, then continue',
     '  /deny <id>                  deny an execution waiting for approval (cancels it)',
@@ -59,7 +65,7 @@ const HELP = [
     '  /stream                     toggle token-by-token streaming of answers',
     '  /budget                     show the call/cost budget (AI_MAX_CALLS / AI_MAX_COST_USD)',
     '  /clear                      clear the screen',
-    '  /exit                       leave the session',
+    '  /exit, /quit                leave the session',
     '',
     'Anything else is sent to the runtime as a request.',
 ];
@@ -209,6 +215,8 @@ export class ReplSession {
                 return this.resume(args[0]);
             case 'executions':
                 return this.executionsList();
+            case 'agents':
+                return args[0] === 'stop' ? this.agentStop(args[1]) : this.agentsList();
             case 'resume-execution':
                 return this.resumeExecution(args[0]);
             case 'approve':
@@ -327,6 +335,32 @@ export class ReplSession {
             return { lines: ['no conversations yet.'] };
         return { lines: ['Recent conversations:', ...list.map((c, i) => `  ${i + 1}. ${c.id}  ${c.title} (${c.turns} turns)`)] };
     }
+    /** Agent tasks across this project's executions, newest first. */
+    agentsList() {
+        if (!this.runtime.executionStore.enabled)
+            return { lines: ['agent tasks are not persisted (stateless mode).'] };
+        const tasks = this.runtime.agentTasks().slice(0, 12);
+        if (!tasks.length)
+            return { lines: ['no agent tasks yet.', '(agents run when `runtime.agents.enabled` is set and a plan delegates to one)'] };
+        // A waiting task's question goes on its own line: it is the one thing the user must read to act.
+        const lines = tasks.flatMap((t) => {
+            const steps = `${t.innerSteps.succeeded}/${t.innerSteps.total}`;
+            const spend = `${t.callsUsed}/${t.callsReserved} call(s), ${t.toolCallsUsed} tool call(s)`;
+            const why = t.interruption ? `  (${t.interruption.kind})` : '';
+            // `stepId` is planner-authored and `question` is model-authored: both go through displaySafe,
+            // like every other untrusted string this file renders.
+            const row = `  ${t.agentTaskId}  [${t.state}]  ${t.agentId} @ ${displaySafe(t.stepId, 40)}  ${steps} inner step(s), ${spend}, ${t.findings} finding(s)${why}`;
+            return t.question ? [row, `      ? ${displaySafe(t.question, 200)}`] : [row];
+        });
+        return { lines: ['Agent tasks:', ...lines, '', 'stop one with /agents stop <agent-task-id>'] };
+    }
+    /** Stop one agent task. Every outcome is reported — a stop that looks like nothing happened is a bug. */
+    agentStop(id) {
+        if (!id)
+            return { lines: ['usage: /agents stop <agent-task-id>'] };
+        const r = this.runtime.stopAgentTask(id);
+        return { lines: [`${r.ok ? 'stopped' : 'not stopped'} ${id}: ${r.reason}${r.state ? ` (state: ${r.state})` : ''}`] };
+    }
     executionsList() {
         if (!this.runtime.executionStore.enabled)
             return { lines: ['executions are disabled (stateless mode).'] };
@@ -362,13 +396,31 @@ export class ReplSession {
     status() {
         const ws = this.runtime.workspaceInfo();
         const providers = this.runtime.ai.providers();
-        return {
-            lines: [
-                `workspace: ${ws?.name ?? '(none)'}${ws?.git.branch ? ` @ ${ws.git.branch}` : ''}`,
-                `mode:      ${this.mode}`,
-                `providers: ${providers.length} configured (${providers.filter((p) => p.enabled).length} enabled)`,
-            ],
-        };
+        const lines = [
+            `workspace: ${ws?.name ?? '(none)'}${ws?.git.branch ? ` @ ${ws.git.branch}` : ''}`,
+            `mode:      ${this.mode}`,
+            `providers: ${providers.length} configured (${providers.filter((p) => p.enabled).length} enabled)`,
+        ];
+        // Phase 3.6: agent work is the one thing that can be UNFINISHED and invisible — a task left waiting
+        // or interrupted holds its execution up, so /status names it rather than leaving the user to think
+        // to run /agents. Absent entirely when nothing has ever delegated, so the flag-off output is
+        // unchanged.
+        // Only executions that are themselves still going: a non-terminal task on a finished execution is
+        // stale bookkeeping, and reporting it as "unfinished work" forever would train the user to ignore
+        // this line — which is the one line that has to be trusted when something IS waiting.
+        const live = this.runtime.executionStore.enabled ? this.runtime.executions().filter((e) => !EXEC_TERMINAL.has(e.status)) : [];
+        const tasks = live.flatMap((e) => this.runtime.agentTasks(e.id));
+        if (tasks.length) {
+            const unfinished = tasks.filter((t) => !AGENT_TERMINAL.has(t.state));
+            const waiting = unfinished.filter((t) => t.state === 'waiting_for_clarification' || t.state === 'waiting_for_input');
+            lines.push(`agents:    ${tasks.length} task(s), ${unfinished.length} unfinished${waiting.length ? `, ${waiting.length} waiting for an answer` : ''}`);
+            for (const t of unfinished.slice(0, 3)) {
+                lines.push(`             ${t.agentTaskId} [${t.state}] ${displaySafe(t.agentId, 24)} @ ${displaySafe(t.stepId, 16)}  ${t.innerSteps.succeeded}/${t.innerSteps.total} step(s)`);
+            }
+            if (unfinished.length > 3)
+                lines.push(`             … ${unfinished.length - 3} more (/agents)`);
+        }
+        return { lines };
     }
     setOrShowMode(next) {
         if (!next)

package/dist/executions/agentTasks.d.ts

@@ -35,11 +35,11 @@ export declare const persistedAgentTask: z.ZodObject<{
         detail: z.ZodOptional<z.ZodString>;
     }, "strict", z.ZodTypeAny, {
         at: number;
-        kind: "pause" | "crash" | "parent-cancel";
+        kind: "crash" | "pause" | "parent-cancel";
         detail?: string | undefined;
     }, {
         at: number;
-        kind: "pause" | "crash" | "parent-cancel";
+        kind: "crash" | "pause" | "parent-cancel";
         detail?: string | undefined;
     }>>;
     provenance: z.ZodObject<{
@@ -361,42 +361,14 @@ export declare const persistedAgentTask: z.ZodObject<{
 }, "strict", z.ZodTypeAny, {
     v: 1;
     state: "running" | "failed" | "completed" | "waiting_for_clarification" | "cancelled" | "paused" | "waiting_for_input" | "created" | "queued";
-    createdAt: number;
-    updatedAt: number;
     stepId: string;
     agentTaskId: string;
     callsUsed: number;
-    envelopeHash: string;
     agentId: string;
-    provenance: {
-        planVersion: number;
-        executionId?: string | undefined;
-    };
-    agentDefHash: string;
-    stepInputHash: string;
-    attempt: number;
-    innerCompletedSteps: string[];
-    innerObservations: z.objectOutputType<{
-        stepId: z.ZodString;
-        skill: z.ZodOptional<z.ZodString>;
-        tool: z.ZodOptional<z.ZodString>;
-        agent: z.ZodOptional<z.ZodString>;
-        agentTaskId: z.ZodOptional<z.ZodString>;
-        ok: z.ZodBoolean;
-        output: z.ZodOptional<z.ZodString>;
-        error: z.ZodOptional<z.ZodString>;
-        code: z.ZodOptional<z.ZodString>;
-        data: z.ZodOptional<z.ZodUnknown>;
-        artifacts: z.ZodOptional<z.ZodArray<z.ZodUnknown, "many">>;
-        callsUsed: z.ZodOptional<z.ZodNumber>;
-    }, z.ZodTypeAny, "passthrough">[];
-    innerObservationsOmitted: number;
     innerSteps: {
         succeeded: number;
         total: number;
     };
-    callsReserved: number;
-    callsRefunded: number;
     toolCallsUsed: number;
     findings: z.objectOutputType<{
         id: z.ZodString;
@@ -440,7 +412,42 @@ export declare const persistedAgentTask: z.ZodObject<{
         supersededBy: z.ZodOptional<z.ZodString>;
         createdAt: z.ZodNumber;
     }, z.ZodTypeAny, "passthrough">[];
+    createdAt: number;
+    updatedAt: number;
+    envelopeHash: string;
+    provenance: {
+        planVersion: number;
+        executionId?: string | undefined;
+    };
+    agentDefHash: string;
+    stepInputHash: string;
+    attempt: number;
+    innerCompletedSteps: string[];
+    innerObservations: z.objectOutputType<{
+        stepId: z.ZodString;
+        skill: z.ZodOptional<z.ZodString>;
+        tool: z.ZodOptional<z.ZodString>;
+        agent: z.ZodOptional<z.ZodString>;
+        agentTaskId: z.ZodOptional<z.ZodString>;
+        ok: z.ZodBoolean;
+        output: z.ZodOptional<z.ZodString>;
+        error: z.ZodOptional<z.ZodString>;
+        code: z.ZodOptional<z.ZodString>;
+        data: z.ZodOptional<z.ZodUnknown>;
+        artifacts: z.ZodOptional<z.ZodArray<z.ZodUnknown, "many">>;
+        callsUsed: z.ZodOptional<z.ZodNumber>;
+    }, z.ZodTypeAny, "passthrough">[];
+    innerObservationsOmitted: number;
+    callsReserved: number;
+    callsRefunded: number;
     diagnostics: unknown[];
+    interruption?: {
+        at: number;
+        kind: "crash" | "pause" | "parent-cancel";
+        detail?: string | undefined;
+    } | undefined;
+    startedAt?: number | undefined;
+    endedAt?: number | undefined;
     innerPlan?: {
         id: string;
         version: number;
@@ -458,13 +465,6 @@ export declare const persistedAgentTask: z.ZodObject<{
         goal: string;
         reason?: string | undefined;
     } | undefined;
-    startedAt?: number | undefined;
-    endedAt?: number | undefined;
-    interruption?: {
-        at: number;
-        kind: "pause" | "crash" | "parent-cancel";
-        detail?: string | undefined;
-    } | undefined;
     innerPlanVersion?: number | undefined;
     innerCheckpoint?: z.objectOutputType<{
         at: z.ZodNumber;
@@ -488,42 +488,14 @@ export declare const persistedAgentTask: z.ZodObject<{
 }, {
     v: 1;
     state: "running" | "failed" | "completed" | "waiting_for_clarification" | "cancelled" | "paused" | "waiting_for_input" | "created" | "queued";
-    createdAt: number;
-    updatedAt: number;
     stepId: string;
     agentTaskId: string;
     callsUsed: number;
-    envelopeHash: string;
     agentId: string;
-    provenance: {
-        planVersion: number;
-        executionId?: string | undefined;
-    };
-    agentDefHash: string;
-    stepInputHash: string;
-    attempt: number;
-    innerCompletedSteps: string[];
-    innerObservations: z.objectInputType<{
-        stepId: z.ZodString;
-        skill: z.ZodOptional<z.ZodString>;
-        tool: z.ZodOptional<z.ZodString>;
-        agent: z.ZodOptional<z.ZodString>;
-        agentTaskId: z.ZodOptional<z.ZodString>;
-        ok: z.ZodBoolean;
-        output: z.ZodOptional<z.ZodString>;
-        error: z.ZodOptional<z.ZodString>;
-        code: z.ZodOptional<z.ZodString>;
-        data: z.ZodOptional<z.ZodUnknown>;
-        artifacts: z.ZodOptional<z.ZodArray<z.ZodUnknown, "many">>;
-        callsUsed: z.ZodOptional<z.ZodNumber>;
-    }, z.ZodTypeAny, "passthrough">[];
-    innerObservationsOmitted: number;
     innerSteps: {
         succeeded: number;
         total: number;
     };
-    callsReserved: number;
-    callsRefunded: number;
     toolCallsUsed: number;
     findings: z.objectInputType<{
         id: z.ZodString;
@@ -567,7 +539,42 @@ export declare const persistedAgentTask: z.ZodObject<{
         supersededBy: z.ZodOptional<z.ZodString>;
         createdAt: z.ZodNumber;
     }, z.ZodTypeAny, "passthrough">[];
+    createdAt: number;
+    updatedAt: number;
+    envelopeHash: string;
+    provenance: {
+        planVersion: number;
+        executionId?: string | undefined;
+    };
+    agentDefHash: string;
+    stepInputHash: string;
+    attempt: number;
+    innerCompletedSteps: string[];
+    innerObservations: z.objectInputType<{
+        stepId: z.ZodString;
+        skill: z.ZodOptional<z.ZodString>;
+        tool: z.ZodOptional<z.ZodString>;
+        agent: z.ZodOptional<z.ZodString>;
+        agentTaskId: z.ZodOptional<z.ZodString>;
+        ok: z.ZodBoolean;
+        output: z.ZodOptional<z.ZodString>;
+        error: z.ZodOptional<z.ZodString>;
+        code: z.ZodOptional<z.ZodString>;
+        data: z.ZodOptional<z.ZodUnknown>;
+        artifacts: z.ZodOptional<z.ZodArray<z.ZodUnknown, "many">>;
+        callsUsed: z.ZodOptional<z.ZodNumber>;
+    }, z.ZodTypeAny, "passthrough">[];
+    innerObservationsOmitted: number;
+    callsReserved: number;
+    callsRefunded: number;
     diagnostics: unknown[];
+    interruption?: {
+        at: number;
+        kind: "crash" | "pause" | "parent-cancel";
+        detail?: string | undefined;
+    } | undefined;
+    startedAt?: number | undefined;
+    endedAt?: number | undefined;
     innerPlan?: {
         id: string;
         version: number;
@@ -585,13 +592,6 @@ export declare const persistedAgentTask: z.ZodObject<{
         goal: string;
         reason?: string | undefined;
     } | undefined;
-    startedAt?: number | undefined;
-    endedAt?: number | undefined;
-    interruption?: {
-        at: number;
-        kind: "pause" | "crash" | "parent-cancel";
-        detail?: string | undefined;
-    } | undefined;
     innerPlanVersion?: number | undefined;
     innerCheckpoint?: z.objectInputType<{
         at: z.ZodNumber;
@@ -613,15 +613,16 @@ export declare const persistedAgentTask: z.ZodObject<{
         message: z.ZodString;
     }, z.ZodTypeAny, "passthrough"> | undefined;
 }>;
-export interface AgentTaskView {
+/** The result of reading agent tasks back: what parsed, and how much did not. */
+export interface AgentTasksRead {
     tasks: AgentTaskRecord[];
-    /** Records that failed validation and were left out of the view (still on disk, untouched). */
+    /** Records that failed validation and were left out (still on disk, untouched). */
     dropped: number;
 }
 /**
  * Validate the agent tasks on an execution. Pure: it reads, it never writes. Callers that then persist
  * the execution are choosing to drop the unparseable records — reading alone never does.
  */
-export declare function parseAgentTasks(exec: Pick<Execution, 'agentTasks'>): AgentTaskView;
+export declare function parseAgentTasks(exec: Pick<Execution, 'agentTasks'>): AgentTasksRead;
 /** One task by id, validated — the lookup every resume path uses. */
 export declare function findAgentTask(exec: Pick<Execution, 'agentTasks'>, agentTaskId: string): AgentTaskRecord | undefined;

package/dist/index.d.ts

@@ -102,8 +102,9 @@ export type { AdmissionRejection, AdmissionResult } from './agents/admit.js';
 export type { StepObservationCode } from './orchestration/executor.js';
 export { PLAN_STEP_STATUSES } from './orchestration/plan.js';
 export { parseAgentTasks, findAgentTask } from './executions/agentTasks.js';
-export type { AgentTaskView } from './executions/agentTasks.js';
-export { AGENT_TERMINAL, AGENT_RESUMABLE } from './agents/task.js';
+export type { AgentTasksRead } from './executions/agentTasks.js';
+export { AGENT_TERMINAL, AGENT_RESUMABLE, agentTaskView } from './agents/task.js';
+export type { AgentTaskView } from './agents/task.js';
 export type { ProgressSnapshot } from './orchestration/executor.js';
 export { mcpToolId } from './mcp/toolAdapter.js';
 export { MCP_PROTOCOL_VERSION } from './mcp/protocol.js';

package/dist/index.js

@@ -80,7 +80,7 @@ export { PLAN_STEP_STATUSES } from './orchestration/plan.js';
 // trust records this version cannot parse. The state sets are exported with it because "is this task
 // finished?" must have one answer, not one per caller.
 export { parseAgentTasks, findAgentTask } from './executions/agentTasks.js';
-export { AGENT_TERMINAL, AGENT_RESUMABLE } from './agents/task.js';
+export { AGENT_TERMINAL, AGENT_RESUMABLE, agentTaskView } from './agents/task.js';
 // ── MCP connectivity (Phase 3.2) — external servers as ordinary Runtime tools ──
 // The CONFIG + STATUS surface is public; the client, transports, and manager internals are not, so the
 // wire implementation stays free to change without a breaking release.

package/dist/orchestration/executor.js

@@ -34,7 +34,11 @@ async function runStepInner(step, deps) {
         if (step.agent) {
             if (!deps.runAgent)
                 return { stepId: step.id, agent: step.agent, ok: false, code: 'agent-not-enabled', error: 'agent execution is not enabled' };
-            return deps.runAgent(step, { reservation: stepCalls(step, Number.POSITIVE_INFINITY, deps.reserve), ...(deps.signal ? { signal: deps.signal } : {}) });
+            // `return await`, NOT a bare return. In an async function a returned promise is ADOPTED, not
+            // caught, so a bare return here escapes this try/catch entirely: a throwing agent rejected the
+            // whole executePlan instead of failing its own step, and left its wave-mates running unawaited.
+            // The skill and tool branches above both await, which is why only agents had this hole.
+            return await deps.runAgent(step, { reservation: stepCalls(step, Number.POSITIVE_INFINITY, deps.reserve), ...(deps.signal ? { signal: deps.signal } : {}) });
         }
         return { stepId: step.id, ok: false, error: 'step names neither a skill nor a tool' };
     }

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/events.d.ts

@@ -6,10 +6,15 @@
  * Token-streaming extension point: `response.delta` is reserved here (content-bearing, redacted like
  * everything else). Provider token streaming is NOT implemented in 1.0 — no delta is ever emitted yet —
  * but declaring the arm keeps the host/emitter architecture ready for it without a breaking change.
+ *
+ * EVOLUTION CONTRACT: this union GROWS. A new arm is additive at runtime — an existing consumer keeps
+ * receiving the events it knows — but it breaks an exhaustive `switch` at COMPILE time. Consumers must
+ * carry a default case. Arms added this way are announced in the CHANGELOG.
  */
 import type { Clock } from '../util/clock.js';
 import type { ErrorCategory } from '../types.js';
 import type { ExecutableMode, ModeSource, RuntimeMode, RuntimeStatus } from './types.js';
+import type { AgentTaskState } from '../agents/task.js';
 export type RuntimeEvent = {
     type: 'runtime.started';
     ts: number;
@@ -54,6 +59,45 @@ export type RuntimeEvent = {
     ts: number;
     runId: string;
     text: string;
+} | {
+    type: 'agent.task.started';
+    ts: number;
+    runId: string;
+    agentTaskId: string;
+    agentId: string;
+    stepId: string;
+    state: AgentTaskState;
+} | {
+    type: 'agent.task.progress';
+    ts: number;
+    runId: string;
+    agentTaskId: string;
+    agentId: string;
+    stepId: string;
+    /** Per inner WAVE, never per inner step: a chatty agent would otherwise flood the ring buffer
+     *  and push every other event out of it. */
+    innerSteps: {
+        total: number;
+        succeeded: number;
+    };
+    callsUsed: number;
+    toolCallsUsed: number;
+} | {
+    type: 'agent.task.completed';
+    ts: number;
+    runId: string;
+    agentTaskId: string;
+    agentId: string;
+    stepId: string;
+    state: AgentTaskState;
+    innerSteps: {
+        total: number;
+        succeeded: number;
+    };
+    callsUsed: number;
+    toolCallsUsed: number;
+    /** How many findings were ADMITTED. Never the findings themselves. */
+    findings: number;
 };
 /** Distributive Omit so an event can be emitted without pre-stamping `ts`. */
 type WithoutTs<T> = T extends unknown ? Omit<T, 'ts'> : never;

package/dist/runtime/events.js

@@ -6,6 +6,10 @@
  * Token-streaming extension point: `response.delta` is reserved here (content-bearing, redacted like
  * everything else). Provider token streaming is NOT implemented in 1.0 — no delta is ever emitted yet —
  * but declaring the arm keeps the host/emitter architecture ready for it without a breaking change.
+ *
+ * EVOLUTION CONTRACT: this union GROWS. A new arm is additive at runtime — an existing consumer keeps
+ * receiving the events it knows — but it breaks an exhaustive `switch` at COMPILE time. Consumers must
+ * carry a default case. Arms added this way are announced in the CHANGELOG.
  */
 import { systemClock } from '../util/clock.js';
 import { redact } from '../security/redact.js';

package/dist/runtime/runtime.d.ts

@@ -25,6 +25,7 @@ import type { SkillSource, LoadedSource } from '../skills/discovery.js';
 import type { AgentDefinition } from '../agents/definition.js';
 import { ExecutionStore } from '../executions/store.js';
 import type { Execution } from '../executions/execution.js';
+import type { AgentTaskState, AgentTaskView } from '../agents/task.js';
 import { ArtifactStore } from '../artifacts/artifacts.js';
 import type { CompareInput } from '../comparison/comparator.js';
 import type { ComparisonResult } from '../comparison/comparison.js';
@@ -87,6 +88,8 @@ export declare class Runtime {
     /** Live runs, so a pause/cancel can abort the agent tasks actually in flight. Only ever populated
      *  when agents are enabled, so pause/cancel are unchanged with the flag off. */
     private readonly liveRuns;
+    /** Phase 3.6: agent tasks running RIGHT NOW in this process, and how to stop each one on its own. */
+    private readonly liveAgentTasks;
     /** The config file's `budget:` ceilings, kept only so the 3.3 pre-pass can decline a model call. */
     private readonly _configBudget?;
     private readonly approval?;
@@ -175,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;
@@ -285,14 +297,28 @@ export declare class Runtime {
     private runPersistence;
     /** Run `fn` while heartbeating the execution lease so a long run never lets the lease expire. */
     private withHeartbeat;
+    /**
+     * Build the OrchestrateInput. The optional half is an OBJECT, not a positional tail: this function
+     * grew to ten parameters and a caller that passed five of them silently got no sink, no signal and no
+     * provenance — a replan that persisted nothing and could not be cancelled. Named fields cannot be
+     * short-counted.
+     */
     private orchestrateInput;
     /** Record an EXECUTED orchestration outcome for learning. plan-only, dry-run, and waiting states are
      * 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). */
@@ -364,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).
      *
@@ -409,6 +455,27 @@ export declare class Runtime {
      * hand one step's completed inner work to a different step with the same id and a different input.
      */
     private agentResumeLookup;
+    /**
+     * Every agent task this Runtime can see, newest execution first (Phase 3.6). Live ones (running in
+     * this process) and persisted ones are the same list: a task's record IS its status, so there is no
+     * second source to disagree with.
+     */
+    agentTasks(executionId?: string): AgentTaskView[];
+    /**
+     * Stop one agent task. Four cases, and NONE of them is a silent no-op — a `stop` that appears to do
+     * nothing is indistinguishable from a bug:
+     *
+     *  - running in this process: abort it, then let the worker record `cancelled` as it unwinds;
+     *  - persisted and not finished (another process, or a dead one): write `cancelled` with a
+     *    `parent-cancel` interruption, so the record stops claiming it is queued or running;
+     *  - already finished: report that, and change nothing — a terminal state is sticky;
+     *  - unknown id: say so.
+     */
+    stopAgentTask(agentTaskId: string): {
+        ok: boolean;
+        state?: AgentTaskState;
+        reason: string;
+    };
     /** Abort a run that is in flight, recording WHY so a task can tell a pause from a cancellation. */
     private abortLiveRun;
     /** Mark an execution paused (it can be resumed later). */