@loopingai/core 0.1.0

package/dist/subagent/index.d.ts

@@ -0,0 +1,147 @@
+import { Agent } from "agents";
+import type { ModelPair, ModelRuntime } from "../agent/model.js";
+import type { ToolFamilyBuilder } from "../contract/plugin.js";
+import { type RecipePolicy } from "../contract/validation.js";
+import type { RecipeChunkResult, RecipeExecutionRequest, SubtaskId, SubtaskRuntime } from "../subtasks/types.js";
+import { type SubtaskTypeRegistry } from "../subtasks/subtask-types.js";
+import { type WorkspaceBacking } from "./workspace.js";
+/**
+ * Everything the facet needs that comes from the *host*: resolved config, the
+ * capability policy, the installed subtask types and tool families, the model
+ * runtime, and a workspace backend.
+ *
+ * A Durable Object class is constructed by the runtime, so it cannot take
+ * constructor arguments — which is exactly the problem a library version of this
+ * facet has to solve. {@link RecipeSubagentBase} takes it from an abstract
+ * method instead: the consumer subclasses once, and everything host-specific
+ * arrives through that one seam.
+ */
+export interface SubagentRuntime {
+    policy: RecipePolicy;
+    types: SubtaskTypeRegistry;
+    models: ModelRuntime;
+    toolFamilies: ReadonlyMap<string, ToolFamilyBuilder>;
+    /** `CoreConfig.toolOutputWindow`. */
+    toolOutputWindow: number;
+    /** `CoreConfig.model.maxOutputTokens`. */
+    maxOutputTokens: number;
+    /**
+     * Build the durable file store over this facet's own SQLite.
+     *
+     * Supplied by the host because the backend is a plugin's: core declares the
+     * {@link WorkspaceBacking} shape and the caps, `@loopingai/plugins/workspace`
+     * supplies the `@cloudflare/shell` implementation, and an agent that never
+     * delegates file work installs neither.
+     */
+    workspaceBacking(sql: SqlStorage, name: () => string | undefined): WorkspaceBacking;
+}
+/**
+ * Message prefix of the error thrown when a child that already holds a cached
+ * terminal result receives a *different* request. Custom error classes don't
+ * survive DO RPC, so this prefix is the cross-boundary contract: it signals a
+ * parent lifecycle bug — stale children must be deleted before a genuinely new
+ * execution — and a Workflow retry after the parent's cleanup will succeed.
+ */
+export declare const FINGERPRINT_MISMATCH = "recipe-subagent: request fingerprint mismatch";
+/** Deterministic managed-child name for one Subtask execution (shared with C3). */
+export declare function subagentName(taskId: string, subtaskId: SubtaskId): string;
+/**
+ * `RecipeSubagent` — the isolated, stateless managed child that executes one
+ * Subtask under a resolved Recipe. Created as an Agents SDK sub-agent (facet)
+ * beneath the caller's `ReactiveAgent`, so it needs no wrangler Durable Object
+ * binding and no `new_sqlite_classes` entry; it must only be exported from the
+ * worker entry (`src/index.ts`) so `ctx.exports` can resolve it by class name.
+ *
+ * It never constructs a Session, never reads parent history beyond the
+ * references supplied on its request, never uses recall or durable memory, and
+ * never resolves a Recipe itself — it defensively re-validates the resolved
+ * Recipe the parent sends and accepts no configuration beyond it.
+ *
+ * Retry safety: the child persists at most one terminal result in its own
+ * SQLite, keyed by the deterministic request fingerprint, plus the rolling
+ * `run_state` of an in-progress multi-chunk run. A retry with the same
+ * fingerprint replays the terminal result or resumes the run without repeating
+ * completed work; a different request for the same child name is rejected
+ * ({@link FINGERPRINT_MISMATCH}). Transient platform faults throw and cache
+ * nothing, so the enclosing Workflow step can retry. The parent deletes the child
+ * (`deleteSubAgent`) only after its durable copy of the result succeeds, which
+ * wipes this storage — the workspace and run state included.
+ *
+ * Not "stateless" like the single-shot original: it owns per-execution durable
+ * state (the workspace and the run checkpoint), scoped to one execution and swept
+ * with the child.
+ */
+export declare abstract class RecipeSubagentBase<TEnv extends Cloudflare.Env = Cloudflare.Env> extends Agent<TEnv> {
+    /**
+     * Supply the host runtime. Called per RPC, not memoized here — an
+     * implementation that builds something expensive should memoize its own.
+     *
+     * ```ts
+     * export class RecipeSubagent extends RecipeSubagentBase<Env> {
+     *   protected subagentRuntime() {
+     *     return (this._rt ??= buildSubagentRuntime(this.env));
+     *   }
+     * }
+     * ```
+     */
+    protected abstract subagentRuntime(): SubagentRuntime;
+    /**
+     * Test-only `ModelPair` injection (a field, so never on the RPC stub).
+     * A whole pair — rather than model instances — so error-path tests can throw
+     * synchronously from the pair's factories, the repo convention (a rejecting
+     * `doGenerate` inside `generateText` leaks an unhandled rejection through
+     * the AI SDK telemetry span that workerd flags as a failure).
+     */
+    modelsOverride?: ModelPair;
+    private _workspace?;
+    /**
+     * The chunk currently executing here, if any. In memory only — it exists to be
+     * interrupted mid-call, and an isolate that lost it has no in-flight call left
+     * to interrupt. See {@link abortRun}.
+     */
+    private inflight?;
+    onStart(): Promise<void>;
+    /**
+     * Idempotent schema bootstrap. Also called lazily from the RPCs so
+     * `runInDurableObject`-style tests reach ready tables without RPC dispatch
+     * (mirroring how `AgentDB` migrates on construction).
+     */
+    private ensureTables;
+    /** The recipe's durable workspace, backed by this facet's own SQLite storage. */
+    private workspace;
+    /**
+     * Execute one durable chunk of a Subtask under the parent's resolved Recipe.
+     *
+     * A terminal outcome (completed / failed) is cached and replayed on retry. A
+     * mid-run chunk persists its rolling state to `run_state` and returns a
+     * `done: false` yield for the Workflow to run another chunk. `chunk` is a
+     * separate argument — never part of `request` — so every chunk fingerprints
+     * identically and the cache/resume keys line up. Only transient platform faults
+     * throw (nothing cached), so a Workflow retry resumes from the last checkpoint.
+     */
+    executeChunk(request: RecipeExecutionRequest, _chunk: number, runtime?: SubtaskRuntime): Promise<RecipeChunkResult>;
+    /**
+     * Interrupt the chunk running here right now, so a cancellation lands on the
+     * current model call instead of at the next chunk boundary (up to `chunkSoftMs`
+     * later — minutes, for a long recipe). Returns whether there was one to stop.
+     *
+     * Distinct from {@link abortExecution}, which releases *external* state after
+     * the fact; this only stops local work. An aborted run yields rather than
+     * producing a terminal result, so nothing is cached and the parent resolves the
+     * row itself. Reaching a facet mid-`executeChunk` works because it is awaiting
+     * a model `fetch` at the time, which does not hold the input gate closed.
+     */
+    abortRun(): Promise<boolean>;
+    /**
+     * Best-effort cleanup on cancellation: rebuild the recipe's tool families and
+     * run their `abort` hooks (e.g. release an external resource recorded in the
+     * workspace session file). Reconstructible from the workspace, so it is safe on a fresh
+     * isolate. The parent supplies the validated tool families it resolved.
+     */
+    abortExecution(toolFamilies: string[]): Promise<void>;
+    /** Persist a terminal result to the cache and return it as a done chunk. */
+    private cacheTerminal;
+    /** Persist the rolling run state (called after every model turn). */
+    private saveRunState;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/subagent/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/subagent/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,QAAQ,CAAC;AAG/B,OAAO,KAAK,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEjE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAC/D,OAAO,EAGL,KAAK,YAAY,EAClB,MAAM,2BAA2B,CAAC;AACnC,OAAO,KAAK,EAEV,iBAAiB,EACjB,sBAAsB,EAEtB,SAAS,EACT,cAAc,EACf,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAEL,KAAK,mBAAmB,EACzB,MAAM,8BAA8B,CAAC;AAEtC,OAAO,EAAuB,KAAK,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAI5E;;;;;;;;;;GAUG;AACH,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,YAAY,CAAC;IACrB,KAAK,EAAE,mBAAmB,CAAC;IAC3B,MAAM,EAAE,YAAY,CAAC;IACrB,YAAY,EAAE,WAAW,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC;IACrD,qCAAqC;IACrC,gBAAgB,EAAE,MAAM,CAAC;IACzB,0CAA0C;IAC1C,eAAe,EAAE,MAAM,CAAC;IACxB;;;;;;;OAOG;IACH,gBAAgB,CACd,GAAG,EAAE,UAAU,EACf,IAAI,EAAE,MAAM,MAAM,GAAG,SAAS,GAC7B,gBAAgB,CAAC;CACrB;AAED;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,kDACgB,CAAC;AAElD,mFAAmF;AACnF,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS,GAAG,MAAM,CAEzE;AAkBD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,8BAAsB,kBAAkB,CACtC,IAAI,SAAS,UAAU,CAAC,GAAG,GAAG,UAAU,CAAC,GAAG,CAC5C,SAAQ,KAAK,CAAC,IAAI,CAAC;IACnB;;;;;;;;;;;OAWG;IACH,SAAS,CAAC,QAAQ,CAAC,eAAe,IAAI,eAAe;IAErD;;;;;;OAMG;IACH,cAAc,CAAC,EAAE,SAAS,CAAC;IAE3B,OAAO,CAAC,UAAU,CAAC,CAAmB;IAEtC;;;;OAIG;IACH,OAAO,CAAC,QAAQ,CAAC,CAAkB;IAE7B,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAI9B;;;;OAIG;IACH,OAAO,CAAC,YAAY;IAmBpB,iFAAiF;IACjF,OAAO,CAAC,SAAS;IAOjB;;;;;;;;;OASG;IACG,YAAY,CAChB,OAAO,EAAE,sBAAsB,EAC/B,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC,iBAAiB,CAAC;IAmH7B;;;;;;;;;;OAUG;IACG,QAAQ,IAAI,OAAO,CAAC,OAAO,CAAC;IAMlC;;;;;OAKG;IACG,cAAc,CAAC,YAAY,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAa3D,4EAA4E;IAC5E,OAAO,CAAC,aAAa;IAgBrB,qEAAqE;IACrE,OAAO,CAAC,YAAY;CAUrB"}

package/dist/subagent/index.js

@@ -0,0 +1,299 @@
+import { Agent } from "agents";
+import { z } from "zod";
+import { CHUNK_SOFT_MS } from "../platform.js";
+import { buildRecipeTools } from "../runtime/tool-families.js";
+import { RecipeValidationError, validateRecipe } from "../contract/validation.js";
+import { SubtaskParamsError } from "../subtasks/subtask-types.js";
+import { renderSubagentPrompt } from "./prompt.js";
+import { makeWorkspaceHandle } from "./workspace.js";
+import { fingerprintRequest } from "./fingerprint.js";
+import { runResumableChunk } from "./run.js";
+/**
+ * Message prefix of the error thrown when a child that already holds a cached
+ * terminal result receives a *different* request. Custom error classes don't
+ * survive DO RPC, so this prefix is the cross-boundary contract: it signals a
+ * parent lifecycle bug — stale children must be deleted before a genuinely new
+ * execution — and a Workflow retry after the parent's cleanup will succeed.
+ */
+export const FINGERPRINT_MISMATCH = "recipe-subagent: request fingerprint mismatch";
+/** Deterministic managed-child name for one Subtask execution (shared with C3). */
+export function subagentName(taskId, subtaskId) {
+    return `subtask:${taskId}:${subtaskId}`;
+}
+/** Zod mirror of {@link RecipeExecutionResult} for parsing the cached JSON. */
+const cachedResultSchema = z.discriminatedUnion("status", [
+    z.object({
+        status: z.literal("completed"),
+        resultParts: z
+            .array(z.object({ kind: z.literal("text"), text: z.string() }))
+            .min(1),
+        modelId: z.string()
+    }),
+    z.object({
+        status: z.literal("failed"),
+        error: z.string(),
+        modelId: z.string().nullable()
+    })
+]);
+/**
+ * `RecipeSubagent` — the isolated, stateless managed child that executes one
+ * Subtask under a resolved Recipe. Created as an Agents SDK sub-agent (facet)
+ * beneath the caller's `ReactiveAgent`, so it needs no wrangler Durable Object
+ * binding and no `new_sqlite_classes` entry; it must only be exported from the
+ * worker entry (`src/index.ts`) so `ctx.exports` can resolve it by class name.
+ *
+ * It never constructs a Session, never reads parent history beyond the
+ * references supplied on its request, never uses recall or durable memory, and
+ * never resolves a Recipe itself — it defensively re-validates the resolved
+ * Recipe the parent sends and accepts no configuration beyond it.
+ *
+ * Retry safety: the child persists at most one terminal result in its own
+ * SQLite, keyed by the deterministic request fingerprint, plus the rolling
+ * `run_state` of an in-progress multi-chunk run. A retry with the same
+ * fingerprint replays the terminal result or resumes the run without repeating
+ * completed work; a different request for the same child name is rejected
+ * ({@link FINGERPRINT_MISMATCH}). Transient platform faults throw and cache
+ * nothing, so the enclosing Workflow step can retry. The parent deletes the child
+ * (`deleteSubAgent`) only after its durable copy of the result succeeds, which
+ * wipes this storage — the workspace and run state included.
+ *
+ * Not "stateless" like the single-shot original: it owns per-execution durable
+ * state (the workspace and the run checkpoint), scoped to one execution and swept
+ * with the child.
+ */
+export class RecipeSubagentBase extends Agent {
+    /**
+     * Test-only `ModelPair` injection (a field, so never on the RPC stub).
+     * A whole pair — rather than model instances — so error-path tests can throw
+     * synchronously from the pair's factories, the repo convention (a rejecting
+     * `doGenerate` inside `generateText` leaks an unhandled rejection through
+     * the AI SDK telemetry span that workerd flags as a failure).
+     */
+    modelsOverride;
+    _workspace;
+    /**
+     * The chunk currently executing here, if any. In memory only — it exists to be
+     * interrupted mid-call, and an isolate that lost it has no in-flight call left
+     * to interrupt. See {@link abortRun}.
+     */
+    inflight;
+    async onStart() {
+        this.ensureTables();
+    }
+    /**
+     * Idempotent schema bootstrap. Also called lazily from the RPCs so
+     * `runInDurableObject`-style tests reach ready tables without RPC dispatch
+     * (mirroring how `AgentDB` migrates on construction).
+     */
+    ensureTables() {
+        this.sql `
+      CREATE TABLE IF NOT EXISTS execution_cache (
+        slot INTEGER PRIMARY KEY CHECK (slot = 1),
+        fingerprint TEXT NOT NULL,
+        result_json TEXT NOT NULL,
+        created_at INTEGER NOT NULL
+      )
+    `;
+        this.sql `
+      CREATE TABLE IF NOT EXISTS run_state (
+        slot INTEGER PRIMARY KEY CHECK (slot = 1),
+        fingerprint TEXT NOT NULL,
+        state_json TEXT NOT NULL,
+        updated_at INTEGER NOT NULL
+      )
+    `;
+    }
+    /** The recipe's durable workspace, backed by this facet's own SQLite storage. */
+    workspace() {
+        return (this._workspace ??= this.subagentRuntime().workspaceBacking(this.ctx.storage.sql, () => this.name));
+    }
+    /**
+     * Execute one durable chunk of a Subtask under the parent's resolved Recipe.
+     *
+     * A terminal outcome (completed / failed) is cached and replayed on retry. A
+     * mid-run chunk persists its rolling state to `run_state` and returns a
+     * `done: false` yield for the Workflow to run another chunk. `chunk` is a
+     * separate argument — never part of `request` — so every chunk fingerprints
+     * identically and the cache/resume keys line up. Only transient platform faults
+     * throw (nothing cached), so a Workflow retry resumes from the last checkpoint.
+     */
+    async executeChunk(request, _chunk, runtime = {}) {
+        this.ensureTables();
+        const rt = this.subagentRuntime();
+        const fingerprint = await fingerprintRequest(request);
+        // A terminal result already exists → replay it (idempotent retry).
+        const cached = this.sql `
+      SELECT fingerprint, result_json FROM execution_cache WHERE slot = 1
+    `[0];
+        if (cached) {
+            if (cached.fingerprint !== fingerprint)
+                throw mismatch("terminal");
+            return {
+                done: true,
+                result: cachedResultSchema.parse(JSON.parse(cached.result_json)),
+                progress: []
+            };
+        }
+        // Validate the recipe up front; an unusable recipe (disabled, or with no
+        // soul) and an empty prompt are deterministic, cacheable terminal failures
+        // with no model call.
+        let recipe;
+        try {
+            recipe = validateRecipe(request.recipe, rt.policy);
+        }
+        catch (error) {
+            if (!(error instanceof RecipeValidationError))
+                throw error;
+            return this.cacheTerminal(fingerprint, {
+                status: "failed",
+                error: error.message,
+                modelId: null
+            });
+        }
+        if (request.prompt.trim() === "") {
+            return this.cacheTerminal(fingerprint, {
+                status: "failed",
+                error: "empty subtask prompt",
+                modelId: null
+            });
+        }
+        // Re-check the type's param contract, the same defensive posture as
+        // `validateRecipe`: a play with no scorecard cannot succeed, and failing
+        // here costs no model call and gives the parent a real diagnostic.
+        try {
+            rt.types.validateParams(request.type, request.params);
+        }
+        catch (error) {
+            if (!(error instanceof SubtaskParamsError))
+                throw error;
+            return this.cacheTerminal(fingerprint, {
+                status: "failed",
+                error: error.message,
+                modelId: null
+            });
+        }
+        // Resume an in-progress run, guarding against a stale child holding a
+        // *different* run (the same reuse hazard the terminal cache guards).
+        const saved = this.sql `
+      SELECT fingerprint, state_json FROM run_state WHERE slot = 1
+    `[0];
+        if (saved && saved.fingerprint !== fingerprint)
+            throw mismatch("in-progress");
+        const prev = saved
+            ? JSON.parse(saved.state_json)
+            : null;
+        const models = this.modelsOverride ??
+            rt.models.createModelPair({
+                primaryModelId: recipe.primaryModelId,
+                fallbackModelId: recipe.fallbackModelId,
+                // AI Gateway correlation: tie this child's model calls to its Subtask.
+                metadata: { taskId: request.taskId, subtaskId: request.subtaskId }
+            });
+        const workspace = makeWorkspaceHandle(this.workspace());
+        const progress = [];
+        const { tools } = buildRecipeTools(recipe.toolFamilies, rt.toolFamilies, {
+            workspace,
+            emitProgress: (event) => progress.push(event),
+            params: request.params,
+            runtime
+        });
+        const { system, prompt } = renderSubagentPrompt({ ...request, recipe });
+        const controller = new AbortController();
+        this.inflight = controller;
+        let outcome, state;
+        try {
+            ({ outcome, state } = await runResumableChunk(prev, {
+                system,
+                seedPrompt: prompt,
+                models,
+                tools,
+                limits: recipe.limits,
+                chunkSoftMs: CHUNK_SOFT_MS,
+                historyWindow: recipe.historyWindow,
+                toolOutputWindow: rt.toolOutputWindow,
+                reportMetrics: recipe.reportMetrics,
+                maxOutputTokens: rt.maxOutputTokens,
+                now: () => Date.now(),
+                progress,
+                checkpoint: (s) => this.saveRunState(fingerprint, s),
+                abortSignal: controller.signal
+            }));
+        }
+        finally {
+            this.inflight = undefined;
+        }
+        // The per-step checkpoint already ran; persist the final state too so a chunk
+        // that yielded without a completed step still advances durably.
+        this.saveRunState(fingerprint, state);
+        if (outcome.done) {
+            return this.cacheTerminal(fingerprint, outcome.result, outcome.progress);
+        }
+        return { done: false, progress: outcome.progress };
+    }
+    /**
+     * Interrupt the chunk running here right now, so a cancellation lands on the
+     * current model call instead of at the next chunk boundary (up to `chunkSoftMs`
+     * later — minutes, for a long recipe). Returns whether there was one to stop.
+     *
+     * Distinct from {@link abortExecution}, which releases *external* state after
+     * the fact; this only stops local work. An aborted run yields rather than
+     * producing a terminal result, so nothing is cached and the parent resolves the
+     * row itself. Reaching a facet mid-`executeChunk` works because it is awaiting
+     * a model `fetch` at the time, which does not hold the input gate closed.
+     */
+    async abortRun() {
+        if (!this.inflight)
+            return false;
+        this.inflight.abort();
+        return true;
+    }
+    /**
+     * Best-effort cleanup on cancellation: rebuild the recipe's tool families and
+     * run their `abort` hooks (e.g. release an external resource recorded in the
+     * workspace session file). Reconstructible from the workspace, so it is safe on a fresh
+     * isolate. The parent supplies the validated tool families it resolved.
+     */
+    async abortExecution(toolFamilies) {
+        this.ensureTables();
+        const rt = this.subagentRuntime();
+        const ctx = {
+            workspace: makeWorkspaceHandle(this.workspace()),
+            emitProgress: () => { },
+            params: {},
+            runtime: {}
+        };
+        const { abort } = buildRecipeTools(toolFamilies, rt.toolFamilies, ctx);
+        if (abort)
+            await abort(ctx);
+    }
+    /** Persist a terminal result to the cache and return it as a done chunk. */
+    cacheTerminal(fingerprint, result, progress = []) {
+        this.sql `
+      INSERT INTO execution_cache (slot, fingerprint, result_json, created_at)
+      VALUES (1, ${fingerprint}, ${JSON.stringify(result)}, ${Date.now()})
+      ON CONFLICT (slot) DO UPDATE SET
+        fingerprint = excluded.fingerprint,
+        result_json = excluded.result_json,
+        created_at = excluded.created_at
+    `;
+        return { done: true, result, progress };
+    }
+    /** Persist the rolling run state (called after every model turn). */
+    saveRunState(fingerprint, state) {
+        this.sql `
+      INSERT INTO run_state (slot, fingerprint, state_json, updated_at)
+      VALUES (1, ${fingerprint}, ${JSON.stringify(state)}, ${Date.now()})
+      ON CONFLICT (slot) DO UPDATE SET
+        fingerprint = excluded.fingerprint,
+        state_json = excluded.state_json,
+        updated_at = excluded.updated_at
+    `;
+    }
+}
+/** The cross-RPC stale-child error (see {@link FINGERPRINT_MISMATCH}). */
+function mismatch(phase) {
+    return new Error(`${FINGERPRINT_MISMATCH}: this child already holds a ${phase} state for a ` +
+        "different request; the parent must delete a stale child before starting a " +
+        "genuinely new execution");
+}
+//# sourceMappingURL=index.js.map

package/dist/subagent/index.js.map

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

package/dist/subagent/prompt.d.ts

@@ -0,0 +1,34 @@
+import type { RecipeExecutionRequest } from "../subtasks/types.js";
+import type { ValidatedRecipe } from "../contract/recipe.js";
+/**
+ * Deterministic rendering of one subagent invocation. Pure — no model, no
+ * Session, no lookups: everything comes verbatim from the request. The four
+ * sections stay clearly separated and labeled so tests (and the model) can tell
+ * them apart: the execution's budget, the main-agent instruction, the verbatim
+ * conversation reference snapshots, and generated dependency output — which is
+ * explicitly marked as generated and never presented as conversation evidence.
+ */
+/**
+ * A request whose Recipe has been through `validateRecipe`, so its limits are
+ * merged rather than partial. Required rather than convenient: the budget line
+ * below states a number to the model, and stating "up to undefined turns" — or
+ * quietly rendering a Recipe's override as the whole budget — is worse than not
+ * telling it at all.
+ */
+export type RenderableExecution = RecipeExecutionRequest & {
+    recipe: ValidatedRecipe;
+};
+export interface RenderedInvocation {
+    /** The validated Recipe soul, verbatim — the invocation's system prompt. */
+    system: string;
+    /** The sectioned user message (instruction, references, dependency results). */
+    prompt: string;
+}
+/**
+ * Render the sectioned user message for one execution. Reference snapshots are
+ * emitted exactly as captured at decomposition — `[ref N]` labels with the
+ * message role, no summarizing, rewriting, or interpolation. Sections with no
+ * content are omitted entirely.
+ */
+export declare function renderSubagentPrompt(request: RenderableExecution): RenderedInvocation;
+//# sourceMappingURL=prompt.d.ts.map

package/dist/subagent/prompt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt.d.ts","sourceRoot":"","sources":["../../src/subagent/prompt.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AACnE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAE7D;;;;;;;GAOG;AAEH;;;;;;GAMG;AACH,MAAM,MAAM,mBAAmB,GAAG,sBAAsB,GAAG;IACzD,MAAM,EAAE,eAAe,CAAC;CACzB,CAAC;AAsBF,MAAM,WAAW,kBAAkB;IACjC,4EAA4E;IAC5E,MAAM,EAAE,MAAM,CAAC;IACf,gFAAgF;IAChF,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,mBAAmB,GAC3B,kBAAkB,CA8BpB"}

package/dist/subagent/prompt.js

@@ -0,0 +1,46 @@
+/**
+ * The budget, in the terms the runner actually enforces.
+ *
+ * Worth its own section because a subagent that does not know its budget invents
+ * one, and a *main* agent writing the prompt invents one for it: in one logged
+ * play the instruction said "you have up to 20 actions total" — 20 was the turn
+ * budget — and the subagent stopped after eleven game moves reasoning that it
+ * must be out. Turns and actions are not the same currency and this is the line
+ * that says so.
+ */
+function renderBudget(limits) {
+    const minutes = Math.round(limits.maxWallMs / 60_000);
+    return (`# Budget\nUp to ${limits.maxTurns} turns and about ${minutes} minutes. ` +
+        "One turn is one tool call, however much that call does — anything a tool " +
+        "counts internally is its own budget, not this one. Reaching either ceiling " +
+        "does not drop your work: you get one last turn, with no tools, to write up " +
+        "what you have.");
+}
+/**
+ * Render the sectioned user message for one execution. Reference snapshots are
+ * emitted exactly as captured at decomposition — `[ref N]` labels with the
+ * message role, no summarizing, rewriting, or interpolation. Sections with no
+ * content are omitted entirely.
+ */
+export function renderSubagentPrompt(request) {
+    const sections = [renderBudget(request.recipe.limits)];
+    const prompt = request.prompt.trim();
+    if (prompt !== "") {
+        sections.push(`# Task\n${prompt}`);
+    }
+    if (request.references.length > 0) {
+        const refs = request.references.map((ref, i) => `[ref ${i + 1}] (${ref.role}): ${ref.text}`);
+        sections.push("# Conversation references (verbatim snapshots of the caller's conversation)\n" +
+            refs.join("\n"));
+    }
+    if (request.dependencyResults.length > 0) {
+        const deps = request.dependencyResults.map((dep) => {
+            const text = dep.resultParts.map((part) => part.text).join("\n");
+            return `[dependency ${dep.subtaskId}] (${dep.type}): ${text}`;
+        });
+        sections.push("# Dependency results (generated output from prerequisite subtasks — not conversation evidence)\n" +
+            deps.join("\n"));
+    }
+    return { system: request.recipe.soul, prompt: sections.join("\n\n") };
+}
+//# sourceMappingURL=prompt.js.map

package/dist/subagent/prompt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt.js","sourceRoot":"","sources":["../../src/subagent/prompt.ts"],"names":[],"mappings":"AAuBA;;;;;;;;;GASG;AACH,SAAS,YAAY,CAAC,MAAiC;IACrD,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,SAAS,GAAG,MAAM,CAAC,CAAC;IACtD,OAAO,CACL,mBAAmB,MAAM,CAAC,QAAQ,oBAAoB,OAAO,YAAY;QACzE,2EAA2E;QAC3E,6EAA6E;QAC7E,6EAA6E;QAC7E,gBAAgB,CACjB,CAAC;AACJ,CAAC;AAQD;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB,CAClC,OAA4B;IAE5B,MAAM,QAAQ,GAAa,CAAC,YAAY,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC;IAEjE,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;IACrC,IAAI,MAAM,KAAK,EAAE,EAAE,CAAC;QAClB,QAAQ,CAAC,IAAI,CAAC,WAAW,MAAM,EAAE,CAAC,CAAC;IACrC,CAAC;IAED,IAAI,OAAO,CAAC,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAClC,MAAM,IAAI,GAAG,OAAO,CAAC,UAAU,CAAC,GAAG,CACjC,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC,QAAQ,CAAC,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,MAAM,GAAG,CAAC,IAAI,EAAE,CACxD,CAAC;QACF,QAAQ,CAAC,IAAI,CACX,+EAA+E;YAC7E,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAClB,CAAC;IACJ,CAAC;IAED,IAAI,OAAO,CAAC,iBAAiB,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACzC,MAAM,IAAI,GAAG,OAAO,CAAC,iBAAiB,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE;YACjD,MAAM,IAAI,GAAG,GAAG,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACjE,OAAO,eAAe,GAAG,CAAC,SAAS,MAAM,GAAG,CAAC,IAAI,MAAM,IAAI,EAAE,CAAC;QAChE,CAAC,CAAC,CAAC;QACH,QAAQ,CAAC,IAAI,CACX,kGAAkG;YAChG,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAClB,CAAC;IACJ,CAAC;IAED,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;AACxE,CAAC"}