@dynamicagents/core 0.9.0

package/dist/db/schema.d.ts

@@ -0,0 +1,468 @@
+/**
+ * Core's two tables. Both live in the caller's agent DO SQLite
+ * (`this.ctx.storage`), so a row is unreachable from any other caller by
+ * construction.
+ *
+ * A plugin's tables are **not** here and never will be: drizzle's durable-sqlite
+ * migrator keeps one flat integer journal and one global `__drizzle_migrations`
+ * table, which independently-versioned packages cannot share. Plugins own their
+ * storage through `PluginStore` — idempotent `CREATE TABLE IF NOT EXISTS` plus
+ * their own version bookkeeping, outside this journal entirely. See
+ * {@link file://./db.ts}.
+ *
+ * Indexes are declared in each table's config callback rather than as standalone
+ * `index(...)` exports: only the callback form is recorded in the drizzle-kit
+ * snapshot, so the standalone form makes every later `generate` diff propose
+ * dropping the index it can no longer see.
+ */
+/**
+ * Durable state for async A2A tasks (the accept + notify lifecycle).
+ *
+ * One row per task: written by the Worker's accept path (`beginTask`, keyed by
+ * `message_id` for gatekeeper dedupe) and mutated by the turn workflow via DO RPC
+ * (`markWorking`, `saveTask`, `cancelTask`). `GetTask` / `ListTasks` read it
+ * through `DurableTaskStore`.
+ */
+export declare const notifyTasks: import("drizzle-orm/sqlite-core").SQLiteTableWithColumns<{
+    name: "notify_tasks";
+    schema: undefined;
+    columns: {
+        taskId: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "task_id";
+            tableName: "notify_tasks";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: true;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: number | undefined;
+        }>;
+        messageId: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "message_id";
+            tableName: "notify_tasks";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: number | undefined;
+        }>;
+        contextId: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "context_id";
+            tableName: "notify_tasks";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: number | undefined;
+        }>;
+        state: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "state";
+            tableName: "notify_tasks";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: number | undefined;
+        }>;
+        taskJson: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "task_json";
+            tableName: "notify_tasks";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: number | undefined;
+        }>;
+        createdAt: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "created_at";
+            tableName: "notify_tasks";
+            dataType: "number";
+            columnType: "SQLiteInteger";
+            data: number;
+            driverParam: number;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        updatedAt: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "updated_at";
+            tableName: "notify_tasks";
+            dataType: "number";
+            columnType: "SQLiteInteger";
+            data: number;
+            driverParam: number;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+    };
+    dialect: "sqlite";
+}>;
+/**
+ * Durable subtasks: the units a parent A2A task is decomposed into.
+ *
+ * The integer primary key assigns a caller-local, monotonically increasing
+ * `SubtaskId` (autoincrement, so ids are never reused after cleanup deletes
+ * rows). References and result parts are stored as JSON text and parsed back
+ * into the `Subtask` contract by `models/subtasks.ts`.
+ * `recipe_id`/`recipe_version` are null until execution starts, then record the
+ * resolved recipe after the fact.
+ */
+export declare const subtasks: import("drizzle-orm/sqlite-core").SQLiteTableWithColumns<{
+    name: "subtasks";
+    schema: undefined;
+    columns: {
+        id: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "id";
+            tableName: "subtasks";
+            dataType: "number";
+            columnType: "SQLiteInteger";
+            data: number;
+            driverParam: number;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: true;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        taskId: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "task_id";
+            tableName: "subtasks";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: number | undefined;
+        }>;
+        round: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "round";
+            tableName: "subtasks";
+            dataType: "number";
+            columnType: "SQLiteInteger";
+            data: number;
+            driverParam: number;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        ordinal: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "ordinal";
+            tableName: "subtasks";
+            dataType: "number";
+            columnType: "SQLiteInteger";
+            data: number;
+            driverParam: number;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        type: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "type";
+            tableName: "subtasks";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: number | undefined;
+        }>;
+        recipeId: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "recipe_id";
+            tableName: "subtasks";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: number | undefined;
+        }>;
+        recipeVersion: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "recipe_version";
+            tableName: "subtasks";
+            dataType: "number";
+            columnType: "SQLiteInteger";
+            data: number;
+            driverParam: number;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        prompt: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "prompt";
+            tableName: "subtasks";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: number | undefined;
+        }>;
+        referencesJson: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "references_json";
+            tableName: "subtasks";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: number | undefined;
+        }>;
+        paramsJson: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "params_json";
+            tableName: "subtasks";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: number | undefined;
+        }>;
+        status: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "status";
+            tableName: "subtasks";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: number | undefined;
+        }>;
+        resultPartsJson: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "result_parts_json";
+            tableName: "subtasks";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: number | undefined;
+        }>;
+        error: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "error";
+            tableName: "subtasks";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: number | undefined;
+        }>;
+        createdAt: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "created_at";
+            tableName: "subtasks";
+            dataType: "number";
+            columnType: "SQLiteInteger";
+            data: number;
+            driverParam: number;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        updatedAt: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "updated_at";
+            tableName: "subtasks";
+            dataType: "number";
+            columnType: "SQLiteInteger";
+            data: number;
+            driverParam: number;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        completedAt: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "completed_at";
+            tableName: "subtasks";
+            dataType: "number";
+            columnType: "SQLiteInteger";
+            data: number;
+            driverParam: number;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+    };
+    dialect: "sqlite";
+}>;

package/dist/db/schema.js

@@ -0,0 +1,88 @@
+import { sqliteTable, text, integer, index, uniqueIndex } from "drizzle-orm/sqlite-core";
+/**
+ * Core's two tables. Both live in the caller's agent DO SQLite
+ * (`this.ctx.storage`), so a row is unreachable from any other caller by
+ * construction.
+ *
+ * A plugin's tables are **not** here and never will be: drizzle's durable-sqlite
+ * migrator keeps one flat integer journal and one global `__drizzle_migrations`
+ * table, which independently-versioned packages cannot share. Plugins own their
+ * storage through `PluginStore` — idempotent `CREATE TABLE IF NOT EXISTS` plus
+ * their own version bookkeeping, outside this journal entirely. See
+ * {@link file://./db.ts}.
+ *
+ * Indexes are declared in each table's config callback rather than as standalone
+ * `index(...)` exports: only the callback form is recorded in the drizzle-kit
+ * snapshot, so the standalone form makes every later `generate` diff propose
+ * dropping the index it can no longer see.
+ */
+/**
+ * Durable state for async A2A tasks (the accept + notify lifecycle).
+ *
+ * One row per task: written by the Worker's accept path (`beginTask`, keyed by
+ * `message_id` for gatekeeper dedupe) and mutated by the turn workflow via DO RPC
+ * (`markWorking`, `saveTask`, `cancelTask`). `GetTask` / `ListTasks` read it
+ * through `DurableTaskStore`.
+ */
+export const notifyTasks = sqliteTable("notify_tasks", {
+    taskId: text("task_id").primaryKey(),
+    /** Gatekeeper-assigned dedupe key — null for tasks created outside `beginTask`. */
+    messageId: text("message_id").unique(),
+    /** A2A context id, denormalized out of `task_json` so `ListTasks` can filter on it. */
+    contextId: text("context_id").notNull().default(""),
+    /** Human-readable `TaskState` (`working`, `input-required`, …) — see `taskStateLabel`. */
+    state: text("state").notNull(),
+    /**
+     * The task in its **A2A wire form** (`Task.toJSON`), not the in-memory proto
+     * object. Storing the wire form means what is on disk is exactly what goes
+     * on the wire, and both survive a change to the SDK's class shape;
+     * `JSON.stringify(task)` would persist in-memory internals instead.
+     */
+    taskJson: text("task_json").notNull(),
+    createdAt: integer("created_at").notNull(),
+    updatedAt: integer("updated_at").notNull()
+}, (table) => [
+    index("idx_notify_tasks_created_at").on(table.createdAt),
+    index("idx_notify_tasks_context").on(table.contextId),
+    index("idx_notify_tasks_state").on(table.state)
+]);
+/**
+ * Durable subtasks: the units a parent A2A task is decomposed into.
+ *
+ * The integer primary key assigns a caller-local, monotonically increasing
+ * `SubtaskId` (autoincrement, so ids are never reused after cleanup deletes
+ * rows). References and result parts are stored as JSON text and parsed back
+ * into the `Subtask` contract by `models/subtasks.ts`.
+ * `recipe_id`/`recipe_version` are null until execution starts, then record the
+ * resolved recipe after the fact.
+ */
+export const subtasks = sqliteTable("subtasks", {
+    id: integer("id").primaryKey({ autoIncrement: true }),
+    taskId: text("task_id").notNull(),
+    /** Main-agent round that delegated this subtask (0-based). */
+    round: integer("round").notNull(),
+    /** Position within the parent task, increasing across every round. */
+    ordinal: integer("ordinal").notNull(),
+    type: text("type").notNull(),
+    /** Resolved recipe key, written only at execution start. */
+    recipeId: text("recipe_id"),
+    /** Resolved recipe version, written only at execution start. */
+    recipeVersion: integer("recipe_version"),
+    prompt: text("prompt").notNull(),
+    /** JSON `SubtaskReference[]` — verbatim role+text snapshots from decomposition. */
+    referencesJson: text("references_json").notNull(),
+    /** JSON `SubtaskParams` — the type's required inputs, validated at delegation. */
+    paramsJson: text("params_json").notNull().default("{}"),
+    status: text("status").notNull(),
+    /** JSON `SubtaskResultPart[]` — text-only terminal output; null until complete. */
+    resultPartsJson: text("result_parts_json"),
+    error: text("error"),
+    createdAt: integer("created_at").notNull(),
+    updatedAt: integer("updated_at").notNull(),
+    completedAt: integer("completed_at")
+}, (table) => [
+    uniqueIndex("idx_subtasks_task_ordinal").on(table.taskId, table.ordinal),
+    index("idx_subtasks_task_round").on(table.taskId, table.round),
+    index("idx_subtasks_status").on(table.status),
+    index("idx_subtasks_created_at").on(table.createdAt)
+]);

package/dist/env.d.ts

@@ -0,0 +1,53 @@
+/**
+ * The Worker `env` slices core reads, declared structurally.
+ *
+ * A published package cannot reference the ambient `Env` that `wrangler types`
+ * generates into a consumer's `worker-configuration.d.ts` — that interface only
+ * exists inside the app. So core never names `Env`. Every function that needs a
+ * binding either takes it as a parameter, or takes an object satisfying one of
+ * the slices below, and a consumer's generated `Env` satisfies them structurally
+ * with no cast.
+ *
+ * The two secrets are the zero-trust contract and are the only names core
+ * insists on; everything else is passed in. Even these are only a *default*:
+ * `createA2AWorker`'s `secrets` option reads them from wherever a consumer keeps
+ * them, so a Worker whose bindings are already named something else does not
+ * have to rename them.
+ *
+ * That is *all* it does. The secrets are read once per request and belong to the
+ * deployment, not to an agent: several agents share one Worker as tenants of one
+ * origin, and they share this one signing identity with it. What separates them
+ * is the tenant claim on the gatekeeper token, not a key apiece. See
+ * {@link file://./worker/index.ts}.
+ */
+/** Workers AI, backing the chat loop (and whatever a plugin runs on it). */
+export interface AiEnv {
+    AI: Ai;
+}
+/**
+ * The two secrets every Dynamic Agents agent must carry.
+ *
+ * - `A2A_SIGNING_KEY` — Ed25519 private JWK (JSON, **must** include `kid`). Signs
+ *   the AgentCard and every push-notification callback JWT. Its public half is
+ *   served at the agent's JWKS path and pinned by the gatekeeper on first
+ *   registration (Trust-On-First-Use).
+ * - `GATEKEEPER_ORIGINS` — JSON array of origins allowed to call this agent. The
+ *   allowlist a gatekeeper JWT's `jku` and `iss` are checked against; see
+ *   {@link file://./a2a/verify.ts}.
+ *
+ * No shared secret ever crosses the boundary in either direction: the agent
+ * verifies the gatekeeper with the gatekeeper's public JWKS, and the gatekeeper verifies
+ * the agent with the agent's.
+ */
+export interface A2ASecretsEnv {
+    A2A_SIGNING_KEY: string;
+    GATEKEEPER_ORIGINS: string;
+}
+/** The minimum an agent Worker must bind for core to function. */
+export type CoreEnv = AiEnv & A2ASecretsEnv;
+/**
+ * Parse `GATEKEEPER_ORIGINS`. Accepts a JSON array (the documented form) or a
+ * single bare origin, so a misconfigured secret fails with a readable message
+ * rather than as an empty allowlist that rejects every caller identically.
+ */
+export declare function parseGatekeeperOrigins(raw: string): string[];

package/dist/env.js

@@ -0,0 +1,47 @@
+/**
+ * The Worker `env` slices core reads, declared structurally.
+ *
+ * A published package cannot reference the ambient `Env` that `wrangler types`
+ * generates into a consumer's `worker-configuration.d.ts` — that interface only
+ * exists inside the app. So core never names `Env`. Every function that needs a
+ * binding either takes it as a parameter, or takes an object satisfying one of
+ * the slices below, and a consumer's generated `Env` satisfies them structurally
+ * with no cast.
+ *
+ * The two secrets are the zero-trust contract and are the only names core
+ * insists on; everything else is passed in. Even these are only a *default*:
+ * `createA2AWorker`'s `secrets` option reads them from wherever a consumer keeps
+ * them, so a Worker whose bindings are already named something else does not
+ * have to rename them.
+ *
+ * That is *all* it does. The secrets are read once per request and belong to the
+ * deployment, not to an agent: several agents share one Worker as tenants of one
+ * origin, and they share this one signing identity with it. What separates them
+ * is the tenant claim on the gatekeeper token, not a key apiece. See
+ * {@link file://./worker/index.ts}.
+ */
+/**
+ * Parse `GATEKEEPER_ORIGINS`. Accepts a JSON array (the documented form) or a
+ * single bare origin, so a misconfigured secret fails with a readable message
+ * rather than as an empty allowlist that rejects every caller identically.
+ */
+export function parseGatekeeperOrigins(raw) {
+    const trimmed = raw.trim();
+    if (!trimmed)
+        throw new Error("GATEKEEPER_ORIGINS is empty");
+    if (!trimmed.startsWith("["))
+        return [trimmed];
+    let parsed;
+    try {
+        parsed = JSON.parse(trimmed);
+    }
+    catch (err) {
+        throw new Error(`GATEKEEPER_ORIGINS is not valid JSON: ${err.message}`);
+    }
+    if (!Array.isArray(parsed) || parsed.some((o) => typeof o !== "string")) {
+        throw new Error("GATEKEEPER_ORIGINS must be a JSON array of origin strings");
+    }
+    if (parsed.length === 0)
+        throw new Error("GATEKEEPER_ORIGINS is empty");
+    return parsed;
+}