@cleocode/playbooks 2026.4.93 → 2026.4.95

package/dist/approval.d.ts

@@ -0,0 +1,113 @@
+/**
+ * HMAC-SHA256 resume tokens for HITL approval gates.
+ *
+ * Tokens bind `{runId, nodeId, bindings}` so they cannot be forged or replayed
+ * across different executions. The secret defaults to a well-known dev value —
+ * production deployments MUST set the `CLEO_PLAYBOOK_SECRET` env var to a
+ * high-entropy secret. If the secret rotates, existing tokens are invalidated
+ * because the HMAC output changes.
+ *
+ * Binding canonicalization uses sorted-keys JSON so that `{a:1,b:2}` and
+ * `{b:2,a:1}` produce the same token — semantically identical payloads
+ * should always yield the same gate identity.
+ *
+ * @task T889 / T908 / W4-16
+ */
+import type { DatabaseSync } from 'node:sqlite';
+import type { PlaybookApproval } from '@cleocode/contracts';
+/**
+ * Error code: approval token not found in the DB.
+ * Raised by {@link approveGate} / {@link rejectGate}.
+ */
+export declare const E_APPROVAL_NOT_FOUND: "E_APPROVAL_NOT_FOUND";
+/**
+ * Error code: approval has already transitioned out of `pending`.
+ * Raised by {@link approveGate} / {@link rejectGate} to prevent re-decisions.
+ */
+export declare const E_APPROVAL_ALREADY_DECIDED: "E_APPROVAL_ALREADY_DECIDED";
+/**
+ * Resolve the HMAC secret for resume-token generation.
+ *
+ * @param env - Override env source (defaults to `process.env`). Used in tests.
+ * @returns The configured secret, or a dev-only fallback if unset.
+ */
+export declare function getPlaybookSecret(env?: NodeJS.ProcessEnv): string;
+/**
+ * Generate a deterministic 32-char hex HMAC-SHA256 resume token.
+ *
+ * The token is derived from `HMAC(secret, "runId:nodeId:canonicalBindings")`
+ * and truncated to 32 hex chars (128 bits). Determinism is an intentional
+ * design choice: the same (runId, nodeId, bindings, secret) tuple always
+ * produces the same token, preventing duplicate gates for the same step.
+ *
+ * @param runId - Playbook run identifier.
+ * @param nodeId - Node identifier within the run graph.
+ * @param bindings - Current runtime bindings (canonicalized via sorted-keys JSON).
+ * @param secret - HMAC secret (defaults to {@link getPlaybookSecret}).
+ * @returns A 32-char lowercase hex string.
+ */
+export declare function generateResumeToken(runId: string, nodeId: string, bindings: Record<string, unknown>, secret?: string): string;
+/**
+ * Input for {@link createApprovalGate}.
+ */
+export interface CreateApprovalGateInput {
+    /** Run identifier (FK to `playbook_runs.run_id`). */
+    runId: string;
+    /** Node identifier within the run graph. */
+    nodeId: string;
+    /** Runtime bindings at gate creation time. */
+    bindings: Record<string, unknown>;
+    /** If true, gate is created pre-approved (policy auto-pass). Default false. */
+    autoPassed?: boolean;
+    /** Optional approver identity (required if `autoPassed=true` recorded by policy). */
+    approver?: string;
+    /** Optional human-readable reason (policy name, approval note, etc.). */
+    reason?: string;
+    /** Override secret for token generation. Defaults to env-resolved secret. */
+    secret?: string;
+}
+/**
+ * Create an HITL approval gate row in `playbook_approvals`.
+ *
+ * If `autoPassed` is true, the gate is written with `status='approved'`
+ * and `auto_passed=1` — used by the policy engine to short-circuit gates
+ * that match auto-pass rules. Otherwise status is `'pending'` and the
+ * runtime blocks until {@link approveGate} or {@link rejectGate} is called.
+ *
+ * @param db - Open `node:sqlite` handle with the T889 migration applied.
+ * @param input - Gate parameters.
+ * @returns The inserted {@link PlaybookApproval}, round-tripped from the DB.
+ */
+export declare function createApprovalGate(db: DatabaseSync, input: CreateApprovalGateInput): PlaybookApproval;
+/**
+ * Transition an approval gate to `approved` state.
+ *
+ * @param db - Open sqlite handle.
+ * @param token - The resume token returned from {@link createApprovalGate}.
+ * @param approver - Identity of the approver (agent id, user email, etc.).
+ * @param reason - Optional justification note.
+ * @returns The updated {@link PlaybookApproval} record.
+ * @throws Error with `E_APPROVAL_NOT_FOUND` code if no gate matches the token.
+ * @throws Error with `E_APPROVAL_ALREADY_DECIDED` code if the gate is not pending.
+ */
+export declare function approveGate(db: DatabaseSync, token: string, approver: string, reason?: string): PlaybookApproval;
+/**
+ * Transition an approval gate to `rejected` state. Same semantics as
+ * {@link approveGate} but records a rejection — runtime will halt the run.
+ *
+ * @param db - Open sqlite handle.
+ * @param token - The resume token.
+ * @param approver - Identity of the rejector.
+ * @param reason - Optional justification.
+ * @returns The updated {@link PlaybookApproval} record.
+ * @throws Error with `E_APPROVAL_NOT_FOUND` if the token is unknown.
+ * @throws Error with `E_APPROVAL_ALREADY_DECIDED` if the gate is not pending.
+ */
+export declare function rejectGate(db: DatabaseSync, token: string, approver: string, reason?: string): PlaybookApproval;
+/**
+ * List all gates that are still awaiting a decision, oldest first.
+ *
+ * @param db - Open sqlite handle.
+ * @returns Pending {@link PlaybookApproval} records ordered by `requested_at`.
+ */
+export declare function getPendingApprovals(db: DatabaseSync): PlaybookApproval[];

package/dist/approval.js

@@ -0,0 +1,244 @@
+/**
+ * HMAC-SHA256 resume tokens for HITL approval gates.
+ *
+ * Tokens bind `{runId, nodeId, bindings}` so they cannot be forged or replayed
+ * across different executions. The secret defaults to a well-known dev value —
+ * production deployments MUST set the `CLEO_PLAYBOOK_SECRET` env var to a
+ * high-entropy secret. If the secret rotates, existing tokens are invalidated
+ * because the HMAC output changes.
+ *
+ * Binding canonicalization uses sorted-keys JSON so that `{a:1,b:2}` and
+ * `{b:2,a:1}` produce the same token — semantically identical payloads
+ * should always yield the same gate identity.
+ *
+ * @task T889 / T908 / W4-16
+ */
+import { createHmac, randomUUID } from 'node:crypto';
+/**
+ * Dev-only fallback secret. Surfaced through {@link getPlaybookSecret} so
+ * production code paths can override via `CLEO_PLAYBOOK_SECRET`.
+ */
+const DEFAULT_SECRET = 'cleo-playbook-dev-secret-do-not-use-in-production';
+/**
+ * Token length (hex chars). 32 hex chars = 128 bits of HMAC output — enough
+ * for collision resistance while keeping tokens URL-safe and log-friendly.
+ */
+const TOKEN_LENGTH = 32;
+/**
+ * Error code: approval token not found in the DB.
+ * Raised by {@link approveGate} / {@link rejectGate}.
+ */
+export const E_APPROVAL_NOT_FOUND = 'E_APPROVAL_NOT_FOUND';
+/**
+ * Error code: approval has already transitioned out of `pending`.
+ * Raised by {@link approveGate} / {@link rejectGate} to prevent re-decisions.
+ */
+export const E_APPROVAL_ALREADY_DECIDED = 'E_APPROVAL_ALREADY_DECIDED';
+/**
+ * Resolve the HMAC secret for resume-token generation.
+ *
+ * @param env - Override env source (defaults to `process.env`). Used in tests.
+ * @returns The configured secret, or a dev-only fallback if unset.
+ */
+export function getPlaybookSecret(env = process.env) {
+    return env['CLEO_PLAYBOOK_SECRET'] ?? DEFAULT_SECRET;
+}
+/**
+ * Generate a deterministic 32-char hex HMAC-SHA256 resume token.
+ *
+ * The token is derived from `HMAC(secret, "runId:nodeId:canonicalBindings")`
+ * and truncated to 32 hex chars (128 bits). Determinism is an intentional
+ * design choice: the same (runId, nodeId, bindings, secret) tuple always
+ * produces the same token, preventing duplicate gates for the same step.
+ *
+ * @param runId - Playbook run identifier.
+ * @param nodeId - Node identifier within the run graph.
+ * @param bindings - Current runtime bindings (canonicalized via sorted-keys JSON).
+ * @param secret - HMAC secret (defaults to {@link getPlaybookSecret}).
+ * @returns A 32-char lowercase hex string.
+ */
+export function generateResumeToken(runId, nodeId, bindings, secret = getPlaybookSecret()) {
+    // Canonicalize bindings via sorted-keys JSON for determinism.
+    const canonical = JSON.stringify(bindings, Object.keys(bindings).sort());
+    const payload = `${runId}:${nodeId}:${canonical}`;
+    return createHmac('sha256', secret).update(payload).digest('hex').slice(0, TOKEN_LENGTH);
+}
+/**
+ * Narrow a raw status string to {@link PlaybookApprovalStatus}, guarding
+ * against unexpected DB values that would otherwise poison downstream types.
+ *
+ * @internal
+ */
+function narrowStatus(s) {
+    if (s === 'pending' || s === 'approved' || s === 'rejected')
+        return s;
+    throw new Error(`invariant: unknown playbook_approvals.status '${s}'`);
+}
+/**
+ * Read a required string column from a raw sqlite row.
+ *
+ * @internal
+ */
+function readString(row, key) {
+    const v = row[key];
+    if (typeof v !== 'string') {
+        throw new Error(`invariant: expected string for column ${key}, got ${typeof v}`);
+    }
+    return v;
+}
+/**
+ * Read a required integer column from a raw sqlite row.
+ *
+ * @internal
+ */
+function readInt(row, key) {
+    const v = row[key];
+    if (typeof v === 'number')
+        return v;
+    if (typeof v === 'bigint')
+        return Number(v);
+    throw new Error(`invariant: expected integer for column ${key}, got ${typeof v}`);
+}
+/**
+ * Read an optional string column. Returns `undefined` for both `null`
+ * (SQL NULL) and missing keys.
+ *
+ * @internal
+ */
+function readOptionalString(row, key) {
+    const v = row[key];
+    if (v === null || v === undefined)
+        return undefined;
+    if (typeof v !== 'string') {
+        throw new Error(`invariant: expected string|null for column ${key}, got ${typeof v}`);
+    }
+    return v;
+}
+/**
+ * Map a raw `playbook_approvals` row to the camelCase {@link PlaybookApproval}
+ * contract shape. Validates types, converts the `auto_passed` 0/1 integer to
+ * a boolean, and strips nullable fields rather than emitting `null`.
+ *
+ * @internal
+ */
+function rowToApproval(row) {
+    const approval = {
+        approvalId: readString(row, 'approval_id'),
+        runId: readString(row, 'run_id'),
+        nodeId: readString(row, 'node_id'),
+        token: readString(row, 'token'),
+        requestedAt: readString(row, 'requested_at'),
+        status: narrowStatus(readString(row, 'status')),
+        autoPassed: readInt(row, 'auto_passed') === 1,
+    };
+    const approvedAt = readOptionalString(row, 'approved_at');
+    const approver = readOptionalString(row, 'approver');
+    const reason = readOptionalString(row, 'reason');
+    if (approvedAt !== undefined)
+        approval.approvedAt = approvedAt;
+    if (approver !== undefined)
+        approval.approver = approver;
+    if (reason !== undefined)
+        approval.reason = reason;
+    return approval;
+}
+/**
+ * Create an HITL approval gate row in `playbook_approvals`.
+ *
+ * If `autoPassed` is true, the gate is written with `status='approved'`
+ * and `auto_passed=1` — used by the policy engine to short-circuit gates
+ * that match auto-pass rules. Otherwise status is `'pending'` and the
+ * runtime blocks until {@link approveGate} or {@link rejectGate} is called.
+ *
+ * @param db - Open `node:sqlite` handle with the T889 migration applied.
+ * @param input - Gate parameters.
+ * @returns The inserted {@link PlaybookApproval}, round-tripped from the DB.
+ */
+export function createApprovalGate(db, input) {
+    const token = generateResumeToken(input.runId, input.nodeId, input.bindings, input.secret);
+    const approvalId = randomUUID();
+    const autoPassed = input.autoPassed ?? false;
+    const status = autoPassed ? 'approved' : 'pending';
+    const stmt = db.prepare(`
+    INSERT INTO playbook_approvals
+      (approval_id, run_id, node_id, token, status, auto_passed, approver, reason)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+  `);
+    stmt.run(approvalId, input.runId, input.nodeId, token, status, autoPassed ? 1 : 0, input.approver ?? null, input.reason ?? null);
+    const row = db
+        .prepare('SELECT * FROM playbook_approvals WHERE approval_id = ?')
+        .get(approvalId);
+    if (row === undefined) {
+        throw new Error(`${E_APPROVAL_NOT_FOUND}: insert did not round-trip (approval_id=${approvalId})`);
+    }
+    return rowToApproval(row);
+}
+/**
+ * Transition an approval gate to `approved` state.
+ *
+ * @param db - Open sqlite handle.
+ * @param token - The resume token returned from {@link createApprovalGate}.
+ * @param approver - Identity of the approver (agent id, user email, etc.).
+ * @param reason - Optional justification note.
+ * @returns The updated {@link PlaybookApproval} record.
+ * @throws Error with `E_APPROVAL_NOT_FOUND` code if no gate matches the token.
+ * @throws Error with `E_APPROVAL_ALREADY_DECIDED` code if the gate is not pending.
+ */
+export function approveGate(db, token, approver, reason) {
+    return transitionGate(db, token, 'approved', approver, reason);
+}
+/**
+ * Transition an approval gate to `rejected` state. Same semantics as
+ * {@link approveGate} but records a rejection — runtime will halt the run.
+ *
+ * @param db - Open sqlite handle.
+ * @param token - The resume token.
+ * @param approver - Identity of the rejector.
+ * @param reason - Optional justification.
+ * @returns The updated {@link PlaybookApproval} record.
+ * @throws Error with `E_APPROVAL_NOT_FOUND` if the token is unknown.
+ * @throws Error with `E_APPROVAL_ALREADY_DECIDED` if the gate is not pending.
+ */
+export function rejectGate(db, token, approver, reason) {
+    return transitionGate(db, token, 'rejected', approver, reason);
+}
+/**
+ * Internal shared transition logic for approve/reject. Performs row lookup,
+ * state validation, update, and round-trip fetch in a single atomic flow.
+ *
+ * @internal
+ */
+function transitionGate(db, token, next, approver, reason) {
+    const existing = db.prepare('SELECT * FROM playbook_approvals WHERE token = ?').get(token);
+    if (existing === undefined) {
+        throw new Error(`${E_APPROVAL_NOT_FOUND}: no approval gate for token`);
+    }
+    const existingStatus = narrowStatus(readString(existing, 'status'));
+    if (existingStatus !== 'pending') {
+        const approvalId = readString(existing, 'approval_id');
+        throw new Error(`${E_APPROVAL_ALREADY_DECIDED}: gate ${approvalId} is already ${existingStatus}`);
+    }
+    db.prepare(`UPDATE playbook_approvals
+       SET status = ?, approved_at = datetime('now'), approver = ?, reason = ?
+     WHERE token = ?`).run(next, approver, reason ?? null, token);
+    const row = db.prepare('SELECT * FROM playbook_approvals WHERE token = ?').get(token);
+    if (row === undefined) {
+        // Unreachable: UPDATE just succeeded on this token.
+        throw new Error(`${E_APPROVAL_NOT_FOUND}: row vanished after update (token=${token})`);
+    }
+    return rowToApproval(row);
+}
+/**
+ * List all gates that are still awaiting a decision, oldest first.
+ *
+ * @param db - Open sqlite handle.
+ * @returns Pending {@link PlaybookApproval} records ordered by `requested_at`.
+ */
+export function getPendingApprovals(db) {
+    const rows = db
+        .prepare(`SELECT * FROM playbook_approvals
+        WHERE status = 'pending'
+        ORDER BY requested_at ASC, approval_id ASC`)
+        .all();
+    return rows.map(rowToApproval);
+}

package/dist/index.d.ts

@@ -0,0 +1,30 @@
+/**
+ * @cleocode/playbooks — Playbook DSL + runtime for T889 Orchestration Coherence v3.
+ *
+ * This package is scaffolded in Wave 0. Subsequent waves will populate:
+ * - `schema.ts`     (W4-6)  — types + Drizzle table defs
+ * - `parser.ts`     (W4-7)  — .cantbook YAML parser
+ * - `state.ts`      (W4-8)  — DB CRUD for playbook_runs + playbook_approvals
+ * - `policy.ts`     (W4-9)  — HITL auto-policy rules
+ * - `runtime.ts`    (W4-10) — state machine executor
+ * - `approval.ts`   (W4-16) — resume token generation + approval ops
+ * - `skill-composer.ts` (W4-2..5) — three-source skill bundle composer
+ *
+ * @remarks
+ * Only the {@link PLAYBOOKS_PACKAGE_VERSION} constant is exported from the
+ * Wave 0 scaffold. Each follow-up wave adds a named barrel export here.
+ *
+ * @task T889 Orchestration Coherence v3 — Wave 0 scaffold
+ */
+/**
+ * Package version string matching the monorepo's CalVer cadence.
+ *
+ * Consumers can use this to assert dependency alignment at runtime
+ * (e.g. ensuring the `@cleocode/playbooks` runtime matches CLEO core).
+ */
+export declare const PLAYBOOKS_PACKAGE_VERSION: string;
+export { approveGate, type CreateApprovalGateInput, createApprovalGate, E_APPROVAL_ALREADY_DECIDED, E_APPROVAL_NOT_FOUND, generateResumeToken, getPendingApprovals, getPlaybookSecret, rejectGate, } from './approval.js';
+export { type ParsePlaybookResult, PlaybookParseError, parsePlaybook, } from './parser.js';
+export { DEFAULT_POLICY_RULES, type EvaluatePolicyResult, evaluatePolicy, type PolicyRule, } from './policy.js';
+export { type AgentDispatcher, type AgentDispatchInput, type AgentDispatchResult, type DeterministicRunInput, type DeterministicRunner, type DeterministicRunResult, E_PLAYBOOK_RESUME_BLOCKED, E_PLAYBOOK_RUNTIME_INVALID, type ExecutePlaybookOptions, type ExecutePlaybookResult, executePlaybook, type PlaybookTerminalStatus, type ResumePlaybookOptions, resumePlaybook, } from './runtime.js';
+export { type CreatePlaybookApprovalInput, type CreatePlaybookRunInput, createPlaybookApproval, createPlaybookRun, deletePlaybookRun, getPlaybookApprovalByToken, getPlaybookRun, type ListPlaybookRunsOptions, listPlaybookApprovals, listPlaybookRuns, updatePlaybookApproval, updatePlaybookRun, } from './state.js';

package/dist/index.js

@@ -0,0 +1,34 @@
+/**
+ * @cleocode/playbooks — Playbook DSL + runtime for T889 Orchestration Coherence v3.
+ *
+ * This package is scaffolded in Wave 0. Subsequent waves will populate:
+ * - `schema.ts`     (W4-6)  — types + Drizzle table defs
+ * - `parser.ts`     (W4-7)  — .cantbook YAML parser
+ * - `state.ts`      (W4-8)  — DB CRUD for playbook_runs + playbook_approvals
+ * - `policy.ts`     (W4-9)  — HITL auto-policy rules
+ * - `runtime.ts`    (W4-10) — state machine executor
+ * - `approval.ts`   (W4-16) — resume token generation + approval ops
+ * - `skill-composer.ts` (W4-2..5) — three-source skill bundle composer
+ *
+ * @remarks
+ * Only the {@link PLAYBOOKS_PACKAGE_VERSION} constant is exported from the
+ * Wave 0 scaffold. Each follow-up wave adds a named barrel export here.
+ *
+ * @task T889 Orchestration Coherence v3 — Wave 0 scaffold
+ */
+/**
+ * Package version string matching the monorepo's CalVer cadence.
+ *
+ * Consumers can use this to assert dependency alignment at runtime
+ * (e.g. ensuring the `@cleocode/playbooks` runtime matches CLEO core).
+ */
+export const PLAYBOOKS_PACKAGE_VERSION = '2026.4.85';
+export { approveGate, createApprovalGate, E_APPROVAL_ALREADY_DECIDED, E_APPROVAL_NOT_FOUND, generateResumeToken, getPendingApprovals, getPlaybookSecret, rejectGate, } from './approval.js';
+// W4-7: .cantbook YAML parser → PlaybookDefinition
+export { PlaybookParseError, parsePlaybook, } from './parser.js';
+// W4-9: HITL auto-policy evaluator
+export { DEFAULT_POLICY_RULES, evaluatePolicy, } from './policy.js';
+// W4-10 / T930: playbook runtime state machine + HITL resume
+export { E_PLAYBOOK_RESUME_BLOCKED, E_PLAYBOOK_RUNTIME_INVALID, executePlaybook, resumePlaybook, } from './runtime.js';
+// W4-8: state layer CRUD for playbook_runs + playbook_approvals
+export { createPlaybookApproval, createPlaybookRun, deletePlaybookRun, getPlaybookApprovalByToken, getPlaybookRun, listPlaybookApprovals, listPlaybookRuns, updatePlaybookApproval, updatePlaybookRun, } from './state.js';

package/dist/parser.d.ts

@@ -0,0 +1,60 @@
+/**
+ * .cantbook YAML parser → PlaybookDefinition.
+ *
+ * Grammar (see contracts/playbook.ts):
+ *   version: "1.0"
+ *   name: <string>
+ *   description?: <string>
+ *   inputs?: [{name, required?, default?, description?}]
+ *   nodes: [<agentic | deterministic | approval node>]
+ *   edges: [{from, to, contract?:{requires?[], ensures?[]}}]
+ *   error_handlers?: [{on, action, message?}]
+ *
+ * Validation:
+ *   - version MUST be "1.0"
+ *   - name MUST be non-empty
+ *   - node ids MUST be unique
+ *   - every edge.from + edge.to MUST reference a known node id
+ *   - nodes form a DAG when combined with edges (no cycles)
+ *   - agentic nodes MUST have skill OR agent (at least one)
+ *   - deterministic nodes MUST have command + args
+ *   - approval nodes MUST have prompt
+ *   - depends[] entries MUST be valid node ids
+ *   - iteration_cap (max_iterations) MUST be 0..10 (hard limit)
+ *
+ * @task T889 / T904 / W4-7
+ */
+import type { PlaybookDefinition } from '@cleocode/contracts';
+/**
+ * Error thrown on any structural or semantic parse failure. Carries a
+ * `code`/`exitCode` pair so callers can bubble up consistent LAFS envelopes.
+ */
+export declare class PlaybookParseError extends Error {
+    readonly field?: string | undefined;
+    readonly value?: unknown | undefined;
+    /** Stable envelope error code for LAFS. */
+    readonly code = "E_PLAYBOOK_PARSE";
+    /** Process exit code used by CLI wrappers when a parse fails. */
+    readonly exitCode = 70;
+    /**
+     * @param message - Human-readable reason the playbook is invalid.
+     * @param field - Offending field path (e.g. `"nodes[0].id"`).
+     * @param value - Offending value for diagnostics (never re-thrown).
+     */
+    constructor(message: string, field?: string | undefined, value?: unknown | undefined);
+}
+/** Result of a successful {@link parsePlaybook} call. */
+export interface ParsePlaybookResult {
+    /** Validated, normalized definition ready for runtime execution. */
+    definition: PlaybookDefinition;
+    /** SHA-256 hex of the input source (for tamper detection). */
+    sourceHash: string;
+}
+/**
+ * Parse raw .cantbook YAML text into a validated {@link PlaybookDefinition}.
+ *
+ * @param source - Raw .cantbook YAML text.
+ * @returns The validated definition plus a deterministic SHA-256 source hash.
+ * @throws {PlaybookParseError} On any structural or semantic violation.
+ */
+export declare function parsePlaybook(source: string): ParsePlaybookResult;