@dynamicagents/core 0.9.0

package/dist/round/workflow.d.ts

@@ -0,0 +1,147 @@
+import type { WorkflowStep } from "cloudflare:workers";
+import type { CoreConfig } from "../config.js";
+import type { GatekeeperIdentity } from "../a2a/verify.js";
+import type { RoundFailureKind } from "../agent/inference.js";
+import type { RoundAgentBase } from "./agent.js";
+import type { RoundPolicy } from "./policy.js";
+/**
+ * The async task controller. The gatekeeper does not wait for a synchronous reply:
+ * the Worker accepts a turn (returns a `submitted` Task) and hands the actual work
+ * to this durable Workflow, which orchestrates it end to end and delivers the
+ * reply to the gatekeeper's push-notification webhook.
+ *
+ * The shape is a **round loop**, not a fixed sequence of phases:
+ *
+ * 0. **Pre-work** — resolve the caller's agent, mark the Task working.
+ * 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 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 —
+ * `mainAgentLimits`, in turns or in wall clock — is handed no tools but the
+ * answer, so it has to give one; every other round chooses. That is the whole
+ * reason this is a loop, and the whole termination argument.
+ *
+ * Why a Workflow (not a DO alarm or `waitUntil`): `step.do(...)` gives durable,
+ * independently-retried steps that survive isolate eviction, and a future
+ * `escalate` decision (ask the human, then continue) slots in cleanly as another
+ * branch of the loop built on `step.waitForEvent(...)`.
+ *
+ * A Workflow is a separate entrypoint and cannot touch the agent DO's SQLite
+ * directly, so: the task inputs travel as the workflow **payload**, and the agent
+ * runtime plus task state are reached only through **native DO RPC**.
+ *
+ * Idempotency: the instance id is derived from the gatekeeper's `messageId`
+ * (deterministic across dispatch retries), so a re-dispatch never starts a second
+ * run. Within a run, every step is re-runnable: the Subtask rows and the Session
+ * are the source of truth, and each round recovers from them rather than
+ * re-inferring.
+ */
+export interface HandleTaskParams {
+    /** The accepted task id (echoed back to the gatekeeper on the callback). */
+    taskId: string;
+    /** The user turn text to answer. */
+    text: string;
+    /** The verified calling gatekeeper-agent identity (keys the DO + the Session). */
+    identity: GatekeeperIdentity;
+    /** A2A context id, echoed on the completed Task. */
+    contextId: string;
+    /** Gatekeeper push-notification webhook (also the callback JWT `aud`). */
+    pushUrl: string;
+    /** Per-task validation token the gatekeeper set; echoed in the callback header. */
+    pushToken: string;
+    /** This agent's card-signing JWKS URL — the callback JWT `jku` (pinned key). */
+    jku: string;
+}
+/**
+ * What distinguishes one agent's use of this loop from another's.
+ *
+ * The whole body below is agent-agnostic — it names no soul, no plugin and no
+ * model. Two delegating agents differ only in these values, which is why they
+ * share one workflow body behind two thin entrypoints rather than two copies of a
+ * 250-line orchestration.
+ */
+export interface HandleTaskDeps {
+    /**
+     * 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: GatekeeperIdentity) => 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
+     * its arguments — and so a Worker whose secret is named something else works
+     * 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.
+ *
+ * Typed on the abstract base rather than a concrete class: the orchestration
+ * below calls only methods the base declares, and every delegating agent's stub
+ * satisfies it.
+ */
+type AgentStub = DurableObjectStub<RoundAgentBase>;
+/**
+ * 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 declare function runHandleTask(p: HandleTaskParams, step: WorkflowStep, deps: HandleTaskDeps): Promise<void>;
+export {};

package/dist/round/workflow.js

@@ -0,0 +1,387 @@
+import { CHUNK_STEP, MAX_CHUNKS_PER_BRANCH, STEP_TIMEOUT_MS } from "../platform.js";
+import { buildCompletedTask, buildFailedTask } from "../a2a/notify.js";
+import { deliverAbandonedTask, 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, 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
+ * 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>`,
+ * `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.
+ */
+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.
+    // See {@link ResolveAgent}.
+    const agent = () => deps.resolveAgent(p.identity);
+    const push = {
+        taskId: p.taskId,
+        contextId: p.contextId,
+        pushUrl: p.pushUrl,
+        pushToken: p.pushToken,
+        jku: p.jku
+    };
+    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
+    // returns, so a replay reconstructs the identical number and the `mode` input
+    // below stays deterministic.
+    let turnsUsed = 0;
+    // The Task's own start, in a step so replays read the original instant rather
+    // than restarting the clock — otherwise a Workflow that retried its way through
+    // the night would never observe the deadline it had long since passed.
+    //
+    // When escalation lands, this is the line that needs care: a Task suspended on
+    // `step.waitForEvent(...)` must **rebase** it on resume, or a human's thinking
+    // time is charged to the agent and a Task that asked a question is dead before
+    // the answer arrives. `turnsUsed` needs no such handling — waiting costs none.
+    const startedAtMs = await step.do("started", async () => Date.now());
+    // At most one round per turn of the budget, **plus one**: an `open` round always
+    // spends at least one turn, so `maxTurns` of them exhaust the budget — and the
+    // forced-answer round that follows needs an iteration of its own to happen in.
+    // Off by one here and a Task of cheap rounds would fall out of the loop with no
+    // reply instead of being made to give one.
+    for (let round = 0; round <= limits.maxTurns; round++) {
+        // The clock is read *inside a step* so its answer is cached with the round:
+        // `mode` is a step input, and a replay that re-read `Date.now()` would
+        // reconstruct a different one. Time is the budget a Task can spend without
+        // spending the other — a round waiting on slow subtasks moves it while
+        // `turnsUsed` does not.
+        const overdue = await step.do(`deadline:${round}`, async () => Date.now() - startedAtMs >= limits.maxWallMs);
+        // Out of turns or out of time ⇒ this round gets no tools at all and must
+        // answer. Not a failure mode: it is how a ceiling returns the work instead of
+        // dropping it.
+        const mode = turnsUsed >= limits.maxTurns || overdue ? "final" : "open";
+        if (mode === "final") {
+            // Worth its own line: from the outside, a round the budget ended is
+            // indistinguishable from a model that simply chose to answer.
+            console.warn("[handle-task] task budget spent, forcing an answer", {
+                taskId: p.taskId,
+                round,
+                turnsUsed,
+                overdue
+            });
+        }
+        // The main agent decides. `runTaskTurn` persists whatever the round produced
+        // — a final reply, or the Subtask rows plus the acknowledgment it already
+        // pushed — so this step returns only the verdict plus what it cost. A typed
+        // `failed` is a real outcome (both models produced unusable output, with no
+        // 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}`, 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 agent().runTaskTurn({
+                taskId: p.taskId,
+                text: p.text,
+                identity: p.identity,
+                round,
+                mode,
+                turnsRemaining: limits.maxTurns - turnsUsed,
+                push
+            });
+            if (result.status === "replied")
+                return {
+                    status: result.status,
+                    reply: result.reply,
+                    turns: result.turns
+                };
+            if (result.status === "failed")
+                return {
+                    status: result.status,
+                    kind: result.kind,
+                    error: result.error,
+                    turns: result.turns
+                };
+            return { status: result.status, turns: result.turns };
+        });
+        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, {
+                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 Subtasks, then loop and let the model decide
+        // again.
+        const executed = await executeSubtasks(p, step, agent, round, push);
+        if (executed === "canceled")
+            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
+    // delegated with no turns left to do it with.
+    console.error("[handle-task] round budget exhausted without a reply", {
+        taskId: p.taskId
+    });
+    await deliver(p, step, agent, null, deps);
+}
+/**
+ * Run every Subtask one round delegated, concurrently, to termination.
+ *
+ * **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.
+ *
+ * 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 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);
+        });
+        return "canceled";
+    }
+    // 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
+ * make sure the row ends terminal either way.
+ *
+ * `executeSubtaskChunk(id, chunk)` advances one chunk: a single-chunk recipe is
+ * `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 {@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
+ * survives every retry — or a run that never terminates within the chunk budget —
+ * means nobody is left to resolve this row: fail *the branch* and let the next
+ * round disclose the gap, rather than discarding the durable work its siblings
+ * finished.
+ *
+ * What bounds a branch is its Recipe's turns and wall clock, both enforced inside
+ * the child, both ending in a report rather than a kill. `MAX_CHUNKS_PER_BRANCH`
+ * is a platform backstop held unreachable by design, so the `failSubtask` below
+ * should never fire — if it does, a Recipe has been given more turns than the cap
+ * allows.
+ *
+ * Step ids are unique across rounds (SQLite assigns them), so these names need no
+ * round prefix.
+ */
+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, 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;
+            });
+            if (done)
+                return;
+        }
+        // Unreachable while every Recipe's `maxTurns` stays under the cap: a chunk
+        // that yields always advanced a turn, so the budget summary comes first.
+        console.error("[handle-task] subtask exceeded its chunk budget", {
+            taskId: p.taskId,
+            subtaskId: id
+        });
+        await step.do(`fail:${id}`, async () => {
+            await agent().failSubtask(id, `execution exceeded ${MAX_CHUNKS_PER_BRANCH} chunks`);
+        });
+    }
+    catch (err) {
+        console.error("[handle-task] subtask execution exhausted retries", {
+            taskId: p.taskId,
+            subtaskId: id,
+            err: String(err)
+        });
+        await step.do(`fail:${id}`, async () => {
+            await agent().failSubtask(id, `execution exhausted retries: ${String(err)}`);
+        });
+    }
+}
+/**
+ * Persist the terminal Task, then notify the gatekeeper. A null `reply` delivers a
+ * `failed` Task with the policy's user-safe text; the diagnostic is already
+ * 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 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, 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
+        },
+        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

@@ -0,0 +1,127 @@
+import type { ToolSet } from "ai";
+import type { SessionMessage } from "agents/experimental/memory/session";
+import { type CoreConfig, type CoreConfigOverrides } from "../config.js";
+import { type AgentPlugin, type EnrichResultContext, type MainAgentToolContext, type ResolveRuntimeContext, type ToolFamilyBuilder, type TurnGateContext } from "../contract/plugin.js";
+import type { PluginStore } from "../db/db.js";
+import { type WorkspaceBacking } from "../subagent/workspace.js";
+import type { RecipePolicy } from "../contract/validation.js";
+import { type SubtaskTypeRegistry } from "../subtasks/subtask-types.js";
+import type { RecipeExecutionResult, SubtaskRuntime } from "../subtasks/types.js";
+export { buildRecipeTools, collectToolFamilies } from "./tool-families.js";
+/**
+ * The agent runtime: everything that used to be a module-level constant,
+ * resolved once per Durable Object instance from the host's config and its
+ * installed plugins.
+ *
+ * This is the whole point of the package split. In the predecessor repo the
+ * subtask registry was imported at module scope and every derived value — the
+ * type map, the delegate tool's enum and description, the round contract, the
+ * known-tool-family allowlist — was computed at *import time*. That made the
+ * registry unoverridable, pulled every domain's module into every bundle, and
+ * could not read `env`, which does not exist at module scope on Workers.
+ *
+ * Build it in `onStart`:
+ *
+ * ```ts
+ * async onStart() {
+ *   this.runtime = createAgentRuntime({
+ *     config: { model: { chatModelId: "…" } },
+ *     plugins: plugins(this.env)
+ *   });
+ * }
+ * ```
+ */
+export interface AgentRuntime {
+    config: CoreConfig;
+    plugins: readonly AgentPlugin[];
+    /** The installed subtask types — what `delegate` may name. */
+    types: SubtaskTypeRegistry;
+    /** Every tool family the installed plugins registered, by name. */
+    toolFamilies: ReadonlyMap<string, ToolFamilyBuilder>;
+    /** The capability boundary `validateRecipe` enforces. */
+    policy: RecipePolicy;
+    /** Plugin-owned stores, to hand to `new AgentDB(storage, { stores })`. */
+    stores: readonly PluginStore[];
+    /** Every binding and secret the installed plugins require of the host. */
+    requirements: {
+        secrets: string[];
+        bindings: string[];
+    };
+    /**
+     * The subagent workspace backend — the one plugin that declared it, or an
+     * in-memory fallback when none did. Always defined, so a host writes
+     * `workspaceBacking: runtime.workspaceBacking` into its `SubagentRuntime`
+     * unconditionally.
+     */
+    workspaceBacking: (sql: SqlStorage, name: () => string | undefined) => WorkspaceBacking;
+    /** The plugin that declared a subtask type, or null. */
+    pluginForType(type: string): AgentPlugin | null;
+    /** Tools the installed plugins offer the *main* agent, merged. */
+    mainAgentTools(ctx: MainAgentToolContext): Promise<ToolSet>;
+    /**
+     * 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;
+    /**
+     * Ask every plugin declaring {@link AgentPlugin.shouldHandleTurn} whether this
+     * turn should run. `true` when none declares one, and `false` if any single
+     * gate declines.
+     *
+     * Never rejects: a gate that fails is logged against its plugin key and
+     * counted as `true`, because the failure mode of a broken gate must be a noisy
+     * agent, never a silent one.
+     */
+    shouldHandleTurn(ctx: TurnGateContext): Promise<boolean>;
+    /**
+     * Announce the messages a compaction is folding into a summary to every plugin
+     * declaring {@link AgentPlugin.onMessagesDisplaced}. Pass it straight to
+     * `buildAgentSession`'s option of the same name — it reads no `this`, so the
+     * bare reference works.
+     *
+     * Never rejects: listeners are fanned out with `Promise.allSettled` and each
+     * rejection is logged against the plugin key that caused it.
+     */
+    onMessagesDisplaced(messages: SessionMessage[]): Promise<void>;
+    /**
+     * Resolve the session state an execution needs, by asking the plugin that owns
+     * its type. Returns `{}` for a type whose plugin declares no
+     * `resolveRuntime` — most of them.
+     */
+    resolveRuntime(ctx: ResolveRuntimeContext): Promise<SubtaskRuntime>;
+    /** Let the owning plugin amend a terminal result before it is persisted. */
+    enrichResult(ctx: EnrichResultContext, result: RecipeExecutionResult): Promise<RecipeExecutionResult>;
+    /** Let the owning plugin release whatever `resolveRuntime` acquired. */
+    onAbort(ctx: ResolveRuntimeContext): Promise<void>;
+}
+export interface CreateAgentRuntimeOptions {
+    plugins: readonly AgentPlugin[];
+    /**
+     * Required, because {@link CoreConfigOverrides} requires a model pair and core
+     * ships no default for it. Everything else in it stays optional.
+     */
+    config: CoreConfigOverrides;
+    /**
+     * Verify that every secret and binding the plugins declared is actually
+     * present, given the Worker `env`. Off by default because core cannot know
+     * which of a consumer's bindings are optional; pass `env` to switch it on.
+     *
+     * Typed `object`, not `Record<string, unknown>`, and that is not looseness.
+     * `Env` is the ambient interface `wrangler types` generates into a consumer's
+     * `worker-configuration.d.ts`; an interface has no index signature, so it does
+     * not satisfy `Record<string, unknown>` and every consumer would have to cast
+     * their own `this.env` to pass it. Requiring a cast to opt into a *check* is
+     * how the check goes unused.
+     */
+    env?: object;
+}
+/**
+ * Thrown when the installed plugins and the host disagree — a contract-version
+ * skew, a duplicate key, or a missing binding. Always at DO start, never mid-request.
+ */
+export declare class RuntimeSetupError extends Error {
+    constructor(message: string);
+}
+export declare function createAgentRuntime(options: CreateAgentRuntimeOptions): AgentRuntime;