@relayflows/sdk 2.0.0

package/dist/cli/run.js

@@ -0,0 +1,316 @@
+import { join, resolve } from 'node:path';
+import { toKernelSpec } from '../compile.js';
+import { JournalClient, JournalProtocolError } from '../journal-client.js';
+import { checkFlow, } from './check.js';
+export async function runFlow(path, dataDir, options = {}) {
+    const checked = checkFlow(path);
+    if (!checked.report.ok || checked.flow === undefined) {
+        return { exitCode: 2, report: fromCheckReport('run', checked.report) };
+    }
+    return executeCheckedFlow(checked, dataDir, options);
+}
+async function executeCheckedFlow(checked, dataDir, options) {
+    const socketPath = socketFor(dataDir);
+    const client = new JournalClient(socketPath);
+    const connected = await connect(client, 'run', dataDir, checked.report);
+    if (connected !== undefined)
+        return connected;
+    try {
+        const spec = toKernelSpec(checked.flow);
+        const outcome = await client.runStart(spec);
+        return await classifyOutcome(client, 'run', outcome, checked.report, socketPath, options);
+    }
+    catch (error) {
+        return protocolFailure('run', checked.report, socketPath, error);
+    }
+    finally {
+        client.close();
+    }
+}
+export async function resumeFlow(runId, dataDir, options = {}) {
+    const socketPath = socketFor(dataDir);
+    const base = emptyReport('resume');
+    const client = new JournalClient(socketPath);
+    const connected = await connect(client, 'resume', dataDir, base);
+    if (connected !== undefined)
+        return connected;
+    try {
+        const outcome = await client.runResume(runId);
+        return await classifyOutcome(client, 'resume', outcome, base, socketPath, options);
+    }
+    catch (error) {
+        if (!(error instanceof JournalProtocolError) || error.code !== 'run_not_found') {
+            return protocolFailure('resume', base, socketPath, error, runId);
+        }
+        return {
+            exitCode: 2,
+            report: {
+                ...base,
+                runId,
+                socketPath,
+                diagnostics: [{
+                        severity: 'refusal',
+                        kind: 'run_unavailable',
+                        message: `Run "${runId}" could not be resumed by relayflowd at "${socketPath}": ${errorMessage(error)}`,
+                    }],
+            },
+        };
+    }
+    finally {
+        client.close();
+    }
+}
+export async function connect(client, command, dataDir, base) {
+    const socketPath = socketFor(dataDir);
+    try {
+        await client.connect();
+    }
+    catch {
+        client.close();
+        return {
+            exitCode: 2,
+            report: {
+                ...fromBase(command, base),
+                socketPath,
+                diagnostics: [
+                    ...base.diagnostics,
+                    {
+                        severity: 'refusal',
+                        kind: 'daemon_unreachable',
+                        message: `No compatible relayflowd is listening at "${socketPath}". Start it with: relayflowd --data-dir ${JSON.stringify(dataDir)} serve`,
+                    },
+                ],
+            },
+        };
+    }
+    try {
+        await client.hello(`flows-${command}`);
+        return undefined;
+    }
+    catch (error) {
+        client.close();
+        return protocolFailure(command, base, socketPath, error);
+    }
+}
+/// Exported for tests. The `running`-with-no-identifiable-step branch (#179)
+/// only occurs in a sub-second window against a live daemon, so pinning it
+/// needs a stubbed client rather than a real run -- the integration test that
+/// found it reproduced the bug roughly 1 time in 12.
+export async function classifyOutcome(client, command, outcome, base, socketPath, options) {
+    let current = outcome;
+    let parkedStep;
+    let needsHuman = false;
+    let unclassifiedPolls = 0;
+    while (current.status === 'parked') {
+        const inspection = await inspectOutOfBandStep(client, current.run_id);
+        if (inspection?.parkedStep !== undefined) {
+            parkedStep = inspection.parkedStep;
+            needsHuman = inspection.needsHuman;
+            break;
+        }
+        if (inspection?.runningStep !== undefined) {
+            await waitForRunningStep(client, current.run_id, inspection.runningStep, options);
+            current = await client.runResume(current.run_id);
+            continue;
+        }
+        if (inspection?.status === 'completed' || inspection?.status === 'failed') {
+            current = await client.runResume(current.run_id);
+            continue;
+        }
+        // The run is still RUNNING but no step is identifiable at this instant.
+        //
+        // That is a healthy state, not a protocol error. It happens when a worker
+        // has just completed the step this run parked on and the daemon has not yet
+        // finished driving what follows: nothing is `needs_human`, `runnable` or
+        // `running` for a moment, while the snapshot's own status is `running`.
+        // Breaking here left `status === 'parked'` with no `parkedStep`, so the
+        // tail reported `parked without a classifiable completion` -- a spurious
+        // failure on a run that was about to succeed (#179). Reproduced 1 in 4-15
+        // locally; the probe that caught it printed
+        // `inspection={"status":"running","needsHuman":false}`.
+        //
+        // So poll it, bounded. Resuming immediately would spin, since the daemon
+        // needs a moment to advance.
+        if (inspection?.status === 'running' && unclassifiedPolls < MAX_UNCLASSIFIED_POLLS) {
+            unclassifiedPolls += 1;
+            // `delay(ms, signal)`, not a bare setTimeout: every other wait in this
+            // file is cancel-aware, and an uncancellable one here would keep polling
+            // the daemon for up to 2s after a Ctrl-C or a lifecycle abort.
+            throwIfCanceled(options.signal, current.run_id);
+            await delay(UNCLASSIFIED_POLL_MS, options.signal);
+            // Redundant resumes are safe: `run.resume` is idempotent on a run that
+            // is already progressing -- it returns the current state rather than
+            // re-dispatching. This loop leans on that up to MAX_UNCLASSIFIED_POLLS
+            // times while the daemon is mid-transition.
+            current = await client.runResume(current.run_id);
+            continue;
+        }
+        // Fail closed rather than loop forever: if it never resolves, the original
+        // error below still fires and says so.
+        break;
+    }
+    const report = {
+        ...fromBase(command, base),
+        ok: current.status === 'completed' && current.completion_reason === 'success',
+        runId: current.run_id,
+        socketPath,
+        status: current.status,
+        ...(current.completion_reason !== null ? { completionReason: current.completion_reason } : {}),
+        completedSteps: current.completed_steps,
+    };
+    if (report.ok)
+        return { exitCode: 0, report };
+    if (current.status === 'failed' && current.completion_reason !== null) {
+        return {
+            exitCode: 1,
+            report: {
+                ...report,
+                diagnostics: [...report.diagnostics, {
+                        severity: 'failure',
+                        kind: current.completion_reason,
+                        message: `Run "${current.run_id}" failed with completionReason: ${current.completion_reason}.`,
+                    }],
+            },
+        };
+    }
+    if (current.status === 'parked' && parkedStep !== undefined) {
+        return {
+            exitCode: 3,
+            report: {
+                ...report,
+                parkedStep,
+                diagnostics: [...report.diagnostics, {
+                        severity: 'parked',
+                        kind: 'run_parked',
+                        message: needsHuman
+                            ? `Run "${current.run_id}" parked at step "${parkedStep.id}" (${parkedStep.type}): waiting for human recovery after the worker attempt failed.`
+                            : `Run "${current.run_id}" parked at step "${parkedStep.id}" (${parkedStep.type}): no worker is attached for step type "${parkedStep.type}".`,
+                    }],
+            },
+        };
+    }
+    return protocolFailure(command, base, socketPath, new Error(`relayflowd returned status ${current.status} without a classifiable completion`), current.run_id);
+}
+// Bound on re-polling a run that reports `running` with no identifiable step.
+// 40 x 50ms = 2s, far longer than the sub-second window observed in #179, and
+// short enough that a genuinely stuck run still reports rather than hangs.
+const MAX_UNCLASSIFIED_POLLS = 40;
+const UNCLASSIFIED_POLL_MS = 50;
+async function inspectOutOfBandStep(client, runId) {
+    const snapshot = await client.runGet(runId);
+    const entries = Object.entries(snapshot.steps);
+    const humanEntry = entries.find(([, step]) => step.type !== 'deterministic' && step.state === 'needs_human');
+    const runnableEntry = entries.find(([, step]) => step.type !== 'deterministic' && step.state === 'runnable');
+    const runningEntry = entries.find(([, step]) => step.type !== 'deterministic' && step.state === 'running');
+    const parkedEntry = humanEntry ?? runnableEntry;
+    const parkedStep = parkedEntry === undefined ? undefined : {
+        id: parkedEntry[0],
+        type: parkedEntry[1].type,
+    };
+    const runningStep = runningEntry === undefined ? undefined : {
+        id: runningEntry[0],
+        type: runningEntry[1].type,
+        leaseDeadlineMs: runningEntry[1].lease_deadline_ms ?? Number.NaN,
+    };
+    return {
+        status: snapshot.status,
+        needsHuman: humanEntry !== undefined,
+        ...(parkedStep !== undefined ? { parkedStep } : {}),
+        ...(runningStep !== undefined ? { runningStep } : {}),
+    };
+}
+async function waitForRunningStep(client, runId, runningStep, options) {
+    let leaseDeadlineMs = runningStep.leaseDeadlineMs;
+    if (!Number.isFinite(leaseDeadlineMs)) {
+        throw new Error(`running step "${runningStep.id}" omitted lease_deadline_ms`);
+    }
+    options.onWait?.({
+        runId,
+        stepId: runningStep.id,
+        stepType: runningStep.type,
+        leaseDeadlineMs,
+    });
+    while (true) {
+        throwIfCanceled(options.signal, runningStep.id);
+        const remainingMs = leaseDeadlineMs - Date.now();
+        if (remainingMs <= 0) {
+            throw new Error(`worker lease for step "${runningStep.id}" expired at ${leaseDeadlineMs} without completion`);
+        }
+        await delay(Math.min(50, remainingMs), options.signal);
+        const snapshot = await client.runGet(runId);
+        const step = snapshot.steps[runningStep.id];
+        if (step?.state !== 'running')
+            return;
+        if (step.lease_deadline_ms !== undefined && step.lease_deadline_ms !== leaseDeadlineMs) {
+            leaseDeadlineMs = step.lease_deadline_ms;
+            options.onWait?.({
+                runId,
+                stepId: runningStep.id,
+                stepType: runningStep.type,
+                leaseDeadlineMs,
+            });
+        }
+    }
+}
+export function protocolFailure(command, base, socketPath, error, runId) {
+    return {
+        exitCode: 1,
+        report: {
+            ...fromBase(command, base),
+            ...(runId !== undefined ? { runId } : {}),
+            socketPath,
+            diagnostics: [...base.diagnostics, {
+                    severity: 'failure',
+                    kind: 'protocol_error',
+                    message: `relayflowd could not complete the ${command} request: ${errorMessage(error)}`,
+                }],
+        },
+    };
+}
+export function fromCheckReport(command, report) {
+    return {
+        ok: false,
+        command,
+        ...(report.path !== undefined ? { path: report.path } : {}),
+        ...(report.projectConfigPath !== undefined ? { projectConfigPath: report.projectConfigPath } : {}),
+        resolutions: report.resolutions,
+        diagnostics: report.diagnostics,
+    };
+}
+export function emptyReport(command) {
+    return { ok: false, command, resolutions: [], diagnostics: [] };
+}
+function fromBase(command, base) {
+    return 'command' in base ? base : fromCheckReport(command, base);
+}
+export function socketFor(dataDir) {
+    return join(resolve(dataDir), 'relayflowd.sock');
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : 'unknown protocol error';
+}
+function throwIfCanceled(signal, stepId) {
+    if (signal?.aborted === true)
+        throw new Error(`waiting for running step "${stepId}" was canceled`);
+}
+function delay(ms, signal) {
+    return new Promise((resolveDelay, rejectDelay) => {
+        const finish = () => {
+            signal?.removeEventListener('abort', cancel);
+            resolveDelay();
+        };
+        const timer = setTimeout(finish, ms);
+        if (signal === undefined)
+            return;
+        const cancel = () => {
+            clearTimeout(timer);
+            signal.removeEventListener('abort', cancel);
+            rejectDelay(new Error('worker wait canceled'));
+        };
+        if (signal.aborted)
+            cancel();
+        else
+            signal.addEventListener('abort', cancel, { once: true });
+    });
+}
+//# sourceMappingURL=run.js.map

package/dist/cli/run.js.map

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

package/dist/cli/tick-runner.d.ts

@@ -0,0 +1,151 @@
+/**
+ * `flows tick start` — drive a scheduled relayflow.
+ *
+ * A sibling of `hn-monitor.ts`, not a new species: a public function that
+ * composes the primitives directly — connect journal → hello → loop
+ * `emitDueTicks` → drain on abort → close. The differences from hn-monitor are
+ * only the ones the grid forces.
+ *
+ * ## Why the cursor is persisted, and why that is the whole point
+ *
+ * `emitDueTicks` starts a FRESH cursor at the current slot:
+ *
+ *     const firstDue = cursor.lastEmittedSlot === undefined
+ *       ? currentSlot
+ *       : cursor.lastEmittedSlot + 1;
+ *
+ * That is right for a schedule's first ever poll — a new hourly schedule must
+ * not backfill from the epoch. But it means an in-memory-only cursor makes a
+ * restart SKIP every slot between shutdown and restart, silently. The dedupe
+ * key `(schedule_id, scheduled_for_ms)` makes re-delivery of a slot harmless,
+ * so a lost cursor cannot double-fire; nothing in the primitive protects
+ * against the skip. The runner is where that is either handled or lost, so it
+ * persists the cursor and reloads it on start.
+ *
+ * The distinction the file keeps: "no cursor on disk" means first run, start
+ * at the current slot. "A cursor on disk behind the grid" means catch up, and
+ * report anything past `maxCatchUp` as skipped. Conflating the two either
+ * backfills a new schedule from 1970 or silently drops a restart's arrears.
+ *
+ * ## Why a skip must reach the operator
+ *
+ * `skippedSlots` and `TickEmitError` exist because a skip that is only a
+ * return value is a skip that a `throw` can discard. `emitDueTicks` guarantees
+ * the accounting survives its own failure; this runner is the consumer that
+ * makes it visible. A skipped slot is real scheduled work that did not run.
+ */
+import { type TickSchedule } from '../tick-source.js';
+import type { EventSubmitResult, HelloResult } from '../protocol.js';
+import type { CliIo } from '../cli.js';
+/**
+ * Minimum client surface the runner uses. Concrete protocol return types
+ * rather than `unknown`, so a rename in the journal protocol fails to compile
+ * here instead of drifting silently past the interface — the same reason
+ * `HnMonitorClient` is shaped this way.
+ */
+export interface TickRunnerClient {
+    hello(client: string): Promise<HelloResult>;
+    eventSubmit(spec: unknown, event: {
+        type: string;
+        payload?: unknown;
+        key?: string;
+    }): Promise<EventSubmitResult>;
+    close(): void;
+}
+/** Where the runner's durable cursor lives, and what it holds. */
+export interface TickRunnerState {
+    scheduleId: string;
+    /** Mirror of `TickCursor.lastEmittedSlot`. Absent before the first emit. */
+    lastEmittedSlot?: number;
+    /**
+     * Wall clock of the last successful submit. Not used for scheduling — the
+     * grid owns that — but it is what makes a dead runner detectable, so
+     * `staleAfterMs` means something end to end rather than only inside the
+     * kernel's own sweep.
+     */
+    lastEmittedAtMs?: number;
+    /** Every slot ever passed over, oldest first. Append-only. */
+    skippedSlots: number[];
+}
+interface TickRunnerArgsBase {
+    /** Data directory containing `relayflowd.sock`. Required. */
+    dataDir: string;
+    /** Absolute path to the canonical flow spec JSON. Required. */
+    specPath: string;
+    /** The grid. Validated at declaration, before anything connects. */
+    schedule: TickSchedule;
+    /** How often to look for due slots. Default 15000ms. */
+    pollIntervalMs?: number;
+    /**
+     * Where to persist the cursor. Defaults to
+     * `<dataDir>/tick-state/<scheduleId>.json`.
+     */
+    statePath?: string;
+    /**
+     * Cap on poll iterations. Undefined = unbounded (production). 0 means
+     * "connect, poll zero times, drain, exit 0" — used by tests that only need
+     * the setup and teardown paths.
+     */
+    maxPolls?: number;
+    /** AbortSignal for external cancellation (tests, SIGINT wiring). */
+    signal?: AbortSignal;
+    /** Injectable clock so tests can place `now` on the grid deliberately. */
+    now?: () => number;
+}
+/**
+ * Test injection surface. `connectClient` is supplied alone here — unlike
+ * hn-monitor, this runner attaches no worker, so there is no pairing to
+ * enforce: a tick is submitted through `event.submit` and the kernel dispatches
+ * to whatever worker the flow's trigger names.
+ */
+export interface TickRunnerArgs extends TickRunnerArgsBase {
+    /**
+     * Async, because a real `JournalClient` needs `connect()` before `hello()`.
+     * A synchronous injection surface hid that: the unit tests' fake client has
+     * no transport, so it connected vacuously and the missing `connect()` only
+     * surfaced against a live daemon with `journal client: not connected
+     * (hello)`. The default path below owns connect+hello so no caller can
+     * forget half of it.
+     */
+    connectClient?: (socketPath: string) => Promise<TickRunnerClient>;
+}
+/** Absolute path to the state file for one schedule. */
+export declare function tickStatePath(dataDir: string, scheduleId: string): string;
+/**
+ * Load the durable cursor, distinguishing "no state" from "state behind the
+ * grid". A missing file is a first run and must start at the current slot; a
+ * present file must be honoured however far behind it is, so the arrears are
+ * either caught up or reported.
+ *
+ * A malformed or foreign-schedule state file is a hard error rather than a
+ * silent reset: resetting would convert an operator's corrupted file into a
+ * silent skip of everything since the last good emit, which is the failure
+ * this runner exists to prevent.
+ */
+export declare function loadTickState(path: string, scheduleId: string): Promise<TickRunnerState>;
+/**
+ * Persist the cursor. Written to a temp file and renamed, so a crash mid-write
+ * leaves the previous good state rather than a truncated file — a truncated
+ * file would be a hard error on next start, which is safe but needlessly
+ * blocks a runner that had a perfectly good cursor a moment earlier.
+ */
+export declare function saveTickState(path: string, state: TickRunnerState): Promise<void>;
+/** One poll's accounting, for logging and for tests to assert on. */
+export interface TickPollReport {
+    emittedSlots: number[];
+    skippedSlots: number[];
+    /** Set when the poll threw. The partial accounting is still present. */
+    failure?: unknown;
+}
+/**
+ * Run `flows tick start`. Returns 0 on clean shutdown, 1 on a fatal error.
+ *
+ * Fatal means: the schedule is invalid, the state file is unreadable or
+ * belongs to another schedule, the journal cannot be reached, or a submit
+ * failed. A submit failure is fatal by design — `emitDueTicks` leaves the slot
+ * due, so retrying is the next poll's job, but a runner that swallows journal
+ * failures and keeps looping is the silent-zero this is meant to prevent.
+ */
+export declare function runTickRunner(args: TickRunnerArgs, io: CliIo): Promise<number>;
+export {};
+//# sourceMappingURL=tick-runner.d.ts.map

package/dist/cli/tick-runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tick-runner.d.ts","sourceRoot":"","sources":["../../src/cli/tick-runner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAKH,OAAO,EASL,KAAK,YAAY,EAClB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AACrE,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,WAAW,CAAC;AAMvC;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC/B,KAAK,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IAC5C,WAAW,CACT,IAAI,EAAE,OAAO,EACb,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,OAAO,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,GACvD,OAAO,CAAC,iBAAiB,CAAC,CAAC;IAC9B,KAAK,IAAI,IAAI,CAAC;CACf;AAED,kEAAkE;AAClE,MAAM,WAAW,eAAe;IAC9B,UAAU,EAAE,MAAM,CAAC;IACnB,4EAA4E;IAC5E,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;;;OAKG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,8DAA8D;IAC9D,YAAY,EAAE,MAAM,EAAE,CAAC;CACxB;AAED,UAAU,kBAAkB;IAC1B,6DAA6D;IAC7D,OAAO,EAAE,MAAM,CAAC;IAChB,+DAA+D;IAC/D,QAAQ,EAAE,MAAM,CAAC;IACjB,oEAAoE;IACpE,QAAQ,EAAE,YAAY,CAAC;IACvB,wDAAwD;IACxD,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,oEAAoE;IACpE,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,0EAA0E;IAC1E,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAED;;;;;GAKG;AACH,MAAM,WAAW,cAAe,SAAQ,kBAAkB;IACxD;;;;;;;OAOG;IACH,aAAa,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,OAAO,CAAC,gBAAgB,CAAC,CAAC;CACnE;AAUD,wDAAwD;AACxD,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAEzE;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,aAAa,CACjC,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,eAAe,CAAC,CA6C1B;AAED;;;;;GAKG;AACH,wBAAsB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAMvF;AAED,qEAAqE;AACrE,MAAM,WAAW,cAAc;IAC7B,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,wEAAwE;IACxE,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;;;;;;;GAQG;AACH,wBAAsB,aAAa,CAAC,IAAI,EAAE,cAAc,EAAE,EAAE,EAAE,KAAK,GAAG,OAAO,CAAC,MAAM,CAAC,CA4GpF"}