@cleocode/playbooks 2026.4.94 → 2026.4.95

package/dist/schema.d.ts

@@ -0,0 +1,374 @@
+/**
+ * Drizzle ORM table definitions for playbook state.
+ * Both tables are added to tasks.db via migration at
+ * packages/core/migrations/drizzle-tasks/20260417220000_t889-playbook-tables/.
+ *
+ * @task T889 / T904 / W4-6
+ */
+export declare const playbookRuns: import("drizzle-orm/sqlite-core").SQLiteTableWithColumns<{
+    name: "playbook_runs";
+    schema: undefined;
+    columns: {
+        runId: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: string;
+            tableName: "playbook_runs";
+            dataType: "string";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: true;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}>;
+        playbookName: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: string;
+            tableName: "playbook_runs";
+            dataType: "string";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}>;
+        playbookHash: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: string;
+            tableName: "playbook_runs";
+            dataType: "string";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}>;
+        currentNode: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: string;
+            tableName: "playbook_runs";
+            dataType: "string";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}>;
+        bindings: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: string;
+            tableName: "playbook_runs";
+            dataType: "string";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}>;
+        errorContext: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: string;
+            tableName: "playbook_runs";
+            dataType: "string";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}>;
+        status: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: string;
+            tableName: "playbook_runs";
+            dataType: "string";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}>;
+        iterationCounts: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: string;
+            tableName: "playbook_runs";
+            dataType: "string";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}>;
+        epicId: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: string;
+            tableName: "playbook_runs";
+            dataType: "string";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}>;
+        sessionId: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: string;
+            tableName: "playbook_runs";
+            dataType: "string";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}>;
+        startedAt: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: string;
+            tableName: "playbook_runs";
+            dataType: "string";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}>;
+        completedAt: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: string;
+            tableName: "playbook_runs";
+            dataType: "string";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}>;
+    };
+    dialect: "sqlite";
+}>;
+export declare const playbookApprovals: import("drizzle-orm/sqlite-core").SQLiteTableWithColumns<{
+    name: "playbook_approvals";
+    schema: undefined;
+    columns: {
+        approvalId: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: string;
+            tableName: "playbook_approvals";
+            dataType: "string";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: true;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}>;
+        runId: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: string;
+            tableName: "playbook_approvals";
+            dataType: "string";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}>;
+        nodeId: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: string;
+            tableName: "playbook_approvals";
+            dataType: "string";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}>;
+        token: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: string;
+            tableName: "playbook_approvals";
+            dataType: "string";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}>;
+        requestedAt: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: string;
+            tableName: "playbook_approvals";
+            dataType: "string";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}>;
+        approvedAt: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: string;
+            tableName: "playbook_approvals";
+            dataType: "string";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}>;
+        approver: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: string;
+            tableName: "playbook_approvals";
+            dataType: "string";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}>;
+        reason: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: string;
+            tableName: "playbook_approvals";
+            dataType: "string";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}>;
+        status: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: string;
+            tableName: "playbook_approvals";
+            dataType: "string";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}>;
+        autoPassed: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: string;
+            tableName: "playbook_approvals";
+            dataType: "number int53";
+            data: number;
+            driverParam: number;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}>;
+    };
+    dialect: "sqlite";
+}>;
+export type { PlaybookApproval, PlaybookApprovalStatus, PlaybookRun, PlaybookRunStatus, } from '@cleocode/contracts';

package/dist/schema.js

@@ -0,0 +1,34 @@
+/**
+ * Drizzle ORM table definitions for playbook state.
+ * Both tables are added to tasks.db via migration at
+ * packages/core/migrations/drizzle-tasks/20260417220000_t889-playbook-tables/.
+ *
+ * @task T889 / T904 / W4-6
+ */
+import { integer, sqliteTable, text } from 'drizzle-orm/sqlite-core';
+export const playbookRuns = sqliteTable('playbook_runs', {
+    runId: text('run_id').primaryKey(),
+    playbookName: text('playbook_name').notNull(),
+    playbookHash: text('playbook_hash').notNull(),
+    currentNode: text('current_node'),
+    bindings: text('bindings').notNull().default('{}'),
+    errorContext: text('error_context'),
+    status: text('status').notNull().default('running'),
+    iterationCounts: text('iteration_counts').notNull().default('{}'),
+    epicId: text('epic_id'),
+    sessionId: text('session_id'),
+    startedAt: text('started_at').notNull().default("(datetime('now'))"),
+    completedAt: text('completed_at'),
+});
+export const playbookApprovals = sqliteTable('playbook_approvals', {
+    approvalId: text('approval_id').primaryKey(),
+    runId: text('run_id').notNull(),
+    nodeId: text('node_id').notNull(),
+    token: text('token').notNull().unique(),
+    requestedAt: text('requested_at').notNull().default("(datetime('now'))"),
+    approvedAt: text('approved_at'),
+    approver: text('approver'),
+    reason: text('reason'),
+    status: text('status').notNull().default('pending'),
+    autoPassed: integer('auto_passed').notNull().default(0),
+});

package/dist/state.d.ts

@@ -0,0 +1,96 @@
+/**
+ * State layer for playbook runtime — CRUD against playbook_runs + playbook_approvals.
+ * Uses node:sqlite DatabaseSync for consistency with rest of CLEO.
+ *
+ * All JSON-shaped columns (`bindings`, `iteration_counts`) are serialized to
+ * text at the write boundary and strictly parsed on read. Parse failures throw
+ * rather than silently reset state, per the data-integrity contract of ADR-013.
+ *
+ * Multi-column updates and cross-table operations run inside a BEGIN/COMMIT
+ * transaction so partial failures cannot leave the run in a half-mutated state.
+ *
+ * @task T889 / T904 / W4-8
+ */
+import type { DatabaseSync } from 'node:sqlite';
+import type { PlaybookApproval, PlaybookRun, PlaybookRunStatus } from '@cleocode/contracts';
+/**
+ * Input payload for {@link createPlaybookRun}. `playbookHash` MUST be a stable
+ * digest of the `.cantbook` source so replays can prove definition parity.
+ */
+export interface CreatePlaybookRunInput {
+    playbookName: string;
+    playbookHash: string;
+    epicId?: string;
+    sessionId?: string;
+    initialBindings?: Record<string, unknown>;
+}
+/**
+ * Input payload for {@link createPlaybookApproval}. Callers MUST supply an
+ * opaque `token` — approval resume flows look up runs by this value.
+ */
+export interface CreatePlaybookApprovalInput {
+    runId: string;
+    nodeId: string;
+    token: string;
+    autoPassed?: boolean;
+}
+/**
+ * Filter options for {@link listPlaybookRuns}. All fields are optional; when
+ * omitted the call returns the most recent runs ordered by `started_at DESC`.
+ */
+export interface ListPlaybookRunsOptions {
+    status?: PlaybookRunStatus;
+    epicId?: string;
+    limit?: number;
+}
+/**
+ * Inserts a new playbook run with a freshly generated UUID, `status='running'`,
+ * and the provided initial bindings. Returns the hydrated {@link PlaybookRun}
+ * read back from the row so callers see all server-defaulted columns
+ * (`started_at`, empty `iteration_counts`, etc.).
+ */
+export declare function createPlaybookRun(db: DatabaseSync, input: CreatePlaybookRunInput): PlaybookRun;
+/**
+ * Fetches a playbook run by its primary key. Returns `null` when the run
+ * does not exist. Never throws on missing rows.
+ */
+export declare function getPlaybookRun(db: DatabaseSync, runId: string): PlaybookRun | null;
+/**
+ * Applies a partial patch to a playbook run inside a transaction so mixed
+ * column updates (e.g. `status` + `currentNode`) commit atomically. Returns
+ * the fully-hydrated run read back after commit.
+ */
+export declare function updatePlaybookRun(db: DatabaseSync, runId: string, patch: Partial<Omit<PlaybookRun, 'runId' | 'startedAt'>>): PlaybookRun;
+/**
+ * Lists playbook runs filtered by status and/or epic. Defaults to `ORDER BY
+ * started_at DESC` so the newest runs surface first for dashboards.
+ */
+export declare function listPlaybookRuns(db: DatabaseSync, opts?: ListPlaybookRunsOptions): PlaybookRun[];
+/**
+ * Deletes a playbook run by primary key. Returns `true` if a row was removed.
+ * CASCADE wipes all associated approvals via the foreign-key constraint on
+ * `playbook_approvals.run_id`.
+ */
+export declare function deletePlaybookRun(db: DatabaseSync, runId: string): boolean;
+/**
+ * Inserts a new approval record with a freshly generated UUID, `status='pending'`,
+ * and the caller-supplied opaque token. Returns the hydrated
+ * {@link PlaybookApproval} so callers see the server-defaulted `requested_at`.
+ */
+export declare function createPlaybookApproval(db: DatabaseSync, input: CreatePlaybookApprovalInput): PlaybookApproval;
+/**
+ * Fetches an approval by its opaque token. Returns `null` if no row matches.
+ * The token column carries a UNIQUE constraint so at most one row is returned.
+ */
+export declare function getPlaybookApprovalByToken(db: DatabaseSync, token: string): PlaybookApproval | null;
+/**
+ * Applies a partial patch to an approval record inside a transaction. Used by
+ * the approval-resume flow to transactionally set both `status` and
+ * `approved_at` when a human resolves a HITL checkpoint.
+ */
+export declare function updatePlaybookApproval(db: DatabaseSync, approvalId: string, patch: Partial<Omit<PlaybookApproval, 'approvalId' | 'requestedAt'>>): PlaybookApproval;
+/**
+ * Lists all approvals for a given run, ordered by `requested_at ASC` so the
+ * first HITL checkpoint surfaces first.
+ */
+export declare function listPlaybookApprovals(db: DatabaseSync, runId: string): PlaybookApproval[];