@loopingai/core 0.8.1 → 0.8.3

package/dist/a2a/deliver.d.ts

@@ -29,6 +29,40 @@ export interface DeliverTerminalOptions {
      * An agent with no managed children omits it and no `sweep` step appears.
      */
     sweep?: () => Promise<void>;
+    /**
+     * Prefix for this delivery's three step names. Empty by default, which is the
+     * only value an ordinary turn may use.
+     *
+     * **Step names are durable cache keys**, so this is not cosmetic. A workflow
+     * that delivers twice — an ordinary delivery, then
+     * {@link deliverAbandonedTask} from a `catch` above it — would otherwise call
+     * `step.do("complete")` a second time and be handed the *first* call's cached
+     * result, so the failed Task it built would never be written and the outcome
+     * would depend on Workflows' caching semantics for a step whose failure was
+     * caught. A distinct prefix makes the second delivery its own set of steps,
+     * where the guarded write decides the outcome as it is supposed to.
+     */
+    stepPrefix?: string;
+}
+/**
+ * Thrown when a delivery failed *after* its terminal Task was durably saved.
+ *
+ * The distinction it carries is the difference between "this turn produced
+ * nothing" and "this turn produced a result the gateway has not heard about
+ * yet", and only the first of those is an abandoned task.
+ *
+ * Without it, an ordinary delivery whose `notify` step exhausted its retries
+ * would unwind into an abandoned-task recovery, which would write a generic
+ * failure over a real answer. The guarded write refuses that now
+ * ({@link file://../db/models/tasks.ts}), but refusing it is not enough on its
+ * own: the recovery would then succeed at doing nothing, swallow a genuine
+ * callback failure, and log the word "abandoned" about a turn that completed.
+ * So the two work together — this stops the recovery being attempted, and the
+ * guard is the backstop for the narrow window where a `complete` step throws
+ * without saying whether its write applied.
+ */
+export declare class TaskAlreadyTerminalError extends Error {
+    constructor(cause: unknown);
 }
 /**
  * Persist a turn's terminal Task, then notify the gateway.
@@ -47,3 +81,79 @@ export interface DeliverTerminalOptions {
  * it. Everything it calls already lives here.
  */
 export declare function deliverTerminalTask(step: WorkflowStep, options: DeliverTerminalOptions): Promise<void>;
+/** What {@link deliverAbandonedTask} needs to end a turn nobody else will. */
+export interface AbandonedTaskOptions {
+    /** Which Task this is about, and where its callback goes. */
+    push: TurnPushContext;
+    /** The agent's card-signing key, for the callback JWT. */
+    signingKey: string;
+    /** The guarded write — same contract as {@link DeliverTerminalOptions.saveTask}. */
+    saveTask: (task: PlainTask) => Promise<boolean>;
+    /**
+     * The user-facing words. The host's, always: core ships no prompt copy and no
+     * user-facing copy, and a paraphrase invented at the failure site is exactly
+     * what this parameter exists to prevent.
+     */
+    text: string;
+    /** Best-effort child cleanup. Omitted by an agent that delegates to nothing. */
+    sweep?: () => Promise<void>;
+    /** Log prefix — conventionally the agent's tenant id. */
+    label?: string;
+}
+/**
+ * Turn an unrecoverable orchestration fault into a delivered failed Task.
+ *
+ * ## The failure this exists for
+ *
+ * A turn ends badly in two different ways. A **typed** failure — the models were
+ * tried and nothing usable came back — is a value, and the ordinary delivery
+ * path carries it. A **transient** fault instead throws, so the step retries and
+ * recovers without paying for a second inference. That is the right default.
+ *
+ * What neither covers is a transient fault that never stops being one. `step.do`
+ * retries a bounded number of times and then rethrows, and with nothing above it
+ * to catch that, the orchestration unwinds, the delivery path is never reached,
+ * and the Workflow instance errors with the Task still sitting in `working`. The
+ * user is told nothing at all — and because the instance dies mid-`run`, the
+ * runtime records it as *"your Worker's code had hung and would never generate a
+ * response"*, which reads like a bug in the workflow rather than a provider that
+ * was refusing every request.
+ *
+ * Observed exactly that way in a deployed agent on 2026-08-19: a turn step
+ * exhausted its four attempts against a rate-limited provider, and the agent
+ * simply went quiet.
+ *
+ * ## Three behaviours here are load-bearing
+ *
+ * **It resolves after a successful delivery — it does not rethrow.** Rethrowing
+ * would reproduce the very "hung Worker" record this exists to remove, and the
+ * instance genuinely has finished its job: the Task is terminal and the gateway
+ * has been told.
+ *
+ * **It rethrows the *original* `cause` when the delivery itself fails.**
+ * Swallowing there would mark the instance successful while the user got
+ * nothing — strictly worse than the erroring instance being replaced, because it
+ * would also be silent in the Workflows console. `cause` is what an operator
+ * needs to see, not the delivery's own secondary fault.
+ *
+ * **It refuses to run at all once a terminal Task exists.** A
+ * {@link TaskAlreadyTerminalError} means the ordinary delivery persisted its
+ * result and only the callback failed, so the original fault is rethrown and
+ * nothing is written. An earlier draft of this claimed the guarded write alone
+ * made that safe; it did not. The write refused only cancellation conflicts, so
+ * `completed → failed` applied cleanly and a turn that succeeded would have been
+ * rewritten as a generic failure because a webhook was flaky. The guard now
+ * refuses any terminal-over-different-terminal write as a backstop, and this
+ * check is what stops the attempt being made in the first place — without it the
+ * recovery would quietly succeed at doing nothing, swallowing a real callback
+ * failure and logging "abandoned" about a completed turn.
+ *
+ * ## Why it is exported rather than private to `/round`
+ *
+ * `runHandleTask` wraps itself in it, so every round agent gets this without
+ * asking. But an agent whose turn is a single inference writes its own workflow
+ * body and has the identical exposure — and the alternative to exporting this is
+ * that each such host reimplements the delivery, which is precisely the mistake
+ * this function was extracted from.
+ */
+export declare function deliverAbandonedTask(step: WorkflowStep, cause: unknown, options: AbandonedTaskOptions): Promise<void>;

package/dist/a2a/deliver.js

@@ -1,4 +1,30 @@
+import { buildFailedTask } from "./notify.js";
 import { createPushChannel } from "./push.js";
+/**
+ * Thrown when a delivery failed *after* its terminal Task was durably saved.
+ *
+ * The distinction it carries is the difference between "this turn produced
+ * nothing" and "this turn produced a result the gateway has not heard about
+ * yet", and only the first of those is an abandoned task.
+ *
+ * Without it, an ordinary delivery whose `notify` step exhausted its retries
+ * would unwind into an abandoned-task recovery, which would write a generic
+ * failure over a real answer. The guarded write refuses that now
+ * ({@link file://../db/models/tasks.ts}), but refusing it is not enough on its
+ * own: the recovery would then succeed at doing nothing, swallow a genuine
+ * callback failure, and log the word "abandoned" about a turn that completed.
+ * So the two work together — this stops the recovery being attempted, and the
+ * guard is the backstop for the narrow window where a `complete` step throws
+ * without saying whether its write applied.
+ */
+export class TaskAlreadyTerminalError extends Error {
+    constructor(cause) {
+        super("the terminal Task was saved; the callback after it failed", {
+            cause
+        });
+        this.name = "TaskAlreadyTerminalError";
+    }
+}
 /**
  * Persist a turn's terminal Task, then notify the gateway.
  *
@@ -16,7 +42,8 @@ import { createPushChannel } from "./push.js";
  * it. Everything it calls already lives here.
  */
 export async function deliverTerminalTask(step, options) {
-    const task = await step.do("complete", async () => {
+    const at = options.stepPrefix ?? "";
+    const task = await step.do(`${at}complete`, async () => {
         const terminal = options.terminal();
         return (await options.saveTask(terminal)) ? terminal : null;
     });
@@ -28,7 +55,7 @@ export async function deliverTerminalTask(step, options) {
     if (options.sweep) {
         const sweep = options.sweep;
         try {
-            await step.do("sweep", async () => {
+            await step.do(`${at}sweep`, async () => {
                 await sweep();
             });
         }
@@ -43,7 +70,116 @@ export async function deliverTerminalTask(step, options) {
     // terminal messageId is deterministic and the gateway is idempotent and
     // 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(options.signingKey, options.push).deliver(task);
+    //
+    // Wrapped, because by this line the Task is durably terminal: anything that
+    // fails from here is a callback that did not land, never a turn that produced
+    // nothing. See {@link TaskAlreadyTerminalError}.
+    try {
+        await step.do(`${at}notify`, async () => {
+            await createPushChannel(options.signingKey, options.push).deliver(task);
+        });
+    }
+    catch (err) {
+        throw new TaskAlreadyTerminalError(err);
+    }
+}
+/**
+ * The step-name prefix an abandoned delivery runs under.
+ *
+ * Its own namespace so it can never collide with the ordinary delivery's — see
+ * {@link DeliverTerminalOptions.stepPrefix}.
+ */
+const ABANDONED_PREFIX = "abandoned:";
+/**
+ * Turn an unrecoverable orchestration fault into a delivered failed Task.
+ *
+ * ## The failure this exists for
+ *
+ * A turn ends badly in two different ways. A **typed** failure — the models were
+ * tried and nothing usable came back — is a value, and the ordinary delivery
+ * path carries it. A **transient** fault instead throws, so the step retries and
+ * recovers without paying for a second inference. That is the right default.
+ *
+ * What neither covers is a transient fault that never stops being one. `step.do`
+ * retries a bounded number of times and then rethrows, and with nothing above it
+ * to catch that, the orchestration unwinds, the delivery path is never reached,
+ * and the Workflow instance errors with the Task still sitting in `working`. The
+ * user is told nothing at all — and because the instance dies mid-`run`, the
+ * runtime records it as *"your Worker's code had hung and would never generate a
+ * response"*, which reads like a bug in the workflow rather than a provider that
+ * was refusing every request.
+ *
+ * Observed exactly that way in a deployed agent on 2026-08-19: a turn step
+ * exhausted its four attempts against a rate-limited provider, and the agent
+ * simply went quiet.
+ *
+ * ## Three behaviours here are load-bearing
+ *
+ * **It resolves after a successful delivery — it does not rethrow.** Rethrowing
+ * would reproduce the very "hung Worker" record this exists to remove, and the
+ * instance genuinely has finished its job: the Task is terminal and the gateway
+ * has been told.
+ *
+ * **It rethrows the *original* `cause` when the delivery itself fails.**
+ * Swallowing there would mark the instance successful while the user got
+ * nothing — strictly worse than the erroring instance being replaced, because it
+ * would also be silent in the Workflows console. `cause` is what an operator
+ * needs to see, not the delivery's own secondary fault.
+ *
+ * **It refuses to run at all once a terminal Task exists.** A
+ * {@link TaskAlreadyTerminalError} means the ordinary delivery persisted its
+ * result and only the callback failed, so the original fault is rethrown and
+ * nothing is written. An earlier draft of this claimed the guarded write alone
+ * made that safe; it did not. The write refused only cancellation conflicts, so
+ * `completed → failed` applied cleanly and a turn that succeeded would have been
+ * rewritten as a generic failure because a webhook was flaky. The guard now
+ * refuses any terminal-over-different-terminal write as a backstop, and this
+ * check is what stops the attempt being made in the first place — without it the
+ * recovery would quietly succeed at doing nothing, swallowing a real callback
+ * failure and logging "abandoned" about a completed turn.
+ *
+ * ## Why it is exported rather than private to `/round`
+ *
+ * `runHandleTask` wraps itself in it, so every round agent gets this without
+ * asking. But an agent whose turn is a single inference writes its own workflow
+ * body and has the identical exposure — and the alternative to exporting this is
+ * that each such host reimplements the delivery, which is precisely the mistake
+ * this function was extracted from.
+ */
+export async function deliverAbandonedTask(step, cause, options) {
+    // Nothing was abandoned: the ordinary delivery already persisted a terminal
+    // Task and only its callback failed. Rethrow the fault that actually
+    // happened, so the instance still errors exactly as it did before any
+    // recovery existed and the gateway's own backstop clears the pending marker.
+    //
+    // Checked **here** rather than in each caller's `catch` on purpose. This whole
+    // change exists because a recovery every host had to remember to wire was one
+    // three hosts forgot; a caveat every host had to remember to check would be
+    // the same mistake a second time.
+    if (cause instanceof TaskAlreadyTerminalError)
+        throw cause.cause;
+    const label = options.label ?? "agent";
+    // Logged before anything is attempted: if the delivery below also fails, this
+    // line is the only record of what actually went wrong.
+    console.error(`[${label}] task abandoned after retries were exhausted`, {
+        taskId: options.push.taskId,
+        error: String(cause)
     });
+    try {
+        await deliverTerminalTask(step, {
+            push: options.push,
+            signingKey: options.signingKey,
+            saveTask: options.saveTask,
+            terminal: () => buildFailedTask(options.push.taskId, options.push.contextId, options.text),
+            sweep: options.sweep,
+            stepPrefix: ABANDONED_PREFIX
+        });
+    }
+    catch (deliveryFailed) {
+        console.error(`[${label}] could not deliver the failed Task`, {
+            taskId: options.push.taskId,
+            error: String(deliveryFailed)
+        });
+        throw cause;
+    }
 }

package/dist/a2a/index.d.ts

@@ -22,7 +22,7 @@ export { A2A_JWS_ALG, audienceFor, endpointUrl, jwksUrl } from "@loopingai/a2a-p
 export { IDENTITY_CLAIM, TENANT_CLAIM, GatewayAuthError, bearerToken, normalizeGatewayOrigins, verifyGatewayToken, type GatewayIdentity, type VerifyOptions } from "./verify.js";
 export { A2A_RPC_PATH, buildBaseCard, signCard, wireCard, parsePrivateJwk, publicCardJwks, type AgentManifest, type BuildCardOptions, type CardSigningConfig, type WireAgentCard } from "./card.js";
 export { NOTIFICATION_TOKEN_HEADER, buildSubmittedTask, buildWorkingTask, buildCompletedTask, buildFailedTask, buildNoReplyCompletedTask, signCallbackJwt, postNotification } from "./notify.js";
-export { deliverTerminalTask, type DeliverTerminalOptions } from "./deliver.js";
+export { deliverTerminalTask, deliverAbandonedTask, TaskAlreadyTerminalError, type DeliverTerminalOptions, type AbandonedTaskOptions } from "./deliver.js";
 export { signCallerToken, type CallerTokenOptions } from "./caller-token.js";
 export { SelfOrigin } from "./self-origin.js";
 export { callerContext } from "./caller.js";

package/dist/a2a/index.js

@@ -22,7 +22,7 @@ export { A2A_JWS_ALG, audienceFor, endpointUrl, jwksUrl } from "@loopingai/a2a-p
 export { IDENTITY_CLAIM, TENANT_CLAIM, GatewayAuthError, bearerToken, normalizeGatewayOrigins, verifyGatewayToken } from "./verify.js";
 export { A2A_RPC_PATH, buildBaseCard, signCard, wireCard, parsePrivateJwk, publicCardJwks } from "./card.js";
 export { NOTIFICATION_TOKEN_HEADER, buildSubmittedTask, buildWorkingTask, buildCompletedTask, buildFailedTask, buildNoReplyCompletedTask, signCallbackJwt, postNotification } from "./notify.js";
-export { deliverTerminalTask } from "./deliver.js";
+export { deliverTerminalTask, deliverAbandonedTask, TaskAlreadyTerminalError } from "./deliver.js";
 export { signCallerToken } from "./caller-token.js";
 export { SelfOrigin } from "./self-origin.js";
 export { callerContext } from "./caller.js";

package/dist/db/models/tasks.d.ts

@@ -78,6 +78,19 @@ export declare function makeTasks(db: DB): {
      * `canceled` onto a `submitted`/`working` row, or re-writing it onto an
      * already-`canceled` one, stays allowed: that is how the a2a-js handler's own
      * cancel branch records the cancellation.
+     *
+     * **And no terminal row may be replaced by a *different* terminal state.**
+     * The two rules above were written about cancellation and between them left
+     * `completed → failed` wide open, which is not hypothetical: a workflow whose
+     * `notify` step exhausts its retries throws *after* `complete` durably saved
+     * a completed Task, and an abandoned-task recovery above it would then write
+     * a generic failure over a real answer and post a callback contradicting it.
+     * A turn that succeeded would be recorded as having failed because a webhook
+     * was flaky.
+     *
+     * Same terminal state re-written is still allowed, and must be: a Workflow
+     * replay legitimately re-runs `complete` and saves what it already saved, and
+     * refusing that would suppress the callback that replay exists to send.
      */
     save(task: Task): boolean;
     /**

package/dist/db/models/tasks.js

@@ -15,6 +15,21 @@ function nowIso() {
 export function stateOf(task) {
     return task.status?.state ?? TaskState.TASK_STATE_UNSPECIFIED;
 }
+/**
+ * The states a task never leaves.
+ *
+ * `INPUT_REQUIRED` and `AUTH_REQUIRED` are deliberately absent: a turn parked on
+ * either is waiting, not finished, and will move again.
+ */
+const TERMINAL_STATES = new Set([
+    TaskState.TASK_STATE_COMPLETED,
+    TaskState.TASK_STATE_FAILED,
+    TaskState.TASK_STATE_CANCELED,
+    TaskState.TASK_STATE_REJECTED
+]);
+function isTerminal(state) {
+    return TERMINAL_STATES.has(state);
+}
 /**
  * Query methods for the `notify_tasks` table (async A2A task state).
  *
@@ -143,6 +158,19 @@ export function makeTasks(db) {
          * `canceled` onto a `submitted`/`working` row, or re-writing it onto an
          * already-`canceled` one, stays allowed: that is how the a2a-js handler's own
          * cancel branch records the cancellation.
+         *
+         * **And no terminal row may be replaced by a *different* terminal state.**
+         * The two rules above were written about cancellation and between them left
+         * `completed → failed` wide open, which is not hypothetical: a workflow whose
+         * `notify` step exhausts its retries throws *after* `complete` durably saved
+         * a completed Task, and an abandoned-task recovery above it would then write
+         * a generic failure over a real answer and post a callback contradicting it.
+         * A turn that succeeded would be recorded as having failed because a webhook
+         * was flaky.
+         *
+         * Same terminal state re-written is still allowed, and must be: a Workflow
+         * replay legitimately re-runs `complete` and saves what it already saved, and
+         * refusing that would suppress the callback that replay exists to send.
          */
         save(task) {
             const existing = readOne(task.id);
@@ -162,6 +190,11 @@ export function makeTasks(db) {
                 existingState !== TaskState.TASK_STATE_CANCELED) {
                 return false;
             }
+            if (isTerminal(existingState) &&
+                isTerminal(incomingState) &&
+                incomingState !== existingState) {
+                return false;
+            }
             upsert(task);
             return true;
         },

package/dist/round/turn.js

@@ -51,8 +51,9 @@ function byRound(branches) {
  * than carried, from the durable rows that are the record of what happened.
  *
  * Failed and skipped branches are included so the model can disclose them rather
- * than quietly answering as if the work had been done; their diagnostics are not
- * (see `delegateCallOutput`).
+ * than quietly answering as if the work had been done — and, since a failed
+ * branch carries its reason in `output`, so it can tell a wall it should stop
+ * at from a hiccup worth retrying (see `delegateCallOutput`).
  */
 function delegationPair(taskId, round, replyText, branches) {
     const toolCallId = delegateToolCallId(taskId, round);

package/dist/round/workflow.d.ts

@@ -102,6 +102,13 @@ export interface HandleTaskDeps {
      * with no change here.
      */
     signingKey: string;
+    /**
+     * Log prefix for the abandoned-task line, conventionally the agent's tenant
+     * id. Optional because nothing here needs it to work — but a deployment that
+     * mounts several agents on one Worker gets one log stream, and without this
+     * every one of them reports going quiet under the same name.
+     */
+    label?: string;
 }
 /**
  * The caller's agent DO stub — every phase runs through it.
@@ -112,19 +119,29 @@ export interface HandleTaskDeps {
  */
 type AgentStub = DurableObjectStub<RoundAgentBase>;
 /**
- * The orchestration itself, split from the `WorkflowEntrypoint` wiring so it can
- * be driven with a fake `step` in tests (workerd forbids constructing a
+ * The orchestration, split from the `WorkflowEntrypoint` wiring so it can be
+ * driven with a fake `step` in tests (workerd forbids constructing a
  * `WorkflowEntrypoint` outside the runtime) — and so a second agent can reuse it
  * with different deps.
  *
- * Every `step.do` return here is a small projection — a status, an id, a reply.
- * Never a Subtask row: a step return is capped at 1 MiB and a Subtask carries
- * verbatim history snapshots, so the rows stay in the DO and the Workflow carries
- * references to them.
+ * ## What the wrapper adds, and why it is not the host's job
+ *
+ * Core distinguishes two ways a turn ends badly. A **typed** failure is a value
+ * and {@link deliver} carries it. A **transient** fault throws, so the step
+ * retries and recovers from the durable rows without paying for a second
+ * inference. Neither covers a transient fault that never stops being one: the
+ * step exhausts its retries, {@link orchestrate} unwinds, the delivery below is
+ * never reached, and the instance errors with the Task still in `working` — the
+ * user told nothing, and the runtime recording a hang. See
+ * {@link deliverAbandonedTask}, which was written for a deployed agent that did
+ * exactly this on 2026-08-19.
  *
- * **Step names are durable cache keys.** Everything inside the round loop carries
- * its round for that reason: `turn:<round>`, `deadline:<round>`, `scan:<round>`,
- * `cancel:<round>`. Renaming one silently re-runs its effect on replay.
+ * This is caught **here** rather than left to each `WorkflowEntrypoint` because
+ * everything the recovery needs is already in {@link HandleTaskDeps}: the stub
+ * (typed on `RoundAgentBase`, so `saveTask` and `sweepTaskChildren` are both
+ * reachable), `policy.copy.taskFailed`, and `signingKey`. A host has nothing to
+ * add — so asking it to remember buys nothing and costs exactly what it cost the
+ * starter, where three of four agents never wrote the `catch` at all.
  */
 export declare function runHandleTask(p: HandleTaskParams, step: WorkflowStep, deps: HandleTaskDeps): Promise<void>;
 export {};

package/dist/round/workflow.js

@@ -1,6 +1,6 @@
 import { CHUNK_STEP, MAX_CHUNKS_PER_BRANCH, STEP_TIMEOUT_MS } from "../platform.js";
 import { buildCompletedTask, buildFailedTask } from "../a2a/notify.js";
-import { deliverTerminalTask } from "../a2a/deliver.js";
+import { deliverAbandonedTask, deliverTerminalTask } from "../a2a/deliver.js";
 /**
  * The same retries, and a timeout a **round** can actually be measured against.
  *
@@ -31,11 +31,67 @@ function turnStep(config) {
     };
 }
 /**
- * The orchestration itself, split from the `WorkflowEntrypoint` wiring so it can
- * be driven with a fake `step` in tests (workerd forbids constructing a
+ * The orchestration, split from the `WorkflowEntrypoint` wiring so it can be
+ * driven with a fake `step` in tests (workerd forbids constructing a
  * `WorkflowEntrypoint` outside the runtime) — and so a second agent can reuse it
  * with different deps.
  *
+ * ## What the wrapper adds, and why it is not the host's job
+ *
+ * Core distinguishes two ways a turn ends badly. A **typed** failure is a value
+ * and {@link deliver} carries it. A **transient** fault throws, so the step
+ * retries and recovers from the durable rows without paying for a second
+ * inference. Neither covers a transient fault that never stops being one: the
+ * step exhausts its retries, {@link orchestrate} unwinds, the delivery below is
+ * never reached, and the instance errors with the Task still in `working` — the
+ * user told nothing, and the runtime recording a hang. See
+ * {@link deliverAbandonedTask}, which was written for a deployed agent that did
+ * exactly this on 2026-08-19.
+ *
+ * This is caught **here** rather than left to each `WorkflowEntrypoint` because
+ * everything the recovery needs is already in {@link HandleTaskDeps}: the stub
+ * (typed on `RoundAgentBase`, so `saveTask` and `sweepTaskChildren` are both
+ * reachable), `policy.copy.taskFailed`, and `signingKey`. A host has nothing to
+ * add — so asking it to remember buys nothing and costs exactly what it cost the
+ * starter, where three of four agents never wrote the `catch` at all.
+ */
+export async function runHandleTask(p, step, deps) {
+    try {
+        await orchestrate(p, step, deps);
+    }
+    catch (cause) {
+        // Everything this needs is already in `deps` — which is the argument for it
+        // living here rather than in each host's `catch`. Four agents in the starter
+        // called this function and only one had written that `catch`; the other three
+        // carried the 2026-08-19 failure silently. A guard nobody can forget is worth
+        // more than a helper everybody must remember.
+        await deliverAbandonedTask(step, cause, {
+            push: {
+                taskId: p.taskId,
+                contextId: p.contextId,
+                pushUrl: p.pushUrl,
+                pushToken: p.pushToken,
+                jku: p.jku
+            },
+            signingKey: deps.signingKey,
+            // Resolved inside each closure, never hoisted — see {@link ResolveAgent}.
+            saveTask: (task) => deps.resolveAgent(p.identity).saveTask(task),
+            // The round never got far enough to say *which* credential or model was at
+            // fault, so `failureCopy` has nothing to answer and the policy's own words
+            // are the honest ones. The diagnostic is logged instead.
+            text: deps.policy.copy.taskFailed,
+            sweep: async () => {
+                await deps.resolveAgent(p.identity).sweepTaskChildren(p.taskId);
+            },
+            label: deps.label
+        });
+    }
+}
+/**
+ * The orchestration proper — every ordinary outcome ends inside here, and
+ * anything that escapes is what {@link runHandleTask} turns into a delivered
+ * failure.
+ *
  * Every `step.do` return here is a small projection — a status, an id, a reply.
  * Never a Subtask row: a step return is capped at 1 MiB and a Subtask carries
  * verbatim history snapshots, so the rows stay in the DO and the Workflow carries
@@ -43,9 +99,11 @@ function turnStep(config) {
  *
  * **Step names are durable cache keys.** Everything inside the round loop carries
  * its round for that reason: `turn:<round>`, `deadline:<round>`, `scan:<round>`,
- * `cancel:<round>`. Renaming one silently re-runs its effect on replay.
+ * `cancel:<round>`. Renaming one silently re-runs its effect on replay — and the
+ * recovery path in {@link runHandleTask} runs under its own prefix for the same
+ * reason, so a second delivery cannot be handed this one's cached results.
  */
-export async function runHandleTask(p, step, deps) {
+async function orchestrate(p, step, deps) {
     const limits = deps.config.mainAgentLimits;
     // 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.

package/dist/subtasks/delegate.d.ts

@@ -61,12 +61,29 @@ export declare function makeDelegateTool(types: SubtaskTypeRegistry, maxSubtasks
  */
 export declare function delegateToolCallId(taskId: string, round: number): string;
 /**
- * One branch's outcome, as the tool result carries it. `output` is null for any
- * branch that did not complete.
+ * One branch's outcome, as the tool result carries it. `output` carries the
+ * branch's report when it completed and its failure reason when it did not.
  *
- * There is no `error` field, and that is deliberate: internal diagnostics never
- * reach the model. It discloses *that* something failed, in user-safe words; the
- * durable row keeps the detail.
+ * **A failed branch says why, and that is a reversal worth explaining.** This
+ * used to be `null` for anything that did not complete, on the principle that
+ * internal diagnostics never reach the model. The principle was right about
+ * *diagnostics* and wrong about this field: what a facet writes into `error` is
+ * not a stack trace, it is a sentence addressed to the delegating model —
+ * "there is no checkout in this workspace yet… clone the repository before
+ * delegating", "every credential has reached its limit; send this request again
+ * after that". Withholding those left the parent with `status: "failed"` and
+ * nothing else, and a parent that cannot tell a transient failure from a
+ * permanent one retries. In the run that prompted this it retried twelve times
+ * over nine minutes, then apologised to the user for a wall it was never shown.
+ *
+ * What replaces the old rule is a constraint on the writer rather than a filter
+ * here: **an `error` is model-visible, so a facet must write it in words that
+ * are safe for one to read and act on.** Bounded by {@link MAX_OUTPUT_CHARS} on
+ * the way through, because a facet that ignores that is a context-window
+ * problem rather than a disclosure one.
+ *
+ * Still one field, not two. The model's question is "what came back from this
+ * branch", and `status` already says which kind of answer it is getting.
  *
  * A type alias, not an interface: this is serialized as the tool result's
  * `JSONValue`, and only aliases get the implicit index signature that satisfies.
@@ -93,5 +110,11 @@ export type DelegateSubtaskOutcome = {
  * and carries the durable `subtaskId`.
  */
 export declare function delegateCallInput(reply: string, branches: CompositionBranch[]): DecompositionProposal;
-/** Rebuild one round's call result from its durable rows, in stable ordinal order. */
+/**
+ * Rebuild one round's call result from its durable rows, in stable ordinal order.
+ *
+ * A completed branch reports its parts; any other branch reports its `error`, or
+ * `null` when it has none to give — a cancelled branch usually does not, and
+ * inventing a sentence for it would be worse than the absence.
+ */
 export declare function delegateCallOutput(branches: CompositionBranch[]): DelegateSubtaskOutcome[];

package/dist/subtasks/delegate.js

@@ -68,6 +68,21 @@ export function makeDelegateTool(types, maxSubtasks) {
 export function delegateToolCallId(taskId, round) {
     return `task_${taskId}_round_${round}_delegate`;
 }
+/**
+ * Ceiling on one branch's `output`, applied to both halves of it.
+ *
+ * A round's history holds every branch of every earlier round, so this is
+ * multiplied by the whole delegation history rather than paid once. Generous
+ * enough for a report a subagent meant to be read, far short of a build log a
+ * failing one dumped into `error`.
+ */
+const MAX_OUTPUT_CHARS = 8_000;
+function bounded(text) {
+    if (text.length <= MAX_OUTPUT_CHARS)
+        return text;
+    const suffix = "\n…[truncated]";
+    return `${text.slice(0, MAX_OUTPUT_CHARS - suffix.length)}${suffix}`;
+}
 /**
  * Rebuild one round's call input from its durable rows, in stable ordinal order.
  * Typed as {@link DecompositionProposal} — the same type the model's own calls
@@ -95,14 +110,22 @@ export function delegateCallInput(reply, branches) {
         }))
     };
 }
-/** Rebuild one round's call result from its durable rows, in stable ordinal order. */
+/**
+ * Rebuild one round's call result from its durable rows, in stable ordinal order.
+ *
+ * A completed branch reports its parts; any other branch reports its `error`, or
+ * `null` when it has none to give — a cancelled branch usually does not, and
+ * inventing a sentence for it would be worse than the absence.
+ */
 export function delegateCallOutput(branches) {
     return branches.map((branch) => ({
         subtaskId: branch.subtaskId,
         type: branch.type,
         status: branch.status,
         output: branch.status === "completed"
-            ? (branch.resultParts ?? []).map((part) => part.text).join("\n")
-            : null
+            ? bounded((branch.resultParts ?? []).map((part) => part.text).join("\n"))
+            : branch.error
+                ? bounded(branch.error)
+                : null
     }));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@loopingai/core",
-  "version": "0.8.1",
+  "version": "0.8.3",
   "description": "Shared, mandatory foundation for Looping agents on Cloudflare Workers: zero-trust A2A, durable task lifecycle, delegation and subagent runtime, test harness.",
   "keywords": [
     "a2a",