@dynamicagents/core 0.9.0

package/dist/contract/recipe.d.ts

@@ -0,0 +1,180 @@
+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}. A turn count cannot do that job — nothing
+ * predicts how long a turn takes — so no per-chunk turn budget belongs on a
+ * Recipe.
+ *
+ * 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;
+    /** Required, never defaulted — see `validateRecipe`. */
+    soul: string;
+    toolFamilies: string[];
+    enabled: boolean;
+    /**
+     * Only the budget fields this Recipe overrides; the rest come from the host's
+     * `CoreConfig.subagentLimits`, which reaches validation as
+     * `RecipePolicy.baselineLimits`. `{}` 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;
+    /**
+     * The pair this recipe will actually run on — **the host's, always**.
+     *
+     * These exist only here, never on {@link ResolvedRecipe}, and that asymmetry
+     * is the design: a recipe cannot state a model, so the only way to hold one is
+     * to have been through `validateRecipe`, which copies the host's. Recipe data
+     * has no path to influence them.
+     *
+     * Guaranteed non-empty and guaranteed distinct, because `resolveConfig`
+     * refuses a config that is either — so the fallback is always a genuinely
+     * different model from the primary, which is the entire point of having one.
+     */
+    primaryModelId: string;
+    fallbackModelId: string;
+}
+/**
+ * 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 `SubtaskTypeRegistry.paramProperties`). 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.**
+     * Advice written in the runtime instead has to be repeated per call site, and
+     * the copies drift — into telling the main agent two contradictory things
+     * about the same domain, twice per round.
+     */
+    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;
+}

package/dist/contract/recipe.js

@@ -0,0 +1 @@
+export {};

package/dist/contract/validation.d.ts

@@ -0,0 +1,91 @@
+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 tool families it may select, which models it runs
+ * on, and how a malformed one is made safe or refused. A domain cannot widen
+ * its *capabilities* by declaring them — the legal tool families come from
+ * {@link RecipePolicy}, which the host builds from its installed plugins, and
+ * the model pair comes from the host's config with no declaration involved at
+ * all. 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 {
+    /**
+     * The pair every recipe runs on: the host agent's own, copied verbatim onto
+     * each {@link ValidatedRecipe}.
+     *
+     * There is no allowlist any more, because there is nothing to check against
+     * it — a recipe cannot state a model. `modelAllowlist` existed to police
+     * recipe-stated preferences, and it could only ever contain these same two
+     * ids, so the "preference" it policed could never reach a third model. It
+     * could only swap the primary for the fallback, which is not a capability
+     * anyone wants and which broke the pair's distinctness.
+     */
+    primaryModelId: string;
+    /** See {@link primaryModelId}. Guaranteed distinct from it by `resolveConfig`. */
+    fallbackModelId: string;
+    /**
+     * Tool-family keys the runtime recognizes — derived from the installed
+     * plugins, never hardcoded.
+     *
+     * A main-agent-only tool is never a valid family — the Session's
+     * `set_context`, or anything a plugin offers only through `mainAgentTools`
+     * (an episodic-memory search, say). A subagent has no Session or durable
+     * memory to reach, and such a tool's absence from every plugin's
+     * `toolFamilies` makes it 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): the host's model pair is stamped
+ * on, 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 — models because there is no field to select one with, tools because
+ * the legal set comes from the installed plugins rather than the declaration.
+ *
+ * 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;

package/dist/contract/validation.js

@@ -0,0 +1,84 @@
+/**
+ * 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 function resolveLimits(limits, baseline) {
+    const positiveInt = (n, fallback) => typeof n === "number" && Number.isInteger(n) && n > 0 ? n : fallback;
+    return {
+        maxTurns: positiveInt(limits?.maxTurns, baseline.maxTurns),
+        maxWallMs: positiveInt(limits?.maxWallMs, baseline.maxWallMs)
+    };
+}
+/**
+ * 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 class RecipeValidationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "RecipeValidationError";
+    }
+}
+/**
+ * Code-owned defensive validation of an already-resolved recipe. Returns a
+ * normalized copy (never mutates the input): the host's model pair is stamped
+ * on, 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 — models because there is no field to select one with, tools because
+ * the legal set comes from the installed plugins rather than the declaration.
+ *
+ * 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 function validateRecipe(recipe, policy) {
+    if (!recipe.enabled) {
+        throw new RecipeValidationError(`recipe "${recipe.key}" (v${recipe.version}) is disabled`);
+    }
+    if (recipe.soul.trim() === "") {
+        throw new RecipeValidationError(`recipe "${recipe.key}" (v${recipe.version}) has no soul`);
+    }
+    if (!Number.isInteger(recipe.historyWindow) || recipe.historyWindow <= 0) {
+        throw new RecipeValidationError(`recipe "${recipe.key}" (v${recipe.version}) has no usable historyWindow ` +
+            `(got ${recipe.historyWindow}); every recipe states its own`);
+    }
+    const toolFamilies = [...new Set(recipe.toolFamilies)].filter((family) => policy.knownToolFamilies.has(family));
+    return {
+        ...recipe,
+        // The host's pair, copied. Not selected, not substituted, not merged —
+        // there is nothing on a `ResolvedRecipe` to select *from*.
+        //
+        // This used to substitute a recipe's stated preference against
+        // an allowlist, per slot and independently. That produced a real defect:
+        // a recipe preferring the host's *fallback* as its primary, and stating no
+        // fallback of its own, resolved to the same id in both slots — so the
+        // fallback retried the model that had just failed, defeating the distinct-
+        // pair invariant `resolveConfig` enforces one layer up.
+        //
+        // Copying wholesale makes that unrepresentable: the pair here is exactly the
+        // pair the agent configured, which `resolveConfig` has already guaranteed is
+        // non-empty and distinct.
+        primaryModelId: policy.primaryModelId,
+        fallbackModelId: policy.fallbackModelId,
+        toolFamilies,
+        limits: resolveLimits(recipe.limits, policy.baselineLimits)
+    };
+}

package/dist/db/db.d.ts

@@ -0,0 +1,147 @@
+import { type DrizzleSqliteDODatabase } from "drizzle-orm/durable-sqlite";
+import * as schema from "./schema.js";
+export type DB = DrizzleSqliteDODatabase<typeof schema>;
+/**
+ * A table owner outside core's migration journal.
+ *
+ * What a plugin cannot share is the **migrator**. `drizzle-orm/durable-sqlite/
+ * migrator` keeps one flat integer journal and one global
+ * `__drizzle_migrations` table, and two independently-versioned npm packages
+ * cannot share that index space — not hypothetically: the two predecessor
+ * agents, both consuming the same `notify_tasks` module, had already forked the
+ * journal at index 1 (`0001_unusual_nova` vs `0001_great_goliath`). Worse,
+ * `drizzle-kit generate` diffs against a snapshot in one output directory, so a
+ * plugin shipping from its own repo cannot produce a correct diff at all.
+ *
+ * **The query builder is a different thing entirely, and a plugin should use
+ * it.** `drizzle(storage, { schema })` is a typed wrapper over the same
+ * `DurableObjectStorage`; it holds no journal, no connection, and no state that
+ * a second handle could disturb. So the rule is narrow — *never import the
+ * migrator* — rather than "no drizzle".
+ *
+ * A plugin therefore does three things: declares its tables with `sqliteTable`
+ * as usual, emits idempotent DDL here, and queries through its own drizzle
+ * handle. Version bookkeeping lives in the {@link PLUGIN_MIGRATIONS_TABLE} row
+ * this class manages for it. Only the DDL is hand-written, and that pattern is
+ * not novel here — it is what the subagent facet already does for its own two
+ * tables.
+ *
+ * ```ts
+ * // schema.ts — an ordinary drizzle table, under the plugin's own prefix.
+ * export const arcScorecards = sqliteTable("arc_scorecards", {
+ *   cardId: text("card_id").primaryKey(),
+ *   lastUsedAt: integer("last_used_at").notNull()
+ * });
+ *
+ * // The DDL half: idempotent, re-run on every hibernation wake-up.
+ * const store: PluginStore = {
+ *   plugin: "arc-agi",
+ *   version: 2,
+ *   ensureTables(sql, from) {
+ *     sql.exec(`CREATE TABLE IF NOT EXISTS arc_scorecards (…)`);
+ *     if (from < 2) sql.exec(`ALTER TABLE arc_scorecards ADD COLUMN …`);
+ *   }
+ * };
+ *
+ * // The query half: drizzle, over the plugin's own handle.
+ * const db = drizzle(storage, { schema: { arcScorecards } });
+ * db.select().from(arcScorecards).where(gte(arcScorecards.lastUsedAt, since));
+ * ```
+ */
+export interface PluginStore {
+    /** Stable identifier. Also the bookkeeping row's key — never rename it. */
+    plugin: string;
+    /**
+     * Monotonically increasing schema version, starting at 1. Bump it whenever
+     * {@link ensureTables} needs to do something it did not do before.
+     */
+    version: number;
+    /**
+     * Bring this plugin's tables up to {@link version}.
+     *
+     * Called once per DO instance, and re-called on every hibernation wake-up, so
+     * it **must be idempotent**. `from` is the version last recorded for this
+     * plugin (0 on first ever run), which is what lets an upgrade path branch
+     * without re-running earlier DDL.
+     */
+    ensureTables(sql: SqlStorage, from: number): void;
+}
+/** Bookkeeping for {@link PluginStore} versions. Core owns the table; plugins own their rows. */
+export declare const PLUGIN_MIGRATIONS_TABLE = "plugin_migrations";
+export interface AgentDBOptions {
+    /**
+     * Plugin-owned stores to bring up alongside core's own tables. Order is
+     * preserved but must not matter: a plugin that depends on another plugin's
+     * table is a plugin that should have been one plugin.
+     */
+    stores?: readonly PluginStore[];
+    /**
+     * `CoreConfig.maxSubtasks` — the durable guard `createDecomposition` enforces.
+     * Passed rather than imported so one resolved config governs both the schema
+     * offered to the model and the write that has to hold.
+     */
+    maxSubtasks: number;
+}
+/**
+ * The agent's database: one drizzle handle over the DO's SQLite, with a memoized
+ * namespace per table domain (`db.tasks`, `db.subtasks`).
+ *
+ * Constructed once per DO instance. Core's migrations run in the constructor —
+ * the durable-sqlite migrator is idempotent, so a fresh `AgentDB` on every
+ * hibernation wake-up re-validates the schema safely. Call `ensureReady()` (and
+ * await it) before issuing any queries.
+ *
+ * Plugin stores are brought up in the same place but through a different
+ * mechanism, deliberately — see {@link PluginStore}.
+ */
+export declare class AgentDB {
+    private readonly storage;
+    private readonly options;
+    private readonly db;
+    private readonly _ready;
+    private _tasks?;
+    private _subtasks?;
+    constructor(storage: DurableObjectStorage, options: AgentDBOptions);
+    ensureReady(): Promise<void>;
+    get tasks(): {
+        begin(input: {
+            messageId: string;
+            taskId: string;
+            contextId: string;
+        }): import("../a2a/task.js").PlainTask;
+        get(taskId: string): import("../a2a/task.js").PlainTask | null;
+        list(query: import("./index.js").TaskListQuery): {
+            tasks: import("../a2a/task.js").PlainTask[];
+            totalSize: number;
+        };
+        save(task: import("@a2a-js/sdk").Task): boolean;
+        markWorking(taskId: string): "ok" | "canceled";
+        cancel(taskId: string): import("../a2a/task.js").PlainTask | null;
+        cleanup(): void;
+    };
+    get subtasks(): {
+        createDecomposition(taskId: string, round: number, drafts: import("../subtasks/types.js").SubtaskDraft[]): import("../subtasks/types.js").Subtask[];
+        get(id: import("../subtasks/types.js").SubtaskId): import("../subtasks/types.js").Subtask | null;
+        list(taskId: string): import("../subtasks/types.js").Subtask[];
+        listRound(taskId: string, round: number): import("../subtasks/types.js").Subtask[];
+        start(id: import("../subtasks/types.js").SubtaskId, recipe: {
+            recipeId: string;
+            recipeVersion: number;
+        }): boolean;
+        complete(id: import("../subtasks/types.js").SubtaskId, resultParts: import("../subtasks/types.js").SubtaskResultPart[]): boolean;
+        fail(id: import("../subtasks/types.js").SubtaskId, error: string): boolean;
+        cancelRunning(id: import("../subtasks/types.js").SubtaskId): boolean;
+        cancelPending(taskId: string): number;
+        cleanup(): void;
+    };
+    /**
+     * Run each plugin store's DDL and record its version, after core's own
+     * migrations so a plugin may safely reference core tables (nothing should, but
+     * the ordering is free and the alternative is a surprising failure).
+     *
+     * A store that throws fails DO start rather than being skipped: a plugin whose
+     * tables are missing would otherwise fail later, at its first tool call, in a
+     * request the user is waiting on.
+     */
+    private applyStores;
+}

package/dist/db/db.js

@@ -0,0 +1,90 @@
+import { drizzle } from "drizzle-orm/durable-sqlite";
+import { migrate } from "drizzle-orm/durable-sqlite/migrator";
+import * as schema from "./schema.js";
+import dbMigrations from "./migrations/index.js";
+import { makeTasks } from "./models/tasks.js";
+import { makeSubtasks } from "./models/subtasks.js";
+/** Bookkeeping for {@link PluginStore} versions. Core owns the table; plugins own their rows. */
+export const PLUGIN_MIGRATIONS_TABLE = "plugin_migrations";
+/**
+ * The agent's database: one drizzle handle over the DO's SQLite, with a memoized
+ * namespace per table domain (`db.tasks`, `db.subtasks`).
+ *
+ * Constructed once per DO instance. Core's migrations run in the constructor —
+ * the durable-sqlite migrator is idempotent, so a fresh `AgentDB` on every
+ * hibernation wake-up re-validates the schema safely. Call `ensureReady()` (and
+ * await it) before issuing any queries.
+ *
+ * Plugin stores are brought up in the same place but through a different
+ * mechanism, deliberately — see {@link PluginStore}.
+ */
+export class AgentDB {
+    storage;
+    options;
+    db;
+    _ready;
+    _tasks;
+    _subtasks;
+    constructor(storage, options) {
+        this.storage = storage;
+        this.options = options;
+        this.db = drizzle(storage, { schema });
+        this._ready = migrate(this.db, dbMigrations).then(() => {
+            this.applyStores(options.stores ?? []);
+        });
+    }
+    ensureReady() {
+        return this._ready;
+    }
+    get tasks() {
+        return (this._tasks ??= makeTasks(this.db));
+    }
+    get subtasks() {
+        return (this._subtasks ??= makeSubtasks(this.db, {
+            maxSubtasks: this.options.maxSubtasks
+        }));
+    }
+    /**
+     * Run each plugin store's DDL and record its version, after core's own
+     * migrations so a plugin may safely reference core tables (nothing should, but
+     * the ordering is free and the alternative is a surprising failure).
+     *
+     * A store that throws fails DO start rather than being skipped: a plugin whose
+     * tables are missing would otherwise fail later, at its first tool call, in a
+     * request the user is waiting on.
+     */
+    applyStores(stores) {
+        if (stores.length === 0)
+            return;
+        const sql = this.storage.sql;
+        sql.exec(`CREATE TABLE IF NOT EXISTS ${PLUGIN_MIGRATIONS_TABLE} (
+         plugin TEXT PRIMARY KEY,
+         version INTEGER NOT NULL,
+         updated_at INTEGER NOT NULL
+       )`);
+        const seen = new Set();
+        for (const store of stores) {
+            if (seen.has(store.plugin)) {
+                throw new Error(`duplicate PluginStore '${store.plugin}' — two plugins claim the same storage namespace`);
+            }
+            seen.add(store.plugin);
+            if (!Number.isInteger(store.version) || store.version < 1) {
+                throw new Error(`PluginStore '${store.plugin}' version must be an integer >= 1, got ${store.version}`);
+            }
+            const row = sql
+                .exec(`SELECT version FROM ${PLUGIN_MIGRATIONS_TABLE} WHERE plugin = ?`, store.plugin)
+                .toArray()[0];
+            const from = row?.version ?? 0;
+            if (from > store.version) {
+                throw new Error(`PluginStore '${store.plugin}' is at version ${from} on disk but the ` +
+                    `installed plugin declares ${store.version} — downgrade is not supported`);
+            }
+            store.ensureTables(sql, from);
+            if (from !== store.version) {
+                sql.exec(`INSERT INTO ${PLUGIN_MIGRATIONS_TABLE} (plugin, version, updated_at)
+             VALUES (?, ?, ?)
+             ON CONFLICT(plugin) DO UPDATE SET version = excluded.version, updated_at = excluded.updated_at`, store.plugin, store.version, Date.now());
+            }
+        }
+    }
+}

package/dist/db/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * `@dynamicagents/core/db` — the two tables core owns, and the seam a plugin uses to
+ * own its own without touching core's migration journal.
+ */
+export { AgentDB, PLUGIN_MIGRATIONS_TABLE, type AgentDBOptions, type DB, type PluginStore } from "./db.js";
+export { notifyTasks, subtasks } from "./schema.js";
+export { makeTasks, stateOf, type TaskListQuery } from "./models/tasks.js";
+export { makeSubtasks, type SubtaskModelOptions } from "./models/subtasks.js";

package/dist/db/index.js

@@ -0,0 +1,8 @@
+/**
+ * `@dynamicagents/core/db` — the two tables core owns, and the seam a plugin uses to
+ * own its own without touching core's migration journal.
+ */
+export { AgentDB, PLUGIN_MIGRATIONS_TABLE } from "./db.js";
+export { notifyTasks, subtasks } from "./schema.js";
+export { makeTasks, stateOf } from "./models/tasks.js";
+export { makeSubtasks } from "./models/subtasks.js";

package/dist/db/migrations/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Drizzle migrations, inlined for Cloudflare Workers.
+ *
+ * GENERATED FILE — do not edit. Run `npm run db:generate` after changing
+ * `src/db/schema.ts`; that runs `drizzle-kit generate` and then
+ * `scripts/build-migrations.mjs`, which rebuilds this from
+ * `meta/_journal.json` and the `.sql` files beside it.
+ *
+ * Key format: "m{zero-padded idx}" — what drizzle's durable-sqlite migrator
+ * reads from `config.migrations[key]`.
+ *
+ * This journal is CORE's alone. A plugin must never add an entry: the journal is
+ * a flat integer sequence over one shared `__drizzle_migrations` table, and two
+ * independently-versioned packages writing to it will collide. Plugins own their
+ * tables through `PluginStore` instead — see `src/db/db.ts`.
+ */
+import type { migrate } from "drizzle-orm/durable-sqlite/migrator";
+type MigrationConfig = Parameters<typeof migrate>[1];
+declare const dbMigrations: MigrationConfig;
+export default dbMigrations;