@loopingai/core 0.3.0 → 0.4.0

package/dist/round/agent.d.ts

@@ -0,0 +1,267 @@
+import type { AiEnv, A2ASecretsEnv } from "../env.js";
+import type { GatewayIdentity } from "../a2a/verify.js";
+import type { TurnPushContext } from "../a2a/push.js";
+import type { Subtask, SubtaskChunkOutcome, SubtaskId, SubtaskScan, TurnTaskResult } from "../subtasks/types.js";
+import { LoopingAgent } 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 Subtask DAG, and the
+ * isolated subagent execution beneath it.
+ *
+ * Everything {@link LoopingAgent} 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`, `skipBlockedSubtasks`,
+ * `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 LoopingAgent<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 Subtask DAG 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: GatewayIdentity;
+        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 SubtaskNode} narrow does not apply.
+     */
+    private compositionBranches;
+    /** A Task's Subtasks, every round, in stable ordinal order. */
+    listSubtasks(taskId: string): Promise<Subtask[]>;
+    /**
+     * The Workflow's per-wave scan for **one round's** DAG: report a cancellation,
+     * or skip every pending Subtask blocked by a dependency that did not succeed and
+     * return the refreshed DAG as scheduler {@link SubtaskNode}s.
+     *
+     * Scoped to the round because dependency edges never cross one: an earlier
+     * round's rows are already terminal and irrelevant to this wave, and including
+     * them would only widen a projection that has a size cap.
+     *
+     * Skipping runs to a fixpoint because it propagates: a node skipped for a
+     * failed prerequisite blocks *its* dependents in turn. Bounded by the
+     * per-round maximum. Independent branches are untouched — one branch's failure
+     * never stops work that does not depend on it.
+     *
+     * The cancellation verdict rides along rather than being probed separately, so
+     * a wave costs one round trip and cannot act on a stale answer.
+     */
+    skipBlockedSubtasks(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 on scheduler-invariant violations — 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;
+    /**
+     * Load a Subtask's dependency results, in ordinal order.
+     *
+     * Order is semantic: it feeds the child's request fingerprint, so a retry must
+     * build the identical array or the cache misses. A dependency that has not
+     * completed means the scheduler ran this node too early.
+     */
+    private loadDependencyResults;
+    /** 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 of a wave 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.
+     */
+    protected onTaskCanceled(taskId: string): Promise<void>;
+}
+//# sourceMappingURL=agent.d.ts.map

package/dist/round/agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../src/round/agent.ts"],"names":[],"mappings":"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"}