@loopingai/core 0.5.1 → 0.7.0

package/dist/round/turn.js

@@ -1,7 +1,7 @@
 import { generateText, hasToolCall, isStepCount } from "ai";
 import { appendOnce } from "../agent/session.js";
 import { deterministicSessionMessage, finalReplyMessageId, parseRoundAckMessageId, roundAckMessageId, sessionText, taskUserMessageId } from "../agent/history.js";
-import { buildIntermediateContentHandler, isTransientAiError } from "../agent/inference.js";
+import { buildIntermediateContentHandler, isTransientAiError, nonRecoverableKind } from "../agent/inference.js";
 import { controlTools, controlToolSet } from "../agent/control.js";
 import { FINAL_REPLY_TOOL_NAME } from "../agent/final-reply.js";
 import { stepAllowance } from "../agent/budget.js";
@@ -240,9 +240,12 @@ async function attempt(args, control, model, instructions, messages) {
                 // change here.
                 ...control.map((c) => hasToolCall(c.name))
             ],
-            // We do our own primary → fallback recovery, so disable the SDK's
-            // per-model backoff (it would only add latency and duplicate the fallback).
-            maxRetries: 0,
+            // Retries on *this* model before the slot is given up, honouring the
+            // provider's own `retry-after`. Not a duplicate of the fallback: the
+            // fallback answers "this model cannot do it", and a 429 says "not yet" —
+            // and when both slots share a credential the fallback cannot even answer
+            // that. See `ModelConfig.maxRetries`.
+            maxRetries: args.maxRetries,
             // Charged here rather than from `result.steps` so a throw mid-loop still
             // bills the steps already spent — the `catch` below has no `result` to read.
             onStepEnd: async (step) => {
@@ -329,9 +332,16 @@ const MAX_REPAIR_ATTEMPTS = 3;
  * The id a repaired exchange is anchored on, derived from the Task and round like
  * every other id here. Suffixed per repair, so several rejected calls can sit in
  * one attempt's messages without colliding.
+ *
+ * Underscore-separated for the same reason as
+ * {@link file://../subtasks/delegate.ts delegateToolCallId}: this reaches a
+ * provider as a `tool_use.id`, and Anthropic rejects anything outside
+ * `^[a-zA-Z0-9_-]+$`. A repair exchange is exactly the moment a round is already
+ * in trouble, so an id that 400s here turns a recoverable bad call into a dead
+ * round.
  */
 function controlCallId(taskId, round) {
-    return `task:${taskId}:round:${round}:control`;
+    return `task_${taskId}_round_${round}_control`;
 }
 /**
  * A rejected control call paired with its rejection, as the exchange the model has
@@ -400,7 +410,20 @@ function repairExchange(toolCallId, rejected, error) {
  * Throws only on a transient platform fault (for the Workflow step to retry).
  * A deterministic failure that outlasts every repair on both slots, with durable
  * work behind it, degrades to {@link joinSuccessfulBranches} rather than discarding
- * completed branches; with nothing behind it, it resolves to `{ status: "failed" }`.
+ * completed branches; with nothing behind it, it resolves to
+ * `{ status: "failed", kind: "exhausted" }`.
+ *
+ * The third failure is neither, and it short-circuits the *model* recoveries
+ * above: a {@link nonRecoverableKind} error ends the round from wherever it
+ * happens, carrying that kind — without repairing and **without reaching the
+ * fallback slot**, both of which would only present the same dead credential
+ * again. See that function for why the transient/deterministic split cannot
+ * express it.
+ *
+ * It does **not** skip the deterministic join. That path needs no credential —
+ * it is string concatenation over rows that are already durable — so completed
+ * branches are still delivered, and the credential fault reaches the operator
+ * through the log rather than by throwing away finished work.
  */
 export async function runTurn(args) {
     const { session, taskId, round, text, systemSuffix, models, branches } = args;
@@ -434,6 +457,34 @@ export async function runTurn(args) {
             // and so is a repair.
             const outcome = await attempt(args, control, model, system, slotMessages);
             if (!outcome.ok) {
+                // Before anything else, and before the fallback slot exists as an
+                // option: a failure nothing can clear ends the round here. Repairing
+                // asks a dead credential to try again; falling through spends the
+                // second slot presenting the *same* dead credential. Both are pure
+                // cost, and both delay the only useful outcome — telling an operator
+                // what to fix.
+                const nonRecoverable = nonRecoverableKind(outcome.error);
+                if (nonRecoverable) {
+                    console.error("[turn] non-recoverable model failure", {
+                        taskId,
+                        round,
+                        model: modelId,
+                        kind: nonRecoverable,
+                        error: String(outcome.error)
+                    });
+                    // What ends here is *inference*, not the round's ability to answer.
+                    // Branches that already completed are durable rows, and joining them
+                    // costs no credential — so the same rescue the exhausted path takes
+                    // applies, and the operator hears about the fault from the log above.
+                    const joined = await deterministicJoin(args);
+                    if (joined)
+                        return joined;
+                    return {
+                        status: "failed",
+                        kind: nonRecoverable,
+                        error: String(outcome.error)
+                    };
+                }
                 errors.push(outcome.error);
                 const { rejected } = outcome;
                 diagnostics.push(rejected
@@ -458,7 +509,7 @@ export async function runTurn(args) {
                 if (rejected &&
                     repair < MAX_REPAIR_ATTEMPTS &&
                     args.budget.spent < args.budget.allowance) {
-                    slotMessages.push(...repairExchange(`${controlCallId(taskId, round)}:repair:${repair}`, rejected, outcome.error));
+                    slotMessages.push(...repairExchange(`${controlCallId(taskId, round)}_repair_${repair}`, rejected, outcome.error));
                     continue;
                 }
                 break;
@@ -484,13 +535,29 @@ export async function runTurn(args) {
     const detail = `round ${round} exhausted both models — ${diagnostics.join("; ")}`;
     // Both models failed deterministically. Any branch results behind us are durable
     // and useful; deliver them joined rather than failing a Task whose work is done.
-    if (branches.some((b) => b.status === "completed")) {
-        console.warn("[turn] falling back to deterministic join", {
-            taskId,
-            round
-        });
-        const reply = await appendOnce(session, deterministicSessionMessage(finalReplyMessageId(taskId), "assistant", joinSuccessfulBranches(branches, args.partialNote)));
-        return { status: "replied", reply };
-    }
-    return { status: "failed", error: detail };
+    const joined = await deterministicJoin(args);
+    if (joined)
+        return joined;
+    return { status: "failed", kind: "exhausted", error: detail };
+}
+/**
+ * Deliver the branch results this round already has, when no model will produce
+ * an answer over them.
+ *
+ * The one recovery on this file that needs **no** model: a filter, a join and a
+ * durable append. That is why both failure paths reach it — a ladder that ran out
+ * of attempts, and one that stopped on a fault no attempt could clear. Neither
+ * has an answer to write; both have work worth returning.
+ *
+ * `undefined` when nothing completed, which is the caller's signal to fail with
+ * its own kind. No branches means nothing to join, and a Task with no work behind
+ * it should not report success.
+ */
+async function deterministicJoin(args) {
+    const { session, taskId, round, branches } = args;
+    if (!branches.some((b) => b.status === "completed"))
+        return undefined;
+    console.warn("[turn] falling back to deterministic join", { taskId, round });
+    const reply = await appendOnce(session, deterministicSessionMessage(finalReplyMessageId(taskId), "assistant", joinSuccessfulBranches(branches, args.partialNote)));
+    return { status: "replied", reply };
 }

package/dist/round/workflow.d.ts

@@ -1,6 +1,7 @@
 import type { WorkflowStep } from "cloudflare:workers";
 import type { CoreConfig } from "../config.js";
 import type { GatewayIdentity } from "../a2a/verify.js";
+import type { RoundFailureKind } from "../agent/inference.js";
 import type { RoundAgentBase } from "./agent.js";
 import type { RoundPolicy } from "./policy.js";
 /**
@@ -15,10 +16,10 @@ import type { RoundPolicy } from "./policy.js";
  * 1. **Round** — one main-agent inference that either answers the user (the Task
  *    is done) or delegates durable Subtasks plus the acknowledgment the user sees
  *    while they run.
- * 2. **Execute** — a delegating round's Subtask DAG runs in waves, every
- *    dependency-ready node concurrently, each in an isolated managed subagent.
- *    Then the loop returns to 1, where the model sees the results and decides
- *    again — answer, or delegate once more.
+ * 2. **Execute** — a delegating round's Subtasks all run at once, each in an
+ *    isolated managed subagent. Then the loop returns to 1, where the model sees
+ *    the results and decides again — answer, or delegate once more. Sequencing
+ *    lives here, in the loop, not inside a round.
  * 3. **Deliver** — persist the terminal Task, then POST a signed callback.
  *
  * The main agent is never forced either way. A round that has run out of budget —
@@ -78,6 +79,22 @@ export interface HandleTaskDeps {
     config: CoreConfig;
     /** The user-facing copy. Only `copy.taskFailed` is read out here. */
     policy: RoundPolicy;
+    /**
+     * Terminal copy for a round that produced no answer, by {@link
+     * RoundFailureKind} — an expired credential, models that could not do it, and
+     * whatever that union grows to cover.
+     *
+     * A hook rather than more `RoundPolicy` copy, because the useful words are
+     * deployment-specific ("run `claude setup-token`, then
+     * `wrangler secret put …`") and most agents cannot hit these conditions at
+     * all. Returning `undefined` — or omitting this — falls back to
+     * `policy.copy.taskFailed`, so an agent that does not care changes nothing,
+     * and one that only cares about *some* kinds answers for those alone.
+     *
+     * Core still owns the delivery: this supplies only the message, so the
+     * guarded write that doubles as the cancellation check stays in one place.
+     */
+    failureCopy?: (kind: RoundFailureKind, detail: string) => string | undefined;
     /**
      * The deployment's Ed25519 private JWK, for the terminal callback. Passed
      * rather than read off a module-scope `env` so this stays a pure function of
@@ -106,9 +123,8 @@ type AgentStub = DurableObjectStub<RoundAgentBase>;
  * references to them.
  *
  * **Step names are durable cache keys.** Everything inside the round loop carries
- * its round for that reason: `turn:<round>`, `deadline:<round>`,
- * `scan:<round>:<wave>`, `cancel:<round>:<wave>`. Renaming one silently re-runs
- * its effect on replay.
+ * its round for that reason: `turn:<round>`, `deadline:<round>`, `scan:<round>`,
+ * `cancel:<round>`. Renaming one silently re-runs its effect on replay.
  */
 export declare function runHandleTask(p: HandleTaskParams, step: WorkflowStep, deps: HandleTaskDeps): Promise<void>;
 export {};

package/dist/round/workflow.js

@@ -1,7 +1,35 @@
-import { MAX_CHUNKS_PER_BRANCH } from "../platform.js";
+import { CHUNK_STEP, MAX_CHUNKS_PER_BRANCH, STEP_TIMEOUT_MS } from "../platform.js";
 import { buildCompletedTask, buildFailedTask } from "../a2a/notify.js";
-import { createPushChannel } from "../a2a/push.js";
-import { selectWave } from "../subtasks/scheduler.js";
+import { deliverTerminalTask } from "../a2a/deliver.js";
+/**
+ * The same retries, and a timeout a **round** can actually be measured against.
+ *
+ * A chunk and a round are bounded by different things, and sharing one constant
+ * hid that. A chunk has {@link CHUNK_SOFT_MS}: it checkpoints and hands back a
+ * fresh step, so `STEP_TIMEOUT_MS` is a ceiling it is sized to stay under. A
+ * round has no soft deadline at all — `runTurn` runs up to
+ * `mainAgentLimits.maxTurns` sequential model-plus-tool steps in one
+ * `generateText`, and its only bound is that step count. Twenty turns whose
+ * tools each take the {@link file://../platform.ts MAX_TOOL_CALL_MS} they are
+ * permitted is hours, not half an hour, so a perfectly legal round could be
+ * killed and replayed whole.
+ *
+ * So the ceiling comes from the agent's own patience: a round cannot usefully
+ * outlive the wall clock its Task is allowed, because the `deadline:` step fails
+ * the Task at that point anyway. Floored at `STEP_TIMEOUT_MS` so a deliberately
+ * tight `maxWallMs` cannot produce a step timeout shorter than the single tool
+ * call core tells hosts they may install.
+ *
+ * This remains a backstop against a hang, not a budget. What actually bounds
+ * what a round *spends* is `TurnBudget`, and what bounds the Task is
+ * `mainAgentLimits` — both of which are checked whatever this says.
+ */
+function turnStep(config) {
+    return {
+        ...CHUNK_STEP,
+        timeout: Math.max(config.mainAgentLimits.maxWallMs, STEP_TIMEOUT_MS)
+    };
+}
 /**
  * The orchestration itself, split from the `WorkflowEntrypoint` wiring so it can
  * be driven with a fake `step` in tests (workerd forbids constructing a
@@ -14,9 +42,8 @@ import { selectWave } from "../subtasks/scheduler.js";
  * references to them.
  *
  * **Step names are durable cache keys.** Everything inside the round loop carries
- * its round for that reason: `turn:<round>`, `deadline:<round>`,
- * `scan:<round>:<wave>`, `cancel:<round>:<wave>`. Renaming one silently re-runs
- * its effect on replay.
+ * its round for that reason: `turn:<round>`, `deadline:<round>`, `scan:<round>`,
+ * `cancel:<round>`. Renaming one silently re-runs its effect on replay.
  */
 export async function runHandleTask(p, step, deps) {
     const limits = deps.config.mainAgentLimits;
@@ -80,7 +107,7 @@ export async function runHandleTask(p, step, deps) {
         // durable work to fall back on) and routes to failed delivery; a transient
         // fault throws and the step retries, recovering from the durable rows with no
         // second inference.
-        const turn = await step.do(`turn:${round}`, async () => {
+        const turn = await step.do(`turn:${round}`, turnStep(deps.config), async () => {
             // Projected to a plain object: an RPC return carries a `Disposable` brand a
             // step result cannot serialize. Every branch must carry `turns` — a field
             // this projection drops is a field the budget never sees.
@@ -102,6 +129,7 @@ export async function runHandleTask(p, step, deps) {
             if (result.status === "failed")
                 return {
                     status: result.status,
+                    kind: result.kind,
                     error: result.error,
                     turns: result.turns
                 };
@@ -110,27 +138,33 @@ export async function runHandleTask(p, step, deps) {
         turnsUsed += turn.turns;
         if (turn.status === "canceled")
             return;
+        // The round produced no answer. `kind` is the whole difference between the
+        // two ways that happens — models that could not do it, versus a fault that
+        // stopped the round on its first attempt and that only a human can clear —
+        // and it exists to be turned into words the reader can act on. Same
+        // delivery either way; the diagnostic is logged, never shown.
         if (turn.status === "failed") {
             console.error("[handle-task] round failed", {
                 taskId: p.taskId,
                 round,
+                kind: turn.kind,
                 error: turn.error
             });
-            await deliver(p, step, agent, null, deps);
+            await deliver(p, step, agent, null, deps, {
+                kind: turn.kind,
+                detail: turn.error
+            });
             return;
         }
         if (turn.status === "replied") {
             await deliver(p, step, agent, turn.reply, deps);
             return;
         }
-        // Delegated: run this round's DAG, then loop and let the model decide again.
-        const executed = await executeDag(p, step, agent, round, push, deps);
+        // Delegated: run this round's Subtasks, then loop and let the model decide
+        // again.
+        const executed = await executeSubtasks(p, step, agent, round, push);
         if (executed === "canceled")
             return;
-        if (executed === "stuck") {
-            await deliver(p, step, agent, null, deps);
-            return;
-        }
     }
     // Unreachable: a `final` round is handed only `final_reply`, so it either
     // answers or fails, and both return above. Reaching here means a round
@@ -141,58 +175,49 @@ export async function runHandleTask(p, step, deps) {
     await deliver(p, step, agent, null, deps);
 }
 /**
- * Drive one round's Subtask DAG to termination, one wave at a time.
+ * Run every Subtask one round delegated, concurrently, to termination.
  *
- * Bounded by `maxSubtasks + 1` iterations rather than looping until `done`: a
- * wave that reports `ready` always retires at least one active node, so N
- * Subtasks need at most N waves of work plus one final scan to observe `done`.
- * Exhausting the budget means the DAG stopped making progress, which is the same
- * corruption `stuck` names.
+ * **One pass is the whole thing.** A round's Subtasks are independent of one
+ * another, so they are all runnable the moment they exist, and `runBranch` is
+ * contractually obliged to leave its row terminal — it resolves a deterministic
+ * failure itself and has a `fail:<id>` backstop once the retries are gone. So
+ * there is nothing left to re-scan afterwards, and no way for this to make no
+ * progress. Sequencing between units of work is the round loop's job.
  *
- * Every step name carries the round, because step names are durable cache keys:
- * two rounds of the same Task reusing `scan:0` would replay the first round's
- * cached answer into the second.
+ * Both step names carry the round, because step names are durable cache keys: two
+ * rounds of the same Task reusing `scan` would replay the first round's cached
+ * answer into the second.
  */
-async function executeDag(p, step, agent, round, push, deps) {
-    for (let wave = 0; wave <= deps.config.maxSubtasks; wave++) {
-        // One durable step per wave: `skipBlockedSubtasks` reports cancellation,
-        // propagates skips past any branch that just failed, and returns the
-        // refreshed DAG projection — one round trip, one consistent answer.
-        const scan = await step.do(`scan:${round}:${wave}`, async () => {
-            const result = await agent().skipBlockedSubtasks(p.taskId, round);
-            return result.canceled
-                ? { canceled: true, nodes: [] }
-                : { canceled: false, nodes: result.nodes };
+async function executeSubtasks(p, step, agent, round, push) {
+    // One durable step: `scanSubtasks` reports cancellation and returns the ids
+    // still owing an outcome — one round trip, one consistent answer. It writes
+    // nothing, so a replay that re-runs it costs only the read.
+    const scan = await step.do(`scan:${round}`, async () => {
+        const result = await agent().scanSubtasks(p.taskId, round);
+        return result.canceled
+            ? { canceled: true, ids: [] }
+            : { canceled: false, ids: result.ids };
+    });
+    if (scan.canceled) {
+        await step.do(`cancel:${round}`, async () => {
+            await agent().cancelPendingSubtasks(p.taskId);
         });
-        if (scan.canceled) {
-            await step.do(`cancel:${round}:${wave}`, async () => {
-                await agent().cancelPendingSubtasks(p.taskId);
-            });
-            return "canceled";
-        }
-        const decision = selectWave(scan.nodes);
-        if (decision.kind === "done")
-            return "done";
-        if (decision.kind === "stuck") {
-            console.error("[handle-task] subtask DAG made no progress", {
-                taskId: p.taskId,
-                round,
-                wave,
-                active: decision.active
-            });
-            return "stuck";
-        }
-        // Every dependency-ready node runs concurrently — the per-round Subtask
-        // maximum is the only fan-out bound. `runBranch` never rejects, so a single
-        // branch cannot fast-fail `Promise.all` and strand its siblings' durable
-        // results.
-        await Promise.all(decision.ids.map((id) => runBranch(p, step, agent, id, push)));
+        return "canceled";
     }
-    console.error("[handle-task] subtask DAG exceeded its wave budget", {
-        taskId: p.taskId,
-        round
-    });
-    return "stuck";
+    // Every Subtask runs concurrently — the per-round Subtask maximum is the only
+    // fan-out bound. `runBranch` never rejects, so a single branch cannot fast-fail
+    // `Promise.all` and strand its siblings' durable results.
+    //
+    // A cancellation arriving mid-pass is still honored, just not from here:
+    // `onTaskCanceled` aborts the live children *and* transitions every row still
+    // `pending` in the same sweep, and `executeSubtaskChunk` re-checks before
+    // publishing. That transition is what lets this pass end without a second
+    // scan. Without it, a branch whose RPC had not yet claimed its row when the
+    // cancellation landed would return terminal while leaving the row `pending`,
+    // and — since the next round's turn reports `canceled` and the workflow exits
+    // — nothing would resolve it before the 30-day cleanup.
+    await Promise.all(scan.ids.map((id) => runBranch(p, step, agent, id, push)));
+    return "done";
 }
 /**
  * Run one Subtask to termination as a sequence of durable **chunk** steps, and
@@ -202,7 +227,9 @@ async function executeDag(p, step, agent, round, push, deps) {
  * `done` on chunk 0 (step `execute:<id>`); a long recipe yields `done: false` and
  * the loop runs the next chunk (`execute:<id>:chunk:<n>`) until it terminates.
  * Each chunk is its own retryable step, and the child resumes from its
- * checkpoint — so no step approaches the platform timeout.
+ * checkpoint — so no step approaches the {@link CHUNK_STEP} timeout. `CHUNK_SOFT_MS`
+ * is what holds that true, and is sized against it rather than the other way
+ * round; a boundary here is not free, so it wants to be rare, not frequent.
  *
  * It resolves a deterministic branch failure into a `failed` row itself and
  * throws only on a transient fault (retry me) or a lifecycle bug. So a throw that
@@ -226,7 +253,7 @@ async function runBranch(p, step, agent, id, push) {
             // Chunk 0 keeps the plain `execute:<id>` step name so single-chunk branches
             // replay identically; later chunks append `:chunk:<n>`.
             const stepName = chunk === 0 ? `execute:${id}` : `execute:${id}:chunk:${chunk}`;
-            const done = await step.do(stepName, async () => {
+            const done = await step.do(stepName, CHUNK_STEP, async () => {
                 // The DO posts any progress itself; the step returns only the verdict.
                 const outcome = await agent().executeSubtaskChunk(id, chunk, push);
                 return outcome.done;
@@ -258,60 +285,45 @@ async function runBranch(p, step, agent, id, push) {
 /**
  * Persist the terminal Task, then notify the gateway. A null `reply` delivers a
  * `failed` Task with the policy's user-safe text; the diagnostic is already
- * logged.
+ * logged. Given a `failure`, the host's {@link HandleTaskDeps.failureCopy} may
+ * replace that text — same delivery, different words.
  *
- * The Task is built **inside** the step and returned, so `notify` posts exactly
- * what was persisted: building it in the body would re-stamp `new Date()` on
- * every replay and post a Task that differs from the stored one.
+ * `failure` is optional because only a round's own inference carries a kind. The
+ * other path here — a budget that ran out mid-delegation — is not a model failure
+ * and is deliberately not given a kind of its own until something needs to tell
+ * it apart.
  *
- * **The guarded write is the cancellation check.** `saveTask` refuses to write a
- * terminal state over a `canceled` row and says so, and it does that read and
- * write in one synchronous pass inside the DO. Probing first and saving second
- * would leave a window — between the two calls, and again between this step and
- * `notify` — in which a `tasks/cancel` lands and the gateway still receives a
- * `completed` callback. Keying the notify on "did the write apply" closes it.
+ * The delivery itself is {@link deliverTerminalTask}, which is shared with agents
+ * that never delegate. What is a round's own is the two things passed to it: the
+ * choice of terminal Task, and the child sweep.
  */
-async function deliver(p, step, agent, reply, deps) {
-    const task = await step.do("complete", async () => {
-        const terminal = reply !== null
-            ? buildCompletedTask(p.taskId, p.contextId, reply)
-            : buildFailedTask(p.taskId, p.contextId, deps.policy.copy.taskFailed);
-        return (await agent().saveTask(terminal)) ? terminal : null;
-    });
-    if (!task)
-        return;
-    // Sweep this Task's managed children now that it is terminal and every `execute`
-    // step has unwound. Deleting them here — rather than right after each successful
-    // chunk — keeps `deleteSubAgent`'s facet-abort from landing on a still-open
-    // `executeChunk` RPC, which telemetry mis-records as a failure. Best-effort and
-    // idempotent, so it is safe on replay.
-    //
-    // Caught, not left to propagate: the terminal Task is already durably saved, so
-    // a sweep that still fails once the step's own retries are exhausted must not
-    // block `notify` below — the gateway is owed its result regardless of whether
-    // this Task's children were reclaimed.
-    try {
-        await step.do("sweep", async () => {
-            await agent().sweepTaskChildren(p.taskId);
-        });
-    }
-    catch (err) {
-        console.error("[handle-task] sweep failed after retries", {
-            taskId: p.taskId,
-            err: String(err)
-        });
-    }
-    // Notify the gateway: a card-key-signed callback POST. Retried by the step on a
-    // non-2xx; the terminal messageId is deterministic and the gateway is
-    // idempotent/single-use, so retries are safe. If it ultimately fails, the
-    // gateway's own reaction backstop clears the pending marker.
-    await step.do("notify", async () => {
-        await createPushChannel(deps.signingKey, {
+async function deliver(p, step, agent, reply, deps, failure) {
+    // Resolved outside the step body so a replay cannot take a different branch
+    // than the write it is replaying.
+    const failedText = (failure && deps.failureCopy?.(failure.kind, failure.detail)) ||
+        deps.policy.copy.taskFailed;
+    await deliverTerminalTask(step, {
+        push: {
             taskId: p.taskId,
             contextId: p.contextId,
             pushUrl: p.pushUrl,
             pushToken: p.pushToken,
             jku: p.jku
-        }).deliver(task);
+        },
+        signingKey: deps.signingKey,
+        // `agent()` inside the body, never hoisted: a stub is a live connection and
+        // a severed one never reconnects.
+        saveTask: (task) => agent().saveTask(task),
+        terminal: () => reply !== null
+            ? buildCompletedTask(p.taskId, p.contextId, reply)
+            : buildFailedTask(p.taskId, p.contextId, failedText),
+        // Sweep this Task's managed children now that it is terminal and every
+        // `execute` step has unwound. Deleting them here — rather than right after
+        // each successful chunk — keeps `deleteSubAgent`'s facet-abort from landing
+        // on a still-open `executeChunk` RPC, which telemetry mis-records as a
+        // failure. Best-effort and idempotent, so it is safe on replay.
+        sweep: async () => {
+            await agent().sweepTaskChildren(p.taskId);
+        }
     });
 }

package/dist/runtime/index.d.ts

@@ -59,8 +59,10 @@ export interface AgentRuntime {
     /** Tools the installed plugins offer the *main* agent, merged. */
     mainAgentTools(ctx: MainAgentToolContext): Promise<ToolSet>;
     /**
-     * Every plugin's `capability` block, for the main agent's soul. Returns `""`
-     * when none declares one, so a call site can append unconditionally.
+     * The capability blocks for the main agent's soul, in plugin declaration
+     * order: each plugin's own {@link AgentPlugin.capability} and the one on its
+     * {@link AgentPlugin.subtaskType}, if it declares either. Returns `""` when
+     * none does, so a call site can append unconditionally.
      */
     renderCapabilities(): string;
     /**

package/dist/runtime/index.js

@@ -109,8 +109,14 @@ export function createAgentRuntime(options) {
         renderCapabilities() {
             const blocks = [];
             for (const plugin of plugins) {
+                // Both blocks a plugin may declare, emitted adjacently: a plugin that
+                // declares a subtask type puts its capability on the *type*, and one
+                // that only offers main-agent tools puts it on the plugin. Declaring
+                // both is legal and means the model reads both.
                 if (plugin.capability)
                     blocks.push(plugin.capability);
+                if (plugin.subtaskType?.capability)
+                    blocks.push(plugin.subtaskType.capability);
             }
             return blocks.join("\n\n");
         },

package/dist/subagent/fingerprint.d.ts

@@ -11,8 +11,8 @@ export declare const FINGERPRINT_VERSION = 1;
  * Canonical JSON of the fields that define an execution's identity, rebuilt as
  * literals in fixed key order so `JSON.stringify` is deterministic (object
  * insertion order). Array order is semantic and preserved: the parent builds
- * references and dependency results from ordinal-ordered rows, so a retry of the
- * same execution is byte-identical.
+ * references from ordinal-ordered rows, so a retry of the same execution is
+ * byte-identical.
  *
  * **Limits are canonicalized as *declared*, not as merged.** The predecessor
  * merged them against the house baseline first, on the reasoning that `{}` and

package/dist/subagent/fingerprint.js

@@ -10,8 +10,8 @@ export const FINGERPRINT_VERSION = 1;
  * Canonical JSON of the fields that define an execution's identity, rebuilt as
  * literals in fixed key order so `JSON.stringify` is deterministic (object
  * insertion order). Array order is semantic and preserved: the parent builds
- * references and dependency results from ordinal-ordered rows, so a retry of the
- * same execution is byte-identical.
+ * references from ordinal-ordered rows, so a retry of the same execution is
+ * byte-identical.
  *
  * **Limits are canonicalized as *declared*, not as merged.** The predecessor
  * merged them against the house baseline first, on the reasoning that `{}` and
@@ -36,13 +36,12 @@ export function canonicalRequest(request) {
         recipe: {
             key: request.recipe.key,
             version: request.recipe.version,
-            // No model ids. They used to be hashed because a recipe declared them;
-            // it no longer can, and their absence here is the same trade this file
-            // already makes for `limits`: the host's own configuration stays out of
-            // the fingerprint, so changing it does not invalidate every checkpoint at
-            // once and restart every in-flight run from turn zero with its budget
-            // already spent. A run that resumes on a newly configured model resumes
-            // from conversation state, which is model-independent.
+            // No model ids. Their absence is the same trade this file already makes
+            // for `limits`: the host's own configuration stays out of the fingerprint,
+            // so changing it does not invalidate every checkpoint at once and restart
+            // every in-flight run from turn zero with its budget already spent. A run
+            // that resumes on a newly configured model resumes from conversation
+            // state, which is model-independent.
             soul: request.recipe.soul,
             toolFamilies: request.recipe.toolFamilies,
             enabled: request.recipe.enabled,
@@ -55,14 +54,6 @@ export function canonicalRequest(request) {
             role: ref.role,
             text: ref.text
         })),
-        dependencyResults: request.dependencyResults.map((dep) => ({
-            subtaskId: dep.subtaskId,
-            type: dep.type,
-            resultParts: dep.resultParts.map((part) => ({
-                kind: part.kind,
-                text: part.text
-            }))
-        })),
         // Params ARE identity: the same prompt against a different external resource
         // is different work, and must not replay a cached result. Key order is fixed
         // by sorting, so an equivalent params object always canonicalizes identically.