@dynamicagents/core 0.9.0

package/dist/round/index.d.ts

@@ -0,0 +1,25 @@
+/**
+ * `@dynamicagents/core/round` — the delegating round loop.
+ *
+ * A round agent answers the user or hands work to isolated subagents, waits for
+ * their durable results, and decides again. This subpath ships the whole
+ * mechanism of that: the round loop and its primary→fallback→repair ladder
+ * ({@link runTurn}), the durable Workflow orchestration that runs a round's
+ * subtasks concurrently ({@link runHandleTask}), the Durable Object body ({@link
+ * RoundAgentBase}), and the subagent facet host ({@link RecipeSubagentHost}).
+ *
+ * **Opt-in, and its own subpath on purpose.** An agent whose turn is a single
+ * inference — one that never delegates — imports none of this and carries none of
+ * it in its bundle. Core's root barrel does not re-export it.
+ *
+ * **Core still ships no prompt copy.** Everything the model and the user read
+ * comes from the {@link RoundPolicy} an agent supplies: the round contract, the
+ * budget-spent note, and the three user-facing strings. That is the line — core
+ * owns the machine, you own the words.
+ */
+export type { RoundPolicy } from "./policy.js";
+export { RoundAgentBase } from "./agent.js";
+export { RecipeSubagentHost, type SubagentClass } from "./subagent.js";
+export { runHandleTask, type HandleTaskDeps, type HandleTaskParams } from "./workflow.js";
+export type { NonRecoverableKind, RoundFailureKind } from "../agent/inference.js";
+export { buildTurnInstructions, joinSuccessfulBranches, renderTurnMessages, runTurn, type RoundMode, type RunTurnArgs, type RunTurnOutcome, type TurnInstructions } from "./turn.js";

package/dist/round/index.js

@@ -0,0 +1,23 @@
+/**
+ * `@dynamicagents/core/round` — the delegating round loop.
+ *
+ * A round agent answers the user or hands work to isolated subagents, waits for
+ * their durable results, and decides again. This subpath ships the whole
+ * mechanism of that: the round loop and its primary→fallback→repair ladder
+ * ({@link runTurn}), the durable Workflow orchestration that runs a round's
+ * subtasks concurrently ({@link runHandleTask}), the Durable Object body ({@link
+ * RoundAgentBase}), and the subagent facet host ({@link RecipeSubagentHost}).
+ *
+ * **Opt-in, and its own subpath on purpose.** An agent whose turn is a single
+ * inference — one that never delegates — imports none of this and carries none of
+ * it in its bundle. Core's root barrel does not re-export it.
+ *
+ * **Core still ships no prompt copy.** Everything the model and the user read
+ * comes from the {@link RoundPolicy} an agent supplies: the round contract, the
+ * budget-spent note, and the three user-facing strings. That is the line — core
+ * owns the machine, you own the words.
+ */
+export { RoundAgentBase } from "./agent.js";
+export { RecipeSubagentHost } from "./subagent.js";
+export { runHandleTask } from "./workflow.js";
+export { buildTurnInstructions, joinSuccessfulBranches, renderTurnMessages, runTurn } from "./turn.js";

package/dist/round/policy.d.ts

@@ -0,0 +1,98 @@
+import type { AgentLimits } from "../config.js";
+/**
+ * Everything about a round loop that is **yours**, not core's.
+ *
+ * The round loop in this subpath is mechanism: concurrent subtask execution,
+ * chunked subagent runs, cancellation ordering, idempotent recovery, the
+ * primary→fallback→repair ladder. None of it varies between agents, and every
+ * place it *did* vary between two agents in one repo turned out to be a bug.
+ *
+ * What genuinely varies is what the model is told and what the user reads — and
+ * core ships no prompt copy, deliberately, so that no run ever executes under an
+ * identity nobody chose. This interface is that boundary, made explicit: supply
+ * the words, get the machine.
+ *
+ * ```ts
+ * export const policy: RoundPolicy = {
+ *   roundContract: ({ typeKeys, maxSubtasks }) => `…`,
+ *   finalRoundNote: (limits) => `…`,
+ *   copy: {
+ *     taskFailed: "Sorry — something went wrong handling that request.",
+ *     recoveredReply: "Working on your request.",
+ *     partialNote: "Some parts of this request could not be completed…"
+ *   }
+ * };
+ * ```
+ *
+ * Nothing here is optional and nothing has a default. A stub that returned an
+ * empty contract would produce a round the model has no way to end correctly,
+ * and a lending default would be exactly the house prompt copy core refuses to
+ * have.
+ *
+ * ## Each prompt string owns its own leading separator
+ *
+ * {@link roundContract} and {@link finalRoundNote} are concatenated directly
+ * onto text that came from somewhere else — the soul, the caller context, and
+ * for `finalRoundNote` the open contract itself. The composition adds nothing
+ * between them, so **start each with a blank line** (`\n\n`, or a template
+ * literal opening on an empty line, which is what the starter does):
+ *
+ * ```ts
+ * roundContract: () => `
+ *
+ * # Answering this request
+ * …`
+ * ```
+ *
+ * Return `"# Answering this request…"` with no leading newline and the model
+ * reads `Calling workspace: 1.# Answering this request` — a run-together line
+ * that costs nothing to produce and is invisible in every test that does not
+ * assert on the rendered prompt.
+ *
+ * Core does not insert the separator for you, because these are *your* sections
+ * and a section that cannot control its own spacing cannot control its shape —
+ * a policy that legitimately wants a single newline, or continues the previous
+ * paragraph, has no way to say so once core has decided.
+ */
+export interface RoundPolicy {
+    /**
+     * The round contract: how a round ends, and what `delegate` takes. Appended to
+     * the soul and the caller context on every round.
+     *
+     * `typeKeys` is the installed subtask types — the only values `delegate` may
+     * name. Per-type guidance is *not* written here: each type declares its own
+     * via `SubtaskTypeSpec.delegationGuidance`, and the loop appends it, so this
+     * text names no domain.
+     */
+    roundContract(ctx: {
+        typeKeys: readonly string[];
+        maxSubtasks: number;
+    }): string;
+    /**
+     * Appended when the task has spent its budget. That round is handed no work
+     * tools and no `delegate`, so this explains a constraint the model can already
+     * see rather than imposing one.
+     */
+    finalRoundNote(limits: AgentLimits): string;
+    /** The strings a user can actually read. */
+    copy: {
+        /**
+         * User-facing text on a failed Task. The diagnostic is logged separately —
+         * this is what the person sees.
+         */
+        taskFailed: string;
+        /**
+         * Stand-in acknowledgement for the unreachable case where a round's subtasks
+         * are durable but its acknowledgement is not in the Session. Neutral by
+         * design: the work is valid and running, so the user gets an honest
+         * acknowledgement rather than a failed Task.
+         */
+        recoveredReply: string;
+        /**
+         * Appended when a deterministic join has to disclose gaps — both models
+         * failed, but earlier branches succeeded and their results are worth
+         * delivering.
+         */
+        partialNote: string;
+    };
+}

package/dist/round/policy.js

@@ -0,0 +1 @@
+export {};

package/dist/round/subagent.d.ts

@@ -0,0 +1,87 @@
+import type { AgentPlugin } from "../contract/plugin.js";
+import type { CoreConfigOverrides, ModelConfig } from "../config.js";
+import type { AiEnv } from "../env.js";
+import type { ModelRuntime } from "../agent/model.js";
+import { RecipeSubagentBase, type SubagentRuntime } from "../subagent/index.js";
+import type { PluginHost } from "../host/plugin-host.js";
+/**
+ * The host half of a subagent facet: the same plugins as its parent, assembled
+ * into the {@link SubagentRuntime} the base class executes recipes with.
+ *
+ * `RecipeSubagentBase` already ships the whole body — resumable chunks, the
+ * terminal-result cache keyed by request fingerprint, workspace wiring,
+ * cancellation, the fingerprint-mismatch contract. All that was ever missing is
+ * this assembly, and a Durable Object class is constructed by the runtime, so it
+ * cannot take constructor arguments. The two abstract methods are that seam.
+ *
+ * ## Why the facet builds its own runtime instead of asking its parent
+ *
+ * The obvious move is to read it off the parent, which already has one. It does
+ * not work: the SDK reaches a parent through `this.parentAgent(Cls)`, which is an
+ * **RPC stub**, and a `SubagentRuntime` is mostly functions — `models`, the
+ * `toolFamilies` builder map, `workspaceBacking`. None of that survives
+ * serialization, so the call would return a shape that type-checks and is inert.
+ *
+ * So each agent gets its own facet class over this base, building the same
+ * runtime from the same `plugins.ts` its parent uses:
+ *
+ * ```ts
+ * export class MySubagent extends RecipeSubagentHost<Env> {
+ *   protected agentConfig() { return MY_CONFIG; }
+ *   protected agentPlugins(host: PluginHost<Env>) { return plugins(host); }
+ * }
+ * ```
+ *
+ * It must be a **named, exported** class, not one produced by a factory: the
+ * framework resolves a facet through `ctx.exports[this.constructor.name]`, so an
+ * anonymous class breaks the lookup, and so does a bundler that minifies class
+ * names.
+ *
+ * ## Not a bound Durable Object
+ *
+ * A facet is created beneath its calling agent, so it needs no wrangler binding
+ * and no `new_sqlite_classes` entry — only an export from the Worker entry so
+ * `ctx.exports` can resolve it. It *does* need a test-only binding, because the
+ * Vitest pool only marks bound classes as DO classes.
+ */
+export declare abstract class RecipeSubagentHost<TEnv extends Cloudflare.Env & AiEnv = Cloudflare.Env & AiEnv> extends RecipeSubagentBase<TEnv> {
+    private _rt?;
+    /** This facet's agent config — the same object its parent DO passes. */
+    protected abstract agentConfig(): CoreConfigOverrides;
+    /** This facet's plugins — the same list its parent DO installs. */
+    protected abstract agentPlugins(host: PluginHost<TEnv>): AgentPlugin[];
+    /**
+     * Built once per facet instance. The base calls this per RPC and documents
+     * that an implementation building anything expensive should memoize its own.
+     */
+    protected subagentRuntime(): SubagentRuntime;
+    /**
+     * Which provider this facet's chunks run on. Mirrors
+     * {@link file://../host/agent.ts DynamicAgent.modelRuntime}, and **must be
+     * overridden to match it** — a facet that keeps the Workers AI default while
+     * its parent runs on another provider would silently execute every subtask on
+     * a different model than the round that delegated it.
+     *
+     * The two seams take the same arguments precisely so that keeping them in step
+     * needs no discipline: write the provider once as a
+     * {@link file://../agent/model.ts ModelRuntimeFactory} and have both return
+     * it. Two hand-copied runtime-construction bodies is what this shape exists to
+     * stop, because nothing type-checks their agreement.
+     *
+     * Note the cheapest way to satisfy this is to override *neither* seam, which
+     * is what an agent on core's default does.
+     *
+     * Takes the model config rather than reading `this.config`, because the facet
+     * resolves its config inside `buildRuntime` and this is called from there.
+     */
+    protected modelRuntime(model: ModelConfig): ModelRuntime;
+    private buildRuntime;
+}
+/**
+ * A **concrete** facet constructor, as `subAgent()` requires one.
+ *
+ * {@link RecipeSubagentHost} is abstract, and `subAgent()` rightly refuses an
+ * abstract class — it is what constructs one. So the seam on the agent side is
+ * typed as this: any named subclass below it.
+ */
+export type SubagentClass = new (...args: ConstructorParameters<typeof RecipeSubagentBase>) => RecipeSubagentBase;

package/dist/round/subagent.js

@@ -0,0 +1,108 @@
+import { createAgentRuntime } from "../runtime/index.js";
+import { workersAIModels } from "../agent/workers-ai/index.js";
+import { RecipeSubagentBase } from "../subagent/index.js";
+/**
+ * The host half of a subagent facet: the same plugins as its parent, assembled
+ * into the {@link SubagentRuntime} the base class executes recipes with.
+ *
+ * `RecipeSubagentBase` already ships the whole body — resumable chunks, the
+ * terminal-result cache keyed by request fingerprint, workspace wiring,
+ * cancellation, the fingerprint-mismatch contract. All that was ever missing is
+ * this assembly, and a Durable Object class is constructed by the runtime, so it
+ * cannot take constructor arguments. The two abstract methods are that seam.
+ *
+ * ## Why the facet builds its own runtime instead of asking its parent
+ *
+ * The obvious move is to read it off the parent, which already has one. It does
+ * not work: the SDK reaches a parent through `this.parentAgent(Cls)`, which is an
+ * **RPC stub**, and a `SubagentRuntime` is mostly functions — `models`, the
+ * `toolFamilies` builder map, `workspaceBacking`. None of that survives
+ * serialization, so the call would return a shape that type-checks and is inert.
+ *
+ * So each agent gets its own facet class over this base, building the same
+ * runtime from the same `plugins.ts` its parent uses:
+ *
+ * ```ts
+ * export class MySubagent extends RecipeSubagentHost<Env> {
+ *   protected agentConfig() { return MY_CONFIG; }
+ *   protected agentPlugins(host: PluginHost<Env>) { return plugins(host); }
+ * }
+ * ```
+ *
+ * It must be a **named, exported** class, not one produced by a factory: the
+ * framework resolves a facet through `ctx.exports[this.constructor.name]`, so an
+ * anonymous class breaks the lookup, and so does a bundler that minifies class
+ * names.
+ *
+ * ## Not a bound Durable Object
+ *
+ * A facet is created beneath its calling agent, so it needs no wrangler binding
+ * and no `new_sqlite_classes` entry — only an export from the Worker entry so
+ * `ctx.exports` can resolve it. It *does* need a test-only binding, because the
+ * Vitest pool only marks bound classes as DO classes.
+ */
+export class RecipeSubagentHost extends RecipeSubagentBase {
+    _rt;
+    /**
+     * Built once per facet instance. The base calls this per RPC and documents
+     * that an implementation building anything expensive should memoize its own.
+     */
+    subagentRuntime() {
+        return (this._rt ??= this.buildRuntime());
+    }
+    /**
+     * Which provider this facet's chunks run on. Mirrors
+     * {@link file://../host/agent.ts DynamicAgent.modelRuntime}, and **must be
+     * overridden to match it** — a facet that keeps the Workers AI default while
+     * its parent runs on another provider would silently execute every subtask on
+     * a different model than the round that delegated it.
+     *
+     * The two seams take the same arguments precisely so that keeping them in step
+     * needs no discipline: write the provider once as a
+     * {@link file://../agent/model.ts ModelRuntimeFactory} and have both return
+     * it. Two hand-copied runtime-construction bodies is what this shape exists to
+     * stop, because nothing type-checks their agreement.
+     *
+     * Note the cheapest way to satisfy this is to override *neither* seam, which
+     * is what an agent on core's default does.
+     *
+     * Takes the model config rather than reading `this.config`, because the facet
+     * resolves its config inside `buildRuntime` and this is called from there.
+     */
+    modelRuntime(model) {
+        return workersAIModels(this.env, model);
+    }
+    buildRuntime() {
+        const config = this.agentConfig();
+        const runtime = createAgentRuntime({
+            config,
+            plugins: this.agentPlugins({
+                env: this.env,
+                storage: this.ctx.storage,
+                // No caller identity exists down here, and nothing reads one: the
+                // per-caller hooks are the parent's surface, never a subagent's. A
+                // throwing thunk is the honest encoding — it can only fire if a plugin
+                // starts reading caller state on the execution path, which is a design
+                // question, not a missing value.
+                callerKey: () => {
+                    throw new Error("a subagent execution has no caller identity — this plugin reads " +
+                        "per-caller state on a path where none exists");
+                },
+                aiGatewayId: config.model?.aiGatewayId ?? ""
+            }),
+            env: this.env
+        });
+        return {
+            policy: runtime.policy,
+            types: runtime.types,
+            models: this.modelRuntime(runtime.config.model),
+            toolFamilies: runtime.toolFamilies,
+            toolOutputWindow: runtime.config.toolOutputWindow,
+            maxOutputTokens: runtime.config.model.maxOutputTokens,
+            maxRetries: runtime.config.model.maxRetries,
+            // Always defined: the plugin that declared a backend, or core's in-memory
+            // fallback. So this needs no null check.
+            workspaceBacking: runtime.workspaceBacking
+        };
+    }
+}

package/dist/round/turn.d.ts

@@ -0,0 +1,249 @@
+import type { ModelMessage, ToolSet } from "ai";
+import type { SessionMessage } from "agents/experimental/memory/session";
+import type { AgentLimits } from "../config.js";
+import type { SubtaskTypeRegistry } from "../subtasks/subtask-types.js";
+import { type SessionLike } from "../agent/session.js";
+import { type OnContent, type RoundFailureKind } from "../agent/inference.js";
+import { type TurnBudget } from "../agent/budget.js";
+import type { ModelPair } from "../agent/model.js";
+import { type ReferenceCatalogEntry } from "../subtasks/catalog.js";
+import type { CompositionBranch, SubtaskDraft } from "../subtasks/types.js";
+import type { RoundPolicy } from "./policy.js";
+/**
+ * One **round** of the main agent: a single inference over the agent's continuous
+ * Session that ends in one of two decisions — answer the user, or delegate.
+ *
+ * This is the whole task pipeline's control point. The Workflow runs rounds in a
+ * loop: a round that delegates gets its Subtasks executed and is followed by
+ * another round; a round that answers ends the Task. So "compose" is not a
+ * separate phase with its own rules — it is simply the round in which the model
+ * decides it has enough to answer.
+ *
+ * Two layers of tools, and the difference is the design:
+ *
+ * - **Work tools** (whatever the installed plugins offer the main agent, plus the
+ *   Session's own `set_context`) carry an `execute` and run *inside* the round's
+ *   tool loop. They never end a round; the model keeps reasoning over their
+ *   results. Every round gets them except the one the budget forced — looking
+ *   something up before answering is ordinary work, not a special phase, right up
+ *   until there is nothing left to spend on it (see {@link RoundMode}).
+ * - **Control tools** — `delegate` and `final_reply` — have no `execute`. The call
+ *   *is* the round's output: the loop halts on it, and for `delegate` the Workflow
+ *   performs it durably. Because the loop halts, the SDK never validates their
+ *   input either, so each one checks its own and the round repairs what it rejects
+ *   — see `agent/control.ts`. A future `escalate` (ask the human) is the same
+ *   shape: another entry there, another variant of {@link TurnDecision}, another
+ *   `case` in the Workflow's switch.
+ *
+ * Nothing forces the *choice*, and that is deliberate. An earlier design pinned
+ * `toolChoice` to a specific tool to force delegation in one phase and forbid it in
+ * another, which meant a request the main agent was best placed to answer got
+ * shipped to a memoryless subagent, and material that came back could only ever be
+ * turned into prose. That is still rejected: the model picks its own ending, and
+ * delegating twice is allowed.
+ *
+ * What *is* forced is that the round end in a control call at all —
+ * `toolChoice: "required"`, with both endings declared as tools. Prose is not an
+ * outcome: see {@link file://../agent/final-reply.ts final-reply.ts} for why not.
+ *
+ * Narration survived that fix by moving house. A round whose results have just come
+ * back can still announce its next step *inside* a `final_reply` — "now sending the
+ * second one" — and that ends the Task as surely as prose did, having done nothing,
+ * while telling the user the opposite. No mechanism can catch it: `final_reply` is a
+ * legitimate ending for exactly this round, and only the model knows whether the
+ * request is finished. So it is the **round contract** that has to close it — which
+ * is why that text is a {@link RoundPolicy} the agent writes, not something core
+ * ships.
+ *
+ * The model reasons over the whole conversation but references it by **catalog
+ * index only** — see {@link renderTurnMessages}.
+ */
+/**
+ * The prompt copy for one configured agent, built once per Durable Object
+ * instance.
+ *
+ * A builder rather than a module-level `const`, because the type enum is a
+ * function of the plugins this agent installed, which is a function of `env`,
+ * which does not exist at module scope on Workers. The DO memoizes the result.
+ */
+export interface TurnInstructions {
+    /** Contract + per-type delegation guidance. Appended to soul + caller context. */
+    open: string;
+    /** Further appended when the budget is spent. */
+    final: string;
+}
+/**
+ * Build both prompt suffixes for one configured agent.
+ *
+ * The agent's contract, then whatever the delegable types have to say about being
+ * delegated — each declared by the type that owns it (`SubtaskTypeSpec`) and
+ * collected by the runtime's registry, so no domain is named by the policy. That
+ * is the rule the two prompt fields on a subtask type exist to hold: everything
+ * the main agent is told about a domain is declared by the plugin that owns it,
+ * never written inside the loop.
+ */
+export declare function buildTurnInstructions(policy: RoundPolicy, types: SubtaskTypeRegistry, maxSubtasks: number, limits: AgentLimits): TurnInstructions;
+/**
+ * Render the model's view for one round: the conversation, with every earlier
+ * round's delegation restored as the call-and-result it actually was, and every
+ * referenceable turn marked with the catalog index the model selects it by.
+ *
+ * One pass, two jobs, because they have to agree. The `[ref N]` markers use
+ * `isCatalogEligible` — the same predicate the catalog is numbered with — so a
+ * marker and its entry can never drift: compaction summaries (`assistant` role,
+ * generated) stay in the messages unmarked, readable for context but structurally
+ * uncitable as conversation evidence, which is exactly the intent.
+ *
+ * A round's acknowledgment is stored as plain assistant text (history is
+ * text-only, and stays that way — `sessionText`, the catalog, compaction, and
+ * recall all read text parts). So its `delegate` call is re-attached to that
+ * message here, and the result appended after it, for this one inference call. The
+ * pair is emitted together, anchored on the ack's deterministic id, so a `tool`
+ * message can never be orphaned from its call — and an ack that has been compacted
+ * away still gets its pair, appended at the end minus the acknowledgment text: a
+ * result the model cannot place beats a malformed history.
+ *
+ * Acks are deliberately **not** catalog-eligible: they are the agent's own
+ * scaffolding, and a subtask referencing "I'm on it" as verbatim conversation
+ * evidence would be noise. That holds for every ack in the Session, not only the
+ * ones this render can pair with branches — see `parseRoundAckMessageId`.
+ *
+ * Everything here is ephemeral — scaffolding for this call only. Reference text is
+ * snapshotted from the catalog, so no `[ref N]` prefix ever reaches a Subtask, and
+ * the Session never sees any of this markup.
+ */
+export declare function renderTurnMessages(history: SessionMessage[], taskId: string, branches: CompositionBranch[]): {
+    messages: ModelMessage[];
+    catalog: ReferenceCatalogEntry[];
+};
+/**
+ * Deterministic fallback reply: the successful branches' text in ordinal order,
+ * plus the policy's short note when some branches did not succeed.
+ *
+ * Used when a round's inference is unavailable but its predecessors' work is
+ * durable. Failing the whole Task because the answering model is down would throw
+ * away good results the user asked for.
+ */
+export declare function joinSuccessfulBranches(branches: CompositionBranch[], partialNote: string): string;
+/**
+ * How much rope this round gets, decided by the Workflow from the Task's spent
+ * budget.
+ *
+ * - `open` — the normal round: `delegate`, `final_reply`, and every work tool.
+ *   It may spend whatever is left of the turn budget.
+ * - `final` — the Task has spent its turns or its wall clock. **No work tools and
+ *   no `delegate`**: the only thing on the table is the answer. This is not a
+ *   punishment but the shape of the ceiling — a budget that ends in a forced
+ *   answer returns the work, where one that simply stopped would discard it.
+ *   Costs one turn, or two if the primary model fails and the fallback has to
+ *   produce the answer instead; a fallback with no step to spend could not answer
+ *   at all.
+ */
+export type RoundMode = "open" | "final";
+export interface RunTurnArgs {
+    /** The DO's one continuous Session. */
+    session: SessionLike;
+    /** Parent Task id — derives the deterministic Session message ids. */
+    taskId: string;
+    /** 0-based round within this Task. */
+    round: number;
+    /** The inbound user text (keeps its `<turn>` provenance wrapper verbatim). Appended on round 0 only. */
+    text: string;
+    /** What this round may do — see {@link RoundMode}. */
+    mode: RoundMode;
+    /**
+     * The Task's unspent turns, and the tally this round writes back into them.
+     * Mutated in place as the model works, so the primary and the fallback draw on
+     * one allowance rather than one each — see `TurnBudget`.
+     *
+     * There is no per-round allowance beyond what the Task has left: an early round
+     * that dithers spends what a later one would have had, and is then handed a
+     * `final` round to answer in. The caller reads `spent` when the round returns.
+     */
+    budget: TurnBudget;
+    /** Per-request system-prompt suffix (verified caller context). */
+    systemSuffix: string;
+    /** The main agent's gated **work** tools, merged over the session's own tools. */
+    tools: ToolSet;
+    /** Primary + fallback model pair. */
+    models: ModelPair;
+    /** Every earlier round's branches, all rounds, in stable ordinal order. */
+    branches: CompositionBranch[];
+    /** The installed subtask types — what `delegate` may name. */
+    types: SubtaskTypeRegistry;
+    /** `CoreConfig.maxSubtasks`, the per-round fan-out bound. */
+    maxSubtasks: number;
+    /** `CoreConfig.model.maxOutputTokens`. */
+    maxOutputTokens: number;
+    /** `CoreConfig.model.maxRetries` — retries on *this* model before the fallback. */
+    maxRetries: number;
+    /** The prompt suffixes, memoized by the DO. See {@link buildTurnInstructions}. */
+    instructions: TurnInstructions;
+    /** The note a deterministic join appends when it has to disclose gaps. */
+    partialNote: string;
+    /** Streams intermediate content while the model reasons. Best-effort. */
+    onContent?: OnContent;
+}
+/**
+ * Terminal outcome of one round. `failed` means the round produced no answer and
+ * there was no durable work to fall back on — the parent Task fails rather than
+ * running a synthesized subtask nobody asked for. Transient faults throw instead
+ * (the Workflow step retries).
+ *
+ * `kind` is *why*, not a second outcome. The round is over either way and the
+ * Task it delivers has the same shape; what the kind decides is what a human is
+ * told — `exhausted` is "the models could not do it", a credential kind is "a
+ * human must fix the deployment". Both were once separate statuses, and every
+ * consumer promptly bundled them back together to do the same three things. See
+ * {@link RoundFailureKind}.
+ *
+ * What the round cost is not here: it is in the caller's `TurnBudget`, which every
+ * exit has already charged — including the ones that failed. A round that burned
+ * the primary and recovered on the fallback spent both, and there is no variant
+ * that could quietly forgive the expensive half of a bad round.
+ */
+export type RunTurnOutcome = {
+    status: "replied";
+    reply: string;
+} | {
+    status: "delegated";
+    reply: string;
+    drafts: SubtaskDraft[];
+} | {
+    status: "failed";
+    kind: RoundFailureKind;
+    error: string;
+};
+/**
+ * Run one round against the continuous Session: append the user turn (round 0),
+ * let the model decide over the indexed history, validate any delegation against
+ * this round's catalog, and persist what the user will see.
+ *
+ * Every append uses a deterministic id, so a Workflow-step re-run neither
+ * duplicates the turn nor changes an already-delivered reply.
+ *
+ * Two nested recoveries, and they answer different failures. Within a slot, a
+ * decomposition the catalog rejects is handed back to the *same* model as a failed
+ * tool result, up to {@link MAX_REPAIR_ATTEMPTS} times — a shape error is the one
+ * thing a model can fix once it sees it. Across slots, an attempt that produced no
+ * decision at all moves to the fallback model, which is what that slot is for.
+ *
+ * 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", 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 declare function runTurn(args: RunTurnArgs): Promise<RunTurnOutcome>;