@dynamicagents/core 0.9.0

package/dist/platform.js

@@ -0,0 +1,140 @@
+/**
+ * What the Cloudflare Workflows runtime imposes, and the two numbers derived from
+ * it. Nothing here is a budget or a preference — see {@link file://./config.ts}
+ * for those, and note that no Recipe can reach these. They change when the
+ * platform changes, and for no other reason.
+ *
+ * The distinction is worth keeping sharp, because collapsing it produces a
+ * specific bug: using a *turn count* to keep a step under the step timeout only
+ * works if you can predict how long a turn takes. You cannot. Time bounds time
+ * here; turns bound cost, over in `config.ts`.
+ */
+/**
+ * The step timeout **we configure**, passed as `WorkflowStepConfig.timeout` on
+ * every step that can hold a model call or a container command.
+ *
+ * This is the one value in this file that is **not** a platform fact, and
+ * treating it as one is the mistake to avoid: ten minutes is Workflows'
+ * *default* step timeout, not its ceiling, and a step that never passes a config
+ * inherits it silently. Sizing {@link CHUNK_SOFT_MS} against that inherited
+ * default is what once ran a production task as ten four-minute slices, one of
+ * which blew the ten minutes anyway and was retried whole.
+ *
+ * The genuine platform facts are narrower and do not bind us: wall-clock time per
+ * step is effectively unlimited, and a step is bounded by **CPU** time. Measured
+ * over a 59-minute task, the chunk steps used ~100 ms of CPU against 3,146 s of
+ * wall — this ceiling is nowhere near the real one.
+ *
+ * It is still a ceiling worth having, because it is what turns a hung container
+ * into a retry rather than a task that never ends. {@link CHUNK_SOFT_MS} is sized
+ * against it, and that relationship is asserted in `platform.spec.ts`.
+ */
+export const STEP_TIMEOUT_MS = 30 * 60_000;
+/**
+ * Platform fact: a single Workflow instance may run 10,000 steps by default on the
+ * paid plan. Cloudflare will raise it to 25,000 on request — worth knowing, and
+ * worth not relying on: {@link MAX_CHUNKS_PER_BRANCH} is sized against the default
+ * so nothing here needs an account-level exception to be correct. See the
+ * worst-case product asserted in `platform.spec.ts`.
+ */
+export const STEPS_PER_INSTANCE = 10_000;
+/**
+ * How long one durable chunk may run before it checkpoints and yields a fresh
+ * step. Comfortably inside {@link STEP_TIMEOUT_MS} so a slow model turn in flight
+ * when the soft limit trips still has room to finish.
+ *
+ * This is the *only* thing keeping a step under the timeout. A subagent otherwise
+ * runs until its turn or wall-clock budget is spent, however many turns that takes
+ * — which is the point: the runner no longer guesses at turn duration.
+ *
+ * ## Why this is 15 minutes and not 4
+ *
+ * A chunk boundary is not free. It checkpoints, returns through two RPC hops,
+ * starts a fresh step, and re-hydrates the subagent — and for a coding agent it
+ * also means the container connection is re-established. Four minutes bought a
+ * boundary roughly every third tool call: a task that edited one README line spent
+ * 59 minutes across **ten** chunks, and the model was idle for most of each one,
+ * blocked on a single `sb_exec` running the project's test gate.
+ *
+ * ## Why it is not larger, which is the part that bit us
+ *
+ * This is a **soft** deadline, checked between turns (`stopWhen` in
+ * `subagent/run.ts`). A turn that starts one millisecond before it trips still runs
+ * to completion, so the real worst case is:
+ *
+ *     chunk wall  ≤  CHUNK_SOFT_MS + one whole turn
+ *
+ * and one turn is a model call plus a tool call. The old pair ignored that: four
+ * minutes soft under a ten-minute timeout looked like six minutes of headroom, but
+ * a single `sb_exec` may run for {@link MAX_TOOL_CALL_MS}, so a turn could add ten.
+ * That is not a hypothetical — it is the `WorkflowTimeoutError` that cost a
+ * production task ten minutes and a full chunk replay.
+ *
+ * So the headroom is sized against a whole turn, not against a guess:
+ * `STEP_TIMEOUT_MS - CHUNK_SOFT_MS` is 15 minutes, covering
+ * {@link MAX_TOOL_CALL_MS} of tool call plus five minutes for the model call and
+ * its provider retries. Asserted in `platform.spec.ts` — raise the step timeout
+ * before raising this.
+ */
+export const CHUNK_SOFT_MS = 15 * 60_000;
+/**
+ * The longest a **single tool call** may run, and a contract rather than a
+ * mechanism: core has no way to enforce it, because core installs no tools.
+ *
+ * It exists because {@link CHUNK_SOFT_MS} cannot be reasoned about without it. The
+ * soft deadline is checked between turns, so a host that lets one tool block for
+ * longer than the headroom under {@link STEP_TIMEOUT_MS} reintroduces exactly the
+ * step-timeout kill this pair is sized to prevent — and it reintroduces it
+ * invisibly, in a plugin, a long way from this file.
+ *
+ * A host installing a tool that can block (a shell, a container command, a fetch
+ * with no ceiling of its own) must bound it at or below this. See the `timeoutMs`
+ * passed to `@dynamicagents/plugins/computer` in starter.
+ */
+export const MAX_TOOL_CALL_MS = 10 * 60_000;
+/**
+ * Hard ceiling on durable chunk steps for one Subtask branch. A backstop, not a
+ * budget: the Workflow *fails* a branch that reaches it, so reaching it is a bug.
+ * It is held unreachable by two constraints, both asserted in
+ * `platform.spec.ts`:
+ *
+ * 1. It exceeds every Recipe's `maxTurns`. A chunk that yields always advanced at
+ *    least one turn, so a run takes at most `maxTurns` chunks however short they
+ *    are — and they do get short, because `CHUNK_SOFT_MS` and progress events both
+ *    end one early. Counting turns is what makes the bound survive that; any
+ *    estimate of turns-per-chunk would not, since neither of those two is
+ *    predictable.
+ * 2. The worst-case step product stays under {@link STEPS_PER_INSTANCE}.
+ */
+export const MAX_CHUNKS_PER_BRANCH = 40;
+/**
+ * What a step holding a model call or a container command configures instead of
+ * inheriting Workflows' defaults. Both defaults were measured wrong for this
+ * workload.
+ *
+ * **`timeout`.** The default is ten minutes. A step here holds a model call and
+ * its provider retries, or a container command running a project's test suite;
+ * neither fits in ten minutes reliably, and neither uses meaningful CPU while it
+ * waits. Left inherited, that default silently became the ceiling
+ * {@link CHUNK_SOFT_MS} was sized against.
+ *
+ * **`retries`.** The default is five attempts with exponential backoff from ten
+ * seconds. Against a fault that is not transient — a severed Durable Object stub
+ * — that produced five failures in under 10ms each, spread across 160 seconds of
+ * backoff that bought nothing. Three attempts still cover a genuinely transient
+ * fault, since the model call has its own provider-level retry underneath this,
+ * and a flat five-second delay stops a fast permanent failure being paid for at
+ * exponential rates.
+ *
+ * Here rather than in `/round` because the agent that most needs it may not be a
+ * round agent: a single-inference agent runs one model call in one step and has
+ * the same two problems, and importing this from `/round` would put the whole
+ * delegation engine in its bundle.
+ *
+ * For the **short** bookkeeping steps — `working`, `complete`, `notify` and
+ * friends — the defaults are fine and a shared config would only hide that.
+ */
+export const CHUNK_STEP = {
+    timeout: STEP_TIMEOUT_MS,
+    retries: { limit: 3, delay: 5_000, backoff: "constant" }
+};

package/dist/round/agent.d.ts

@@ -0,0 +1,271 @@
+import type { AiEnv, A2ASecretsEnv } from "../env.js";
+import type { GatekeeperIdentity } from "../a2a/verify.js";
+import type { TurnPushContext } from "../a2a/push.js";
+import type { Subtask, SubtaskChunkOutcome, SubtaskId, SubtaskScan, TurnTaskResult } from "../subtasks/types.js";
+import { DynamicAgent } from "../host/agent.js";
+import type { SubagentClass } from "./subagent.js";
+import type { RoundPolicy } from "./policy.js";
+import { type RoundMode } from "./turn.js";
+/**
+ * A **delegating** agent: the round loop, the durable Subtasks it hands out, and
+ * the isolated subagent execution beneath them.
+ *
+ * Everything {@link DynamicAgent} gives every agent, plus the half that only a
+ * delegating one needs — and it is all mechanism. A Workflow drives it through
+ * native Cloudflare RPC (`runTaskTurn`, `scanSubtasks`, `executeSubtaskChunk`,
+ * …), never HTTP: the DO is a private implementation detail of the Worker.
+ *
+ * ## Why core owns this
+ *
+ * Every method below is either idempotent recovery, cancellation ordering, or
+ * child lifecycle, and each one has an ordering that is load-bearing and
+ * invisible: the acknowledgment is appended *before* the rows exist; a fresh
+ * execution deletes its stale child but an ambiguous retry must not; a successful
+ * chunk defers its child's deletion to a single post-delivery sweep. Get any of
+ * them backwards and nothing fails to compile, nothing fails a lint, and the
+ * damage shows up as a duplicated reply or a false-positive error weeks later.
+ *
+ * None of it varies between agents. What varies is the {@link RoundPolicy} — the
+ * words — and the plugins.
+ *
+ * ## What this class does not know
+ *
+ * Nothing here names a domain. `resolveRuntime`, `enrichResult` and `onAbort` are
+ * hooks on `AgentPlugin`, so a plugin that leases an external session or scores a
+ * result gets that without a branch anywhere in this file. That inversion is what
+ * lets one class body serve every delegating agent.
+ */
+export declare abstract class RoundAgentBase<TEnv extends Cloudflare.Env & AiEnv & A2ASecretsEnv = Cloudflare.Env & AiEnv & A2ASecretsEnv> extends DynamicAgent<TEnv> {
+    private _instructions?;
+    /**
+     * The words: the round contract, the budget-spent note, and the strings a user
+     * reads. Core ships none of them — see {@link RoundPolicy}.
+     */
+    protected abstract roundPolicy(): RoundPolicy;
+    /**
+     * The facet class this agent's subtasks execute in.
+     *
+     * A seam because each agent's children must reach that agent's plugins, and a
+     * facet cannot be handed a runtime: `parentAgent()` is an RPC stub, and a
+     * `SubtaskRuntime` is mostly functions. So the class itself carries the
+     * binding — see {@link file://./subagent.ts RecipeSubagentHost}.
+     */
+    protected abstract subagentClass(): SubagentClass;
+    /** The prompt suffixes, built once from this agent's installed subtask types. */
+    private get instructions();
+    /**
+     * The main agent's **work tools** for this caller — the `execute`-bearing tools
+     * every round runs its loop over. The control tools that *end* a round are not
+     * here; `runTurn` adds those.
+     *
+     * The Session's own `set_context`/`load_context` come first, with the installed
+     * plugins' tools layered over them: a soul that instructs the model to record
+     * durable facts with `set_context` needs it actually on the call.
+     *
+     * Which plugin tools appear is the plugins' business, not this class's. A
+     * plugin may shape its surface from durable state — offering a search only once
+     * there is something to search, because a tool whose only possible answer is
+     * "nothing here yet" costs a call to discover that and costs every round the
+     * tokens to describe it.
+     */
+    private mainAgentTools;
+    /** Age out this agent's subtask rows alongside the task rows. */
+    protected cleanupAgentState(): void;
+    /**
+     * One main-agent round: answer the user, or delegate a durable set of Subtasks
+     * and return the acknowledgment the user sees while it runs.
+     *
+     * This is the RPC boundary, so it is where the round's cost becomes a field. The
+     * budget is created here, handed to {@link decideRound} to be spent, and read
+     * back exactly once — so no branch of the round has to remember to report a
+     * number, and none can report the wrong one.
+     */
+    runTaskTurn(input: {
+        taskId: string;
+        text: string;
+        identity: GatekeeperIdentity;
+        round: number;
+        mode: RoundMode;
+        /** What the Task has left. Bounds this round. */
+        turnsRemaining: number;
+        push?: TurnPushContext;
+    }): Promise<TurnTaskResult>;
+    /**
+     * The round itself, charging `budget` as it goes.
+     *
+     * Idempotent, and the recovery order is the contract:
+     *
+     * 1. A canceled Task stops here.
+     * 2. A durable **final reply** means some round already answered — return it
+     *    without inference. Re-answering could produce different words for a reply
+     *    the user may already have received.
+     * 3. Durable **rows for this round** mean this round already delegated —
+     *    recover its acknowledgment from the Session, with no inference and no
+     *    duplicate rows.
+     * 4. Otherwise, infer.
+     *
+     * Cancellation is re-read **after** inference too, not just before it: the model
+     * call is the widest window in the round, and neither the Subtask rows nor the
+     * callback may land for a Task the caller already gave up on. The reply is
+     * already in the Session by then (`runTurn` appends under deterministic ids
+     * before returning) — that is durable history, not output the user sees.
+     *
+     * Returns a typed `failed` result when both models produce unusable output and
+     * no durable work exists to fall back on (the Workflow routes it to failed
+     * delivery); throws only on a transient fault, for the step to retry.
+     */
+    private decideRound;
+    /**
+     * Every round's branches for a Task, in stable ordinal order — what a round
+     * needs to reunite each earlier `delegate` call with its result. Built inside
+     * the DO and consumed here, so the 1 MiB Workflow-step cap that keeps
+     * {@link SubtaskScan} down to ids does not apply.
+     */
+    private compositionBranches;
+    /** A Task's Subtasks, every round, in stable ordinal order. */
+    listSubtasks(taskId: string): Promise<Subtask[]>;
+    /**
+     * The Workflow's scan for **one round's** Subtasks: report a cancellation, or
+     * return the ids that still owe an outcome, in ordinal order.
+     *
+     * Scoped to the round because the Workflow drives one round at a time: an
+     * earlier round's rows are already terminal and would only widen a projection
+     * that has a size cap.
+     *
+     * `running` counts alongside `pending` on purpose. `executeSubtaskChunk`
+     * accepts a row that is either: the latter is its ambiguous-retry path, where a
+     * previous attempt crashed mid-execution and the managed child's fingerprint
+     * cache may still hold the terminal result that makes the retry free. So a row
+     * stranded `running` is re-runnable, and omitting it here would abandon it.
+     *
+     * Ordinal order comes from {@link listRound} and is not incidental: these ids
+     * become durable Workflow step names, so the traversal that produces them has
+     * to be deterministic.
+     *
+     * The cancellation verdict rides along rather than being probed separately, so
+     * the scan costs one round trip and cannot act on a stale answer.
+     */
+    scanSubtasks(taskId: string, round: number): Promise<SubtaskScan>;
+    /** Parent cancellation: cancel every still-pending Subtask. Returns the count. */
+    cancelPendingSubtasks(taskId: string): Promise<number>;
+    /**
+     * Force one branch terminal after the Workflow gave up on it: its
+     * `execute:<id>` step exhausted every retry, so `executeSubtaskChunk` will not
+     * be called again and no one else will resolve the row.
+     *
+     * The Workflow fails the *branch* rather than the Task so composition can
+     * disclose the gap while sibling branches keep their durable results. The
+     * managed child releases its external state and is then swept, both
+     * best-effort — nothing will read its cache now, but an abandoned run may still
+     * hold something outside this system, and dropping the child is not a reason to
+     * leak it. Idempotent: a no-op once the row is terminal.
+     */
+    failSubtask(id: SubtaskId, error: string): Promise<void>;
+    /**
+     * Run **one durable chunk** of a Subtask in an isolated, managed subagent,
+     * posting any progress the chunk emitted and durably recording a terminal
+     * outcome.
+     *
+     * The Workflow calls this repeatedly (chunk 0, 1, …) until it returns
+     * `done: true` — a single-chunk recipe finishes on chunk 0, a long one spans
+     * many. The row status distinguishes the cases with no chunk-number bookkeeping:
+     * chunk 0 claims `pending → running` (fresh — delete any stale child); every
+     * later chunk (and every retry) finds the row already `running` and leaves the
+     * child alone so its checkpointed run state resumes.
+     *
+     * The lifecycle rules that make it safe to re-run:
+     *
+     * - A terminal row short-circuits: the result is already durable.
+     * - A **fresh** execution deletes any stale child first.
+     * - An **ambiguous retry** (row already `running`) must *not* delete the child.
+     * - A **successful** chunk does *not* delete its child here — deletion is
+     *   deferred to a single post-delivery {@link sweepTaskChildren}, so a facet is
+     *   never aborted in the same tick its RPC returned (telemetry would mis-record
+     *   that as a failure). The result is still copied into the parent before any
+     *   delete; that now happens strictly later.
+     *
+     * Throws on a transient fault (the step retries and the child resumes from its
+     * checkpoint) and when the row is in a status this cannot accept — a subtask
+     * that is neither `pending` nor `running` nor already terminal. Both are bugs,
+     * not outcomes.
+     */
+    executeSubtaskChunk(id: SubtaskId, chunk: number, push?: TurnPushContext): Promise<SubtaskChunkOutcome>;
+    /**
+     * Delete every managed child this Task created — called **once**, from the
+     * Workflow's delivery step, after the Task is terminal.
+     *
+     * Per-Subtask deletion is deferred to here rather than run right after each
+     * successful chunk because `deleteSubAgent` aborts the facet: aborting a child
+     * in the same tick its `executeChunk` RPC returned records that
+     * already-successful invocation as `outcome:exception`, which is pure
+     * false-positive error noise (one per completed Subtask). By delivery every
+     * `execute` step has unwound, so these deletes hit **idle** facets and record
+     * nothing. Best-effort and idempotent — a name with no live facet is a silent
+     * no-op — so a Workflow replay of the sweep step is safe.
+     *
+     * Cancellation paths do their own child cleanup, so a canceled Task that never
+     * reaches delivery does not leak.
+     */
+    sweepTaskChildren(taskId: string): Promise<void>;
+    /**
+     * The shared front half of a chunk: resolve terminal/cancel short-circuits,
+     * validate the Recipe, claim the row (fresh-vs-retry), and assemble the
+     * execution request. Deterministic every chunk, so the request — and thus its
+     * fingerprint — is identical across a run's chunks and their retries.
+     */
+    private prepareChunk;
+    /**
+     * Invoke the managed child for one chunk, recreating it once on a fingerprint
+     * mismatch (a stale child from a *different* request — recoverable exactly once;
+     * a second mismatch is a genuine lifecycle bug and must surface).
+     */
+    private executeChunkInChild;
+    /** Let the owning plugin release whatever `resolveRuntime` acquired. */
+    private releaseRuntime;
+    /** The same, from a durable row rather than a built request. Best-effort. */
+    private releaseRuntimeQuietly;
+    /** The validated tool families for a Subtask type, or none if unusable. */
+    private toolFamiliesForType;
+    /**
+     * Best-effort release of a child's external state on cancellation (e.g. close a
+     * leased resource recorded in its workspace). Swallows failures — an unreleased
+     * resource is a documented residual, not a reason to fail cancellation.
+     */
+    private abortChildQuietly;
+    /** Persist a child's terminal outcome. Returns whether the guarded write applied. */
+    private persistResult;
+    /** Re-read a Subtask that must exist (it was just written). */
+    private requireSubtask;
+    /** Delete a managed child, swallowing failures (used on best-effort sweeps). */
+    private deleteChildQuietly;
+    /** Whether the parent Task has been canceled (checked before and after work). */
+    private isTaskCanceled;
+    /**
+     * Interrupt a canceled Task's live children: each `running` Subtask's managed
+     * child gets `abortRun`, so a long recipe stops at its current model call
+     * instead of at the next chunk boundary (up to `chunkSoftMs` later). A subtask
+     * that already finished (e.g. one branch completed while another was
+     * still running) is deliberately retained until the terminal-delivery sweep —
+     * but a canceled Task never reaches delivery, so its idle child is deleted
+     * here instead, or it would leak until the 30-day row cleanup regardless of
+     * that row's own age.
+     *
+     * Only `running` rows have a live RPC to abort. `subAgent` *creates* a facet
+     * that does not exist, so calling it for a `pending` row (no facet was ever
+     * made) would materialize one just to delete it — `deleteChildQuietly` is a
+     * silent no-op there, so it is called unconditionally instead of branching on
+     * status. Bounded by `maxSubtasks`. Best-effort throughout: a child that
+     * cannot be reached is logged, never fatal — cancellation must not fail
+     * because cleanup did.
+     *
+     * The `pending` rows are transitioned here too, and that is not bookkeeping:
+     * it is the only thing that resolves them. Nothing else is coming back to a
+     * pending row once a Task is canceled — the Workflow's scheduler runs a
+     * single pass and does not re-scan, and `prepareChunk` reports a canceled
+     * Task's pending row as terminal *without* claiming it, so a branch whose RPC
+     * had not yet reached the claim when the cancellation landed simply returns.
+     * Left to the loop below, which only deletes the child, the row would sit
+     * non-terminal until the 30-day cleanup.
+     */
+    protected onTaskCanceled(taskId: string): Promise<void>;
+}