@loopingai/core 0.5.0 → 0.6.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,14 +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 };
 }
-//# sourceMappingURL=turn.js.map

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 —
@@ -66,12 +67,34 @@ export interface HandleTaskParams {
  * 250-line orchestration.
  */
 export interface HandleTaskDeps {
-    /** Route to the right DO class for the verified caller. */
+    /**
+     * Route to the right DO class for the verified caller.
+     *
+     * Called **once per step body**, not once per run, so it must stay a cheap
+     * pure lookup — a namespace `get`, nothing cached and nothing awaited. See
+     * {@link ResolveAgent} for why the result must never be hoisted.
+     */
     resolveAgent: (identity: GatewayIdentity) => AgentStub;
     /** Resolved config — the loop reads `mainAgentLimits` and `maxSubtasks`. */
     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
@@ -100,10 +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 {};
-//# sourceMappingURL=workflow.d.ts.map

package/dist/round/workflow.js

@@ -1,7 +1,65 @@
-import { MAX_CHUNKS_PER_BRANCH } from "../platform.js";
+import { 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";
+/**
+ * What the long steps configure instead of inheriting.
+ *
+ * Both halves of this were previously left at Workflows' defaults, and both
+ * defaults were wrong for this workload.
+ *
+ * **`timeout`.** The default is ten minutes. Nothing here passed a config, so that
+ * default silently became the ceiling {@link CHUNK_SOFT_MS} was sized against —
+ * see the note on `STEP_TIMEOUT_MS` in `platform.ts` for what that cost. A step
+ * here holds a model call and its provider retries, or a container command running
+ * a project's test suite; neither fits in ten minutes reliably and neither uses
+ * meaningful CPU while it waits.
+ *
+ * **`retries`.** The default is five attempts with exponential backoff from ten
+ * seconds. The failure documented on {@link ResolveAgent} is what that produces
+ * when the fault is not transient: five retries against a severed stub, each
+ * failing in under 10ms, spread across 160 seconds of backoff that bought nothing.
+ * Three attempts still cover a genuinely transient fault — the model call has its
+ * own provider-level retry underneath this — and a flat five-second delay stops a
+ * fast, permanent failure from being paid for at exponential rates.
+ *
+ * Deliberately applied only to the chunk steps — see {@link turnStep} for why a
+ * round does not share it. The short bookkeeping steps (`working`, `deadline:`,
+ * `scan:`, `complete`, `notify`) are sub-second projections where the defaults
+ * are fine and a shared config would only hide that.
+ */
+const CHUNK_STEP = {
+    timeout: STEP_TIMEOUT_MS,
+    retries: { limit: 3, delay: 5_000, backoff: "constant" }
+};
+/**
+ * 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,14 +72,15 @@ 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;
-    // Pre-work. Routing is pure, so it needs no step of its own.
-    const stub = deps.resolveAgent(p.identity);
+    // Pre-work. Routing is pure, so it needs no step of its own — but it is
+    // deliberately *not* resolved here into a value the steps below close over.
+    // See {@link ResolveAgent}.
+    const agent = () => deps.resolveAgent(p.identity);
     const push = {
         taskId: p.taskId,
         contextId: p.contextId,
@@ -29,7 +88,7 @@ export async function runHandleTask(p, step, deps) {
         pushToken: p.pushToken,
         jku: p.jku
     };
-    const started = await step.do("working", async () => (await stub.markWorking(p.taskId)) === "ok");
+    const started = await step.do("working", async () => (await agent().markWorking(p.taskId)) === "ok");
     if (!started)
         return;
     // Main-agent turns spent so far, across every round. Summed from cached step
@@ -78,11 +137,11 @@ 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.
-            const result = await stub.runTaskTurn({
+            const result = await agent().runTaskTurn({
                 taskId: p.taskId,
                 text: p.text,
                 identity: p.identity,
@@ -100,6 +159,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
                 };
@@ -108,27 +168,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, stub, null, deps);
+            await deliver(p, step, agent, null, deps, {
+                kind: turn.kind,
+                detail: turn.error
+            });
             return;
         }
         if (turn.status === "replied") {
-            await deliver(p, step, stub, turn.reply, deps);
+            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, stub, 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, stub, 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
@@ -136,61 +202,52 @@ export async function runHandleTask(p, step, deps) {
     console.error("[handle-task] round budget exhausted without a reply", {
         taskId: p.taskId
     });
-    await deliver(p, step, stub, null, 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, stub, 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 stub.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 stub.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, stub, 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
@@ -200,7 +257,9 @@ async function executeDag(p, step, stub, 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
@@ -218,15 +277,15 @@ async function executeDag(p, step, stub, round, push, deps) {
  * Step ids are unique across rounds (SQLite assigns them), so these names need no
  * round prefix.
  */
-async function runBranch(p, step, stub, id, push) {
+async function runBranch(p, step, agent, id, push) {
     try {
         for (let chunk = 0; chunk < MAX_CHUNKS_PER_BRANCH; chunk++) {
             // 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 stub.executeSubtaskChunk(id, chunk, push);
+                const outcome = await agent().executeSubtaskChunk(id, chunk, push);
                 return outcome.done;
             });
             if (done)
@@ -239,7 +298,7 @@ async function runBranch(p, step, stub, id, push) {
             subtaskId: id
         });
         await step.do(`fail:${id}`, async () => {
-            await stub.failSubtask(id, `execution exceeded ${MAX_CHUNKS_PER_BRANCH} chunks`);
+            await agent().failSubtask(id, `execution exceeded ${MAX_CHUNKS_PER_BRANCH} chunks`);
         });
     }
     catch (err) {
@@ -249,14 +308,20 @@ async function runBranch(p, step, stub, id, push) {
             err: String(err)
         });
         await step.do(`fail:${id}`, async () => {
-            await stub.failSubtask(id, `execution exhausted retries: ${String(err)}`);
+            await agent().failSubtask(id, `execution exhausted retries: ${String(err)}`);
         });
     }
 }
 /**
  * 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.
+ *
+ * `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 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
@@ -269,12 +334,16 @@ async function runBranch(p, step, stub, id, push) {
  * `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.
  */
-async function deliver(p, step, stub, reply, deps) {
+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;
     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 stub.saveTask(terminal)) ? terminal : null;
+            : buildFailedTask(p.taskId, p.contextId, failedText);
+        return (await agent().saveTask(terminal)) ? terminal : null;
     });
     if (!task)
         return;
@@ -290,7 +359,7 @@ async function deliver(p, step, stub, reply, deps) {
     // this Task's children were reclaimed.
     try {
         await step.do("sweep", async () => {
-            await stub.sweepTaskChildren(p.taskId);
+            await agent().sweepTaskChildren(p.taskId);
         });
     }
     catch (err) {
@@ -313,4 +382,3 @@ async function deliver(p, step, stub, reply, deps) {
         }).deliver(task);
     });
 }
-//# sourceMappingURL=workflow.js.map

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;
     /**
@@ -123,4 +125,3 @@ export declare class RuntimeSetupError extends Error {
     constructor(message: string);
 }
 export declare function createAgentRuntime(options: CreateAgentRuntimeOptions): AgentRuntime;
-//# sourceMappingURL=index.d.ts.map

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");
         },
@@ -178,4 +184,3 @@ export function createAgentRuntime(options) {
         }
     };
 }
-//# sourceMappingURL=index.js.map

package/dist/runtime/tool-families.d.ts

@@ -30,4 +30,3 @@ export declare function collectToolFamilies<TRuntime = SubtaskRuntime>(plugins:
     key: string;
     toolFamilies?: Record<string, ToolFamilyBuilder<TRuntime>>;
 }[]): Map<string, ToolFamilyBuilder<TRuntime>>;
-//# sourceMappingURL=tool-families.d.ts.map

package/dist/runtime/tool-families.js

@@ -59,4 +59,3 @@ export function collectToolFamilies(plugins) {
     }
     return registry;
 }
-//# sourceMappingURL=tool-families.js.map

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
@@ -35,4 +35,3 @@ export declare function canonicalRequest(request: RecipeExecutionRequest): strin
  * fingerprinted, so the key matches exactly what the parent re-sends on retry.
  */
 export declare function fingerprintRequest(request: RecipeExecutionRequest): Promise<string>;
-//# sourceMappingURL=fingerprint.d.ts.map