@loopingai/core 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * `@loopingai/core` — the mandatory foundation for a Looping agent.
+ *
+ * This root entry carries only what nearly every consumer touches: the plugin
+ * contract, the config shape, the runtime factory, and the platform facts.
+ * Everything else lives behind a subpath (`/a2a`, `/agent`, `/db`, `/subtasks`,
+ * `/subagent`, `/worker`, `/testing`), so importing the delegation layer does not
+ * pull in the A2A adapter and importing the test harness never reaches a
+ * production bundle.
+ */
+export { createAgentRuntime, RuntimeSetupError, buildRecipeTools, collectToolFamilies, type AgentRuntime, type CreateAgentRuntimeOptions } from "./runtime/index.js";
+export { PLUGIN_CONTRACT_VERSION, definePlugin, type AgentPlugin, type EmitProgress, type EnrichResultContext, type PluginRequirements, type RecipeToolSet, type ResolveRuntimeContext, type ToolFamilyBuilder, type ToolFamilyContext } from "./contract/plugin.js";
+export type { DelegationNames, RecipeLimits, ResolvedRecipe, SubtaskParams, SubtaskParamsSchema, SubtaskParamsShape, SubtaskTypeSpec, ValidatedRecipe } from "./contract/recipe.js";
+export { RecipeValidationError, resolveLimits, validateRecipe, type RecipePolicy } from "./contract/validation.js";
+export { ConfigError, DEFAULT_CORE_CONFIG, resolveConfig, type AgentLimits, type CoreConfig, type CoreConfigOverrides, type ModelConfig, type RecallConfig, type SessionConfig } from "./config.js";
+export { parseGatewayOrigins, type A2ASecretsEnv, type AiEnv, type CoreEnv } from "./env.js";
+export { CHUNK_SOFT_MS, MAX_CHUNKS_PER_BRANCH, STEP_TIMEOUT_MS, STEPS_PER_INSTANCE } from "./platform.js";
+export type { PluginStore } from "./db/db.js";
+export { makeWorkspaceHandle, WorkspaceLimitError, WORKSPACE_MAX_FILES, WORKSPACE_MAX_FILE_BYTES, type WorkspaceBacking, type WorkspaceEntry, type WorkspaceHandle } from "./subagent/workspace.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EACL,kBAAkB,EAClB,iBAAiB,EACjB,gBAAgB,EAChB,mBAAmB,EACnB,KAAK,YAAY,EACjB,KAAK,yBAAyB,EAC/B,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACL,uBAAuB,EACvB,YAAY,EACZ,KAAK,WAAW,EAChB,KAAK,YAAY,EACjB,KAAK,mBAAmB,EACxB,KAAK,kBAAkB,EACvB,KAAK,aAAa,EAClB,KAAK,qBAAqB,EAC1B,KAAK,iBAAiB,EACtB,KAAK,iBAAiB,EACvB,MAAM,sBAAsB,CAAC;AAE9B,YAAY,EACV,eAAe,EACf,YAAY,EACZ,cAAc,EACd,aAAa,EACb,mBAAmB,EACnB,kBAAkB,EAClB,eAAe,EACf,eAAe,EAChB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EACL,qBAAqB,EACrB,aAAa,EACb,cAAc,EACd,KAAK,YAAY,EAClB,MAAM,0BAA0B,CAAC;AAElC,OAAO,EACL,WAAW,EACX,mBAAmB,EACnB,aAAa,EACb,KAAK,WAAW,EAChB,KAAK,UAAU,EACf,KAAK,mBAAmB,EACxB,KAAK,WAAW,EAChB,KAAK,YAAY,EACjB,KAAK,aAAa,EACnB,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,mBAAmB,EACnB,KAAK,aAAa,EAClB,KAAK,KAAK,EACV,KAAK,OAAO,EACb,MAAM,UAAU,CAAC;AAElB,OAAO,EACL,aAAa,EACb,qBAAqB,EACrB,eAAe,EACf,kBAAkB,EACnB,MAAM,eAAe,CAAC;AAEvB,YAAY,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C,OAAO,EACL,mBAAmB,EACnB,mBAAmB,EACnB,mBAAmB,EACnB,wBAAwB,EACxB,KAAK,gBAAgB,EACrB,KAAK,cAAc,EACnB,KAAK,eAAe,EACrB,MAAM,yBAAyB,CAAC"}

package/dist/index.js

@@ -0,0 +1,18 @@
+/**
+ * `@loopingai/core` — the mandatory foundation for a Looping agent.
+ *
+ * This root entry carries only what nearly every consumer touches: the plugin
+ * contract, the config shape, the runtime factory, and the platform facts.
+ * Everything else lives behind a subpath (`/a2a`, `/agent`, `/db`, `/subtasks`,
+ * `/subagent`, `/worker`, `/testing`), so importing the delegation layer does not
+ * pull in the A2A adapter and importing the test harness never reaches a
+ * production bundle.
+ */
+export { createAgentRuntime, RuntimeSetupError, buildRecipeTools, collectToolFamilies } from "./runtime/index.js";
+export { PLUGIN_CONTRACT_VERSION, definePlugin } from "./contract/plugin.js";
+export { RecipeValidationError, resolveLimits, validateRecipe } from "./contract/validation.js";
+export { ConfigError, DEFAULT_CORE_CONFIG, resolveConfig } from "./config.js";
+export { parseGatewayOrigins } from "./env.js";
+export { CHUNK_SOFT_MS, MAX_CHUNKS_PER_BRANCH, STEP_TIMEOUT_MS, STEPS_PER_INSTANCE } from "./platform.js";
+export { makeWorkspaceHandle, WorkspaceLimitError, WORKSPACE_MAX_FILES, WORKSPACE_MAX_FILE_BYTES } from "./subagent/workspace.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EACL,kBAAkB,EAClB,iBAAiB,EACjB,gBAAgB,EAChB,mBAAmB,EAGpB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACL,uBAAuB,EACvB,YAAY,EASb,MAAM,sBAAsB,CAAC;AAa9B,OAAO,EACL,qBAAqB,EACrB,aAAa,EACb,cAAc,EAEf,MAAM,0BAA0B,CAAC;AAElC,OAAO,EACL,WAAW,EACX,mBAAmB,EACnB,aAAa,EAOd,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,mBAAmB,EAIpB,MAAM,UAAU,CAAC;AAElB,OAAO,EACL,aAAa,EACb,qBAAqB,EACrB,eAAe,EACf,kBAAkB,EACnB,MAAM,eAAe,CAAC;AAIvB,OAAO,EACL,mBAAmB,EACnB,mBAAmB,EACnB,mBAAmB,EACnB,wBAAwB,EAIzB,MAAM,yBAAyB,CAAC"}

package/dist/platform.d.ts

@@ -0,0 +1,47 @@
+/**
+ * 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 is what produced
+ * the bug this file was extracted during: a *turn count* was used to keep a step
+ * under the step timeout, which only works if you can predict how long a turn
+ * takes. You cannot. Time bounds time here; turns bound cost, over in `config.ts`.
+ */
+/**
+ * Platform fact: a `step.do(...)` callback is killed at ~10 minutes (Workflows'
+ * default step timeout). {@link CHUNK_SOFT_MS} is sized against this.
+ */
+export declare const STEP_TIMEOUT_MS: number;
+/**
+ * Platform fact: a single Workflow instance may run ~10,000 steps (paid plan).
+ * {@link MAX_CHUNKS_PER_BRANCH} is sized against this — see the worst-case
+ * product asserted in `platform.spec.ts`.
+ */
+export declare const STEPS_PER_INSTANCE = 10000;
+/**
+ * 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.
+ */
+export declare const CHUNK_SOFT_MS: number;
+/**
+ * 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. That bound survives both; a nominal `maxTurns / turnsPerChunk`
+ *    estimate survived neither, which is why no such estimate exists any more.
+ * 2. The worst-case step product stays under {@link STEPS_PER_INSTANCE}.
+ */
+export declare const MAX_CHUNKS_PER_BRANCH = 40;
+//# sourceMappingURL=platform.d.ts.map

package/dist/platform.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"platform.d.ts","sourceRoot":"","sources":["../src/platform.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH;;;GAGG;AACH,eAAO,MAAM,eAAe,QAAc,CAAC;AAE3C;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,QAAS,CAAC;AAEzC;;;;;;;;GAQG;AACH,eAAO,MAAM,aAAa,QAAa,CAAC;AAExC;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,qBAAqB,KAAK,CAAC"}

package/dist/platform.js

@@ -0,0 +1,47 @@
+/**
+ * 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 is what produced
+ * the bug this file was extracted during: a *turn count* was used to keep a step
+ * under the step timeout, which only works if you can predict how long a turn
+ * takes. You cannot. Time bounds time here; turns bound cost, over in `config.ts`.
+ */
+/**
+ * Platform fact: a `step.do(...)` callback is killed at ~10 minutes (Workflows'
+ * default step timeout). {@link CHUNK_SOFT_MS} is sized against this.
+ */
+export const STEP_TIMEOUT_MS = 10 * 60_000;
+/**
+ * Platform fact: a single Workflow instance may run ~10,000 steps (paid plan).
+ * {@link MAX_CHUNKS_PER_BRANCH} is sized against this — 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.
+ */
+export const CHUNK_SOFT_MS = 4 * 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. That bound survives both; a nominal `maxTurns / turnsPerChunk`
+ *    estimate survived neither, which is why no such estimate exists any more.
+ * 2. The worst-case step product stays under {@link STEPS_PER_INSTANCE}.
+ */
+export const MAX_CHUNKS_PER_BRANCH = 40;
+//# sourceMappingURL=platform.js.map

package/dist/platform.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"platform.js","sourceRoot":"","sources":["../src/platform.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH;;;GAGG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,EAAE,GAAG,MAAM,CAAC;AAE3C;;;;GAIG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,MAAM,CAAC;AAEzC;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,GAAG,MAAM,CAAC;AAExC;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,EAAE,CAAC"}

package/dist/runtime/index.d.ts

@@ -0,0 +1,86 @@
+import type { ToolSet } from "ai";
+import { type CoreConfig, type CoreConfigOverrides } from "../config.js";
+import { type AgentPlugin, type EnrichResultContext, type ResolveRuntimeContext, type ToolFamilyBuilder } from "../contract/plugin.js";
+import type { PluginStore } from "../db/db.js";
+import type { RecipePolicy } from "../contract/validation.js";
+import { type SubtaskTypeRegistry } from "../subtasks/subtask-types.js";
+import type { RecipeExecutionResult, SubtaskRuntime } from "../subtasks/types.js";
+export { buildRecipeTools, collectToolFamilies } from "./tool-families.js";
+/**
+ * The agent runtime: everything that used to be a module-level constant,
+ * resolved once per Durable Object instance from the host's config and its
+ * installed plugins.
+ *
+ * This is the whole point of the package split. In the predecessor repo the
+ * subtask registry was imported at module scope and every derived value — the
+ * type map, the delegate tool's enum and description, the round contract, the
+ * known-tool-family allowlist — was computed at *import time*. That made the
+ * registry unoverridable, pulled every domain's module into every bundle, and
+ * could not read `env`, which does not exist at module scope on Workers.
+ *
+ * Build it in `onStart`:
+ *
+ * ```ts
+ * async onStart() {
+ *   this.runtime = createAgentRuntime({
+ *     config: { model: { chatModelId: "…" } },
+ *     plugins: plugins(this.env)
+ *   });
+ * }
+ * ```
+ */
+export interface AgentRuntime {
+    config: CoreConfig;
+    plugins: readonly AgentPlugin[];
+    /** The installed subtask types — what `delegate` may name. */
+    types: SubtaskTypeRegistry;
+    /** Every tool family the installed plugins registered, by name. */
+    toolFamilies: ReadonlyMap<string, ToolFamilyBuilder>;
+    /** The capability boundary `validateRecipe` enforces. */
+    policy: RecipePolicy;
+    /** Plugin-owned stores, to hand to `new AgentDB(storage, { stores })`. */
+    stores: readonly PluginStore[];
+    /** Every binding and secret the installed plugins require of the host. */
+    requirements: {
+        secrets: string[];
+        bindings: string[];
+    };
+    /** The plugin that declared a subtask type, or null. */
+    pluginForType(type: string): AgentPlugin | null;
+    /** Tools the installed plugins offer the *main* agent, merged. */
+    mainAgentTools(): ToolSet;
+    /**
+     * Every plugin's `capability` block, for the main agent's soul. Returns `""`
+     * when none declares one, so a call site can append unconditionally.
+     */
+    renderCapabilities(): string;
+    /**
+     * Resolve the session state an execution needs, by asking the plugin that owns
+     * its type. Returns `{}` for a type whose plugin declares no
+     * `resolveRuntime` — most of them.
+     */
+    resolveRuntime(ctx: ResolveRuntimeContext): Promise<SubtaskRuntime>;
+    /** Let the owning plugin amend a terminal result before it is persisted. */
+    enrichResult(ctx: EnrichResultContext, result: RecipeExecutionResult): Promise<RecipeExecutionResult>;
+    /** Let the owning plugin release whatever `resolveRuntime` acquired. */
+    onAbort(ctx: ResolveRuntimeContext): Promise<void>;
+}
+export interface CreateAgentRuntimeOptions {
+    plugins: readonly AgentPlugin[];
+    config?: CoreConfigOverrides;
+    /**
+     * Verify that every secret and binding the plugins declared is actually
+     * present, given the Worker `env`. Off by default because core cannot know
+     * which of a consumer's bindings are optional; pass `env` to switch it on.
+     */
+    env?: Record<string, unknown>;
+}
+/**
+ * Thrown when the installed plugins and the host disagree — a contract-version
+ * skew, a duplicate key, or a missing binding. Always at DO start, never mid-request.
+ */
+export declare class RuntimeSetupError extends Error {
+    constructor(message: string);
+}
+export declare function createAgentRuntime(options: CreateAgentRuntimeOptions): AgentRuntime;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/runtime/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,IAAI,CAAC;AAClC,OAAO,EAEL,KAAK,UAAU,EACf,KAAK,mBAAmB,EACzB,MAAM,cAAc,CAAC;AACtB,OAAO,EAEL,KAAK,WAAW,EAChB,KAAK,mBAAmB,EACxB,KAAK,qBAAqB,EAC1B,KAAK,iBAAiB,EACvB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAC9D,OAAO,EAEL,KAAK,mBAAmB,EACzB,MAAM,8BAA8B,CAAC;AACtC,OAAO,KAAK,EACV,qBAAqB,EACrB,cAAc,EACf,MAAM,sBAAsB,CAAC;AAG9B,OAAO,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAE3E;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,UAAU,CAAC;IACnB,OAAO,EAAE,SAAS,WAAW,EAAE,CAAC;IAChC,8DAA8D;IAC9D,KAAK,EAAE,mBAAmB,CAAC;IAC3B,mEAAmE;IACnE,YAAY,EAAE,WAAW,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC;IACrD,yDAAyD;IACzD,MAAM,EAAE,YAAY,CAAC;IACrB,0EAA0E;IAC1E,MAAM,EAAE,SAAS,WAAW,EAAE,CAAC;IAC/B,0EAA0E;IAC1E,YAAY,EAAE;QAAE,OAAO,EAAE,MAAM,EAAE,CAAC;QAAC,QAAQ,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;IAExD,wDAAwD;IACxD,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI,CAAC;IAChD,kEAAkE;IAClE,cAAc,IAAI,OAAO,CAAC;IAC1B;;;OAGG;IACH,kBAAkB,IAAI,MAAM,CAAC;IAE7B;;;;OAIG;IACH,cAAc,CAAC,GAAG,EAAE,qBAAqB,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;IACpE,4EAA4E;IAC5E,YAAY,CACV,GAAG,EAAE,mBAAmB,EACxB,MAAM,EAAE,qBAAqB,GAC5B,OAAO,CAAC,qBAAqB,CAAC,CAAC;IAClC,wEAAwE;IACxE,OAAO,CAAC,GAAG,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACpD;AAED,MAAM,WAAW,yBAAyB;IACxC,OAAO,EAAE,SAAS,WAAW,EAAE,CAAC;IAChC,MAAM,CAAC,EAAE,mBAAmB,CAAC;IAC7B;;;;OAIG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/B;AAED;;;GAGG;AACH,qBAAa,iBAAkB,SAAQ,KAAK;gBAC9B,OAAO,EAAE,MAAM;CAI5B;AAED,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,yBAAyB,GACjC,YAAY,CAiId"}

package/dist/runtime/index.js

@@ -0,0 +1,123 @@
+import { resolveConfig } from "../config.js";
+import { PLUGIN_CONTRACT_VERSION } from "../contract/plugin.js";
+import { makeSubtaskTypes } from "../subtasks/subtask-types.js";
+import { collectToolFamilies } from "./tool-families.js";
+export { buildRecipeTools, collectToolFamilies } from "./tool-families.js";
+/**
+ * Thrown when the installed plugins and the host disagree — a contract-version
+ * skew, a duplicate key, or a missing binding. Always at DO start, never mid-request.
+ */
+export class RuntimeSetupError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "RuntimeSetupError";
+    }
+}
+export function createAgentRuntime(options) {
+    const config = resolveConfig(options.config);
+    const plugins = options.plugins;
+    // --- contract + identity checks, all up front -----------------------------
+    const byKey = new Map();
+    for (const plugin of plugins) {
+        if (byKey.has(plugin.key)) {
+            throw new RuntimeSetupError(`duplicate plugin key "${plugin.key}" — two installed plugins claim it`);
+        }
+        byKey.set(plugin.key, plugin);
+        if (plugin.contractVersion !== PLUGIN_CONTRACT_VERSION) {
+            throw new RuntimeSetupError(`plugin "${plugin.key}" was built against plugin contract v${plugin.contractVersion}, ` +
+                `but this @loopingai/core speaks v${PLUGIN_CONTRACT_VERSION}. ` +
+                "Upgrade whichever of the two is behind — they publish from separate repos, " +
+                "so a version train can leave one lagging.");
+        }
+    }
+    // --- what the plugins contribute ------------------------------------------
+    const specs = plugins.flatMap((p) => (p.subtaskType ? [p.subtaskType] : []));
+    const types = makeSubtaskTypes(specs);
+    const toolFamilies = collectToolFamilies(plugins);
+    const typeOwner = new Map();
+    for (const plugin of plugins) {
+        if (plugin.subtaskType)
+            typeOwner.set(plugin.subtaskType.key, plugin);
+    }
+    const stores = plugins.flatMap((p) => (p.store ? [p.store] : []));
+    const secrets = [
+        ...new Set(plugins.flatMap((p) => [...(p.requires?.secrets ?? [])]))
+    ];
+    const bindings = [
+        ...new Set(plugins.flatMap((p) => [...(p.requires?.bindings ?? [])]))
+    ];
+    if (options.env) {
+        const missing = [];
+        for (const plugin of plugins) {
+            for (const name of [
+                ...(plugin.requires?.secrets ?? []),
+                ...(plugin.requires?.bindings ?? [])
+            ]) {
+                const value = options.env[name];
+                if (value === undefined || value === null || value === "") {
+                    missing.push(`${name} (required by "${plugin.key}")`);
+                }
+            }
+        }
+        if (missing.length > 0) {
+            throw new RuntimeSetupError(`missing bindings or secrets: ${missing.join(", ")}. ` +
+                "A plugin cannot add its own wrangler binding — declare these in wrangler.jsonc " +
+                "(and `wrangler secret put` the secrets).");
+        }
+    }
+    const policy = {
+        modelAllowlist: new Set([
+            config.model.chatModelId,
+            config.model.fallbackChatModelId
+        ]),
+        defaultPrimaryModelId: config.model.chatModelId,
+        defaultFallbackModelId: config.model.fallbackChatModelId,
+        knownToolFamilies: new Set(toolFamilies.keys()),
+        baselineLimits: config.subagentLimits
+    };
+    const pluginForType = (type) => typeOwner.get(type) ?? null;
+    return {
+        config,
+        plugins,
+        types,
+        toolFamilies,
+        policy,
+        stores,
+        requirements: { secrets, bindings },
+        pluginForType,
+        mainAgentTools() {
+            const tools = {};
+            for (const plugin of plugins) {
+                if (plugin.mainAgentTools)
+                    Object.assign(tools, plugin.mainAgentTools());
+            }
+            return tools;
+        },
+        renderCapabilities() {
+            const blocks = [];
+            for (const plugin of plugins) {
+                if (plugin.capability)
+                    blocks.push(plugin.capability);
+            }
+            return blocks.join("\n\n");
+        },
+        async resolveRuntime(ctx) {
+            const plugin = pluginForType(ctx.type);
+            if (!plugin?.resolveRuntime)
+                return {};
+            return (await plugin.resolveRuntime(ctx));
+        },
+        async enrichResult(ctx, result) {
+            const plugin = pluginForType(ctx.request.type);
+            if (!plugin?.enrichResult)
+                return result;
+            return plugin.enrichResult(ctx, result);
+        },
+        async onAbort(ctx) {
+            const plugin = pluginForType(ctx.type);
+            if (plugin?.onAbort)
+                await plugin.onAbort(ctx);
+        }
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/runtime/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/runtime/index.ts"],"names":[],"mappings":"AACA,OAAO,EACL,aAAa,EAGd,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,uBAAuB,EAKxB,MAAM,uBAAuB,CAAC;AAG/B,OAAO,EACL,gBAAgB,EAEjB,MAAM,8BAA8B,CAAC;AAKtC,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAEzD,OAAO,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AA2E3E;;;GAGG;AACH,MAAM,OAAO,iBAAkB,SAAQ,KAAK;IAC1C,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;IAClC,CAAC;CACF;AAED,MAAM,UAAU,kBAAkB,CAChC,OAAkC;IAElC,MAAM,MAAM,GAAG,aAAa,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IAC7C,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IAEhC,6EAA6E;IAE7E,MAAM,KAAK,GAAG,IAAI,GAAG,EAAuB,CAAC;IAC7C,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;QAC7B,IAAI,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC;YAC1B,MAAM,IAAI,iBAAiB,CACzB,yBAAyB,MAAM,CAAC,GAAG,oCAAoC,CACxE,CAAC;QACJ,CAAC;QACD,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;QAE9B,IAAI,MAAM,CAAC,eAAe,KAAK,uBAAuB,EAAE,CAAC;YACvD,MAAM,IAAI,iBAAiB,CACzB,WAAW,MAAM,CAAC,GAAG,wCAAwC,MAAM,CAAC,eAAe,IAAI;gBACrF,oCAAoC,uBAAuB,IAAI;gBAC/D,6EAA6E;gBAC7E,2CAA2C,CAC9C,CAAC;QACJ,CAAC;IACH,CAAC;IAED,6EAA6E;IAE7E,MAAM,KAAK,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IAC7E,MAAM,KAAK,GAAG,gBAAgB,CAAC,KAAK,CAAC,CAAC;IACtC,MAAM,YAAY,GAAG,mBAAmB,CAAC,OAAO,CAAC,CAAC;IAElD,MAAM,SAAS,GAAG,IAAI,GAAG,EAAuB,CAAC;IACjD,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;QAC7B,IAAI,MAAM,CAAC,WAAW;YAAE,SAAS,CAAC,GAAG,CAAC,MAAM,CAAC,WAAW,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;IACxE,CAAC;IAED,MAAM,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IAElE,MAAM,OAAO,GAAG;QACd,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,QAAQ,EAAE,OAAO,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;KACrE,CAAC;IACF,MAAM,QAAQ,GAAG;QACf,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,QAAQ,EAAE,QAAQ,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;KACtE,CAAC;IAEF,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC;QAChB,MAAM,OAAO,GAAa,EAAE,CAAC;QAC7B,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;YAC7B,KAAK,MAAM,IAAI,IAAI;gBACjB,GAAG,CAAC,MAAM,CAAC,QAAQ,EAAE,OAAO,IAAI,EAAE,CAAC;gBACnC,GAAG,CAAC,MAAM,CAAC,QAAQ,EAAE,QAAQ,IAAI,EAAE,CAAC;aACrC,EAAE,CAAC;gBACF,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;gBAChC,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,EAAE,EAAE,CAAC;oBAC1D,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,kBAAkB,MAAM,CAAC,GAAG,IAAI,CAAC,CAAC;gBACxD,CAAC;YACH,CAAC;QACH,CAAC;QACD,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACvB,MAAM,IAAI,iBAAiB,CACzB,gCAAgC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI;gBACpD,iFAAiF;gBACjF,0CAA0C,CAC7C,CAAC;QACJ,CAAC;IACH,CAAC;IAED,MAAM,MAAM,GAAiB;QAC3B,cAAc,EAAE,IAAI,GAAG,CAAC;YACtB,MAAM,CAAC,KAAK,CAAC,WAAW;YACxB,MAAM,CAAC,KAAK,CAAC,mBAAmB;SACjC,CAAC;QACF,qBAAqB,EAAE,MAAM,CAAC,KAAK,CAAC,WAAW;QAC/C,sBAAsB,EAAE,MAAM,CAAC,KAAK,CAAC,mBAAmB;QACxD,iBAAiB,EAAE,IAAI,GAAG,CAAC,YAAY,CAAC,IAAI,EAAE,CAAC;QAC/C,cAAc,EAAE,MAAM,CAAC,cAAc;KACtC,CAAC;IAEF,MAAM,aAAa,GAAG,CAAC,IAAY,EAAsB,EAAE,CACzD,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC;IAE9B,OAAO;QACL,MAAM;QACN,OAAO;QACP,KAAK;QACL,YAAY;QACZ,MAAM;QACN,MAAM;QACN,YAAY,EAAE,EAAE,OAAO,EAAE,QAAQ,EAAE;QAEnC,aAAa;QAEb,cAAc;YACZ,MAAM,KAAK,GAAY,EAAE,CAAC;YAC1B,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;gBAC7B,IAAI,MAAM,CAAC,cAAc;oBACvB,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,cAAc,EAAE,CAAC,CAAC;YAClD,CAAC;YACD,OAAO,KAAK,CAAC;QACf,CAAC;QAED,kBAAkB;YAChB,MAAM,MAAM,GAAa,EAAE,CAAC;YAC5B,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;gBAC7B,IAAI,MAAM,CAAC,UAAU;oBAAE,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;YACxD,CAAC;YACD,OAAO,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QAC7B,CAAC;QAED,KAAK,CAAC,cAAc,CAAC,GAA0B;YAC7C,MAAM,MAAM,GAAG,aAAa,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YACvC,IAAI,CAAC,MAAM,EAAE,cAAc;gBAAE,OAAO,EAAE,CAAC;YACvC,OAAO,CAAC,MAAM,MAAM,CAAC,cAAc,CAAC,GAAG,CAAC,CAAmB,CAAC;QAC9D,CAAC;QAED,KAAK,CAAC,YAAY,CAChB,GAAwB,EACxB,MAA6B;YAE7B,MAAM,MAAM,GAAG,aAAa,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;YAC/C,IAAI,CAAC,MAAM,EAAE,YAAY;gBAAE,OAAO,MAAM,CAAC;YACzC,OAAO,MAAM,CAAC,YAAY,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;QAC1C,CAAC;QAED,KAAK,CAAC,OAAO,CAAC,GAA0B;YACtC,MAAM,MAAM,GAAG,aAAa,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YACvC,IAAI,MAAM,EAAE,OAAO;gBAAE,MAAM,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QACjD,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/runtime/tool-families.d.ts

@@ -0,0 +1,33 @@
+import type { RecipeToolSet, ToolFamilyBuilder, ToolFamilyContext } from "../contract/plugin.js";
+import type { SubtaskRuntime } from "../subtasks/types.js";
+/**
+ * Assemble a recipe's toolset from the installed families.
+ *
+ * This replaces the predecessor's dispatcher, which was an `if / else if` chain
+ * naming three families inline — including a domain one — inside otherwise
+ * generic code, with static imports of that domain's modules at the top of the
+ * file. That is the single edit that made every agent's bundle carry every
+ * domain, and it is why this takes a map instead.
+ *
+ * A family a recipe names but no plugin registered is skipped rather than
+ * throwing: `validateRecipe` already dropped unknown families, so reaching one
+ * here means the policy and the registry disagreed, and a subagent that silently
+ * runs with fewer tools degrades better than one that fails a whole branch. The
+ * skipped names are returned so a caller can log them.
+ */
+export declare function buildRecipeTools<TRuntime = SubtaskRuntime>(families: readonly string[], registry: ReadonlyMap<string, ToolFamilyBuilder<TRuntime>>, ctx: ToolFamilyContext<TRuntime>): RecipeToolSet<TRuntime> & {
+    skipped: string[];
+};
+/**
+ * Collect every family builder the installed plugins registered, refusing
+ * duplicates.
+ *
+ * Two plugins claiming one family name is a misconfiguration whose symptom would
+ * otherwise be a subagent silently getting the wrong domain's tools — so it fails
+ * at DO start, named, instead.
+ */
+export declare function collectToolFamilies<TRuntime = SubtaskRuntime>(plugins: readonly {
+    key: string;
+    toolFamilies?: Record<string, ToolFamilyBuilder<TRuntime>>;
+}[]): Map<string, ToolFamilyBuilder<TRuntime>>;
+//# sourceMappingURL=tool-families.d.ts.map

package/dist/runtime/tool-families.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-families.d.ts","sourceRoot":"","sources":["../../src/runtime/tool-families.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,aAAa,EACb,iBAAiB,EACjB,iBAAiB,EAClB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAE3D;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,GAAG,cAAc,EACxD,QAAQ,EAAE,SAAS,MAAM,EAAE,EAC3B,QAAQ,EAAE,WAAW,CAAC,MAAM,EAAE,iBAAiB,CAAC,QAAQ,CAAC,CAAC,EAC1D,GAAG,EAAE,iBAAiB,CAAC,QAAQ,CAAC,GAC/B,aAAa,CAAC,QAAQ,CAAC,GAAG;IAAE,OAAO,EAAE,MAAM,EAAE,CAAA;CAAE,CAwBjD;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,GAAG,cAAc,EAC3D,OAAO,EAAE,SAAS;IAChB,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,QAAQ,CAAC,CAAC,CAAC;CAC5D,EAAE,GACF,GAAG,CAAC,MAAM,EAAE,iBAAiB,CAAC,QAAQ,CAAC,CAAC,CAgB1C"}

package/dist/runtime/tool-families.js

@@ -0,0 +1,62 @@
+/**
+ * Assemble a recipe's toolset from the installed families.
+ *
+ * This replaces the predecessor's dispatcher, which was an `if / else if` chain
+ * naming three families inline — including a domain one — inside otherwise
+ * generic code, with static imports of that domain's modules at the top of the
+ * file. That is the single edit that made every agent's bundle carry every
+ * domain, and it is why this takes a map instead.
+ *
+ * A family a recipe names but no plugin registered is skipped rather than
+ * throwing: `validateRecipe` already dropped unknown families, so reaching one
+ * here means the policy and the registry disagreed, and a subagent that silently
+ * runs with fewer tools degrades better than one that fails a whole branch. The
+ * skipped names are returned so a caller can log them.
+ */
+export function buildRecipeTools(families, registry, ctx) {
+    const tools = {};
+    const aborts = [];
+    const skipped = [];
+    for (const family of families) {
+        const build = registry.get(family);
+        if (!build) {
+            skipped.push(family);
+            continue;
+        }
+        const built = build(ctx);
+        Object.assign(tools, built.tools);
+        if (built.abort)
+            aborts.push(built.abort);
+    }
+    const abort = aborts.length === 0
+        ? undefined
+        : async (c) => {
+            for (const run of aborts)
+                await run(c);
+        };
+    return { tools, abort, skipped };
+}
+/**
+ * Collect every family builder the installed plugins registered, refusing
+ * duplicates.
+ *
+ * Two plugins claiming one family name is a misconfiguration whose symptom would
+ * otherwise be a subagent silently getting the wrong domain's tools — so it fails
+ * at DO start, named, instead.
+ */
+export function collectToolFamilies(plugins) {
+    const registry = new Map();
+    const owner = new Map();
+    for (const plugin of plugins) {
+        for (const [family, build] of Object.entries(plugin.toolFamilies ?? {})) {
+            const existing = owner.get(family);
+            if (existing) {
+                throw new Error(`tool family "${family}" is registered by both "${existing}" and "${plugin.key}"`);
+            }
+            owner.set(family, plugin.key);
+            registry.set(family, build);
+        }
+    }
+    return registry;
+}
+//# sourceMappingURL=tool-families.js.map

package/dist/runtime/tool-families.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-families.js","sourceRoot":"","sources":["../../src/runtime/tool-families.ts"],"names":[],"mappings":"AAQA;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,gBAAgB,CAC9B,QAA2B,EAC3B,QAA0D,EAC1D,GAAgC;IAEhC,MAAM,KAAK,GAAY,EAAE,CAAC;IAC1B,MAAM,MAAM,GAA+D,EAAE,CAAC;IAC9E,MAAM,OAAO,GAAa,EAAE,CAAC;IAE7B,KAAK,MAAM,MAAM,IAAI,QAAQ,EAAE,CAAC;QAC9B,MAAM,KAAK,GAAG,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QACnC,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;YACrB,SAAS;QACX,CAAC;QACD,MAAM,KAAK,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC;QACzB,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC;QAClC,IAAI,KAAK,CAAC,KAAK;YAAE,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IAC5C,CAAC;IAED,MAAM,KAAK,GACT,MAAM,CAAC,MAAM,KAAK,CAAC;QACjB,CAAC,CAAC,SAAS;QACX,CAAC,CAAC,KAAK,EAAE,CAA8B,EAAE,EAAE;YACvC,KAAK,MAAM,GAAG,IAAI,MAAM;gBAAE,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC;QACzC,CAAC,CAAC;IAER,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC;AACnC,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,mBAAmB,CACjC,OAGG;IAEH,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAuC,CAAC;IAChE,MAAM,KAAK,GAAG,IAAI,GAAG,EAAkB,CAAC;IACxC,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;QAC7B,KAAK,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,YAAY,IAAI,EAAE,CAAC,EAAE,CAAC;YACxE,MAAM,QAAQ,GAAG,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;YACnC,IAAI,QAAQ,EAAE,CAAC;gBACb,MAAM,IAAI,KAAK,CACb,gBAAgB,MAAM,4BAA4B,QAAQ,UAAU,MAAM,CAAC,GAAG,GAAG,CAClF,CAAC;YACJ,CAAC;YACD,KAAK,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC;YAC9B,QAAQ,CAAC,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;QAC9B,CAAC;IACH,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC"}

package/dist/subagent/fingerprint.d.ts

@@ -0,0 +1,38 @@
+import type { RecipeExecutionRequest } from "../subtasks/types.js";
+/**
+ * Version of the canonicalization format below.
+ *
+ * Bump it **only** when a change to `canonicalRequest` would make two equal
+ * executions hash differently. Bumping invalidates every cached result and every
+ * in-flight run's checkpoint, so it is a deliberate act, not a side effect.
+ */
+export declare const FINGERPRINT_VERSION = 1;
+/**
+ * Canonical JSON of the fields that define an execution's identity, rebuilt as
+ * literals in fixed key order so `JSON.stringify` is deterministic (object
+ * insertion order). Array order is semantic and preserved: the parent builds
+ * references and dependency results from ordinal-ordered rows, so a retry of the
+ * same execution is byte-identical.
+ *
+ * **Limits are canonicalized as *declared*, not as merged.** The predecessor
+ * merged them against the house baseline first, on the reasoning that `{}` and
+ * an explicit restatement of the baseline are the same execution and should hash
+ * alike. That reasoning is sound but its cost is not payable once the baseline
+ * lives in a versioned package: a patch release that nudges a default would
+ * change every fingerprint at once, and every in-flight subagent run would miss
+ * its checkpoint and restart from turn zero having already spent its budget.
+ *
+ * Hashing the sparse declaration inverts that trade. A recipe that spells out
+ * the baseline explicitly gets a different key from one that omits it — worth
+ * exactly one redundant execution, once, for a recipe nobody writes — and the
+ * host's baseline becomes free to move. {@link FINGERPRINT_VERSION} is the
+ * deliberate lever for the invalidation the merge used to cause accidentally.
+ */
+export declare function canonicalRequest(request: RecipeExecutionRequest): string;
+/**
+ * SHA-256 hex digest of the canonical request — the deterministic key for the
+ * subagent's single cached terminal result. The raw (pre-validation) request is
+ * fingerprinted, so the key matches exactly what the parent re-sends on retry.
+ */
+export declare function fingerprintRequest(request: RecipeExecutionRequest): Promise<string>;
+//# sourceMappingURL=fingerprint.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"fingerprint.d.ts","sourceRoot":"","sources":["../../src/subagent/fingerprint.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAGnE;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,IAAI,CAAC;AAErC;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,sBAAsB,GAAG,MAAM,CAuCxE;AAqBD;;;;GAIG;AACH,wBAAsB,kBAAkB,CACtC,OAAO,EAAE,sBAAsB,GAC9B,OAAO,CAAC,MAAM,CAAC,CAMjB"}

package/dist/subagent/fingerprint.js

@@ -0,0 +1,97 @@
+/**
+ * Version of the canonicalization format below.
+ *
+ * Bump it **only** when a change to `canonicalRequest` would make two equal
+ * executions hash differently. Bumping invalidates every cached result and every
+ * in-flight run's checkpoint, so it is a deliberate act, not a side effect.
+ */
+export const FINGERPRINT_VERSION = 1;
+/**
+ * Canonical JSON of the fields that define an execution's identity, rebuilt as
+ * literals in fixed key order so `JSON.stringify` is deterministic (object
+ * insertion order). Array order is semantic and preserved: the parent builds
+ * references and dependency results from ordinal-ordered rows, so a retry of the
+ * same execution is byte-identical.
+ *
+ * **Limits are canonicalized as *declared*, not as merged.** The predecessor
+ * merged them against the house baseline first, on the reasoning that `{}` and
+ * an explicit restatement of the baseline are the same execution and should hash
+ * alike. That reasoning is sound but its cost is not payable once the baseline
+ * lives in a versioned package: a patch release that nudges a default would
+ * change every fingerprint at once, and every in-flight subagent run would miss
+ * its checkpoint and restart from turn zero having already spent its budget.
+ *
+ * Hashing the sparse declaration inverts that trade. A recipe that spells out
+ * the baseline explicitly gets a different key from one that omits it — worth
+ * exactly one redundant execution, once, for a recipe nobody writes — and the
+ * host's baseline becomes free to move. {@link FINGERPRINT_VERSION} is the
+ * deliberate lever for the invalidation the merge used to cause accidentally.
+ */
+export function canonicalRequest(request) {
+    const canonical = {
+        v: FINGERPRINT_VERSION,
+        taskId: request.taskId,
+        subtaskId: request.subtaskId,
+        type: request.type,
+        recipe: {
+            key: request.recipe.key,
+            version: request.recipe.version,
+            primaryModelId: request.recipe.primaryModelId,
+            fallbackModelId: request.recipe.fallbackModelId,
+            soul: request.recipe.soul,
+            toolFamilies: request.recipe.toolFamilies,
+            enabled: request.recipe.enabled,
+            limits: canonicalLimits(request.recipe.limits),
+            historyWindow: request.recipe.historyWindow,
+            reportMetrics: request.recipe.reportMetrics
+        },
+        prompt: request.prompt,
+        references: request.references.map((ref) => ({
+            role: ref.role,
+            text: ref.text
+        })),
+        dependencyResults: request.dependencyResults.map((dep) => ({
+            subtaskId: dep.subtaskId,
+            type: dep.type,
+            resultParts: dep.resultParts.map((part) => ({
+                kind: part.kind,
+                text: part.text
+            }))
+        })),
+        // Params ARE identity: the same prompt against a different external resource
+        // is different work, and must not replay a cached result. Key order is fixed
+        // by sorting, so an equivalent params object always canonicalizes identically.
+        params: Object.fromEntries(Object.entries(request.params).sort(([a], [b]) => (a < b ? -1 : 1)))
+    };
+    return JSON.stringify(canonical);
+}
+/**
+ * A recipe's declared budget, normalized: only positive integers count (matching
+ * what `resolveLimits` would honor), and fields appear in fixed order with
+ * absent ones omitted. So `{}`, `{ maxTurns: 0 }`, and `{ maxTurns: 1.5 }` all
+ * canonicalize alike — they all mean "inherit the baseline".
+ */
+function canonicalLimits(limits) {
+    const keep = (n) => typeof n === "number" && Number.isInteger(n) && n > 0 ? n : undefined;
+    const out = {};
+    const maxTurns = keep(limits?.maxTurns);
+    if (maxTurns !== undefined)
+        out.maxTurns = maxTurns;
+    const maxWallMs = keep(limits?.maxWallMs);
+    if (maxWallMs !== undefined)
+        out.maxWallMs = maxWallMs;
+    return out;
+}
+/**
+ * SHA-256 hex digest of the canonical request — the deterministic key for the
+ * subagent's single cached terminal result. The raw (pre-validation) request is
+ * fingerprinted, so the key matches exactly what the parent re-sends on retry.
+ */
+export async function fingerprintRequest(request) {
+    const bytes = new TextEncoder().encode(canonicalRequest(request));
+    const digest = await crypto.subtle.digest("SHA-256", bytes);
+    return [...new Uint8Array(digest)]
+        .map((b) => b.toString(16).padStart(2, "0"))
+        .join("");
+}
+//# sourceMappingURL=fingerprint.js.map

package/dist/subagent/fingerprint.js.map

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