@relayflows/core 0.0.1 → 1.0.1

package/dist/dry-run-format.js

@@ -0,0 +1,79 @@
+/**
+ * Format a DryRunReport as human-readable text for terminal output.
+ */
+export function formatDryRunReport(report) {
+    const lines = [];
+    // Header
+    lines.push(`Dry Run: ${report.name}`);
+    const meta = [`Pattern: ${report.pattern}`];
+    if (report.maxConcurrency !== undefined) {
+        meta.push(`Max Concurrency: ${report.maxConcurrency}`);
+    }
+    lines.push(meta.join(' | '));
+    if (report.description) {
+        lines.push(report.description);
+    }
+    lines.push('');
+    // Agents
+    if (report.agents.length > 0) {
+        lines.push(`Agents (${report.agents.length}):`);
+        const maxNameLen = Math.max(...report.agents.map((a) => a.name.length));
+        const maxCliLen = Math.max(...report.agents.map((a) => a.cli.length));
+        for (const agent of report.agents) {
+            const stepLabel = agent.stepCount === 1 ? '1 step' : `${agent.stepCount} steps`;
+            const cwdInfo = agent.cwd ? ` [cwd: ${agent.cwd}]` : '';
+            lines.push(`  ${agent.name.padEnd(maxNameLen)}  ${agent.cli.padEnd(maxCliLen)}  ${stepLabel}${cwdInfo}`);
+        }
+        lines.push('');
+    }
+    // Permissions
+    if (report.permissions && report.permissions.length > 0) {
+        lines.push(`Permissions (${report.permissions.length} agents):`);
+        for (const perm of report.permissions) {
+            lines.push(`  ${perm.agent}: ${perm.access} (read: ${perm.readPaths}, write: ${perm.writePaths}, deny: ${perm.denyPaths}, scopes: ${perm.scopes}) [${perm.source}]`);
+        }
+        lines.push('');
+    }
+    // Execution Plan
+    if (report.waves.length > 0) {
+        lines.push(`Execution Plan (${report.totalSteps} steps, ${report.estimatedWaves} waves):`);
+        lines.push('');
+        for (const wave of report.waves) {
+            for (let i = 0; i < wave.steps.length; i++) {
+                const step = wave.steps[i];
+                const prefix = i === 0 ? `  Wave ${String(wave.wave).padStart(2)}:` : '          ';
+                // Steps without an agent are deterministic (shell/gate) steps; label
+                // them as such rather than printing the literal "undefined".
+                const actor = step.agent ?? 'deterministic';
+                lines.push(`${prefix}  ${step.name} (${actor})`);
+            }
+        }
+        lines.push('');
+    }
+    // Resource estimation
+    if (report.estimatedPeakConcurrency !== undefined) {
+        lines.push(`Resource Estimate:`);
+        lines.push(`  Peak Concurrency: ${report.estimatedPeakConcurrency} agents`);
+        if (report.estimatedTotalAgentSteps !== undefined) {
+            lines.push(`  Total Agent Steps: ${report.estimatedTotalAgentSteps}`);
+        }
+        lines.push('');
+    }
+    // Validation summary
+    if (report.errors.length > 0) {
+        lines.push(`Validation: FAIL (${report.errors.length} errors, ${report.warnings.length} warnings)`);
+        for (const err of report.errors) {
+            lines.push(`  ERROR: ${err}`);
+        }
+    }
+    else {
+        lines.push(`Validation: PASS (0 errors, ${report.warnings.length} warnings)`);
+    }
+    if (report.warnings.length > 0) {
+        for (const warn of report.warnings) {
+            lines.push(`  WARNING: ${warn}`);
+        }
+    }
+    return lines.join('\n');
+}
+//# sourceMappingURL=dry-run-format.js.map

package/dist/dry-run-format.js.map

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

package/dist/file-db.d.ts

@@ -0,0 +1,85 @@
+import type { WorkflowRunRow, WorkflowStepRow } from './types.js';
+import type { WorkflowDb } from './runner.js';
+/**
+ * Optional hook: fired whenever a persistence write fails (e.g. EACCES,
+ * ENOSPC). Surfaced so the CLI, dashboard, or bootstrap can decide how
+ * to react beyond the single console.warn. Not called for the initial
+ * "directory unwritable" detection — that's stored in {@link isWritable}.
+ */
+export type DbWriteFailureListener = (err: unknown, filePath: string) => void;
+export interface JsonFileWorkflowDbOptions {
+    /** Override the resolved filePath. Kept for tests / advanced callers. */
+    filePath?: string;
+    /** Notified on every underlying write error. */
+    onWriteFailure?: DbWriteFailureListener;
+    /**
+     * When true, if the preferred file path is unwritable, fall back to
+     * `$HOME/.agent-relay/workflow-runs-<basename>.jsonl` so `--resume`
+     * still works in environments where the workflow cwd is read-only
+     * (cloud sandboxes with restrictive workspace ACLs).
+     *
+     * Defaults to `false` — strict "write to this path or run in-memory"
+     * semantics, matching the pre-cache behavior. Opt-in via `true`.
+     */
+    homeFallback?: boolean;
+}
+/**
+ * JSONL-backed WorkflowDb for the CLI.
+ *
+ * Design: the **in-memory cache is the single source of truth** for the
+ * process lifetime. Every mutation updates the cache synchronously and
+ * then best-effort appends to the jsonl file for durability / `--resume`.
+ *
+ * This matters because the runtime correctness of a running workflow
+ * must not depend on disk writes succeeding. If the storage path is
+ * unwritable (ACL-restricted workspace, full disk, ENOSPC), the workflow
+ * still progresses through its state machine correctly — we just lose
+ * the ability to resume a future process from that run.
+ *
+ * Read paths used to re-snapshot the jsonl on every call, which meant
+ * a failed `updateRun(..., { status: 'completed' })` would leave a
+ * subsequent `getRun` returning the stale 'running' row from disk.
+ * That bug surfaced as workflows passing per-step but reporting
+ * `status: 'running'` to callers.
+ *
+ * Storage path resolution:
+ *   1. Try the caller-supplied file path. If the parent directory is
+ *      writable, use it.
+ *   2. If (1) fails and `homeFallback` is true (opt-in, default false),
+ *      try `$HOME/.agent-relay/workflow-runs-<basename>.jsonl`. This is
+ *      outside any workspace mount in cloud sandboxes and almost always
+ *      writable by the agent.
+ *   3. If both fail, run in memory-only mode. The workflow still
+ *      executes correctly; `--resume` won't be available for this run.
+ *
+ * File: `.agent-relay/workflow-runs.jsonl` in the workflow cwd by default.
+ */
+export declare class JsonFileWorkflowDb implements WorkflowDb {
+    private readonly filePath;
+    /** Whether persistence is active. False = in-memory-only mode. */
+    private readonly writable;
+    private appendFailedOnce;
+    private readonly onWriteFailure?;
+    /**
+     * Authoritative in-memory mirror. Every mutation updates this; reads
+     * return from here. The jsonl file is only consulted at construction
+     * (to replay prior state for `--resume`) and is otherwise write-only.
+     */
+    private readonly cache;
+    constructor(filePathOrOptions: string | JsonFileWorkflowDbOptions);
+    /** Returns false if persistence is not active (in-memory-only mode). */
+    isWritable(): boolean;
+    /** Resolved path on disk. For tests + diagnostics. */
+    getStoragePath(): string;
+    hasStepOutputs(runId: string): boolean;
+    private static resolveStoragePath;
+    private static loadSnapshot;
+    private append;
+    insertRun(run: WorkflowRunRow): Promise<void>;
+    updateRun(id: string, patch: Partial<WorkflowRunRow>): Promise<void>;
+    getRun(id: string): Promise<WorkflowRunRow | null>;
+    insertStep(step: WorkflowStepRow): Promise<void>;
+    updateStep(id: string, patch: Partial<WorkflowStepRow>): Promise<void>;
+    getStepsByRunId(runId: string): Promise<WorkflowStepRow[]>;
+}
+//# sourceMappingURL=file-db.d.ts.map

package/dist/file-db.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-db.d.ts","sourceRoot":"","sources":["../src/file-db.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAClE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAI9C;;;;;GAKG;AACH,MAAM,MAAM,sBAAsB,GAAG,CAAC,GAAG,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;AAE9E,MAAM,WAAW,yBAAyB;IACxC,yEAAyE;IACzE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,gDAAgD;IAChD,cAAc,CAAC,EAAE,sBAAsB,CAAC;IACxC;;;;;;;;OAQG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,qBAAa,kBAAmB,YAAW,UAAU;IACnD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAElC,kEAAkE;IAClE,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAU;IACnC,OAAO,CAAC,gBAAgB,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAC,CAAyB;IAEzD;;;;OAIG;IACH,OAAO,CAAC,QAAQ,CAAC,KAAK,CAGpB;gBAEU,iBAAiB,EAAE,MAAM,GAAG,yBAAyB;IAiBjE,wEAAwE;IACxE,UAAU,IAAI,OAAO;IAIrB,sDAAsD;IACtD,cAAc,IAAI,MAAM;IAIxB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO;IAWtC,OAAO,CAAC,MAAM,CAAC,kBAAkB;IA8CjC,OAAO,CAAC,MAAM,CAAC,YAAY;IA6B3B,OAAO,CAAC,MAAM;IAuBR,SAAS,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IAY7C,SAAS,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,CAAC,cAAc,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAYpE,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC;IAIlD,UAAU,CAAC,IAAI,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;IAMhD,UAAU,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,CAAC,eAAe,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAYtE,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC;CAGjE"}

package/dist/file-db.js

@@ -0,0 +1,215 @@
+import { accessSync, appendFileSync, constants as fsConstants, existsSync, mkdirSync, readdirSync, readFileSync, } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+/**
+ * JSONL-backed WorkflowDb for the CLI.
+ *
+ * Design: the **in-memory cache is the single source of truth** for the
+ * process lifetime. Every mutation updates the cache synchronously and
+ * then best-effort appends to the jsonl file for durability / `--resume`.
+ *
+ * This matters because the runtime correctness of a running workflow
+ * must not depend on disk writes succeeding. If the storage path is
+ * unwritable (ACL-restricted workspace, full disk, ENOSPC), the workflow
+ * still progresses through its state machine correctly — we just lose
+ * the ability to resume a future process from that run.
+ *
+ * Read paths used to re-snapshot the jsonl on every call, which meant
+ * a failed `updateRun(..., { status: 'completed' })` would leave a
+ * subsequent `getRun` returning the stale 'running' row from disk.
+ * That bug surfaced as workflows passing per-step but reporting
+ * `status: 'running'` to callers.
+ *
+ * Storage path resolution:
+ *   1. Try the caller-supplied file path. If the parent directory is
+ *      writable, use it.
+ *   2. If (1) fails and `homeFallback` is true (opt-in, default false),
+ *      try `$HOME/.agent-relay/workflow-runs-<basename>.jsonl`. This is
+ *      outside any workspace mount in cloud sandboxes and almost always
+ *      writable by the agent.
+ *   3. If both fail, run in memory-only mode. The workflow still
+ *      executes correctly; `--resume` won't be available for this run.
+ *
+ * File: `.agent-relay/workflow-runs.jsonl` in the workflow cwd by default.
+ */
+export class JsonFileWorkflowDb {
+    filePath;
+    /** Whether persistence is active. False = in-memory-only mode. */
+    writable;
+    appendFailedOnce = false;
+    onWriteFailure;
+    /**
+     * Authoritative in-memory mirror. Every mutation updates this; reads
+     * return from here. The jsonl file is only consulted at construction
+     * (to replay prior state for `--resume`) and is otherwise write-only.
+     */
+    cache;
+    constructor(filePathOrOptions) {
+        const options = typeof filePathOrOptions === 'string' ? { filePath: filePathOrOptions } : filePathOrOptions;
+        this.onWriteFailure = options.onWriteFailure;
+        const requestedPath = options.filePath ?? path.join('.agent-relay', 'workflow-runs.jsonl');
+        const homeFallback = options.homeFallback ?? false;
+        const { resolvedPath, writable } = JsonFileWorkflowDb.resolveStoragePath(requestedPath, homeFallback);
+        this.filePath = resolvedPath;
+        this.writable = writable;
+        // Load existing state from disk (for --resume) once at construction.
+        // From this point on, the cache is authoritative.
+        this.cache = JsonFileWorkflowDb.loadSnapshot(this.filePath);
+    }
+    /** Returns false if persistence is not active (in-memory-only mode). */
+    isWritable() {
+        return this.writable;
+    }
+    /** Resolved path on disk. For tests + diagnostics. */
+    getStoragePath() {
+        return this.filePath;
+    }
+    hasStepOutputs(runId) {
+        try {
+            const dir = path.join(path.dirname(this.filePath), 'step-outputs', runId);
+            return existsSync(dir) && readdirSync(dir).length > 0;
+        }
+        catch {
+            return false;
+        }
+    }
+    // ── Private helpers ─────────────────────────────────────────────────────
+    static resolveStoragePath(requestedPath, homeFallback) {
+        const candidates = [requestedPath];
+        if (homeFallback) {
+            const base = path.basename(requestedPath) || 'workflow-runs.jsonl';
+            candidates.push(path.join(os.homedir(), '.agent-relay', `workflow-runs-${base}`));
+        }
+        for (let i = 0; i < candidates.length; i++) {
+            const candidate = candidates[i];
+            const isLastCandidate = i === candidates.length - 1;
+            try {
+                mkdirSync(path.dirname(candidate), { recursive: true });
+                // If there's a later fallback to try, actively probe writability
+                // so we know whether to move on. Two levels matter:
+                //   1. Directory must be writable to create the jsonl file.
+                //   2. If the jsonl file already exists, IT must also be writable
+                //      — a writable directory does not guarantee a writable file.
+                //      Relayfile-mount, for example, can sync a file and chmod it
+                //      to 0o444 while leaving the parent dir at 0o755; the old
+                //      dir-only check would accept the path and every append would
+                //      then lazy-fail, bypassing the fallback.
+                // If this is already the last candidate, skip the probe and be
+                // optimistic — an unwritable path will surface as a lazy append()
+                // failure handled by the cache + onWriteFailure path. Matches the
+                // pre-cache "warn on first failure" semantic callers expect.
+                if (!isLastCandidate) {
+                    accessSync(path.dirname(candidate), fsConstants.W_OK);
+                    if (existsSync(candidate)) {
+                        accessSync(candidate, fsConstants.W_OK);
+                    }
+                }
+                return { resolvedPath: candidate, writable: true };
+            }
+            catch {
+                // Try the next candidate; if this was the last, fall through
+                // to memory-only.
+            }
+        }
+        // Memory-only mode. Path is reported for diagnostics but nothing
+        // is written to it.
+        return { resolvedPath: requestedPath, writable: false };
+    }
+    static loadSnapshot(filePath) {
+        const runs = new Map();
+        const steps = new Map();
+        let raw = '';
+        try {
+            raw = readFileSync(filePath, 'utf8');
+        }
+        catch {
+            return { runs, steps };
+        }
+        for (const line of raw.split('\n')) {
+            const trimmed = line.trim();
+            if (!trimmed)
+                continue;
+            try {
+                const entry = JSON.parse(trimmed);
+                if (entry.kind === 'run') {
+                    runs.set(entry.row.id, entry.row);
+                }
+                else {
+                    steps.set(entry.row.id, entry.row);
+                }
+            }
+            catch {
+                // Skip malformed lines
+            }
+        }
+        return { runs, steps };
+    }
+    append(entry) {
+        if (!this.writable)
+            return;
+        try {
+            appendFileSync(this.filePath, JSON.stringify(entry) + '\n', 'utf8');
+        }
+        catch (err) {
+            // Notify every failure so callers can aggregate / surface.
+            this.onWriteFailure?.(err, this.filePath);
+            // Warn to console once per process — subsequent failures are noise.
+            if (!this.appendFailedOnce) {
+                this.appendFailedOnce = true;
+                console.warn('[workflow] warning: failed to write run state to ' +
+                    this.filePath +
+                    ' — --resume will not be available for this run. Use --start-from instead. ' +
+                    'Error: ' +
+                    (err instanceof Error ? err.message : String(err)));
+            }
+        }
+    }
+    // ── WorkflowDb interface ─────────────────────────────────────────────────
+    async insertRun(run) {
+        // Shallow-copy so later mutations on the caller's object don't silently
+        // alias into the cache. Matches InMemoryWorkflowDb semantics. The runner
+        // keeps inserted rows in its own stepStates map and occasionally mutates
+        // state.row.status directly before calling updateRun — without this copy
+        // the mutation would land in the cache and bypass updateRun's
+        // updatedAt + append path, causing exactly the observability hazard this
+        // cache is meant to prevent.
+        this.cache.runs.set(run.id, { ...run });
+        this.append({ kind: 'run', row: run });
+    }
+    async updateRun(id, patch) {
+        const existing = this.cache.runs.get(id);
+        if (!existing)
+            return;
+        const updated = {
+            ...existing,
+            ...patch,
+            updatedAt: new Date().toISOString(),
+        };
+        this.cache.runs.set(id, updated);
+        this.append({ kind: 'run', row: updated });
+    }
+    async getRun(id) {
+        return this.cache.runs.get(id) ?? null;
+    }
+    async insertStep(step) {
+        // Shallow-copy to prevent caller-mutation aliasing — see insertRun.
+        this.cache.steps.set(step.id, { ...step });
+        this.append({ kind: 'step', row: step });
+    }
+    async updateStep(id, patch) {
+        const existing = this.cache.steps.get(id);
+        if (!existing)
+            return;
+        const updated = {
+            ...existing,
+            ...patch,
+            updatedAt: new Date().toISOString(),
+        };
+        this.cache.steps.set(id, updated);
+        this.append({ kind: 'step', row: updated });
+    }
+    async getStepsByRunId(runId) {
+        return Array.from(this.cache.steps.values()).filter((s) => s.runId === runId);
+    }
+}
+//# sourceMappingURL=file-db.js.map

package/dist/file-db.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-db.js","sourceRoot":"","sources":["../src/file-db.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,UAAU,EACV,cAAc,EACd,SAAS,IAAI,WAAW,EACxB,UAAU,EACV,SAAS,EACT,WAAW,EACX,YAAY,GACb,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAgC7B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAM,OAAO,kBAAkB;IACZ,QAAQ,CAAS;IAElC,kEAAkE;IACjD,QAAQ,CAAU;IAC3B,gBAAgB,GAAG,KAAK,CAAC;IAChB,cAAc,CAA0B;IAEzD;;;;OAIG;IACc,KAAK,CAGpB;IAEF,YAAY,iBAAqD;QAC/D,MAAM,OAAO,GACX,OAAO,iBAAiB,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,iBAAiB,EAAE,CAAC,CAAC,CAAC,iBAAiB,CAAC;QAC9F,IAAI,CAAC,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC;QAE7C,MAAM,aAAa,GAAG,OAAO,CAAC,QAAQ,IAAI,IAAI,CAAC,IAAI,CAAC,cAAc,EAAE,qBAAqB,CAAC,CAAC;QAC3F,MAAM,YAAY,GAAG,OAAO,CAAC,YAAY,IAAI,KAAK,CAAC;QAEnD,MAAM,EAAE,YAAY,EAAE,QAAQ,EAAE,GAAG,kBAAkB,CAAC,kBAAkB,CAAC,aAAa,EAAE,YAAY,CAAC,CAAC;QACtG,IAAI,CAAC,QAAQ,GAAG,YAAY,CAAC;QAC7B,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QAEzB,qEAAqE;QACrE,kDAAkD;QAClD,IAAI,CAAC,KAAK,GAAG,kBAAkB,CAAC,YAAY,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IAC9D,CAAC;IAED,wEAAwE;IACxE,UAAU;QACR,OAAO,IAAI,CAAC,QAAQ,CAAC;IACvB,CAAC;IAED,sDAAsD;IACtD,cAAc;QACZ,OAAO,IAAI,CAAC,QAAQ,CAAC;IACvB,CAAC;IAED,cAAc,CAAC,KAAa;QAC1B,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,cAAc,EAAE,KAAK,CAAC,CAAC;YAC1E,OAAO,UAAU,CAAC,GAAG,CAAC,IAAI,WAAW,CAAC,GAAG,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC;QACxD,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC;IAED,2EAA2E;IAEnE,MAAM,CAAC,kBAAkB,CAC/B,aAAqB,EACrB,YAAqB;QAErB,MAAM,UAAU,GAAa,CAAC,aAAa,CAAC,CAAC;QAC7C,IAAI,YAAY,EAAE,CAAC;YACjB,MAAM,IAAI,GAAG,IAAI,CAAC,QAAQ,CAAC,aAAa,CAAC,IAAI,qBAAqB,CAAC;YACnE,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,cAAc,EAAE,iBAAiB,IAAI,EAAE,CAAC,CAAC,CAAC;QACpF,CAAC;QAED,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,UAAU,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YAC3C,MAAM,SAAS,GAAG,UAAU,CAAC,CAAC,CAAC,CAAC;YAChC,MAAM,eAAe,GAAG,CAAC,KAAK,UAAU,CAAC,MAAM,GAAG,CAAC,CAAC;YACpD,IAAI,CAAC;gBACH,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;gBACxD,iEAAiE;gBACjE,oDAAoD;gBACpD,4DAA4D;gBAC5D,kEAAkE;gBAClE,kEAAkE;gBAClE,kEAAkE;gBAClE,+DAA+D;gBAC/D,mEAAmE;gBACnE,+CAA+C;gBAC/C,+DAA+D;gBAC/D,kEAAkE;gBAClE,kEAAkE;gBAClE,6DAA6D;gBAC7D,IAAI,CAAC,eAAe,EAAE,CAAC;oBACrB,UAAU,CAAC,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,WAAW,CAAC,IAAI,CAAC,CAAC;oBACtD,IAAI,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;wBAC1B,UAAU,CAAC,SAAS,EAAE,WAAW,CAAC,IAAI,CAAC,CAAC;oBAC1C,CAAC;gBACH,CAAC;gBACD,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;YACrD,CAAC;YAAC,MAAM,CAAC;gBACP,6DAA6D;gBAC7D,kBAAkB;YACpB,CAAC;QACH,CAAC;QAED,iEAAiE;QACjE,oBAAoB;QACpB,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC;IAC1D,CAAC;IAEO,MAAM,CAAC,YAAY,CAAC,QAAgB;QAI1C,MAAM,IAAI,GAAG,IAAI,GAAG,EAA0B,CAAC;QAC/C,MAAM,KAAK,GAAG,IAAI,GAAG,EAA2B,CAAC;QACjD,IAAI,GAAG,GAAG,EAAE,CAAC;QACb,IAAI,CAAC;YACH,GAAG,GAAG,YAAY,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;QACvC,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;QACzB,CAAC;QACD,KAAK,MAAM,IAAI,IAAI,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;YACnC,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;YAC5B,IAAI,CAAC,OAAO;gBAAE,SAAS;YACvB,IAAI,CAAC;gBACH,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAY,CAAC;gBAC7C,IAAI,KAAK,CAAC,IAAI,KAAK,KAAK,EAAE,CAAC;oBACzB,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC;gBACpC,CAAC;qBAAM,CAAC;oBACN,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC;gBACrC,CAAC;YACH,CAAC;YAAC,MAAM,CAAC;gBACP,uBAAuB;YACzB,CAAC;QACH,CAAC;QACD,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;IACzB,CAAC;IAEO,MAAM,CAAC,KAAc;QAC3B,IAAI,CAAC,IAAI,CAAC,QAAQ;YAAE,OAAO;QAC3B,IAAI,CAAC;YACH,cAAc,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,GAAG,IAAI,EAAE,MAAM,CAAC,CAAC;QACtE,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,2DAA2D;YAC3D,IAAI,CAAC,cAAc,EAAE,CAAC,GAAG,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC;YAC1C,oEAAoE;YACpE,IAAI,CAAC,IAAI,CAAC,gBAAgB,EAAE,CAAC;gBAC3B,IAAI,CAAC,gBAAgB,GAAG,IAAI,CAAC;gBAC7B,OAAO,CAAC,IAAI,CACV,mDAAmD;oBACjD,IAAI,CAAC,QAAQ;oBACb,4EAA4E;oBAC5E,SAAS;oBACT,CAAC,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CACrD,CAAC;YACJ,CAAC;QACH,CAAC;IACH,CAAC;IAED,4EAA4E;IAE5E,KAAK,CAAC,SAAS,CAAC,GAAmB;QACjC,wEAAwE;QACxE,yEAAyE;QACzE,yEAAyE;QACzE,yEAAyE;QACzE,8DAA8D;QAC9D,yEAAyE;QACzE,6BAA6B;QAC7B,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,EAAE,EAAE,GAAG,GAAG,EAAE,CAAC,CAAC;QACxC,IAAI,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC,CAAC;IACzC,CAAC;IAED,KAAK,CAAC,SAAS,CAAC,EAAU,EAAE,KAA8B;QACxD,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACzC,IAAI,CAAC,QAAQ;YAAE,OAAO;QACtB,MAAM,OAAO,GAAmB;YAC9B,GAAG,QAAQ;YACX,GAAG,KAAK;YACR,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;SACpC,CAAC;QACF,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,OAAO,CAAC,CAAC;QACjC,IAAI,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,EAAE,OAAO,EAAE,CAAC,CAAC;IAC7C,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,EAAU;QACrB,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,IAAI,CAAC;IACzC,CAAC;IAED,KAAK,CAAC,UAAU,CAAC,IAAqB;QACpC,oEAAoE;QACpE,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,GAAG,IAAI,EAAE,CAAC,CAAC;QAC3C,IAAI,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC,CAAC;IAC3C,CAAC;IAED,KAAK,CAAC,UAAU,CAAC,EAAU,EAAE,KAA+B;QAC1D,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAC1C,IAAI,CAAC,QAAQ;YAAE,OAAO;QACtB,MAAM,OAAO,GAAoB;YAC/B,GAAG,QAAQ;YACX,GAAG,KAAK;YACR,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;SACpC,CAAC;QACF,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,EAAE,OAAO,CAAC,CAAC;QAClC,IAAI,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,EAAE,CAAC,CAAC;IAC9C,CAAC;IAED,KAAK,CAAC,eAAe,CAAC,KAAa;QACjC,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,KAAK,KAAK,CAAC,CAAC;IAChF,CAAC;CACF"}

package/dist/index.d.ts

@@ -1 +1,37 @@
-export {};
+export * from './types.js';
+export * from './runner.js';
+export * from './custom-steps.js';
+export * from './cli-session-collector.js';
+export * from './channel-messenger.js';
+export * from './process-spawner.js';
+export { createProcessBackendExecutor, type ProcessBackendExecutorOptions, } from './process-backend-executor.js';
+export * from './run-summary-table.js';
+export * from './template-resolver.js';
+export * from './verification.js';
+export { StepExecutor, 
+/** @deprecated Use {@link StepExecutor} instead. */
+StepExecutor as WorkflowStepLifecycleExecutor, type StepExecutorDeps, type StepResult, type StepSchedule, } from './step-executor.js';
+export { Models, ClaudeModels, CodexModels, GeminiModels, CursorModels, CLIs, CLIVersions, CLIRegistry, SwarmPatterns, } from '@agent-relay/config';
+export * from './memory-db.js';
+export * from './file-db.js';
+export * from './run.js';
+export * from './cloud-schedules.js';
+export * from './builder.js';
+export * from './coordinator.js';
+export * from './barrier.js';
+export * from './state.js';
+export * from './templates.js';
+export { WorkflowTrajectory, type StepOutcome } from './trajectory.js';
+export { formatDryRunReport } from './dry-run-format.js';
+export { createWorkflowRenderer, type WorkflowRenderer } from './listr-renderer.js';
+export { createDefaultEventLogger } from './default-logger.js';
+export { executeApiStep, type ApiExecutorOptions } from './api-executor.js';
+export type { CloudRunOptions } from './cloud-runner.js';
+export * from './proxy-env.js';
+export * from './budget-tracker.js';
+export * from './provisioner.js';
+export { applySiblingLinks, buildSiblingLinkScript } from './sibling-links.js';
+export type { SiblingLink, SiblingLinkOptions } from './sibling-links.js';
+export { runScriptWorkflow, parseTsxStderr, formatWorkflowParseError, findLocalSdkWorkspace, ensureLocalSdkWorkflowRuntime, } from './run-script.js';
+export type { RunScriptWorkflowOptions, ParsedWorkflowError, LocalSdkWorkspace, ExecFileSyncLike, } from './run-script.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,mBAAmB,CAAC;AAClC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,wBAAwB,CAAC;AACvC,cAAc,sBAAsB,CAAC;AACrC,OAAO,EACL,4BAA4B,EAC5B,KAAK,6BAA6B,GACnC,MAAM,+BAA+B,CAAC;AACvC,cAAc,wBAAwB,CAAC;AACvC,cAAc,wBAAwB,CAAC;AACvC,cAAc,mBAAmB,CAAC;AAClC,OAAO,EACL,YAAY;AACZ,oDAAoD;AACpD,YAAY,IAAI,6BAA6B,EAC7C,KAAK,gBAAgB,EACrB,KAAK,UAAU,EACf,KAAK,YAAY,GAClB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,MAAM,EACN,YAAY,EACZ,WAAW,EACX,YAAY,EACZ,YAAY,EACZ,IAAI,EACJ,WAAW,EACX,WAAW,EACX,aAAa,GACd,MAAM,qBAAqB,CAAC;AAC7B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,cAAc,CAAC;AAC7B,cAAc,UAAU,CAAC;AACzB,cAAc,sBAAsB,CAAC;AACrC,cAAc,cAAc,CAAC;AAC7B,cAAc,kBAAkB,CAAC;AACjC,cAAc,cAAc,CAAC;AAC7B,cAAc,YAAY,CAAC;AAC3B,cAAc,gBAAgB,CAAC;AAC/B,OAAO,EAAE,kBAAkB,EAAE,KAAK,WAAW,EAAE,MAAM,iBAAiB,CAAC;AACvE,OAAO,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,EAAE,sBAAsB,EAAE,KAAK,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AACpF,OAAO,EAAE,wBAAwB,EAAE,MAAM,qBAAqB,CAAC;AAC/D,OAAO,EAAE,cAAc,EAAE,KAAK,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAC5E,YAAY,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACzD,cAAc,gBAAgB,CAAC;AAC/B,cAAc,qBAAqB,CAAC;AACpC,cAAc,kBAAkB,CAAC;AACjC,OAAO,EAAE,iBAAiB,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AAC/E,YAAY,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAC1E,OAAO,EACL,iBAAiB,EACjB,cAAc,EACd,wBAAwB,EACxB,qBAAqB,EACrB,6BAA6B,GAC9B,MAAM,iBAAiB,CAAC;AACzB,YAAY,EACV,wBAAwB,EACxB,mBAAmB,EACnB,iBAAiB,EACjB,gBAAgB,GACjB,MAAM,iBAAiB,CAAC"}

package/dist/index.js

@@ -1,3 +1,34 @@
-// Placeholder for @relayflows/core v0.0.1 — npm namespace reservation.
-// Use 0.1.0+ for the real workflow engine; this version exports nothing.
-export {};
+export * from './types.js';
+export * from './runner.js';
+export * from './custom-steps.js';
+export * from './cli-session-collector.js';
+export * from './channel-messenger.js';
+export * from './process-spawner.js';
+export { createProcessBackendExecutor, } from './process-backend-executor.js';
+export * from './run-summary-table.js';
+export * from './template-resolver.js';
+export * from './verification.js';
+export { StepExecutor, 
+/** @deprecated Use {@link StepExecutor} instead. */
+StepExecutor as WorkflowStepLifecycleExecutor, } from './step-executor.js';
+export { Models, ClaudeModels, CodexModels, GeminiModels, CursorModels, CLIs, CLIVersions, CLIRegistry, SwarmPatterns, } from '@agent-relay/config';
+export * from './memory-db.js';
+export * from './file-db.js';
+export * from './run.js';
+export * from './cloud-schedules.js';
+export * from './builder.js';
+export * from './coordinator.js';
+export * from './barrier.js';
+export * from './state.js';
+export * from './templates.js';
+export { WorkflowTrajectory } from './trajectory.js';
+export { formatDryRunReport } from './dry-run-format.js';
+export { createWorkflowRenderer } from './listr-renderer.js';
+export { createDefaultEventLogger } from './default-logger.js';
+export { executeApiStep } from './api-executor.js';
+export * from './proxy-env.js';
+export * from './budget-tracker.js';
+export * from './provisioner.js';
+export { applySiblingLinks, buildSiblingLinkScript } from './sibling-links.js';
+export { runScriptWorkflow, parseTsxStderr, formatWorkflowParseError, findLocalSdkWorkspace, ensureLocalSdkWorkflowRuntime, } from './run-script.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,mBAAmB,CAAC;AAClC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,wBAAwB,CAAC;AACvC,cAAc,sBAAsB,CAAC;AACrC,OAAO,EACL,4BAA4B,GAE7B,MAAM,+BAA+B,CAAC;AACvC,cAAc,wBAAwB,CAAC;AACvC,cAAc,wBAAwB,CAAC;AACvC,cAAc,mBAAmB,CAAC;AAClC,OAAO,EACL,YAAY;AACZ,oDAAoD;AACpD,YAAY,IAAI,6BAA6B,GAI9C,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,MAAM,EACN,YAAY,EACZ,WAAW,EACX,YAAY,EACZ,YAAY,EACZ,IAAI,EACJ,WAAW,EACX,WAAW,EACX,aAAa,GACd,MAAM,qBAAqB,CAAC;AAC7B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,cAAc,CAAC;AAC7B,cAAc,UAAU,CAAC;AACzB,cAAc,sBAAsB,CAAC;AACrC,cAAc,cAAc,CAAC;AAC7B,cAAc,kBAAkB,CAAC;AACjC,cAAc,cAAc,CAAC;AAC7B,cAAc,YAAY,CAAC;AAC3B,cAAc,gBAAgB,CAAC;AAC/B,OAAO,EAAE,kBAAkB,EAAoB,MAAM,iBAAiB,CAAC;AACvE,OAAO,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,EAAE,sBAAsB,EAAyB,MAAM,qBAAqB,CAAC;AACpF,OAAO,EAAE,wBAAwB,EAAE,MAAM,qBAAqB,CAAC;AAC/D,OAAO,EAAE,cAAc,EAA2B,MAAM,mBAAmB,CAAC;AAE5E,cAAc,gBAAgB,CAAC;AAC/B,cAAc,qBAAqB,CAAC;AACpC,cAAc,kBAAkB,CAAC;AACjC,OAAO,EAAE,iBAAiB,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AAE/E,OAAO,EACL,iBAAiB,EACjB,cAAc,EACd,wBAAwB,EACxB,qBAAqB,EACrB,6BAA6B,GAC9B,MAAM,iBAAiB,CAAC"}

package/dist/integrations/browser.d.ts

@@ -0,0 +1,99 @@
+import type { RunnerStepExecutor, WorkflowStep } from '../types.js';
+import { BrowserClient, type BrowserClientOptions } from '@relayflows/browser-primitive';
+import type { ActionResult, BrowserActionName, BrowserActionParamsMap, BrowserConfig, BrowserSession } from '@relayflows/browser-primitive';
+export type BrowserStepOutputMode = 'last' | 'all' | 'captures' | 'summary' | 'none';
+export type BrowserStepOutputFormat = 'json' | 'text';
+export type BrowserStepAction<TName extends BrowserActionName = BrowserActionName> = {
+    [Name in TName]: {
+        action: Name;
+        params: BrowserActionParamsMap[Name];
+        /** Stable key for captured output. Defaults to the zero-based action index. */
+        id?: string;
+        /** Include this action in output.mode = "captures". Defaults true for extraction actions. */
+        capture?: boolean;
+        /** Output object key when output.mode = "captures". Defaults to id or action_<index>. */
+        outputKey?: string;
+        /** Continue running later actions if this action fails. Defaults false. */
+        continueOnError?: boolean;
+    };
+}[TName];
+export interface BrowserStepOutputConfig {
+    /** Which action results become the workflow step output. Defaults to "last". */
+    mode?: BrowserStepOutputMode;
+    /** Emit JSON for structured chaining or text for simple downstream interpolation. Defaults to "json". */
+    format?: BrowserStepOutputFormat;
+    /** Include per-action metadata such as current URL and timing in JSON output. Defaults false. */
+    includeMetadata?: boolean;
+    /** Include final browser session state in JSON output. Defaults false. */
+    includeSession?: boolean;
+    /** Pretty-print JSON output. Defaults false. */
+    pretty?: boolean;
+}
+export interface BrowserStepConfig {
+    /** Unique step name within the workflow. */
+    name: string;
+    /** Dependencies in the Relay workflow DAG. */
+    dependsOn?: string[];
+    /** Browser settings for this step/session. */
+    config?: BrowserConfig;
+    /** Ordered browser actions to execute in one browser session. */
+    actions: BrowserStepAction[];
+    /** Controls the string captured as {{steps.<name>.output}}. */
+    output?: BrowserStepOutputConfig;
+    /** Reuse a named browser session across browser steps. Defaults to the workspace/config session. */
+    sessionId?: string;
+    /** Close the session after this step, even when persistSession is true. */
+    closeSession?: boolean;
+    /** Workflow step timeout in milliseconds. */
+    timeoutMs?: number;
+    /** Number of retry attempts when the workflow runner retries this integration step. */
+    retries?: number;
+}
+export interface BrowserStepExecutionContext {
+    workspaceId?: string;
+    sessionId?: string;
+    client?: BrowserClient;
+}
+export interface BrowserStepActionRecord<TOutput = unknown> {
+    index: number;
+    id?: string;
+    action: BrowserActionName;
+    success: boolean;
+    output?: TOutput;
+    error?: string;
+    metadata?: ActionResult['metadata'];
+}
+export interface BrowserStepExecutionResult {
+    success: boolean;
+    output: string;
+    results: BrowserStepActionRecord[];
+    session: BrowserSession;
+    error?: string;
+}
+export interface BrowserIntegrationStepResult {
+    output: string;
+    success: boolean;
+}
+/**
+ * Create a Relay integration step that can be used in relay.yaml or passed to
+ * WorkflowRunner directly. Complex action/config objects are serialized into
+ * params so the existing workflow template resolver can interpolate them.
+ */
+export declare function createBrowserStep(config: BrowserStepConfig): WorkflowStep;
+export declare class BrowserStepExecutor implements RunnerStepExecutor {
+    private readonly options;
+    private readonly sessions;
+    constructor(options?: BrowserClientOptions);
+    executeAgentStep(): Promise<string>;
+    execute(config: BrowserStepConfig, context?: BrowserStepExecutionContext): Promise<BrowserStepExecutionResult>;
+    executeIntegrationStep(step: WorkflowStep, resolvedParams: Record<string, string>, context?: {
+        workspaceId?: string;
+    }): Promise<BrowserIntegrationStepResult>;
+    closeSession(sessionId: string): Promise<boolean>;
+    closeAll(): Promise<void>;
+    listSessions(): BrowserSession[];
+    private getOrCreateClient;
+    private resolveSessionKey;
+}
+export declare function browserStepConfigFromWorkflowStep(step: WorkflowStep, resolvedParams: Record<string, string>): BrowserStepConfig;
+//# sourceMappingURL=browser.d.ts.map

package/dist/integrations/browser.d.ts.map

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