ai-runtime-engine 2.8.0 → 3.0.0

package/dist/runtime/runtime.js

@@ -54,7 +54,10 @@ import { executePlan } from '../orchestration/executor.js';
 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 } from '../agents/task.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';
@@ -159,6 +162,8 @@ export 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. */
     liveRuns = new Map();
+    /** Phase 3.6: agent tasks running RIGHT NOW in this process, and how to stop each one on its own. */
+    liveAgentTasks = new Map();
     /** The config file's `budget:` ceilings, kept only so the 3.3 pre-pass can decline a model call. */
     _configBudget;
     approval;
@@ -458,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;
     }
@@ -469,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,
@@ -854,7 +886,14 @@ export class Runtime {
             // entire flag-off delta on this path.
             const planning = await this.capabilityPlanning(effectiveGoal, policy, routing);
             try {
-                const outcome = await orchestrate(this.orchestrateInput(mode, effectiveGoal, policy, routing, partial, planning?.block, this.agentsEnabled ? controller.signal : undefined, { planVersion: 1 }));
+                const outcome = await orchestrate(this.orchestrateInput(mode, effectiveGoal, policy, {
+                    ...(routing ? { routing } : {}),
+                    ...(partial ? { partial } : {}),
+                    ...(planning?.block ? { requiredCapabilities: planning.block } : {}),
+                    ...(this.agentsEnabled ? { signal: controller.signal } : {}),
+                    provenance: { planVersion: 1 },
+                    runId,
+                }));
                 this.recordOrchestration(mode, goal, outcome);
                 return this.mapOutcome(outcome, resolution, runId, undefined, planning);
             }
@@ -887,7 +926,15 @@ export class Runtime {
                 this.liveRuns.set(exec.id, { controller });
             // Phase 3.5: only when there is a store to write to — a stateless run keeps the 2.7.0 shape.
             const sink = this._executions.enabled ? this.runPersistence(exec, controller) : undefined;
-            const outcome = await this.withHeartbeat(exec.id, () => orchestrate(this.orchestrateInput(mode, effectiveGoal, policy, routing, partial, planning?.block, this.agentsEnabled ? controller.signal : undefined, { executionId: exec.id, planVersion: exec.planVersion }, sink)));
+            const outcome = await this.withHeartbeat(exec.id, () => orchestrate(this.orchestrateInput(mode, effectiveGoal, policy, {
+                ...(routing ? { routing } : {}),
+                ...(partial ? { partial } : {}),
+                ...(planning?.block ? { requiredCapabilities: planning.block } : {}),
+                ...(this.agentsEnabled ? { signal: controller.signal } : {}),
+                provenance: { executionId: exec.id, planVersion: exec.planVersion },
+                ...(sink ? { sink } : {}),
+                runId,
+            })));
             exec.status = this.execStatus(outcome.status);
             exec.observations = outcome.observations.map(persistableObservation);
             if (outcome.plan) {
@@ -1011,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();
             },
             /**
@@ -1035,7 +1086,14 @@ export class Runtime {
             clearInterval(timer);
         }
     }
-    orchestrateInput(mode, goal, policy, routing, partial, requiredCapabilities, signal, provenance, sink, agentResume) {
+    /**
+     * 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.
+     */
+    orchestrateInput(mode, goal, policy, opts = {}) {
+        const { routing, partial, requiredCapabilities, signal, provenance, sink, agentResume, runId } = opts;
         return {
             goal,
             mode,
@@ -1046,16 +1104,23 @@ 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 } : {}),
             resolveGaps: (missing) => this.resolveMissingRefs(missing, policy),
             // Phase 3.4: ONE runner source. `agents`, `runAgent` and `reserve` ride along only when agents are
             // enabled AND a definition exists, so with the flag off this object is KEY-identical to 2.6.0.
-            ...this.orchestrateRunners(policy, signal, provenance, sink?.onRecord, agentResume),
+            ...this.orchestrateRunners(policy, {
+                runId: runId ?? 'unknown',
+                ...(signal ? { signal } : {}),
+                ...(provenance ? { provenance } : {}),
+                ...(sink?.onRecord ? { onRecord: sink.onRecord } : {}),
+                ...(agentResume ? { agentResume } : {}),
+            }),
             // Phase 3.5: the commit points. Present ONLY when there is a store to commit to, so a stateless
             // Runtime builds an OrchestrateInput key-identical to 2.7.0.
             ...(sink ? { onPlan: sink.onPlan, onProgress: sink.onProgress } : {}),
@@ -1072,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 '';
@@ -1086,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() {
@@ -1392,7 +1469,7 @@ export class Runtime {
                 // path (whether the pause was approval, budget, or partial-progress) so an approved-but-over-budget
                 // plan pauses for budget rather than silently exceeding it; a raised budget re-applies here.
                 const resumeLookup = this.agentResumeLookup(exec, opts.clarificationAnswer);
-                const exe = await this.withHeartbeat(exec.id, () => executePlan(exec.plan, { ...this.orchestrateRunners(policy, opts.signal ?? controller.signal, { executionId: exec.id, planVersion: exec.planVersion }, sink?.onRecord, resumeLookup), ...(sink ? { onProgress: sink.onProgress } : {}), maxParallelSteps: policy.maxParallelSteps ?? 2, ...(policy.limits ? { limits: policy.limits } : {}), skip: new Set(exec.completedSteps), ...(policy.maxCalls !== undefined ? { callBudget: policy.maxCalls } : {}), ...(opts.signal ? { signal: opts.signal } : {}) }));
+                const exe = await this.withHeartbeat(exec.id, () => executePlan(exec.plan, { ...this.orchestrateRunners(policy, { runId, signal: opts.signal ?? controller.signal, provenance: { executionId: exec.id, planVersion: exec.planVersion }, ...(sink?.onRecord ? { onRecord: sink.onRecord } : {}), agentResume: resumeLookup }), ...(sink ? { onProgress: sink.onProgress } : {}), maxParallelSteps: policy.maxParallelSteps ?? 2, ...(policy.limits ? { limits: policy.limits } : {}), skip: new Set(exec.completedSteps), ...(policy.maxCalls !== undefined ? { callBudget: policy.maxCalls } : {}), ...(opts.signal ? { signal: opts.signal } : {}) }));
                 if (exe.stoppedForBudget) {
                     const done = exe.plan.steps.filter((s) => s.status === 'succeeded').length;
                     const total = exe.plan.steps.length;
@@ -1427,7 +1504,14 @@ export class Runtime {
                 // this arm with no signal, no provenance, no sink and no resume lookup — so a replan persisted
                 // no agent record AT ALL (onRecord is the only writer of `agentTasks`), could not be paused or
                 // cancelled, and elected `pending` from stale records.
-                outcome = await this.withHeartbeat(exec.id, () => orchestrate(this.orchestrateInput('orchestrate', brief ? `${goal}\n\n${brief}` : goal, policy, this.effectiveRouting(), budgetPaused, undefined, this.agentsEnabled ? controller.signal : undefined, { executionId: exec.id, planVersion: exec.planVersion }, sink)));
+                outcome = await this.withHeartbeat(exec.id, () => orchestrate(this.orchestrateInput('orchestrate', brief ? `${goal}\n\n${brief}` : goal, policy, {
+                    ...(this.effectiveRouting() ? { routing: this.effectiveRouting() } : {}),
+                    ...(budgetPaused ? { partial: true } : {}),
+                    ...(this.agentsEnabled ? { signal: controller.signal } : {}),
+                    provenance: { executionId: exec.id, planVersion: exec.planVersion },
+                    ...(sink ? { sink } : {}),
+                    runId,
+                })));
             }
             exec.status = this.execStatus(outcome.status);
             exec.observations = [...observationsBefore, ...outcome.observations.map(persistableObservation)];
@@ -1464,9 +1548,14 @@ export class Runtime {
      * They used to drift: resume built its own pair with no agent runner, so a persisted plan containing
      * an agent step would have failed every one of those steps.
      */
-    orchestrateRunners(policy, signal, provenance, onRecord, agentResume) {
-        const envelopes = policy ? this.agentEnvelopes(policy) : [];
+    orchestrateRunners(policy, opts) {
+        const { runId, signal, provenance, onRecord, agentResume } = opts;
+        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),
@@ -1476,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,
@@ -1503,8 +1593,29 @@ export class Runtime {
                                     return { unavailable: true };
                                 }
                             },
-                            emit: (e) => this.emitter.emit({ type: e.type, agentTaskId: e.record.agentTaskId, agentId: e.record.agentId, stepId: e.record.stepId, state: e.record.state, innerSteps: e.record.innerSteps, callsUsed: e.record.callsUsed, toolCallsUsed: e.record.toolCallsUsed, findings: e.record.findings.length }),
+                            // METADATA ONLY, and ONE BRANCH PER ARM. Building a single object with a union-typed
+                            // `type` compiles while carrying properties from every constituent — TypeScript's
+                            // excess-property check against a union admits anything present in SOME arm — so
+                            // `agent.task.started` was shipping innerSteps/callsUsed/findings it does not declare.
+                            // Narrowing to a literal first makes an extra property a compile error again; the
+                            // key-set test covers what the type system still cannot.
+                            emit: (e) => {
+                                const base = { runId, agentTaskId: e.record.agentTaskId, agentId: e.record.agentId, stepId: e.record.stepId };
+                                if (e.type === 'agent.task.started') {
+                                    this.emitter.emit({ type: 'agent.task.started', ...base, state: e.record.state });
+                                    return;
+                                }
+                                if (e.type === 'agent.task.progress') {
+                                    this.emitter.emit({ type: 'agent.task.progress', ...base, innerSteps: e.record.innerSteps, callsUsed: e.record.callsUsed, toolCallsUsed: e.record.toolCallsUsed });
+                                    return;
+                                }
+                                // `findings` is a COUNT: a claim is agent-authored text and an event is the one
+                                // surface a host may forward anywhere, so no content crosses it.
+                                this.emitter.emit({ type: 'agent.task.completed', ...base, state: e.record.state, innerSteps: e.record.innerSteps, callsUsed: e.record.callsUsed, toolCallsUsed: e.record.toolCallsUsed, findings: e.record.findings.length });
+                            },
                             ...(onRecord ? { onRecord } : {}),
+                            registerAbort: (id, abort) => this.liveAgentTasks.set(id, { abort, agentId: envelope.agentId, stepId: step.id, ...(provenance?.executionId ? { executionId: provenance.executionId } : {}) }),
+                            releaseAbort: (id) => this.liveAgentTasks.delete(id),
                             ...(ctx.signal ?? signal ? { parentSignal: ctx.signal ?? signal } : {}),
                             ...(provenance ? { provenance } : { provenance: { planVersion: 1 } }),
                             abortReason: () => {
@@ -1520,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).
      *
@@ -1631,6 +1788,110 @@ export class Runtime {
             return answer && record.agentTaskId === answeringId ? { record, answer } : { record };
         };
     }
+    /**
+     * 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) {
+        const executions = executionId ? this._executions.list().filter((e) => e.id === executionId) : this._executions.list();
+        return executions.flatMap((e) => parseAgentTasks(e).tasks.map(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) {
+        const live = this.liveAgentTasks.get(agentTaskId);
+        if (live) {
+            live.abort();
+            // Deliberately no `state`: the abort is cooperative and the worker has not unwound yet, so
+            // claiming `cancelled` here would report a state that has not happened.
+            return { ok: true, reason: 'aborted a task running in this process' };
+        }
+        const owning = this._executions.list().find((e) => parseAgentTasks(e).tasks.some((t) => t.agentTaskId === agentTaskId));
+        if (!owning)
+            return { ok: false, reason: 'no such agent task' };
+        // A run this process is executing owns its own record. Writing it from the side would fight the
+        // run's sink, and TAKING ITS LEASE would be worse: the sink refuses a leaseless commit and treats
+        // the refusal as a stop signal, so releasing here would abort the entire run to stop one task.
+        if (this.liveRuns.has(owning.id)) {
+            return { ok: false, reason: `that task belongs to a run in flight — /cancel ${owning.id} stops the whole run` };
+        }
+        // Claim the execution properly. A live lease held elsewhere means another process is mid-run: its
+        // next commit would rewrite the file from its own memory and silently drop this edit, so refuse
+        // rather than pretend.
+        const acq = this._executions.acquire(owning.id);
+        if (!acq.ok || !acq.execution)
+            return { ok: false, reason: `the execution is busy elsewhere (${acq.reason ?? 'unavailable'})` };
+        const exec = acq.execution;
+        try {
+            // Re-read EVERYTHING from the claimed copy. The listing was a snapshot: the task may have
+            // finished since, and writing the snapshot back would revert its own counters and findings.
+            const fresh = parseAgentTasks(exec).tasks.find((t) => t.agentTaskId === agentTaskId);
+            if (!fresh)
+                return { ok: false, reason: 'the task is no longer on the record' };
+            if (AGENT_TERMINAL.has(fresh.state))
+                return { ok: false, state: fresh.state, reason: `already ${fresh.state}` };
+            const now = this.clock.now();
+            const stopped = { ...fresh, state: 'cancelled', interruption: { kind: 'parent-cancel', at: now }, endedAt: now, updatedAt: now };
+            // A cancelled task is not asking anything any more; leaving the question on it would keep
+            // advertising a prompt nobody can answer.
+            delete stopped.pendingInner;
+            exec.agentTasks = (exec.agentTasks ?? []).map((entry) => (entry.agentTaskId === agentTaskId ? stopped : entry));
+            // WITHOUT THIS THE COMMAND IS COSMETIC. `AGENT_RESUMABLE` excludes `cancelled`, so a resume
+            // offers no record for this step and the executor runs the agent again from scratch — a second
+            // paid planning call and the tools fired again, after a human asked it to stop.
+            //
+            // But mark the step done only when the CURRENT plan still contains that exact step. Step ids
+            // recur across replans, so an id from a retired plan could name a completely different step,
+            // and marking it done would silently skip work that was never even started.
+            const stepStillThere = exec.plan?.steps.some((st) => st.id === stopped.stepId && stepIdentity(st) === stopped.stepInputHash);
+            if (stepStillThere && !exec.completedSteps.includes(stopped.stepId))
+                exec.completedSteps = [...exec.completedSteps, stopped.stepId];
+            // A stopped task cannot answer, so a pending wait belonging to it would strand the execution:
+            // resume early-returns on an unanswered inner clarification, and re-election only considers
+            // tasks that are still waiting. Hand the slot to another waiter, or clear it.
+            if (exec.pending?.kind === 'clarification' && exec.pending.agentTaskId === agentTaskId) {
+                const next = this.electWaitingAgent(exec);
+                if (next?.pendingInner)
+                    exec.pending = { kind: 'clarification', question: next.pendingInner.question, agentTaskId: next.agentTaskId };
+                else
+                    delete exec.pending;
+            }
+            // `commit`, not `commitProgress`. The funnel's rules exist to stop an IN-FLIGHT RUN overwriting
+            // a decision made while it was finishing — terminal is sticky, a pause is not the runner's to
+            // erase. This is not a run: it holds the lease it just acquired, it changes one task record, and
+            // it never touches `exec.status`, so a completed execution stays completed. Refusing here would
+            // instead make a stale non-terminal task on a finished execution permanently unstoppable.
+            if (!this._executions.commit(exec))
+                return { ok: false, reason: 'another owner holds this execution' };
+            this.emitter.emit({
+                type: 'agent.task.completed',
+                // A stop is out-of-band: it belongs to no run, so this id identifies the OPERATION. It is
+                // deliberately fresh rather than an execution id borrowed to look like a run id.
+                runId: nextRunId(),
+                agentTaskId,
+                agentId: stopped.agentId,
+                stepId: stopped.stepId,
+                state: 'cancelled',
+                innerSteps: stopped.innerSteps,
+                callsUsed: stopped.callsUsed,
+                toolCallsUsed: stopped.toolCallsUsed,
+                findings: stopped.findings.length,
+            });
+            return { ok: true, state: 'cancelled', reason: stepStillThere ? 'marked a persisted task cancelled' : 'marked a persisted task cancelled (its step is no longer in the plan)' };
+        }
+        finally {
+            this._executions.release(owning.id);
+        }
+    }
     /** Abort a run that is in flight, recording WHY so a task can tell a pause from a cancellation. */
     abortLiveRun(id, reason) {
         const live = this.liveRuns.get(id);

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.8.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",