@dynamicagents/core 0.9.0

package/dist/db/migrations/index.js

@@ -0,0 +1,60 @@
+const dbMigrations = {
+    journal: {
+        entries: [
+            {
+                idx: 0,
+                when: 1785537420937,
+                tag: "0000_init",
+                breakpoints: true
+            },
+            {
+                idx: 1,
+                when: 1786871925215,
+                tag: "0001_drop_depends_on",
+                breakpoints: true
+            }
+        ]
+    },
+    migrations: {
+        m0000: `CREATE TABLE \`notify_tasks\` (
+	\`task_id\` text PRIMARY KEY NOT NULL,
+	\`message_id\` text,
+	\`context_id\` text DEFAULT '' NOT NULL,
+	\`state\` text NOT NULL,
+	\`task_json\` text NOT NULL,
+	\`created_at\` integer NOT NULL,
+	\`updated_at\` integer NOT NULL
+);
+--> statement-breakpoint
+CREATE UNIQUE INDEX \`notify_tasks_message_id_unique\` ON \`notify_tasks\` (\`message_id\`);--> statement-breakpoint
+CREATE INDEX \`idx_notify_tasks_created_at\` ON \`notify_tasks\` (\`created_at\`);--> statement-breakpoint
+CREATE INDEX \`idx_notify_tasks_context\` ON \`notify_tasks\` (\`context_id\`);--> statement-breakpoint
+CREATE INDEX \`idx_notify_tasks_state\` ON \`notify_tasks\` (\`state\`);--> statement-breakpoint
+CREATE TABLE \`subtasks\` (
+	\`id\` integer PRIMARY KEY AUTOINCREMENT NOT NULL,
+	\`task_id\` text NOT NULL,
+	\`round\` integer NOT NULL,
+	\`ordinal\` integer NOT NULL,
+	\`type\` text NOT NULL,
+	\`recipe_id\` text,
+	\`recipe_version\` integer,
+	\`prompt\` text NOT NULL,
+	\`references_json\` text NOT NULL,
+	\`depends_on_json\` text NOT NULL,
+	\`params_json\` text DEFAULT '{}' NOT NULL,
+	\`status\` text NOT NULL,
+	\`result_parts_json\` text,
+	\`error\` text,
+	\`created_at\` integer NOT NULL,
+	\`updated_at\` integer NOT NULL,
+	\`completed_at\` integer
+);
+--> statement-breakpoint
+CREATE UNIQUE INDEX \`idx_subtasks_task_ordinal\` ON \`subtasks\` (\`task_id\`,\`ordinal\`);--> statement-breakpoint
+CREATE INDEX \`idx_subtasks_task_round\` ON \`subtasks\` (\`task_id\`,\`round\`);--> statement-breakpoint
+CREATE INDEX \`idx_subtasks_status\` ON \`subtasks\` (\`status\`);--> statement-breakpoint
+CREATE INDEX \`idx_subtasks_created_at\` ON \`subtasks\` (\`created_at\`);`,
+        m0001: `ALTER TABLE \`subtasks\` DROP COLUMN \`depends_on_json\`;`
+    }
+};
+export default dbMigrations;

package/dist/db/models/subtasks.d.ts

@@ -0,0 +1,100 @@
+import type { DB } from "../db.js";
+import type { Subtask, SubtaskDraft, SubtaskId, SubtaskResultPart } from "../../subtasks/types.js";
+export interface SubtaskModelOptions {
+    /**
+     * Upper bound on subtasks per round, re-checked here as the **durable** guard.
+     * The delegation schema offers the model the same bound, but a schema is a
+     * suggestion to a model and this is the write that has to hold.
+     */
+    maxSubtasks: number;
+}
+/**
+ * Query methods for the `subtasks` table (durable decomposed units of work).
+ *
+ * Bound to a drizzle handle by {@link AgentDB} and reached as `db.subtasks.*`.
+ * durable-sqlite is synchronous; the multi-statement `createDecomposition` runs
+ * inside an explicit `db.transaction` (drizzle maps it to
+ * `storage.transactionSync`), so a mid-create failure rolls back every statement
+ * instead of leaving a partial decomposition. Guarded transitions filter on the expected
+ * current `status`, so a disallowed transition matches no row and is a no-op.
+ */
+export declare function makeSubtasks(db: DB, opts: SubtaskModelOptions): {
+    /**
+     * Create one **round's** decomposition atomically: the whole check-and-insert
+     * sequence runs in one synchronous `db.transaction`, so a failure anywhere
+     * rolls back every statement rather than leaving a truncated subtask set.
+     * Idempotent on `(taskId, round)`: if this round already has Subtasks,
+     * returns them unchanged (a Workflow-step retry must not duplicate work); the
+     * unique `(task_id, ordinal)` index is the schema-level backstop. Enforces the
+     * 1..8 per-round bound as the durable guard.
+     *
+     * `ordinal` continues across rounds (it is the Task-wide position, and what
+     * the unique index is built on), so a later round's rows sort after the
+     * earlier ones in {@link list}.
+     */
+    createDecomposition(taskId: string, round: number, drafts: SubtaskDraft[]): Subtask[];
+    /** Load one Subtask by id. */
+    get(id: SubtaskId): Subtask | null;
+    /** List every round's Subtasks for a Task, in ordinal order. */
+    list(taskId: string): Subtask[];
+    /**
+     * List one round's Subtasks, in ordinal order — what the Workflow's `scan`
+     * projects. It executes a single round at a time, so it must not see a
+     * sibling round's rows; a later round, by contrast, reads {@link list}
+     * across all rounds to reunite each `delegate` call with its results.
+     */
+    listRound(taskId: string, round: number): Subtask[];
+    /**
+     * Begin execution: guarded `pending -> running`, recording the resolved
+     * Recipe id/version after-the-fact. Returns false if the Subtask was not
+     * pending (already started, terminal, or unknown).
+     */
+    start(id: SubtaskId, recipe: {
+        recipeId: string;
+        recipeVersion: number;
+    }): boolean;
+    /**
+     * Persist a successful terminal result: guarded `running -> completed`.
+     * Requires at least one non-empty text result part (a successful Recipe
+     * output invariant).
+     */
+    complete(id: SubtaskId, resultParts: SubtaskResultPart[]): boolean;
+    /**
+     * Persist a failure from either non-terminal status, with a diagnostic message.
+     *
+     * Both sides are reachable and both must land. A child's failed result arrives
+     * on a `running` row. The Workflow's last resort — `failSubtask`, once
+     * `execute:<id>` has exhausted every retry — can arrive on either:
+     * `executeSubtask` may throw before its `pending -> running` claim (an
+     * unresolvable recipe) or after it (a transient child fault). Leaving either
+     * behind strands the row in a non-terminal state that nobody is coming back
+     * to resolve.
+     *
+     * Returns false once the row is terminal — a late loser to the real result.
+     */
+    fail(id: SubtaskId, error: string): boolean;
+    /**
+     * Discard a late result after parent cancellation: guarded
+     * `running -> canceled`. The parent calls this when a child returned a
+     * terminal result but the Task was canceled while it ran — the result is
+     * dropped, and this leaves the row in a truthful terminal state instead of a
+     * `running` that never resolves. Returns false if the Subtask was not running.
+     */
+    cancelRunning(id: SubtaskId): boolean;
+    /**
+     * Cancel every still-pending Subtask of a Task (parent cancellation).
+     * Running Subtasks are left alone here — the parent transitions those with
+     * {@link cancelRunning} once their in-flight result comes back and is
+     * discarded. Returns the number canceled.
+     *
+     * Keyed on the Task rather than one id, so this is the one guarded
+     * transition that cannot go through {@link transition} and sets its own
+     * timestamps. `completedAt` is part of that and not optional: every other
+     * terminal write records it, and a terminal row without one reads as still
+     * in flight to anything measuring how long a Subtask took or when a Task
+     * actually stopped.
+     */
+    cancelPending(taskId: string): number;
+    /** Delete Subtasks older than 30 days (called by the weekly maintenance cron). */
+    cleanup(): void;
+};

package/dist/db/models/subtasks.js

@@ -0,0 +1,241 @@
+import { and, eq, inArray, lt, max } from "drizzle-orm";
+import { z } from "zod";
+import { subtasks } from "../schema.js";
+const referenceSchema = z.object({
+    role: z.enum(["user", "assistant"]),
+    text: z.string()
+});
+const resultPartSchema = z.object({
+    kind: z.literal("text"),
+    text: z.string()
+});
+const referencesSchema = z.array(referenceSchema);
+const resultPartsSchema = z.array(resultPartSchema);
+const paramsSchema = z.record(z.string(), z.string());
+/**
+ * Query methods for the `subtasks` table (durable decomposed units of work).
+ *
+ * Bound to a drizzle handle by {@link AgentDB} and reached as `db.subtasks.*`.
+ * durable-sqlite is synchronous; the multi-statement `createDecomposition` runs
+ * inside an explicit `db.transaction` (drizzle maps it to
+ * `storage.transactionSync`), so a mid-create failure rolls back every statement
+ * instead of leaving a partial decomposition. Guarded transitions filter on the expected
+ * current `status`, so a disallowed transition matches no row and is a no-op.
+ */
+export function makeSubtasks(db, opts) {
+    const rowToSubtask = (row) => ({
+        id: row.id,
+        taskId: row.taskId,
+        round: row.round,
+        ordinal: row.ordinal,
+        type: row.type,
+        recipeId: row.recipeId,
+        recipeVersion: row.recipeVersion,
+        prompt: row.prompt,
+        references: referencesSchema.parse(JSON.parse(row.referencesJson)),
+        params: paramsSchema.parse(JSON.parse(row.paramsJson)),
+        status: row.status,
+        resultParts: row.resultPartsJson === null
+            ? null
+            : resultPartsSchema.parse(JSON.parse(row.resultPartsJson)),
+        error: row.error,
+        createdAt: row.createdAt,
+        updatedAt: row.updatedAt,
+        completedAt: row.completedAt
+    });
+    const list = (taskId) => db
+        .select()
+        .from(subtasks)
+        .where(eq(subtasks.taskId, taskId))
+        .orderBy(subtasks.ordinal)
+        .all()
+        .map(rowToSubtask);
+    /** Rides `idx_subtasks_task_round` — no full-Task scan to reach one round. */
+    const listRound = (taskId, round) => db
+        .select()
+        .from(subtasks)
+        .where(and(eq(subtasks.taskId, taskId), eq(subtasks.round, round)))
+        .orderBy(subtasks.ordinal)
+        .all()
+        .map(rowToSubtask);
+    /** Guarded status update: applies only from a `from` status, returns whether it did. */
+    const transition = (id, from, set) => {
+        const now = Date.now();
+        const statuses = Array.isArray(from) ? from : [from];
+        const updated = db
+            .update(subtasks)
+            .set({ ...set, updatedAt: now })
+            .where(and(eq(subtasks.id, id), inArray(subtasks.status, statuses)))
+            .returning({ id: subtasks.id })
+            .all();
+        return updated.length > 0;
+    };
+    return {
+        /**
+         * Create one **round's** decomposition atomically: the whole check-and-insert
+         * sequence runs in one synchronous `db.transaction`, so a failure anywhere
+         * rolls back every statement rather than leaving a truncated subtask set.
+         * Idempotent on `(taskId, round)`: if this round already has Subtasks,
+         * returns them unchanged (a Workflow-step retry must not duplicate work); the
+         * unique `(task_id, ordinal)` index is the schema-level backstop. Enforces the
+         * 1..8 per-round bound as the durable guard.
+         *
+         * `ordinal` continues across rounds (it is the Task-wide position, and what
+         * the unique index is built on), so a later round's rows sort after the
+         * earlier ones in {@link list}.
+         */
+        createDecomposition(taskId, round, drafts) {
+            return db.transaction(() => {
+                const existing = listRound(taskId, round);
+                if (existing.length > 0)
+                    return existing;
+                if (drafts.length < 1 || drafts.length > opts.maxSubtasks) {
+                    throw new Error(`decomposition must have 1..${opts.maxSubtasks} subtasks, got ${drafts.length}`);
+                }
+                // References must match the persisted shape before we serialize them.
+                for (const d of drafts)
+                    referencesSchema.parse(d.references);
+                const now = Date.now();
+                // Ordinals continue above every earlier round's rows — from the current
+                // maximum, not a row count, so a gap left by {@link cleanup} deleting part
+                // of a Task cannot hand a later round an ordinal that is already taken.
+                // Both read the `(task_id, ordinal)` index; only this one stays monotonic.
+                const highest = db
+                    .select({ max: max(subtasks.ordinal) })
+                    .from(subtasks)
+                    .where(eq(subtasks.taskId, taskId))
+                    .get()?.max ?? null;
+                const firstOrdinal = highest === null ? 0 : highest + 1;
+                drafts.forEach((d, offset) => {
+                    db.insert(subtasks)
+                        .values({
+                        taskId,
+                        round,
+                        ordinal: firstOrdinal + offset,
+                        type: d.type,
+                        recipeId: null,
+                        recipeVersion: null,
+                        prompt: d.prompt,
+                        referencesJson: JSON.stringify(d.references),
+                        paramsJson: JSON.stringify(d.params ?? {}),
+                        status: "pending",
+                        resultPartsJson: null,
+                        error: null,
+                        createdAt: now,
+                        updatedAt: now,
+                        completedAt: null
+                    })
+                        .run();
+                });
+                return listRound(taskId, round);
+            });
+        },
+        /** Load one Subtask by id. */
+        get(id) {
+            const row = db.select().from(subtasks).where(eq(subtasks.id, id)).get();
+            return row ? rowToSubtask(row) : null;
+        },
+        /** List every round's Subtasks for a Task, in ordinal order. */
+        list(taskId) {
+            return list(taskId);
+        },
+        /**
+         * List one round's Subtasks, in ordinal order — what the Workflow's `scan`
+         * projects. It executes a single round at a time, so it must not see a
+         * sibling round's rows; a later round, by contrast, reads {@link list}
+         * across all rounds to reunite each `delegate` call with its results.
+         */
+        listRound(taskId, round) {
+            return listRound(taskId, round);
+        },
+        /**
+         * Begin execution: guarded `pending -> running`, recording the resolved
+         * Recipe id/version after-the-fact. Returns false if the Subtask was not
+         * pending (already started, terminal, or unknown).
+         */
+        start(id, recipe) {
+            return transition(id, "pending", {
+                status: "running",
+                recipeId: recipe.recipeId,
+                recipeVersion: recipe.recipeVersion
+            });
+        },
+        /**
+         * Persist a successful terminal result: guarded `running -> completed`.
+         * Requires at least one non-empty text result part (a successful Recipe
+         * output invariant).
+         */
+        complete(id, resultParts) {
+            const parts = resultPartsSchema.parse(resultParts);
+            if (!parts.some((p) => p.text.trim().length > 0)) {
+                throw new Error("completed subtask requires a non-empty text part");
+            }
+            return transition(id, "running", {
+                status: "completed",
+                resultPartsJson: JSON.stringify(parts),
+                completedAt: Date.now()
+            });
+        },
+        /**
+         * Persist a failure from either non-terminal status, with a diagnostic message.
+         *
+         * Both sides are reachable and both must land. A child's failed result arrives
+         * on a `running` row. The Workflow's last resort — `failSubtask`, once
+         * `execute:<id>` has exhausted every retry — can arrive on either:
+         * `executeSubtask` may throw before its `pending -> running` claim (an
+         * unresolvable recipe) or after it (a transient child fault). Leaving either
+         * behind strands the row in a non-terminal state that nobody is coming back
+         * to resolve.
+         *
+         * Returns false once the row is terminal — a late loser to the real result.
+         */
+        fail(id, error) {
+            return transition(id, ["running", "pending"], {
+                status: "failed",
+                error,
+                completedAt: Date.now()
+            });
+        },
+        /**
+         * Discard a late result after parent cancellation: guarded
+         * `running -> canceled`. The parent calls this when a child returned a
+         * terminal result but the Task was canceled while it ran — the result is
+         * dropped, and this leaves the row in a truthful terminal state instead of a
+         * `running` that never resolves. Returns false if the Subtask was not running.
+         */
+        cancelRunning(id) {
+            return transition(id, "running", {
+                status: "canceled",
+                completedAt: Date.now()
+            });
+        },
+        /**
+         * Cancel every still-pending Subtask of a Task (parent cancellation).
+         * Running Subtasks are left alone here — the parent transitions those with
+         * {@link cancelRunning} once their in-flight result comes back and is
+         * discarded. Returns the number canceled.
+         *
+         * Keyed on the Task rather than one id, so this is the one guarded
+         * transition that cannot go through {@link transition} and sets its own
+         * timestamps. `completedAt` is part of that and not optional: every other
+         * terminal write records it, and a terminal row without one reads as still
+         * in flight to anything measuring how long a Subtask took or when a Task
+         * actually stopped.
+         */
+        cancelPending(taskId) {
+            const now = Date.now();
+            const canceled = db
+                .update(subtasks)
+                .set({ status: "canceled", updatedAt: now, completedAt: now })
+                .where(and(eq(subtasks.taskId, taskId), eq(subtasks.status, "pending")))
+                .returning({ id: subtasks.id })
+                .all();
+            return canceled.length;
+        },
+        /** Delete Subtasks older than 30 days (called by the weekly maintenance cron). */
+        cleanup() {
+            const cutoff = Date.now() - 30 * 24 * 60 * 60 * 1000;
+            db.delete(subtasks).where(lt(subtasks.createdAt, cutoff)).run();
+        }
+    };
+}

package/dist/db/models/tasks.d.ts

@@ -0,0 +1,118 @@
+import { Task, TaskState } from "@a2a-js/sdk";
+import { type PlainTask } from "../../a2a/task.js";
+import type { DB } from "../db.js";
+/** Filters + paging for {@link makeTasks} `list` (the A2A `ListTasks` method). */
+export interface TaskListQuery {
+    /** A2A context id to filter on; empty/absent means no filter. */
+    contextId?: string;
+    /** Task state to filter on, or `undefined` for any state. */
+    state?: TaskState;
+    /** Only tasks whose status was written at or after this epoch-ms instant. */
+    updatedAfter?: number;
+    /** Drop `artifacts` from the returned tasks (the spec's default). */
+    includeArtifacts: boolean;
+    /** Cap on each task's `history`; `undefined` keeps it whole, `0` drops it. */
+    historyLength?: number;
+    limit: number;
+    offset: number;
+}
+/**
+ * A task's state, tolerating the `status`-less task the SDK's generated type
+ * permits (`TaskStatus | undefined`). Nothing we build omits it, so an
+ * unspecified state means the row came from somewhere unexpected — and it
+ * compares equal to none of the states the callers switch on.
+ */
+export declare function stateOf(task: Task): TaskState;
+/**
+ * Query methods for the `notify_tasks` table (async A2A task state).
+ *
+ * Bound to a drizzle handle by {@link AgentDB} and reached as `db.tasks.*`.
+ * Migrations are owned by `AgentDB`, not this factory — it only issues queries.
+ *
+ * Rows hold the task in its **A2A wire form** (`Task.toJSON`), not the in-memory
+ * protobuf shape the SDK hands us. Those differ under v1.0 — enums are numbers
+ * in memory but `SCREAMING_SNAKE` strings on the wire, and `Part.content` is a
+ * `{ $case, value }` wrapper in memory but a bare named key on the wire — so a
+ * plain `JSON.stringify` would persist a shape that is neither valid A2A JSON
+ * nor stable across SDK versions. Encoding on write and decoding on read keeps
+ * the stored bytes the spec's own format, which is also exactly what
+ * `postNotification` puts on the wire.
+ */
+export declare function makeTasks(db: DB): {
+    /**
+     * Accept a turn: return the `submitted` task for the given `messageId`,
+     * creating it on first sight. Idempotent on `messageId` (the gatekeeper's
+     * dedupe key, stable across dispatch retries).
+     */
+    begin(input: {
+        messageId: string;
+        taskId: string;
+        contextId: string;
+    }): PlainTask;
+    /** Load a task by id (for `GetTask` via the Worker's `DurableTaskStore`). */
+    get(taskId: string): PlainTask | null;
+    /**
+     * A page of this caller's tasks for `ListTasks`, newest first, with the
+     * total matching count so the store can decide whether a next page exists.
+     */
+    list(query: TaskListQuery): {
+        tasks: PlainTask[];
+        totalSize: number;
+    };
+    /**
+     * Upsert a task by id, preserving the `message_id` set by {@link begin}.
+     * Returns whether the write applied.
+     *
+     * Guarded exactly like {@link markWorking}, and for the same reason: a
+     * `canceled` row is terminal, so nothing may write a non-canceled state over
+     * it. That closes the window between a workflow's terminal build and its
+     * callback — the read-check-write is synchronous here, so a `CancelTask`
+     * landing mid-delivery makes this return `false` and the notify never fires.
+     *
+     * The reverse direction is guarded too: writing `canceled` over an already
+     * `completed`/`failed` row is refused, mirroring {@link cancel}'s own source
+     * guard. Without it, a cancellation landing between the Workflow's `complete`
+     * and `notify` steps — separate, independently-retried steps — could flip
+     * storage to canceled while `deliver()` still posts the cached completed
+     * task it already built, the exact race this guard exists to close. Writing
+     * `canceled` onto a `submitted`/`working` row, or re-writing it onto an
+     * already-`canceled` one, stays allowed: that is how the a2a-js handler's own
+     * cancel branch records the cancellation.
+     *
+     * **And no terminal row may be replaced by a *different* terminal state.**
+     * The two rules above were written about cancellation and between them left
+     * `completed → failed` wide open, which is not hypothetical: a workflow whose
+     * `notify` step exhausts its retries throws *after* `complete` durably saved
+     * a completed Task, and an abandoned-task recovery above it would then write
+     * a generic failure over a real answer and post a callback contradicting it.
+     * A turn that succeeded would be recorded as having failed because a webhook
+     * was flaky.
+     *
+     * Same terminal state re-written is still allowed, and must be: a Workflow
+     * replay legitimately re-runs `complete` and saves what it already saved, and
+     * refusing that would suppress the callback that replay exists to send.
+     */
+    save(task: Task): boolean;
+    /**
+     * Move a task to `working` (a turn workflow's first step). Returns
+     * `"canceled"` when the row is already canceled, which is the caller's
+     * signal to stop the turn; every other outcome — unknown task, or a task
+     * already past `submitted` — is a no-op reported as `"ok"`, because a
+     * workflow replay legitimately re-runs this step.
+     */
+    markWorking(taskId: string): "ok" | "canceled";
+    /**
+     * Flip the task to `canceled` and return it, or `null` if the row is not
+     * eligible — unknown, or already past `submitted`/`working`. Guarding the
+     * source state (not just the destination, as {@link save} does) matters
+     * because `complete`/`notify` are separate Workflow steps: without this, a
+     * cancellation landing between them would flip an already-`completed` or
+     * `failed` row to `canceled` right as `deliver()` posts the terminal
+     * callback it had already built, silently rewriting a delivered result.
+     * Terminal: once this lands, {@link save} refuses every non-canceled write,
+     * so no completed or failed callback can be built from this row afterwards.
+     */
+    cancel(taskId: string): PlainTask | null;
+    /** Delete all tasks older than 30 days (called by the maintenance cron). */
+    cleanup(): void;
+};