@loopingai/core 0.1.0

package/dist/config.js

@@ -0,0 +1,92 @@
+/**
+ * The shapes of everything an agent tunes, plus a working set of defaults.
+ *
+ * In the predecessor repos this file held bare `export const`s that ~12 modules
+ * imported directly. That is what this package cannot do: a module-level constant
+ * read at import time is not overridable by a consumer, and it freezes the value
+ * into the module graph before `env` exists. So core owns the *shapes* and a
+ * baseline; a consuming agent passes overrides to {@link resolveConfig} once, at
+ * DO start, and the resolved object is threaded through explicitly.
+ *
+ * The distinction against {@link file://./platform.ts} stays sharp: nothing here
+ * is a platform fact, and nothing there is tunable.
+ */
+/**
+ * A working baseline. Every value is overridable; none is a ceiling. These are
+ * the values both predecessor agents converged on in production, so they are a
+ * reasonable place to start rather than an opinion about your domain.
+ */
+export const DEFAULT_CORE_CONFIG = {
+    model: {
+        chatModelId: "@cf/zai-org/glm-5.2",
+        fallbackChatModelId: "@cf/moonshotai/kimi-k2.7-code",
+        aiGatewayId: "default",
+        maxOutputTokens: 16_384,
+        reasoningEffort: "medium",
+        embeddingModelId: "@cf/baai/bge-m3"
+    },
+    mainAgentLimits: { maxTurns: 20, maxWallMs: 60 * 60_000 },
+    subagentLimits: { maxTurns: 20, maxWallMs: 30 * 60_000 },
+    toolOutputWindow: 4,
+    maxSubtasks: 8,
+    session: {
+        memoryMaxTokens: 1200,
+        compactAfterTokens: 16_000,
+        compactTailTokens: 5_000,
+        memoryDescription: "Durable facts worth remembering across all of this caller's conversations — " +
+            "stable preferences, decisions, people, and context. Keep it concise."
+    },
+    recall: { topK: 5, metadataTextMax: 2000 }
+};
+export class ConfigError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ConfigError";
+    }
+}
+/**
+ * Merge overrides onto {@link DEFAULT_CORE_CONFIG} and check the invariants that
+ * are cheap to get wrong and expensive to notice.
+ *
+ * Called once, at DO start, and the result threaded explicitly from there. Do
+ * not call it per-request: the point of resolving is that every module downstream
+ * reads the same object.
+ */
+export function resolveConfig(overrides = {}) {
+    const config = {
+        model: { ...DEFAULT_CORE_CONFIG.model, ...overrides.model },
+        mainAgentLimits: {
+            ...DEFAULT_CORE_CONFIG.mainAgentLimits,
+            ...overrides.mainAgentLimits
+        },
+        subagentLimits: {
+            ...DEFAULT_CORE_CONFIG.subagentLimits,
+            ...overrides.subagentLimits
+        },
+        toolOutputWindow: overrides.toolOutputWindow ?? DEFAULT_CORE_CONFIG.toolOutputWindow,
+        maxSubtasks: overrides.maxSubtasks ?? DEFAULT_CORE_CONFIG.maxSubtasks,
+        session: { ...DEFAULT_CORE_CONFIG.session, ...overrides.session },
+        recall: { ...DEFAULT_CORE_CONFIG.recall, ...overrides.recall }
+    };
+    const positive = (value, name) => {
+        if (!Number.isFinite(value) || value <= 0) {
+            throw new ConfigError(`${name} must be a positive number, got ${value}`);
+        }
+    };
+    positive(config.mainAgentLimits.maxTurns, "mainAgentLimits.maxTurns");
+    positive(config.mainAgentLimits.maxWallMs, "mainAgentLimits.maxWallMs");
+    positive(config.subagentLimits.maxTurns, "subagentLimits.maxTurns");
+    positive(config.subagentLimits.maxWallMs, "subagentLimits.maxWallMs");
+    positive(config.toolOutputWindow, "toolOutputWindow");
+    positive(config.maxSubtasks, "maxSubtasks");
+    positive(config.model.maxOutputTokens, "model.maxOutputTokens");
+    // See SessionConfig.compactTailTokens — below this gap the fixed floor eats
+    // the headroom and compaction fires on nearly every append.
+    const headroom = config.session.compactAfterTokens - config.session.compactTailTokens;
+    if (headroom < 10_000) {
+        throw new ConfigError(`session.compactAfterTokens - session.compactTailTokens must be >= 10000, got ${headroom}. ` +
+            "Lower compactTailTokens along with compactAfterTokens.");
+    }
+    return config;
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

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

package/dist/contract/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The plugin contract — the only thing core and a plugin package both name.
+ *
+ * Re-exported from the package root as well, so a plugin author writes
+ * `import { definePlugin } from "@loopingai/core"` and nothing else.
+ */
+export { PLUGIN_CONTRACT_VERSION, definePlugin, type AgentPlugin, type EmitProgress, type EnrichResultContext, type PluginRequirements, type RecipeToolSet, type ResolveRuntimeContext, type ToolFamilyBuilder, type ToolFamilyContext } from "./plugin.js";
+export type { DelegationNames, RecipeLimits, ResolvedRecipe, SubtaskParams, SubtaskParamsSchema, SubtaskParamsShape, SubtaskTypeSpec, ValidatedRecipe } from "./recipe.js";
+export { RecipeValidationError, resolveLimits, validateRecipe, type RecipePolicy } from "./validation.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/contract/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,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,aAAa,CAAC;AAErB,YAAY,EACV,eAAe,EACf,YAAY,EACZ,cAAc,EACd,aAAa,EACb,mBAAmB,EACnB,kBAAkB,EAClB,eAAe,EACf,eAAe,EAChB,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,qBAAqB,EACrB,aAAa,EACb,cAAc,EACd,KAAK,YAAY,EAClB,MAAM,iBAAiB,CAAC"}

package/dist/contract/index.js

@@ -0,0 +1,9 @@
+/**
+ * The plugin contract — the only thing core and a plugin package both name.
+ *
+ * Re-exported from the package root as well, so a plugin author writes
+ * `import { definePlugin } from "@loopingai/core"` and nothing else.
+ */
+export { PLUGIN_CONTRACT_VERSION, definePlugin } from "./plugin.js";
+export { RecipeValidationError, resolveLimits, validateRecipe } from "./validation.js";
+//# sourceMappingURL=index.js.map

package/dist/contract/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/contract/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EACL,uBAAuB,EACvB,YAAY,EASb,MAAM,aAAa,CAAC;AAarB,OAAO,EACL,qBAAqB,EACrB,aAAa,EACb,cAAc,EAEf,MAAM,iBAAiB,CAAC"}

package/dist/contract/plugin.d.ts

@@ -0,0 +1,163 @@
+import type { ToolSet } from "ai";
+import type { PluginStore } from "../db/db.js";
+import type { WorkspaceHandle } from "../subagent/workspace.js";
+import type { ProgressEvent, RecipeExecutionRequest, RecipeExecutionResult, SubtaskRuntime } from "../subtasks/types.js";
+import type { SubtaskParams, SubtaskTypeSpec } from "./recipe.js";
+/**
+ * The plugin contract — everything an independently-packaged capability may
+ * contribute to an agent, and the only thing core knows about one.
+ *
+ * Nothing in core imports a plugin. A plugin imports core (type-only wherever it
+ * can) and is registered by the *host* at DO start. That direction is what makes
+ * bundle growth proportional to what an agent actually installs, and it is
+ * structural rather than a tree-shaker's opinion.
+ */
+/**
+ * The contract version a plugin was built against.
+ *
+ * Three separate repos means a contract change is a three-repo publish train, and
+ * the failure mode of a skew is a structural-type mismatch several frames from
+ * its cause. `createAgentRuntime` asserts this instead, so a mismatched plugin
+ * fails at DO start with a sentence naming the plugin and both versions.
+ *
+ * The contract is **additive-only** within a major: new capabilities arrive as
+ * optional fields on {@link AgentPlugin}. Removing or re-typing an existing field
+ * requires a major and a bump here.
+ */
+export declare const PLUGIN_CONTRACT_VERSION = 1;
+/**
+ * Emit a user-facing progress note from inside a tool (e.g. a level-up in a
+ * game, a milestone in a long scrape). The resumable runner collects these and
+ * ends the current chunk so the parent can post them promptly. Best-effort — the
+ * runner never lets a progress note affect generation.
+ */
+export type EmitProgress = (event: ProgressEvent) => void;
+/**
+ * Everything a tool family needs to build its tools, closed over so none of it
+ * is ever model input.
+ *
+ * Note what is **not** here: the Worker `env`. The predecessor passed it, which
+ * a published package cannot do — `Env` is the ambient interface `wrangler
+ * types` generates into a consumer's `worker-configuration.d.ts` and does not
+ * exist outside their app. A plugin takes its secrets and bindings as *config at
+ * instantiation* instead, which is also the only thing that works on Workers,
+ * where `env` does not exist at module scope.
+ */
+export interface ToolFamilyContext<TRuntime = SubtaskRuntime> {
+    /** The execution's durable file store. */
+    workspace: WorkspaceHandle;
+    emitProgress: EmitProgress;
+    /**
+     * The subtask's validated params — the ids its type declared it needs. Chosen
+     * by the delegating main agent and checked against its type's contract before
+     * this execution began, so a family may read them directly; they are not this
+     * model's input.
+     */
+    params: SubtaskParams;
+    /**
+     * Session state the parent resolved for this execution — what no model could
+     * supply and none should be asked to. Opaque to core; a plugin narrows it to
+     * whatever its own {@link AgentPlugin.resolveRuntime} wrote.
+     */
+    runtime: TRuntime;
+}
+/**
+ * A tool family's contribution: its tools, plus an optional `abort` hook the
+ * facet runs on cancellation to release external state the family acquired.
+ *
+ * Anything the hook needs must be reconstructible from the workspace, so it is
+ * safe to run on a fresh isolate after eviction.
+ */
+export interface RecipeToolSet<TRuntime = SubtaskRuntime> {
+    tools: ToolSet;
+    abort?: (ctx: ToolFamilyContext<TRuntime>) => Promise<void>;
+}
+/** Builds one tool family's contribution for a single execution. */
+export type ToolFamilyBuilder<TRuntime = SubtaskRuntime> = (ctx: ToolFamilyContext<TRuntime>) => RecipeToolSet<TRuntime>;
+/** What the parent knows when resolving an execution's runtime state. */
+export interface ResolveRuntimeContext {
+    taskId: string;
+    subtaskId: number;
+    type: string;
+    params: SubtaskParams;
+    toolFamilies: readonly string[];
+}
+/** What the parent knows when a plugin gets to enrich a terminal result. */
+export interface EnrichResultContext<TRuntime = SubtaskRuntime> {
+    request: RecipeExecutionRequest;
+    runtime: TRuntime;
+}
+/** Bindings and secrets a plugin needs the *host* to provide in `wrangler.jsonc`. */
+export interface PluginRequirements {
+    /** Secret names, e.g. `["ARC_API_KEY"]`. */
+    secrets?: readonly string[];
+    /** Binding names, e.g. `["BROWSER"]`. */
+    bindings?: readonly string[];
+}
+export interface AgentPlugin<TRuntime = SubtaskRuntime> {
+    /** Stable identifier, unique across installed plugins. */
+    key: string;
+    /**
+     * The {@link PLUGIN_CONTRACT_VERSION} this plugin was built against. Set it
+     * from the imported constant, never as a literal — the point is that it moves
+     * with the core the plugin compiled against.
+     */
+    contractVersion: number;
+    /**
+     * The subtask type this plugin makes delegable, and the recipe it runs under.
+     * A plugin that only contributes main-agent tools declares none.
+     */
+    subtaskType?: SubtaskTypeSpec;
+    /**
+     * Tool families this plugin registers, keyed by family name. A recipe selects
+     * families by name; a name no installed plugin registers is dropped by
+     * `validateRecipe`, so the legal set is exactly what is installed.
+     */
+    toolFamilies?: Record<string, ToolFamilyBuilder<TRuntime>>;
+    /** Tools offered to the *main* agent (e.g. a catalogue lookup before delegating). */
+    mainAgentTools?: () => ToolSet;
+    /**
+     * What the main agent is told it can do with this domain, rendered into its
+     * soul alongside the other capability blocks.
+     */
+    capability?: string;
+    /**
+     * Resolve the session state an execution needs and no model can supply — a
+     * leased external resource, a session handle, a cookie jar.
+     *
+     * Called by the parent before each chunk, and deliberately outside the
+     * execution's fingerprint: what it returns can legitimately change between two
+     * chunks of one run, and must not make a retry look like different work.
+     */
+    resolveRuntime?: (ctx: ResolveRuntimeContext) => Promise<TRuntime>;
+    /**
+     * Amend a terminal result before it is persisted — e.g. append a score the
+     * subagent had no way to read. Returning the result unchanged is always valid.
+     */
+    enrichResult?: (ctx: EnrichResultContext<TRuntime>, result: RecipeExecutionResult) => Promise<RecipeExecutionResult>;
+    /** Release anything {@link resolveRuntime} acquired, when an execution is canceled. */
+    onAbort?: (ctx: ResolveRuntimeContext) => Promise<void>;
+    /** Tables this plugin owns, outside core's migration journal. See {@link PluginStore}. */
+    store?: PluginStore;
+    /**
+     * Bindings and secrets the host must declare in `wrangler.jsonc`. A plugin
+     * cannot add its own binding, so declaring them lets startup fail with a
+     * readable message instead of at the first tool call, in a request a user is
+     * waiting on.
+     */
+    requires?: PluginRequirements;
+}
+/**
+ * Identity helper that pins {@link AgentPlugin.contractVersion} for you and gives
+ * a plugin author inference on `TRuntime`.
+ *
+ * ```ts
+ * export function arcAgi(config: { apiKey: string }) {
+ *   return definePlugin<ArcRuntime>({ key: "arc-agi", … });
+ * }
+ * ```
+ */
+export declare function definePlugin<TRuntime = SubtaskRuntime>(plugin: Omit<AgentPlugin<TRuntime>, "contractVersion"> & {
+    contractVersion?: number;
+}): AgentPlugin<TRuntime>;
+//# sourceMappingURL=plugin.d.ts.map

package/dist/contract/plugin.d.ts.map

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

package/dist/contract/plugin.js

@@ -0,0 +1,39 @@
+/**
+ * The plugin contract — everything an independently-packaged capability may
+ * contribute to an agent, and the only thing core knows about one.
+ *
+ * Nothing in core imports a plugin. A plugin imports core (type-only wherever it
+ * can) and is registered by the *host* at DO start. That direction is what makes
+ * bundle growth proportional to what an agent actually installs, and it is
+ * structural rather than a tree-shaker's opinion.
+ */
+/**
+ * The contract version a plugin was built against.
+ *
+ * Three separate repos means a contract change is a three-repo publish train, and
+ * the failure mode of a skew is a structural-type mismatch several frames from
+ * its cause. `createAgentRuntime` asserts this instead, so a mismatched plugin
+ * fails at DO start with a sentence naming the plugin and both versions.
+ *
+ * The contract is **additive-only** within a major: new capabilities arrive as
+ * optional fields on {@link AgentPlugin}. Removing or re-typing an existing field
+ * requires a major and a bump here.
+ */
+export const PLUGIN_CONTRACT_VERSION = 1;
+/**
+ * Identity helper that pins {@link AgentPlugin.contractVersion} for you and gives
+ * a plugin author inference on `TRuntime`.
+ *
+ * ```ts
+ * export function arcAgi(config: { apiKey: string }) {
+ *   return definePlugin<ArcRuntime>({ key: "arc-agi", … });
+ * }
+ * ```
+ */
+export function definePlugin(plugin) {
+    return {
+        ...plugin,
+        contractVersion: plugin.contractVersion ?? PLUGIN_CONTRACT_VERSION
+    };
+}
+//# sourceMappingURL=plugin.js.map

package/dist/contract/plugin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.js","sourceRoot":"","sources":["../../src/contract/plugin.ts"],"names":[],"mappings":"AAWA;;;;;;;;GAQG;AAEH;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,CAAC;AAqJzC;;;;;;;;;GASG;AACH,MAAM,UAAU,YAAY,CAC1B,MAEC;IAED,OAAO;QACL,GAAG,MAAM;QACT,eAAe,EAAE,MAAM,CAAC,eAAe,IAAI,uBAAuB;KACnE,CAAC;AACJ,CAAC"}

package/dist/contract/recipe.d.ts

@@ -0,0 +1,170 @@
+import type { z } from "zod";
+import type { AgentLimits } from "../config.js";
+/**
+ * What a recipe domain declares.
+ *
+ * These types flow **outward**: the runtime consumes them, and nothing in this
+ * file imports from the runtime. That direction is the whole reason a plugin can
+ * live in a separate package — a new domain is a new module plus one line in the
+ * consuming agent's plugin list, with no edit inside core.
+ *
+ * Two shapes, and the distinction between them carries real weight:
+ *
+ * - A **type** ({@link SubtaskTypeSpec}) is the semantic contract of a unit of
+ *   work: what it means, and what it must be given to be doable at all.
+ * - A **Recipe** ({@link ResolvedRecipe}) is the execution *configuration* —
+ *   models, soul, tool families, budgets. It declares no params, and one Recipe
+ *   may serve several types.
+ */
+/** Params carried by a Subtask: model-chosen, string-valued, shape-checked. */
+export type SubtaskParams = Record<string, string>;
+/**
+ * A type's param declaration, as a shape the agent can read back — not an opaque
+ * validator. The keys have to be *enumerable* because the delegate tool's schema
+ * is built from them: a param the model cannot see declared is a param it will
+ * not send. See {@link SubtaskTypeSpec.params}.
+ */
+export type SubtaskParamsShape = Record<string, z.ZodType<string>>;
+export type SubtaskParamsSchema = z.ZodObject<SubtaskParamsShape>;
+/**
+ * The control-tool names the agent injects when it renders a type's
+ * {@link SubtaskTypeSpec.delegationGuidance}.
+ *
+ * Guidance legitimately names those tools ("ask the user with `final_reply`
+ * rather than guessing"), and their names are the agent's to own. Injecting them
+ * is what lets a domain write that sentence without importing from the runtime —
+ * the direction this module depends on.
+ */
+export interface DelegationNames {
+    delegateTool: string;
+    finalReplyTool: string;
+}
+/**
+ * The execution budget for one Recipe, enforced by the resumable runner (not the
+ * Workflow). Exactly two fields, because there are exactly two things worth
+ * bounding: what an execution **costs** and how long it can **run away for**. The
+ * run ends on whichever it reaches first, and either way through the graceful
+ * budget summary.
+ *
+ * Deliberately *not* here: how a run is sliced into durable chunks. That is a
+ * Workers step-timeout constraint, it is identical for every Recipe, and it lives
+ * in {@link file://../platform.ts}. It used to include a `turnsPerChunk`, on the
+ * theory that a turn count could keep a step under the timeout — it cannot,
+ * because nothing predicts how long a turn takes, and the resulting arithmetic was
+ * wrong by 2-3× in practice.
+ */
+/**
+ * Structurally identical to {@link AgentLimits} — a budget is a budget at both
+ * levels, and keeping one shape means `resolveLimits` merges a recipe's
+ * declaration straight over the host's baseline with no translation. Aliased
+ * rather than redeclared so the two can never drift apart.
+ */
+export type RecipeLimits = AgentLimits;
+/**
+ * A Recipe configuration as a domain **declares** it, one per folder in
+ * `recipes/<domain>/recipe.ts`; caller-local DB rows mapping into this shape are
+ * deferred until a Recipe admin surface exists. Model ids, tool families, and
+ * limits are code-validated downstream
+ * ({@link file://./validation.ts validateRecipe}), which is also what turns this
+ * into a {@link ValidatedRecipe}.
+ *
+ * One rule governs every field here, and it is worth stating once: **if
+ * `config.ts` declares a baseline, a Recipe overrides it; if it does not, the
+ * Recipe must supply it.** So `limits` is partial and merges, while `soul` and
+ * `historyWindow` are required and a missing one is refused rather than filled in.
+ */
+export interface ResolvedRecipe {
+    key: string;
+    version: number;
+    primaryModelId: string;
+    fallbackModelId: string;
+    /** Required, never defaulted — see `validateRecipe`. */
+    soul: string;
+    toolFamilies: string[];
+    enabled: boolean;
+    /**
+     * Only the budget fields this Recipe overrides; the rest come from
+     * `SUBAGENT_LIMITS`. `{}` means "the baseline", which is what most Recipes want.
+     */
+    limits: Partial<RecipeLimits>;
+    /**
+     * Most-recent turns kept verbatim in the rolling model context; older turns are
+     * pruned. Required, and required *of the Recipe*: how much context a domain
+     * needs is a property of the domain, so there is no house default to fall back
+     * to and a missing one is a refused Recipe.
+     */
+    historyWindow: number;
+    /** Append a runtime metrics footer (turns, model calls, wall-clock) to the final result. */
+    reportMetrics: boolean;
+}
+/**
+ * A Recipe that has been through {@link file://./validation.ts validateRecipe} —
+ * limits merged over the baseline, models and tool families checked. The only
+ * shape the runner ever consumes: a `Partial<RecipeLimits>` can never reach it.
+ */
+export interface ValidatedRecipe extends ResolvedRecipe {
+    limits: RecipeLimits;
+}
+/**
+ * One entry in the closed set of Subtask types the main agent may delegate,
+ * declared by the domain that owns it and collected in
+ * {@link file://./index.ts}.
+ *
+ * Two things follow from the set being closed rather than free prose:
+ *
+ * - The delegating model picks from an enum, so an invented type is rejected by
+ *   the tool schema itself instead of silently falling back to a general recipe.
+ * - A type can *require params*. `arc-game` cannot be attempted without a
+ *   scorecard and a game, so a subtask that names neither is refused up front
+ *   rather than discovering it has nothing to play several turns later.
+ *
+ * Params are the model's declared inputs — ids it chose, validated for shape and
+ * resolved against durable rows at execution start. They are never the place for
+ * anything the model cannot know: an API session pinned to one of those ids is
+ * resolved by the parent from the id, never carried in the params.
+ */
+export interface SubtaskTypeSpec {
+    key: string;
+    /** One line shown to the delegating model so it picks the right type. */
+    description: string;
+    /**
+     * Required params for this type, or null when it takes none. Kept to flat
+     * strings: these are ids the model quotes from a tool result, not structures.
+     *
+     * A `z.object`, not an opaque `z.ZodType`, and that is load-bearing: the agent
+     * reads `.shape` back to build the `params` field of the delegate tool's schema
+     * (see `subtaskParamProperties`). Declaring a param the model is never shown is
+     * the failure this shape exists to prevent — describe each key with
+     * `.describe()`, because that text is what the model reads.
+     */
+    params: SubtaskParamsSchema | null;
+    /** How the model is told to obtain each param, appended to the description. */
+    paramsHelp?: string;
+    /**
+     * What the main agent is told it can *do* with this domain, rendered into its
+     * soul alongside the other capability blocks. Omit when the type needs no
+     * introduction beyond {@link description}.
+     *
+     * These two prompt fields exist to hold one rule: **everything the main agent
+     * is told about a domain is declared here, never written inside the runtime.**
+     * Both of them started as hand-written blocks in `agent/prompt.ts` and
+     * `agent/turn.ts`; the main agent read the same advice twice per round from two
+     * files that had already drifted into contradicting each other on how many
+     * subtasks a multi-game request gets.
+     */
+    capability?: string;
+    /**
+     * How to construct a `delegate` payload for this type, rendered into the round
+     * contract the main agent reads every round.
+     *
+     * A function because the text names the control tools, whose names belong to
+     * the agent (see {@link DelegationNames}). Three rules, none of them enforced
+     * beyond a test: it must open with its own `## ` heading, it must not restate
+     * the params schema — the `delegate` tool description already renders that from
+     * {@link params} — and it must stay short, because every round pays for it.
+     */
+    delegationGuidance?: (names: DelegationNames) => string;
+    /** The execution configuration this type runs under. */
+    recipe: ResolvedRecipe;
+}
+//# sourceMappingURL=recipe.d.ts.map

package/dist/contract/recipe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recipe.d.ts","sourceRoot":"","sources":["../../src/contract/recipe.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAC7B,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAEhD;;;;;;;;;;;;;;;GAeG;AAEH,+EAA+E;AAC/E,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAEnD;;;;;GAKG;AACH,MAAM,MAAM,kBAAkB,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC;AACnE,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,SAAS,CAAC,kBAAkB,CAAC,CAAC;AAElE;;;;;;;;GAQG;AACH,MAAM,WAAW,eAAe;IAC9B,YAAY,EAAE,MAAM,CAAC;IACrB,cAAc,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;;;;;;;GAaG;AACH;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GAAG,WAAW,CAAC;AAEvC;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,cAAc,EAAE,MAAM,CAAC;IACvB,eAAe,EAAE,MAAM,CAAC;IACxB,wDAAwD;IACxD,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,OAAO,EAAE,OAAO,CAAC;IACjB;;;OAGG;IACH,MAAM,EAAE,OAAO,CAAC,YAAY,CAAC,CAAC;IAC9B;;;;;OAKG;IACH,aAAa,EAAE,MAAM,CAAC;IACtB,4FAA4F;IAC5F,aAAa,EAAE,OAAO,CAAC;CACxB;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAgB,SAAQ,cAAc;IACrD,MAAM,EAAE,YAAY,CAAC;CACtB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,eAAe;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,yEAAyE;IACzE,WAAW,EAAE,MAAM,CAAC;IACpB;;;;;;;;;OASG;IACH,MAAM,EAAE,mBAAmB,GAAG,IAAI,CAAC;IACnC,+EAA+E;IAC/E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;;;;;;;;OAWG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;;;;;;OASG;IACH,kBAAkB,CAAC,EAAE,CAAC,KAAK,EAAE,eAAe,KAAK,MAAM,CAAC;IACxD,wDAAwD;IACxD,MAAM,EAAE,cAAc,CAAC;CACxB"}

package/dist/contract/recipe.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=recipe.js.map

package/dist/contract/recipe.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"recipe.js","sourceRoot":"","sources":["../../src/contract/recipe.ts"],"names":[],"mappings":""}

package/dist/contract/validation.d.ts

@@ -0,0 +1,86 @@
+import type { AgentLimits } from "../config.js";
+import type { ResolvedRecipe, ValidatedRecipe } from "./recipe.js";
+/**
+ * The capability boundary every recipe passes through, whatever declared it.
+ *
+ * This module imports no domain. It owns only what code must be able to say
+ * about *any* recipe: which models and tool families it may select, and how a
+ * malformed one is made safe or refused. A domain cannot widen its
+ * *capabilities* by declaring them, because the allowlists do not come from the
+ * declaration — they come from {@link RecipePolicy}, which the host builds from
+ * its resolved config and its installed plugins. Its budget is the deliberate
+ * exception; see {@link resolveLimits}.
+ *
+ * In the predecessor repo the two allowlists were module constants, and one of
+ * them hardcoded a domain key (`"arc-game"`) inside otherwise generic code. That
+ * is the coupling this indirection removes: the set of legal families is now
+ * exactly the set of families the installed plugins registered.
+ */
+export interface RecipePolicy {
+    /**
+     * Model ids a recipe may select — normally the two configured chat models, the
+     * only ones proven with this tool-loop pipeline. Extend deliberately, one
+     * validated model at a time.
+     */
+    modelAllowlist: ReadonlySet<string>;
+    /** Substituted when a recipe names a primary model outside the allowlist. */
+    defaultPrimaryModelId: string;
+    /** Substituted when a recipe names a fallback model outside the allowlist. */
+    defaultFallbackModelId: string;
+    /**
+     * Tool-family keys the runtime recognizes — derived from the installed
+     * plugins, never hardcoded.
+     *
+     * `recall` and the Session's `set_context` are never valid families: a
+     * subagent has no Session or durable memory to reach, and their absence from
+     * any plugin's `toolFamilies` makes them structurally impossible to enable
+     * through recipe data.
+     */
+    knownToolFamilies: ReadonlySet<string>;
+    /** The baseline a recipe's declared `limits` merge over. */
+    baselineLimits: AgentLimits;
+}
+/**
+ * Merge a recipe's declared budget over the baseline, per field. A positive
+ * integer wins; anything else — missing, null, zero, fractional — falls back to
+ * the baseline rather than reaching the runner.
+ *
+ * The baseline is a default, not a ceiling: a recipe may declare a budget larger
+ * than the baseline and it is honored — sizing its own branch is what declaring
+ * `limits` is for, so nothing here clamps. What the merge buys, as
+ * defense-in-depth for a recipe that ever comes from data rather than code, is
+ * that a corrupt or absent value cannot reach the runner as a zero, fractional,
+ * or missing budget.
+ *
+ * Exported separately from {@link validateRecipe} because it must never throw.
+ */
+export declare function resolveLimits(limits: Partial<AgentLimits>, baseline: AgentLimits): AgentLimits;
+/**
+ * Thrown by {@link validateRecipe} for a recipe that is unusable as given — it
+ * is disabled, carries no soul, or states no history window. All are
+ * deterministic caller bugs (the parent must only hand enabled, complete recipes
+ * to a subagent), so the child maps this to a terminal failed result rather than
+ * retrying.
+ */
+export declare class RecipeValidationError extends Error {
+    constructor(message: string);
+}
+/**
+ * Code-owned defensive validation of an already-resolved recipe. Returns a
+ * normalized copy (never mutates the input): a model id outside the policy's
+ * allowlist is substituted with the default for its slot — independently per
+ * slot — and unknown tool families are dropped (deduped, order-preserving).
+ * Applied by the parent when it resolves a recipe and re-applied by the subagent
+ * on its inbound request, so recipe data can never select arbitrary models or
+ * tools.
+ *
+ * The split between what is normalized and what is refused follows one rule:
+ * **the host declares a baseline ⇒ merge; it does not ⇒ require.** `limits`
+ * merge. A soul and a `historyWindow` do not: substituting a generic soul would
+ * run the work under an identity nobody declared — the model would answer,
+ * plausibly, as something other than what the recipe is for — and how much
+ * context a domain needs is likewise a property of the domain, not something a
+ * house default can guess. Both fail the recipe outright.
+ */
+export declare function validateRecipe(recipe: ResolvedRecipe, policy: RecipePolicy): ValidatedRecipe;
+//# sourceMappingURL=validation.d.ts.map

package/dist/contract/validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../../src/contract/validation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAChD,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAEnE;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,YAAY;IAC3B;;;;OAIG;IACH,cAAc,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IACpC,6EAA6E;IAC7E,qBAAqB,EAAE,MAAM,CAAC;IAC9B,8EAA8E;IAC9E,sBAAsB,EAAE,MAAM,CAAC;IAC/B;;;;;;;;OAQG;IACH,iBAAiB,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IACvC,4DAA4D;IAC5D,cAAc,EAAE,WAAW,CAAC;CAC7B;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,OAAO,CAAC,WAAW,CAAC,EAC5B,QAAQ,EAAE,WAAW,GACpB,WAAW,CAOb;AAED;;;;;;GAMG;AACH,qBAAa,qBAAsB,SAAQ,KAAK;gBAClC,OAAO,EAAE,MAAM;CAI5B;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,cAAc,EACtB,MAAM,EAAE,YAAY,GACnB,eAAe,CA+BjB"}