@dynamicagents/core 0.9.0

package/dist/subtasks/delegate.js

@@ -0,0 +1,131 @@
+import { tool } from "ai";
+import { makeDecompositionProposalSchema } from "./decomposition.js";
+/**
+ * The `delegate` tool — the single act by which the main agent hands work to
+ * subagents, and the shape both ends of that act agree on.
+ *
+ * Delegation is a **durable tool call**: a round emits it for real (the model
+ * picks it and fills its input), the Workflow performs it over minutes or hours,
+ * and a later round reassembles the call with its result to keep working. The two
+ * halves are separated by a Workflow boundary, not by a fiction — nothing here is
+ * fabricated on the model's behalf.
+ *
+ * This module owns the tool's identity because every round depends on it
+ * agreeing: a later round pairs a synthesized `tool-result` to an earlier round's
+ * `tool-call` by name and id, and a mismatch would not throw — it would silently
+ * produce a malformed history that the model quietly misreads.
+ */
+export const DELEGATE_TOOL_NAME = "delegate";
+/**
+ * The tool as the model sees it. Deliberately **without `execute`**: the Workflow
+ * performs this call, durably, outside the inference — so there is nothing for the
+ * SDK to run, and the tool loop halts on the call rather than trying to continue
+ * past it. That is what makes it a *control* tool: unlike the agent's work tools
+ * (`set_context`, and whatever the installed plugins offer), calling it ends the
+ * round.
+ *
+ * Its `inputSchema` is the delegation contract itself, and it is the **only**
+ * declaration of this tool. One schema has to serve both directions — the calls
+ * the model emits now, and the calls reconstructed from durable rows in later
+ * rounds — because a provider cannot be shown two shapes for one tool name in a
+ * single request. See {@link delegateCallInput} for how a durable row is rendered
+ * back into it.
+ *
+ * Built per registry rather than declared as a module constant: both the type
+ * enum in its schema and the catalogue in its description are facts about which
+ * plugins are installed, and in the predecessor repo both were frozen at import
+ * time — which is exactly what made the type set unoverridable.
+ */
+export function makeDelegateTool(types, maxSubtasks) {
+    return tool({
+        description: "Delegate part of the user's request to isolated subagents and acknowledge it. Their results return to you, and you then decide what to do next — answer the user, or delegate again.\n\n" +
+            "Every subtask must name one of these types, and supply the params that type requires:\n" +
+            types.renderTypes(),
+        inputSchema: makeDecompositionProposalSchema(types, maxSubtasks)
+    });
+}
+/**
+ * The call's id, derived from the parent Task and the round that emitted it —
+ * deterministic and replay-safe, the same discipline as the Session message ids
+ * it sits alongside (see {@link file://../agent/history.ts}). Later rounds rebuild it
+ * rather than storing it.
+ *
+ * **Underscores, not colons, and this is load-bearing.** Unlike a Session message
+ * id, this one is sent to a provider as a `tool_use.id`, and Anthropic validates
+ * that field against `^[a-zA-Z0-9_-]+$`. The colon-separated form this used to
+ * return failed every round from the first delegation onwards — round 0 was fine
+ * because the model authors its own ids, and round 1 reconstructs this one, so
+ * the request 400d deterministically on both the primary and the fallback until
+ * the deterministic join fired. Workers AI never validated the field, which is
+ * why it took a Claude-backed agent to surface it.
+ *
+ * Nothing persists this: both halves of the pair are rebuilt together on every
+ * request, so changing the shape needs no migration. There is no longer a
+ * provider-side backstop in core — the adapter that carried one went with
+ * `./anthropic` in 0.8.0 — so a provider added here that validates tool-call ids
+ * needs to sanitize them on its own way out.
+ */
+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
+ * are validated into — so the reconstructed call and an emitted one cannot drift
+ * apart in shape.
+ *
+ * `referenceIndexes` is omitted rather than faked: this round's references were
+ * snapshotted verbatim onto the rows when it ran, and the catalog they were
+ * chosen from is long gone.
+ *
+ * A subtask proposal carries no identifier of its own, so the model pairs each
+ * entry here with its outcome **by position**: both arrays are built from the
+ * same ordinal-ordered `branches`, and the outcome additionally repeats `type`
+ * and carries the durable `subtaskId`.
+ */
+export function delegateCallInput(reply, branches) {
+    return {
+        reply,
+        subtasks: branches.map((branch) => ({
+            type: branch.type,
+            prompt: branch.prompt,
+            // Reconstructed verbatim from the row: a later round must see the same
+            // params the call really carried, or it cannot reason about what ran.
+            params: branch.params
+        }))
+    };
+}
+/**
+ * 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"
+            ? bounded((branch.resultParts ?? []).map((part) => part.text).join("\n"))
+            : branch.error
+                ? bounded(branch.error)
+                : null
+    }));
+}

package/dist/subtasks/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * `@dynamicagents/core/subtasks` — the delegation layer: what a round may hand out,
+ * and how a proposal becomes durable drafts.
+ */
+export { makeSubtaskTypes, SubtaskParamsError, type SubtaskTypeRegistry } from "./subtask-types.js";
+export { DecompositionValidationError, makeDecompositionProposalSchema, nonBlank, resolveDecomposition } from "./decomposition.js";
+export { DELEGATE_TOOL_NAME, makeDelegateTool, delegateToolCallId, delegateCallInput, delegateCallOutput, type DelegateSubtaskOutcome } from "./delegate.js";
+export { isCatalogEligible, type ReferenceCatalogEntry } from "./catalog.js";
+export * from "./types.js";

package/dist/subtasks/index.js

@@ -0,0 +1,9 @@
+/**
+ * `@dynamicagents/core/subtasks` — the delegation layer: what a round may hand out,
+ * and how a proposal becomes durable drafts.
+ */
+export { makeSubtaskTypes, SubtaskParamsError } from "./subtask-types.js";
+export { DecompositionValidationError, makeDecompositionProposalSchema, nonBlank, resolveDecomposition } from "./decomposition.js";
+export { DELEGATE_TOOL_NAME, makeDelegateTool, delegateToolCallId, delegateCallInput, delegateCallOutput } from "./delegate.js";
+export { isCatalogEligible } from "./catalog.js";
+export * from "./types.js";

package/dist/subtasks/subtask-types.d.ts

@@ -0,0 +1,91 @@
+import { z } from "zod";
+import type { DelegationNames, ResolvedRecipe, SubtaskParams, SubtaskTypeSpec } from "../contract/recipe.js";
+/**
+ * The **closed set of subtask types** the main agent may delegate, as the
+ * runtime uses it: lookup, the delegate enum, param validation, and the
+ * catalogue the delegating model is shown.
+ *
+ * The set is not declared here, and — unlike the predecessor repo — it is not a
+ * module constant. There, `SUBTASK_TYPE_SPECS` was imported at module scope and
+ * every derived value (`SUBTASK_TYPES`, `SUBTASK_TYPE_KEYS`, the delegate tool's
+ * description, the round contract) was computed at *import time*. That made the
+ * registry unoverridable, froze it before `env` exists, and pulled every
+ * domain's module into the bundle whether or not the agent used it.
+ *
+ * So it is a factory. The host builds one registry per DO instance from its
+ * installed plugins, and everything downstream reads that object.
+ */
+export type { DelegationNames, SubtaskParams, SubtaskTypeSpec };
+/** A subtask whose params do not satisfy its type's contract. */
+export declare class SubtaskParamsError extends Error {
+    constructor(message: string);
+}
+export interface SubtaskTypeRegistry {
+    /** Every known spec, in declaration order. */
+    readonly specs: readonly SubtaskTypeSpec[];
+    /** Every known type, keyed by its `key`. */
+    readonly byKey: ReadonlyMap<string, SubtaskTypeSpec>;
+    /** The type keys in declaration order. Empty when the agent delegates nothing. */
+    readonly keys: readonly string[];
+    /**
+     * The keys as a non-empty tuple for `z.enum` in the delegate schema — the
+     * model cannot emit anything outside it, so an unknown type never reaches the
+     * data layer.
+     *
+     * Throws when no type is registered. Not a defensive check but the real
+     * contract: an agent with no subtask types has nothing to delegate to, and
+     * must not offer a delegate tool at all.
+     */
+    enumKeys(): [string, ...string[]];
+    /** Look up a type, or null when it is not one we know. */
+    spec(type: string): SubtaskTypeSpec | null;
+    /**
+     * Resolve a subtask type to the recipe it runs under. Throws
+     * {@link SubtaskParamsError} for an unknown or retired type — the delegate
+     * enum prevents the model from emitting one, so any unknown type reaching
+     * execution is a configuration bug and should fail terminally.
+     */
+    resolveRecipe(type: string): ResolvedRecipe;
+    /**
+     * Validate a subtask's params against its type's contract, returning the
+     * params to persist. A type with no schema must carry no params — a stray
+     * param would otherwise ride along unread, looking meaningful.
+     *
+     * Shape only: whether an id names something the outside world actually offers
+     * is a question for that world, answered when the work starts. Unknown keys
+     * are stripped rather than refused — a model that invents one has produced a
+     * valid subtask with noise attached, and the noise provably cannot reach the
+     * execution.
+     */
+    validateParams(type: string, params: SubtaskParams | undefined): SubtaskParams;
+    /**
+     * Every param key any type declares, as the optional properties of the single
+     * flat `params` object the delegate tool advertises.
+     *
+     * Optional is not a weakening: which keys a given type *requires* is
+     * {@link validateParams}'s call, and it still refuses a subtask whose type's
+     * params are missing. What this adds is **visibility**. One tool schema has to
+     * serve every type, so the only alternative to naming the union of keys here
+     * is naming none of them — and a key the schema does not name is a key the
+     * model has no legal way to send, whatever the description promises. That is
+     * exactly how a domain subtask once reached validation with none of its
+     * declared ids: the field was declared as a free-form record, which the
+     * provider's schema conversion flattens to an object permitting no keys at all.
+     *
+     * Descriptions are prefixed with the owning type, so a flat namespace still
+     * reads unambiguously to the model (and a key two types share names both).
+     */
+    paramProperties(): Record<string, z.ZodType<string | undefined>>;
+    /** The type catalogue as the delegating model is shown it. */
+    renderTypes(): string;
+    /** Every type's {@link SubtaskTypeSpec.delegationGuidance}, for the round contract. */
+    renderDelegationGuidance(names: DelegationNames): string;
+}
+/**
+ * Build the registry from the specs the installed plugins declared.
+ *
+ * Duplicate keys are refused rather than last-one-wins: two plugins claiming one
+ * type is a misconfiguration whose symptom would otherwise be work silently
+ * routed to the wrong domain.
+ */
+export declare function makeSubtaskTypes(specs: readonly SubtaskTypeSpec[]): SubtaskTypeRegistry;

package/dist/subtasks/subtask-types.js

@@ -0,0 +1,103 @@
+import { z } from "zod";
+/** A subtask whose params do not satisfy its type's contract. */
+export class SubtaskParamsError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "SubtaskParamsError";
+    }
+}
+/**
+ * Build the registry from the specs the installed plugins declared.
+ *
+ * Duplicate keys are refused rather than last-one-wins: two plugins claiming one
+ * type is a misconfiguration whose symptom would otherwise be work silently
+ * routed to the wrong domain.
+ */
+export function makeSubtaskTypes(specs) {
+    const byKey = new Map();
+    for (const spec of specs) {
+        if (byKey.has(spec.key)) {
+            throw new Error(`duplicate subtask type "${spec.key}" — two plugins declare the same type`);
+        }
+        byKey.set(spec.key, spec);
+    }
+    const keys = specs.map((s) => s.key);
+    const lookup = (type) => byKey.get(type) ?? null;
+    return {
+        specs,
+        byKey,
+        keys,
+        enumKeys() {
+            if (keys.length === 0) {
+                throw new Error("no subtask types are registered — an agent with no types cannot delegate, " +
+                    "so it must not build a delegate tool");
+            }
+            return keys;
+        },
+        spec: lookup,
+        resolveRecipe(type) {
+            const found = lookup(type);
+            if (!found)
+                throw new SubtaskParamsError(`unknown subtask type: ${type}`);
+            return found.recipe;
+        },
+        validateParams(type, params) {
+            const found = lookup(type);
+            if (!found)
+                throw new SubtaskParamsError(`unknown subtask type: ${type}`);
+            const supplied = params ?? {};
+            if (!found.params) {
+                const extra = Object.keys(supplied);
+                if (extra.length > 0) {
+                    throw new SubtaskParamsError(`subtask type "${type}" takes no params, got: ${extra.join(", ")}`);
+                }
+                return {};
+            }
+            const parsed = found.params.safeParse(supplied);
+            if (!parsed.success) {
+                const detail = parsed.error.issues
+                    .map((i) => `${i.path.join(".") || "(root)"}: ${i.message}`)
+                    .join("; ");
+                throw new SubtaskParamsError(`subtask type "${type}" has invalid params — ${detail}`);
+            }
+            return parsed.data;
+        },
+        paramProperties() {
+            const owners = new Map();
+            const declared = new Map();
+            for (const s of specs) {
+                if (!s.params)
+                    continue;
+                for (const [key, field] of Object.entries(s.params.shape)) {
+                    owners.set(key, [...(owners.get(key) ?? []), s.key]);
+                    declared.set(key, field);
+                }
+            }
+            return Object.fromEntries([...declared].map(([key, field]) => [
+                key,
+                // Described *after* `.optional()`, so the text sits on the schema this
+                // returns rather than on the type it wraps — readable by both the JSON
+                // Schema conversion and anything inspecting these properties directly.
+                field
+                    .optional()
+                    .describe(`${owners.get(key)?.join("/")}: ${field.description ?? key}`)
+            ]));
+        },
+        renderTypes() {
+            return specs
+                .map((s) => {
+                const help = s.paramsHelp ? ` — ${s.paramsHelp}` : "";
+                return `- \`${s.key}\`: ${s.description}${help}`;
+            })
+                .join("\n");
+        },
+        renderDelegationGuidance(names) {
+            const sections = [];
+            for (const s of specs) {
+                if (s.delegationGuidance)
+                    sections.push(s.delegationGuidance(names));
+            }
+            return sections.join("\n\n");
+        }
+    };
+}

package/dist/subtasks/types.d.ts

@@ -0,0 +1,295 @@
+import type { ResolvedRecipe, SubtaskParams } from "../contract/recipe.js";
+import type { RoundFailureKind } from "../agent/inference.js";
+export type SubtaskStatus = "pending" | "running" | "completed" | "failed" | "canceled";
+/** A per-caller, SQLite-assigned, monotonically increasing Subtask identifier. */
+export type SubtaskId = number;
+/**
+ * An exact, verbatim snapshot of one selected Session history message, copied
+ * onto the Subtask at decomposition time. The decomposition model selects which
+ * messages to reference; it never rewrites their content. User-turn provenance
+ * (author/channel) is already inline in the message text's `<turn>` wrapper.
+ */
+export interface SubtaskReference {
+    role: "user" | "assistant";
+    text: string;
+}
+/**
+ * One part of a Subtask's result. Text-only today; file/data kinds are additive
+ * later. Internal to the agent — the terminal A2A Task collapses these to a
+ * single text reply for the gatekeeper/human.
+ */
+export interface SubtaskResultPart {
+    kind: "text";
+    text: string;
+}
+/**
+ * Creation input for one Subtask, before it is persisted. `ordinal` is derived
+ * from the draft's position in the decomposition array, which is the only thing
+ * that distinguishes one draft of a decomposition from another — they carry no
+ * identity of their own until the data layer assigns a {@link SubtaskId}.
+ */
+export interface SubtaskDraft {
+    type: string;
+    prompt: string;
+    references: SubtaskReference[];
+    /** The type's required inputs, already validated for shape. */
+    params: SubtaskParams;
+}
+/**
+ * Session state the parent resolved *from* a Subtask's params at execution
+ * start — the part of an execution's context the model can never supply.
+ *
+ * Deliberately outside {@link RecipeExecutionRequest}: it is not part of an
+ * execution's identity and it can change under us, so fingerprinting it would
+ * make a retry look like a different request. It travels as a separate argument,
+ * the same discipline as the chunk number.
+ */
+export type SubtaskRuntime = Record<string, unknown>;
+/**
+ * Narrow a {@link SubtaskRuntime} to the shape a plugin resolved for itself.
+ *
+ * Runtime is an open bag because core cannot know what a domain needs — the
+ * predecessor repo declared ARC's four fields (`cardId`, `cookies`, `guid`,
+ * `frame`) right here in the delegation types, which meant core imported a
+ * domain's types and every unrelated agent carried them. A plugin now writes and
+ * reads its own slice, and the only thing core does with the bag is carry it.
+ *
+ * The unchecked cast is the point: the plugin that wrote the slice is the plugin
+ * reading it, so the assertion is local and its blast radius is one module.
+ */
+export declare function runtimeAs<T>(runtime: SubtaskRuntime): T;
+/**
+ * A user-facing progress note a tool emits mid-execution (e.g. a game level-up).
+ * The resumable runner collects these and ends the current chunk so the parent
+ * DO can post them promptly; `key` is a stable dedupe id the gatekeeper keys on.
+ */
+export interface ProgressEvent {
+    key: string;
+    text: string;
+}
+/**
+ * One durable chunk's outcome as the facet reports it to the parent DO. `done`
+ * false means the run yielded a chunk boundary and the Workflow must run another
+ * chunk; `done` true carries the terminal {@link RecipeExecutionResult}. Progress
+ * events accumulated during the chunk ride along either way.
+ */
+export type RecipeChunkResult = {
+    done: false;
+    progress: ProgressEvent[];
+} | {
+    done: true;
+    result: RecipeExecutionResult;
+    progress: ProgressEvent[];
+};
+/**
+ * The parent DO's projection of a chunk outcome for the Workflow (RPC-safe, no
+ * result parts — those are persisted on the row). `status` is `running` until the
+ * run is `done`, then the terminal Subtask status.
+ */
+export interface SubtaskChunkOutcome {
+    done: boolean;
+    status: SubtaskStatus;
+    progress: ProgressEvent[];
+}
+/**
+ * RPC-safe input for one isolated `RecipeSubagent` execution, assembled by the
+ * parent at execution start: the already-resolved (and code-validated) Recipe,
+ * the Subtask's non-session prompt, and its verbatim reference snapshots. The
+ * child re-validates the Recipe defensively but never resolves one itself.
+ */
+export interface RecipeExecutionRequest {
+    taskId: string;
+    subtaskId: SubtaskId;
+    /**
+     * The Subtask's semantic type — what the work *is*, and what owns the params
+     * contract. Distinct from `recipe.key`, which names the execution
+     * configuration it runs under: several types may share one Recipe.
+     */
+    type: string;
+    recipe: ResolvedRecipe;
+    prompt: string;
+    references: SubtaskReference[];
+    /**
+     * The Subtask's validated params. Part of the execution's identity — two plays
+     * of different games are different work — so this IS fingerprinted, unlike
+     * {@link SubtaskRuntime}, which is deliberately excluded: the leased scorecard
+     * can legitimately differ between two chunks of one run, and must not make a
+     * retry look like a different execution.
+     */
+    params: SubtaskParams;
+}
+/**
+ * Terminal outcome of one `RecipeSubagent` execution (RPC-safe). `modelId` is a
+ * diagnostic only — which model produced the outcome (null when validation
+ * failed before any model call); it is never persisted on the Subtask row.
+ * Transient platform faults are not results: they throw so the enclosing
+ * Workflow step can retry.
+ */
+export type RecipeExecutionResult = {
+    status: "completed";
+    resultParts: SubtaskResultPart[];
+    modelId: string;
+} | {
+    status: "failed";
+    error: string;
+    modelId: string | null;
+};
+/**
+ * One Subtask as the delegating model emits it. The model selects references
+ * by **catalog index only** — it never emits reference text, and application code
+ * snapshots the catalog entry's exact role+text onto the Subtask (see
+ * `agent/subtasks/decomposition.ts`).
+ */
+export interface SubtaskProposal {
+    type: string;
+    prompt: string;
+    /**
+     * 1-based indices into the ephemeral, per-round reference catalog. Optional:
+     * omitted when the subtask needs no verbatim history, and always absent from a
+     * *reconstructed* historical call, whose references were resolved rounds ago.
+     */
+    referenceIndexes?: number[];
+    /** The type's required inputs; omitted for a type that takes none. */
+    params?: SubtaskParams;
+}
+/**
+ * The model's complete `delegate` call: the acknowledgment the user sees while
+ * the work runs, plus one through eight Subtask proposals. Validated against the
+ * round's ephemeral catalog before anything is persisted; invalid output fails
+ * the attempt (and, with both models exhausted, the round) rather than being
+ * silently repaired.
+ */
+export interface DecompositionProposal {
+    reply: string;
+    subtasks: SubtaskProposal[];
+}
+/**
+ * Terminal outcome of one main-agent round (RPC-safe).
+ *
+ * `replied` is the terminal answer — the round chose to answer the user rather
+ * than delegate, and the Workflow delivers it. `delegated` means the round's
+ * Subtask rows are durable and the Workflow should execute them, after which
+ * another round begins. `failed` means the round produced no answer, with
+ * {@link RoundFailureKind} carrying why; no Subtask is ever synthesized to cover
+ * for it. `canceled` means the caller cancelled during the round: nothing was
+ * persisted and nothing was published. Transient platform faults are not
+ * results: they throw so the enclosing Workflow step can retry (mirrors
+ * {@link RecipeExecutionResult}).
+ *
+ * `turns` is what this round cost, which the Workflow meters against the Task's
+ * budget. This is the **only** type that carries it, and it carries it because the
+ * count has to cross an RPC boundary to reach a Workflow in another isolate;
+ * everything inside the DO shares one mutable
+ * {@link file://../agent/budget.ts TurnBudget} instead. The field is attached in a single place — see `runTaskTurn` — so no
+ * branch can drop it and no branch can invent it.
+ *
+ * The idempotent recovery paths — a round replayed from durable rows rather than
+ * re-inferred — therefore report **0** structurally: they return before any model
+ * runs, so the budget they hand back is untouched. That is exact on a clean
+ * replay, where the Workflow's own cached step return already carries the original
+ * number, and under-counts by one round when a step crashed mid-flight and re-ran.
+ * Accepted rather than fixed: a replying round writes no durable row at all, so
+ * nothing exists to hang a per-round count on, and the wall clock bounds the
+ * crash-loop case anyway.
+ */
+export type TurnTaskResult = {
+    status: "replied";
+    reply: string;
+    turns: number;
+} | {
+    status: "delegated";
+    reply: string;
+    subtasks: Subtask[];
+    turns: number;
+}
+/**
+ * `kind` distinguishes a round that spent both models and got nothing usable
+ * (`exhausted`) from one that stopped on a fault no attempt could clear —
+ * where the fallback was deliberately *not* tried, and the kind is what lets
+ * the host say why in words an operator can act on. Same terminal Task either
+ * way; only the words differ.
+ */
+ | {
+    status: "failed";
+    kind: RoundFailureKind;
+    error: string;
+    turns: number;
+} | {
+    status: "canceled";
+    turns: number;
+};
+/**
+ * Distributive `Omit` — applies per member, so the discriminated union survives.
+ * A plain `Omit<TurnTaskResult, "turns">` collapses all four into one loose shape
+ * whose `reply` and `subtasks` are independently optional.
+ */
+type WithoutTurns<T> = T extends unknown ? Omit<T, "turns"> : never;
+/**
+ * What a round decided, before its cost is attached. The DO's round logic returns
+ * this and lets one wrapper bill the budget, rather than every branch remembering
+ * to report a number it did not compute.
+ */
+export type TurnVerdict = WithoutTurns<TurnTaskResult>;
+/**
+ * One branch's outcome as a later round sees it — a plain, RPC-safe subset of the
+ * durable {@link Subtask} row, loaded across **every** round in stable ordinal
+ * order. Completed and failed branches are both included so the reply can use
+ * available successes and disclose relevant failures.
+ *
+ * Carries `round` and `prompt` — not for composing, but for reconstructing the
+ * per-round `delegate` call that produced these branches (see
+ * `agent/subtasks/delegate.ts`). `references` stays out: it is unbounded history
+ * text, and the call's shape does not need it.
+ */
+export interface CompositionBranch {
+    subtaskId: SubtaskId;
+    round: number;
+    ordinal: number;
+    type: string;
+    prompt: string;
+    params: SubtaskParams;
+    status: SubtaskStatus;
+    resultParts: SubtaskResultPart[] | null;
+    error: string | null;
+}
+/**
+ * The `scan:<round>` projection (RPC-safe): either the caller cancelled, or the
+ * ids of the round's Subtasks that still owe an outcome, in ordinal order.
+ * Returning the verdict with the ids is what lets the Workflow drop its separate
+ * cancellation probe — one round trip, and no gap between asking and acting.
+ *
+ * Ids and nothing else, deliberately: a Workflow step return is capped at 1 MiB
+ * and a Subtask carries verbatim history snapshots bounded only by
+ * `MAX_INBOUND_TEXT_BYTES`, so a scan returning rows would overflow on a large
+ * task. The durable rows are the source of truth; the Workflow carries
+ * references to them and re-reads through the parent when it needs more.
+ */
+export type SubtaskScan = {
+    canceled: true;
+} | {
+    canceled: false;
+    ids: SubtaskId[];
+};
+/** Durable state owned by the main agent for one delegated unit of work. */
+export interface Subtask {
+    id: SubtaskId;
+    taskId: string;
+    /** The main-agent round that delegated this Subtask (0-based). */
+    round: number;
+    /** Position within the parent Task, increasing across every round. */
+    ordinal: number;
+    type: string;
+    recipeId: string | null;
+    recipeVersion: number | null;
+    prompt: string;
+    references: SubtaskReference[];
+    /** The type's required inputs, validated at delegation time. */
+    params: SubtaskParams;
+    status: SubtaskStatus;
+    resultParts: SubtaskResultPart[] | null;
+    error: string | null;
+    createdAt: number;
+    updatedAt: number;
+    completedAt: number | null;
+}
+export {};

package/dist/subtasks/types.js

@@ -0,0 +1,15 @@
+/**
+ * Narrow a {@link SubtaskRuntime} to the shape a plugin resolved for itself.
+ *
+ * Runtime is an open bag because core cannot know what a domain needs — the
+ * predecessor repo declared ARC's four fields (`cardId`, `cookies`, `guid`,
+ * `frame`) right here in the delegation types, which meant core imported a
+ * domain's types and every unrelated agent carried them. A plugin now writes and
+ * reads its own slice, and the only thing core does with the bag is carry it.
+ *
+ * The unchecked cast is the point: the plugin that wrote the slice is the plugin
+ * reading it, so the assertion is local and its blast radius is one module.
+ */
+export function runtimeAs(runtime) {
+    return runtime;
+}