@relayflows/core 0.0.1 → 1.0.0

package/dist/sibling-links.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Sibling-package link setup for workflows that consume a package living in
+ * a sibling repo / worktree on disk.
+ *
+ * Problem it solves: agents running inside a workflow sometimes find that
+ * `npm install` (or `pip install`) resolved an older version of a package
+ * than the one the workflow actually needs — for example when the consumer
+ * workflow runs before the producer has published a new release. Rather
+ * than letting agents see a stale interface (and react by augmenting the
+ * module or writing fallback implementations), linking redirects the
+ * package resolution at dev-time to the sibling's on-disk build output.
+ *
+ * Usage (ESM):
+ *
+ *   import { workflow, applySiblingLinks } from '@relayflows/core';
+ *
+ *   const base = workflow('my-feature').pattern('dag').agent('impl', ...);
+ *   const wf = applySiblingLinks(base, {
+ *     dependsOn: ['install-deps'],
+ *     links: [
+ *       {
+ *         name: '@agent-assistant/proactive',
+ *         path: '../agent-assistant/packages/proactive',
+ *         expect: ['recordSignal', 'drainSignals'],
+ *       },
+ *       {
+ *         name: '@agent-assistant/surfaces',
+ *         path: '../agent-assistant/packages/surfaces',
+ *         expect: ['classifySlackPresenceSignal'],
+ *       },
+ *     ],
+ *   });
+ *
+ *   await wf.step('plan', { agent: 'impl', dependsOn: ['setup-sibling-links'], task: ... })
+ *     .run({ cwd: process.cwd() });
+ *
+ * MVP language support: npm (package.json), Python (pyproject.toml /
+ * setup.py / setup.cfg). Auto-detects from the sibling's manifest. Fails
+ * fast on missing path, unknown manifest, or missing expected exports.
+ */
+/** A single sibling package to link into the workflow's working directory. */
+export interface SiblingLink {
+    /**
+     * Package name as it appears in imports (e.g. "@agent-assistant/proactive",
+     * "my_python_pkg"). For Python, use the import name (underscored), not the
+     * distribution name.
+     */
+    name: string;
+    /**
+     * Path to the sibling package root, relative to the workflow's cwd.
+     * For npm, this is the directory containing package.json.
+     * For Python, the directory containing pyproject.toml / setup.py.
+     */
+    path: string;
+    /**
+     * Optional list of top-level named exports / attributes the workflow
+     * expects to find on the linked package post-setup. When provided, a
+     * language-appropriate import smoke test runs and fails the step if any
+     * are missing.
+     */
+    expect?: string[];
+}
+export interface SiblingLinkOptions {
+    /** Link declarations. All must succeed (fail-fast on any error). */
+    links: SiblingLink[];
+    /**
+     * Step name for the setup step emitted by this helper.
+     * Defaults to `"setup-sibling-links"`.
+     */
+    stepName?: string;
+    /**
+     * dependsOn for the setup step. Typically `['install-deps']` so that
+     * `npm install` / `pip install` has run first.
+     * Defaults to `['install-deps']`.
+     */
+    dependsOn?: string[];
+}
+/**
+ * Adds a single deterministic step to the workflow that links each sibling
+ * package into the workflow's working directory using the appropriate
+ * language-specific mechanism, then smoke-tests each linked package for
+ * expected exports.
+ *
+ * The step fails fast on:
+ *   - Sibling path missing
+ *   - Unknown manifest (no package.json / pyproject.toml / setup.py)
+ *   - Link command failure
+ *   - Missing expected export
+ */
+export declare function applySiblingLinks<T>(wf: T, opts: SiblingLinkOptions): T;
+/**
+ * Builds a bash script that:
+ *   1. For each link, detects its manifest and applies the right link command.
+ *   2. After all links succeed, runs one import smoke test per link that
+ *      declared expected exports.
+ *
+ * Exported for test visibility; not part of the public API.
+ */
+export declare function buildSiblingLinkScript(links: SiblingLink[]): string;
+//# sourceMappingURL=sibling-links.d.ts.map

package/dist/sibling-links.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sibling-links.d.ts","sourceRoot":"","sources":["../src/sibling-links.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAEH,8EAA8E;AAC9E,MAAM,WAAW,WAAW;IAC1B;;;;OAIG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;;;OAIG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;;;;OAKG;IACH,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,MAAM,WAAW,kBAAkB;IACjC,oEAAoE;IACpE,KAAK,EAAE,WAAW,EAAE,CAAC;IAErB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;CACtB;AAOD;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,IAAI,EAAE,kBAAkB,GAAG,CAAC,CAkBvE;AAkBD;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,WAAW,EAAE,GAAG,MAAM,CAsBnE"}

package/dist/sibling-links.js

@@ -0,0 +1,205 @@
+/**
+ * Sibling-package link setup for workflows that consume a package living in
+ * a sibling repo / worktree on disk.
+ *
+ * Problem it solves: agents running inside a workflow sometimes find that
+ * `npm install` (or `pip install`) resolved an older version of a package
+ * than the one the workflow actually needs — for example when the consumer
+ * workflow runs before the producer has published a new release. Rather
+ * than letting agents see a stale interface (and react by augmenting the
+ * module or writing fallback implementations), linking redirects the
+ * package resolution at dev-time to the sibling's on-disk build output.
+ *
+ * Usage (ESM):
+ *
+ *   import { workflow, applySiblingLinks } from '@relayflows/core';
+ *
+ *   const base = workflow('my-feature').pattern('dag').agent('impl', ...);
+ *   const wf = applySiblingLinks(base, {
+ *     dependsOn: ['install-deps'],
+ *     links: [
+ *       {
+ *         name: '@agent-assistant/proactive',
+ *         path: '../agent-assistant/packages/proactive',
+ *         expect: ['recordSignal', 'drainSignals'],
+ *       },
+ *       {
+ *         name: '@agent-assistant/surfaces',
+ *         path: '../agent-assistant/packages/surfaces',
+ *         expect: ['classifySlackPresenceSignal'],
+ *       },
+ *     ],
+ *   });
+ *
+ *   await wf.step('plan', { agent: 'impl', dependsOn: ['setup-sibling-links'], task: ... })
+ *     .run({ cwd: process.cwd() });
+ *
+ * MVP language support: npm (package.json), Python (pyproject.toml /
+ * setup.py / setup.cfg). Auto-detects from the sibling's manifest. Fails
+ * fast on missing path, unknown manifest, or missing expected exports.
+ */
+/**
+ * Adds a single deterministic step to the workflow that links each sibling
+ * package into the workflow's working directory using the appropriate
+ * language-specific mechanism, then smoke-tests each linked package for
+ * expected exports.
+ *
+ * The step fails fast on:
+ *   - Sibling path missing
+ *   - Unknown manifest (no package.json / pyproject.toml / setup.py)
+ *   - Link command failure
+ *   - Missing expected export
+ */
+export function applySiblingLinks(wf, opts) {
+    if (opts.links.length === 0) {
+        return wf;
+    }
+    const stepName = opts.stepName ?? 'setup-sibling-links';
+    const dependsOn = opts.dependsOn ?? ['install-deps'];
+    const script = buildSiblingLinkScript(opts.links);
+    const chain = wf;
+    chain.step(stepName, {
+        type: 'deterministic',
+        dependsOn,
+        command: `bash -c ${shSingleQuote(script)}`,
+        captureOutput: true,
+        failOnError: true,
+    });
+    return wf;
+}
+// ─── Internal: shell-script generation ─────────────────────────────────────
+/**
+ * Shell-quote a string for safe single-quoted inclusion in a bash command.
+ * Single-quoted strings in bash are literal for every character except the
+ * single quote itself, so `$` and backticks are NOT interpreted — which is
+ * exactly what we want for link.name / link.path / JSON payloads that must
+ * pass through bash unchanged.
+ *
+ * Embedded single quotes are escaped via the standard `'\''` POSIX idiom
+ * (close, escape, reopen).
+ */
+function shSingleQuote(value) {
+    return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+/**
+ * Builds a bash script that:
+ *   1. For each link, detects its manifest and applies the right link command.
+ *   2. After all links succeed, runs one import smoke test per link that
+ *      declared expected exports.
+ *
+ * Exported for test visibility; not part of the public API.
+ */
+export function buildSiblingLinkScript(links) {
+    const lines = ['set -euo pipefail', 'echo "=== applySiblingLinks: setting up ==="'];
+    for (const link of links) {
+        // Use SINGLE-quoted shell literals for the assignments. Double-quoted
+        // literals (via JSON.stringify) would let `$`, backticks, and `\` still
+        // trigger substitution or escaping — single-quoted is literal end-to-end.
+        const escapedName = shSingleQuote(link.name);
+        const escapedPath = shSingleQuote(link.path);
+        lines.push(linkOneBlock(link, escapedName, escapedPath));
+    }
+    lines.push('echo "=== applySiblingLinks: verifying exports ==="');
+    for (const link of links) {
+        if (!link.expect || link.expect.length === 0) {
+            continue;
+        }
+        lines.push(verifyExportsBlock(link));
+    }
+    lines.push('echo "APPLY_SIBLING_LINKS_OK"');
+    return lines.join('\n');
+}
+function linkOneBlock(link, escapedName, escapedPath) {
+    void link;
+    return [
+        `SIBLING_PATH=${escapedPath}`,
+        `SIBLING_NAME=${escapedName}`,
+        'echo "--- link: $SIBLING_NAME <- $SIBLING_PATH ---"',
+        'if [ ! -d "$SIBLING_PATH" ]; then',
+        '  echo "SIBLING_PATH_MISSING: $SIBLING_PATH" >&2',
+        '  exit 1',
+        'fi',
+        'if [ -f "$SIBLING_PATH/package.json" ]; then',
+        '  echo "detected: npm"',
+        '  ( cd "$SIBLING_PATH" && npm link --silent )',
+        '  npm link --silent "$SIBLING_NAME"',
+        'elif [ -f "$SIBLING_PATH/pyproject.toml" ] || [ -f "$SIBLING_PATH/setup.py" ] || [ -f "$SIBLING_PATH/setup.cfg" ]; then',
+        '  echo "detected: python"',
+        // Try uv first (fastest when available), but uv refuses to install
+        // outside a venv without --system. Pass --system explicitly so uv
+        // works in non-venv sandboxes (common CI/agent runner shape).
+        // If uv still fails (e.g. broken install), fall through to pip/pip3
+        // via the explicit OR chain rather than relying on `set -e` to
+        // short-circuit between elif branches.
+        '  if command -v uv >/dev/null 2>&1 && uv pip install --system -e "$SIBLING_PATH" --quiet 2>/dev/null; then',
+        '    :',
+        '  elif command -v pip >/dev/null 2>&1; then',
+        '    pip install -e "$SIBLING_PATH" --quiet',
+        '  elif command -v pip3 >/dev/null 2>&1; then',
+        '    pip3 install -e "$SIBLING_PATH" --quiet',
+        '  else',
+        '    echo "NO_PYTHON_INSTALLER: uv / pip / pip3 not found or all failed" >&2',
+        '    exit 1',
+        '  fi',
+        'else',
+        '  echo "UNKNOWN_MANIFEST: expected package.json / pyproject.toml / setup.py / setup.cfg at $SIBLING_PATH" >&2',
+        '  exit 1',
+        'fi',
+    ].join('\n');
+}
+function verifyExportsBlock(link) {
+    const escapedName = shSingleQuote(link.name);
+    const escapedPath = shSingleQuote(link.path);
+    const expectJson = JSON.stringify(link.expect ?? []);
+    // Pick the smoke-test runtime based on what manifest type the sibling had.
+    // Single-quoted assignments are literal — the JSON payload inside EXPECT
+    // survives bash untouched and downstream Node/Python JSON.parse it back.
+    return [
+        `SIBLING_PATH=${escapedPath}`,
+        `SIBLING_NAME=${escapedName}`,
+        `EXPECT=${shSingleQuote(expectJson)}`,
+        'if [ -f "$SIBLING_PATH/package.json" ]; then',
+        nodeVerifyCommand(),
+        'else',
+        pythonVerifyCommand(),
+        'fi',
+    ].join('\n');
+}
+function nodeVerifyCommand() {
+    const script = [
+        'const want = JSON.parse(process.env.APPLY_SIBLING_LINKS_EXPECT);',
+        'const name = process.env.APPLY_SIBLING_LINKS_NAME;',
+        'const mod = await import(name);',
+        'const missing = want.filter((k) => !(k in mod));',
+        'if (missing.length) {',
+        '  console.error(`MISSING_EXPORTS in ${name}: ${missing.join(",")}`);',
+        '  process.exit(1);',
+        '}',
+        'console.log(`${name} OK: ${want.join(",")}`);',
+    ].join(' ');
+    return `  APPLY_SIBLING_LINKS_NAME="$SIBLING_NAME" APPLY_SIBLING_LINKS_EXPECT="$EXPECT" node --input-type=module -e ${shSingleQuote(script)}`;
+}
+function pythonVerifyCommand() {
+    // Python < 3.12 forbids backslashes inside f-string expressions, so we
+    // can't inline `{",".join(missing)}` (which needs `\",\".` when written
+    // as a JS string literal). Bind the separator to a name outside the
+    // f-string first.
+    const script = [
+        'import json, os, importlib',
+        'name = os.environ["APPLY_SIBLING_LINKS_NAME"]',
+        'want = json.loads(os.environ["APPLY_SIBLING_LINKS_EXPECT"])',
+        'mod = importlib.import_module(name)',
+        'missing = [k for k in want if not hasattr(mod, k)]',
+        'sep = ","',
+        'if missing:',
+        '    print(f"MISSING_EXPORTS in {name}: {sep.join(missing)}", flush=True)',
+        '    raise SystemExit(1)',
+        'print(f"{name} OK: {sep.join(want)}", flush=True)',
+    ].join('\n');
+    return [
+        '  APPLY_SIBLING_LINKS_NAME="$SIBLING_NAME" APPLY_SIBLING_LINKS_EXPECT="$EXPECT" \\',
+        `  python3 -c ${shSingleQuote(script)} 2>/dev/null || \\`,
+        `  APPLY_SIBLING_LINKS_NAME="$SIBLING_NAME" APPLY_SIBLING_LINKS_EXPECT="$EXPECT" python -c ${shSingleQuote(script)}`,
+    ].join('\n');
+}
+//# sourceMappingURL=sibling-links.js.map

package/dist/sibling-links.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sibling-links.js","sourceRoot":"","sources":["../src/sibling-links.ts"],"names":[],"mappings":"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"}

package/dist/state.d.ts

@@ -0,0 +1,77 @@
+/**
+ * State Store — CRUD on swarm_state with optional consensus-gated writes.
+ *
+ * Provides a key-value store scoped to a workflow run and namespace.
+ * When consensus gating is enabled, writes require approval from a
+ * ConsensusEngine before being committed.
+ */
+import { EventEmitter } from 'node:events';
+import type { DbClient } from './coordinator.js';
+export interface StateEntry {
+    id: string;
+    runId: string;
+    namespace: string;
+    key: string;
+    value: unknown;
+    expiresAt: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface StateStoreOptions {
+    /** Default namespace for keys. */
+    namespace?: string;
+    /** Default TTL in milliseconds for new entries. */
+    defaultTtlMs?: number;
+}
+export interface WriteOptions {
+    namespace?: string;
+    ttlMs?: number;
+}
+export interface ReadOptions {
+    namespace?: string;
+}
+/** Callback invoked to gate a write. Return true to allow, false to reject. */
+export type ConsensusGate = (runId: string, key: string, value: unknown, agent: string) => Promise<boolean>;
+export interface StateStoreEvents {
+    'state:set': (entry: StateEntry) => void;
+    'state:deleted': (runId: string, key: string, namespace: string) => void;
+    'state:gated': (runId: string, key: string, agent: string) => void;
+}
+export declare class StateStore extends EventEmitter {
+    private db;
+    private defaultNamespace;
+    private defaultTtlMs;
+    private consensusGate;
+    constructor(db: DbClient, options?: StateStoreOptions);
+    /**
+     * Enable consensus-gated writes. When set, every `set()` call will
+     * invoke the gate function before persisting. If the gate returns false,
+     * the write is rejected.
+     */
+    setConsensusGate(gate: ConsensusGate): void;
+    clearConsensusGate(): void;
+    /**
+     * Set a key-value pair. If consensus gating is enabled, the write is
+     * subject to approval.
+     *
+     * @param agent - The agent requesting the write (used for consensus gating).
+     */
+    set(runId: string, key: string, value: unknown, agent: string, options?: WriteOptions): Promise<StateEntry>;
+    get(runId: string, key: string, options?: ReadOptions): Promise<unknown | null>;
+    getEntry(runId: string, key: string, options?: ReadOptions): Promise<StateEntry | null>;
+    getAll(runId: string, options?: ReadOptions): Promise<StateEntry[]>;
+    keys(runId: string, options?: ReadOptions): Promise<string[]>;
+    delete(runId: string, key: string, options?: ReadOptions): Promise<boolean>;
+    deleteAll(runId: string, options?: ReadOptions): Promise<number>;
+    /**
+     * Remove all expired entries for a run (or globally if runId is omitted).
+     * Returns the number of entries purged.
+     */
+    purgeExpired(runId?: string): Promise<number>;
+    /**
+     * Take a snapshot of all state for a run as a plain object.
+     * Useful for persisting into workflow_runs.state_snapshot.
+     */
+    snapshot(runId: string, options?: ReadOptions): Promise<Record<string, unknown>>;
+}
+//# sourceMappingURL=state.d.ts.map

package/dist/state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../src/state.ts"],"names":[],"mappings":"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"}

package/dist/state.js

@@ -0,0 +1,140 @@
+/**
+ * State Store — CRUD on swarm_state with optional consensus-gated writes.
+ *
+ * Provides a key-value store scoped to a workflow run and namespace.
+ * When consensus gating is enabled, writes require approval from a
+ * ConsensusEngine before being committed.
+ */
+import { randomBytes } from 'node:crypto';
+import { EventEmitter } from 'node:events';
+// ── Store ───────────────────────────────────────────────────────────────────
+export class StateStore extends EventEmitter {
+    db;
+    defaultNamespace;
+    defaultTtlMs;
+    consensusGate = null;
+    constructor(db, options = {}) {
+        super();
+        this.db = db;
+        this.defaultNamespace = options.namespace ?? 'default';
+        this.defaultTtlMs = options.defaultTtlMs ?? null;
+    }
+    // ── Consensus gating ──────────────────────────────────────────────────
+    /**
+     * Enable consensus-gated writes. When set, every `set()` call will
+     * invoke the gate function before persisting. If the gate returns false,
+     * the write is rejected.
+     */
+    setConsensusGate(gate) {
+        this.consensusGate = gate;
+    }
+    clearConsensusGate() {
+        this.consensusGate = null;
+    }
+    // ── Write ─────────────────────────────────────────────────────────────
+    /**
+     * Set a key-value pair. If consensus gating is enabled, the write is
+     * subject to approval.
+     *
+     * @param agent - The agent requesting the write (used for consensus gating).
+     */
+    async set(runId, key, value, agent, options = {}) {
+        // Consensus gate check.
+        if (this.consensusGate) {
+            const allowed = await this.consensusGate(runId, key, value, agent);
+            if (!allowed) {
+                this.emit('state:gated', runId, key, agent);
+                throw new Error(`Write to "${key}" rejected by consensus gate for agent "${agent}"`);
+            }
+        }
+        const namespace = options.namespace ?? this.defaultNamespace;
+        const ttlMs = options.ttlMs ?? this.defaultTtlMs;
+        const expiresAt = ttlMs ? new Date(Date.now() + ttlMs).toISOString() : null;
+        const id = `st_${Date.now()}_${randomBytes(4).toString('hex')}`;
+        const now = new Date().toISOString();
+        // Upsert: use the unique (run_id, namespace, key) constraint.
+        const { rows } = await this.db.query(`INSERT INTO swarm_state (id, run_id, namespace, key, value, expires_at, created_at, updated_at)
+       VALUES ($1, $2, $3, $4, $5, $6, $7, $7)
+       ON CONFLICT (run_id, namespace, key)
+       DO UPDATE SET value = EXCLUDED.value, expires_at = EXCLUDED.expires_at, updated_at = EXCLUDED.updated_at
+       RETURNING *`, [id, runId, namespace, key, JSON.stringify(value), expiresAt, now]);
+        const entry = rows[0];
+        this.emit('state:set', entry);
+        return entry;
+    }
+    // ── Read ──────────────────────────────────────────────────────────────
+    async get(runId, key, options = {}) {
+        const namespace = options.namespace ?? this.defaultNamespace;
+        const { rows } = await this.db.query(`SELECT * FROM swarm_state
+       WHERE run_id = $1 AND namespace = $2 AND key = $3
+         AND (expires_at IS NULL OR expires_at > now())`, [runId, namespace, key]);
+        if (rows.length === 0)
+            return null;
+        return rows[0].value;
+    }
+    async getEntry(runId, key, options = {}) {
+        const namespace = options.namespace ?? this.defaultNamespace;
+        const { rows } = await this.db.query(`SELECT * FROM swarm_state
+       WHERE run_id = $1 AND namespace = $2 AND key = $3
+         AND (expires_at IS NULL OR expires_at > now())`, [runId, namespace, key]);
+        return rows[0] ?? null;
+    }
+    async getAll(runId, options = {}) {
+        const namespace = options.namespace ?? this.defaultNamespace;
+        const { rows } = await this.db.query(`SELECT * FROM swarm_state
+       WHERE run_id = $1 AND namespace = $2
+         AND (expires_at IS NULL OR expires_at > now())
+       ORDER BY key ASC`, [runId, namespace]);
+        return rows;
+    }
+    async keys(runId, options = {}) {
+        const namespace = options.namespace ?? this.defaultNamespace;
+        const { rows } = await this.db.query(`SELECT key FROM swarm_state
+       WHERE run_id = $1 AND namespace = $2
+         AND (expires_at IS NULL OR expires_at > now())
+       ORDER BY key ASC`, [runId, namespace]);
+        return rows.map((r) => r.key);
+    }
+    // ── Delete ────────────────────────────────────────────────────────────
+    async delete(runId, key, options = {}) {
+        const namespace = options.namespace ?? this.defaultNamespace;
+        const { rows } = await this.db.query(`DELETE FROM swarm_state WHERE run_id = $1 AND namespace = $2 AND key = $3 RETURNING id`, [runId, namespace, key]);
+        if (rows.length > 0) {
+            this.emit('state:deleted', runId, key, namespace);
+            return true;
+        }
+        return false;
+    }
+    async deleteAll(runId, options = {}) {
+        const namespace = options.namespace ?? this.defaultNamespace;
+        const { rows } = await this.db.query(`DELETE FROM swarm_state WHERE run_id = $1 AND namespace = $2 RETURNING id`, [runId, namespace]);
+        return rows.length;
+    }
+    // ── Expiry cleanup ────────────────────────────────────────────────────
+    /**
+     * Remove all expired entries for a run (or globally if runId is omitted).
+     * Returns the number of entries purged.
+     */
+    async purgeExpired(runId) {
+        if (runId) {
+            const { rows } = await this.db.query(`DELETE FROM swarm_state WHERE run_id = $1 AND expires_at IS NOT NULL AND expires_at <= now() RETURNING id`, [runId]);
+            return rows.length;
+        }
+        const { rows } = await this.db.query(`DELETE FROM swarm_state WHERE expires_at IS NOT NULL AND expires_at <= now() RETURNING id`, []);
+        return rows.length;
+    }
+    // ── Snapshot ───────────────────────────────────────────────────────────
+    /**
+     * Take a snapshot of all state for a run as a plain object.
+     * Useful for persisting into workflow_runs.state_snapshot.
+     */
+    async snapshot(runId, options = {}) {
+        const entries = await this.getAll(runId, options);
+        const result = {};
+        for (const entry of entries) {
+            result[entry.key] = entry.value;
+        }
+        return result;
+    }
+}
+//# sourceMappingURL=state.js.map

package/dist/state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.js","sourceRoot":"","sources":["../src/state.ts"],"names":[],"mappings":"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"}

package/dist/step-executor.d.ts

@@ -0,0 +1,95 @@
+import { ChannelMessenger } from './channel-messenger.js';
+import type { ProcessSpawner } from './process-spawner.js';
+import { TemplateResolver } from './template-resolver.js';
+import type { StepOutcome } from './trajectory.js';
+import type { AgentDefinition, ErrorHandlingConfig, StepCompletionMode, VerificationCheck, WorkflowStep, WorkflowStepCompletionReason, WorkflowStepRow, WorkflowStepStatus } from './types.js';
+import { type VerificationOptions, type VerificationResult, type VerificationSideEffects } from './verification.js';
+type StateLike = {
+    row: WorkflowStepRow;
+};
+export interface StepResult {
+    status: WorkflowStepStatus;
+    output: string;
+    exitCode?: number;
+    exitSignal?: string;
+    duration: number;
+    retries: number;
+    completionReason?: WorkflowStepCompletionReason;
+    error?: string;
+}
+export interface StepSchedule {
+    step: WorkflowStep;
+    readyAt: number;
+    staggerDelay: number;
+}
+export interface StepExecutorDeps<TState extends StateLike = StateLike> {
+    cwd: string;
+    runId?: string;
+    postToChannel?: (text: string) => void;
+    persistStepRow?: (stepId: string, patch: Partial<WorkflowStepRow>) => Promise<void>;
+    persistStepOutput?: (runId: string, stepName: string, output: string) => Promise<void>;
+    resolveTemplate?: (template: string, context: Record<string, unknown>) => string;
+    getStepOutput?: (stepName: string) => string | undefined;
+    loadStepOutput?: (runId: string, stepName: string) => string | undefined;
+    checkAborted?: () => void;
+    waitIfPaused?: () => Promise<void>;
+    log?: (message: string) => void;
+    processSpawner?: ProcessSpawner;
+    templateResolver?: TemplateResolver;
+    channelMessenger?: ChannelMessenger;
+    verificationRunner?: (check: VerificationCheck, output: string, stepName: string, injectedTaskText?: string, options?: VerificationOptions, sideEffects?: VerificationSideEffects) => VerificationResult;
+    executeStep?: (step: WorkflowStep, state: TState, agentMap: Map<string, AgentDefinition>, errorHandling?: ErrorHandlingConfig) => Promise<Partial<StepResult> | void>;
+    onStepStarted?: (step: WorkflowStep, state: TState) => Promise<void> | void;
+    onStepRetried?: (step: WorkflowStep, state: TState, attempt: number, maxRetries: number) => Promise<void> | void;
+    onStepCompleted?: (step: WorkflowStep, state: TState, result: StepResult) => Promise<void> | void;
+    onStepFailed?: (step: WorkflowStep, state: TState, result: StepResult) => Promise<void> | void;
+    onBeginTrack?: (steps: WorkflowStep[]) => Promise<void> | void;
+    onConverge?: (steps: WorkflowStep[], outcomes: StepOutcome[]) => Promise<void> | void;
+    markDownstreamSkipped?: (failedStepName: string) => Promise<void>;
+    buildCompletionMode?: (stepName: string, completionReason?: WorkflowStepCompletionReason) => StepCompletionMode | undefined;
+}
+export interface MonitorStepOptions<TState extends StateLike, TResult> {
+    maxRetries?: number;
+    retryDelayMs?: number;
+    startMessage?: string;
+    onStart?: (attempt: number, state: TState) => Promise<void> | void;
+    onRetry?: (attempt: number, maxRetries: number, state: TState) => Promise<void> | void;
+    execute: (attempt: number, state: TState) => Promise<TResult>;
+    toCompletionResult: (result: TResult, attempt: number, state: TState) => Partial<StepResult>;
+    onAttemptFailed?: (error: unknown, attempt: number, state: TState) => Promise<void> | void;
+    getFailureResult?: (error: unknown, attempt: number, state: TState) => Partial<StepResult>;
+}
+export declare class StepExecutor<TState extends StateLike = StateLike> {
+    private readonly deps;
+    private readonly templateResolver;
+    private readonly channelMessenger;
+    private readonly verificationRunner;
+    constructor(deps: StepExecutorDeps<TState>);
+    findReady(steps: WorkflowStep[], statuses: Map<string, WorkflowStepStatus> | Map<string, TState>): WorkflowStep[];
+    /** @deprecated Use {@link findReady} instead. This is an alias kept for backward compatibility. */
+    findReadySteps(steps: WorkflowStep[], statuses: Map<string, WorkflowStepStatus> | Map<string, TState>): WorkflowStep[];
+    scheduleStep(step: WorkflowStep, options?: {
+        readyAt?: number;
+        staggerDelay?: number;
+    }): StepSchedule;
+    startStep(step: WorkflowStep, state: TState, startMessage?: string): Promise<void>;
+    retryStep(step: WorkflowStep, state: TState, attempt: number, maxRetries: number): Promise<void>;
+    completeStep(step: WorkflowStep, state: TState, result: Partial<StepResult>): Promise<StepResult>;
+    monitorStep<TResult>(step: WorkflowStep, state: TState, options: MonitorStepOptions<TState, TResult>): Promise<StepResult>;
+    executeAll(steps: WorkflowStep[], agentMap: Map<string, AgentDefinition>, errorHandling?: ErrorHandlingConfig, providedStates?: Map<string, TState>): Promise<Map<string, StepResult>>;
+    executeOne(step: WorkflowStep, agentMap: Map<string, AgentDefinition>, errorHandling?: ErrorHandlingConfig, providedState?: TState): Promise<StepResult>;
+    markFailed(stepName: string, error: string): Promise<void>;
+    buildStepOutputContext(stepStates: Map<string, TState>): Record<string, {
+        output: string;
+    }>;
+    resolveStepTemplate(template: string, context: Record<string, unknown>): string;
+    getChannelMessenger(): ChannelMessenger;
+    runVerification(check: VerificationCheck, output: string, stepName: string, injectedTaskText?: string, options?: VerificationOptions): VerificationResult;
+    private executeScheduledStep;
+    private executeWithProcessSpawner;
+    private createEphemeralStates;
+    private createEphemeralState;
+    private getStatus;
+}
+export {};
+//# sourceMappingURL=step-executor.d.ts.map