@relayflows/sdk 2.0.0

package/dist/cli/tick-runner.js

@@ -0,0 +1,258 @@
+/**
+ * `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 { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
+import { JournalClient } from '../journal-client.js';
+import { DEFAULT_MAX_CATCH_UP, TickEmitError, assertTickScheduleValid, emitDueTicks, scheduledForMs, slotFor, } from '../tick-source.js';
+import { sleepInterruptible } from './interruptible-sleep.js';
+/** How often to look for due slots when the caller does not say. */
+const DEFAULT_POLL_INTERVAL_MS = 15_000;
+/** Connect and handshake. Both steps, or neither. */
+async function defaultConnectClient(socketPath) {
+    const client = new JournalClient(socketPath);
+    await client.connect();
+    await client.hello('flows-tick-runner');
+    return client;
+}
+/** Absolute path to the state file for one schedule. */
+export function tickStatePath(dataDir, scheduleId) {
+    return join(dataDir, 'tick-state', `${encodeURIComponent(scheduleId)}.json`);
+}
+/**
+ * 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 async function loadTickState(path, scheduleId) {
+    let raw;
+    try {
+        raw = await readFile(path, 'utf8');
+    }
+    catch (cause) {
+        if (cause.code === 'ENOENT') {
+            return { scheduleId, skippedSlots: [] };
+        }
+        throw cause;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (cause) {
+        throw new Error(`tick state at ${path} is not valid JSON`, { cause });
+    }
+    if (typeof parsed !== 'object' || parsed === null) {
+        throw new Error(`tick state at ${path} is not an object`);
+    }
+    const state = parsed;
+    if (state.scheduleId !== scheduleId) {
+        throw new Error(`tick state at ${path} belongs to schedule ${String(state.scheduleId)}, not ${scheduleId}`);
+    }
+    if (state.lastEmittedSlot !== undefined && !Number.isInteger(state.lastEmittedSlot)) {
+        throw new Error(`tick state at ${path} has a non-integer lastEmittedSlot`);
+    }
+    // Fail closed rather than coerce. `Array.isArray(...) ? ... : []` silently
+    // turned a malformed value into "no slots were skipped" — which is the exact
+    // claim this runner exists to make trustworthy. A state file that cannot say
+    // what it missed must stop the runner, not quietly report that it missed
+    // nothing.
+    if (state.skippedSlots !== undefined && !Array.isArray(state.skippedSlots)) {
+        throw new Error(`tick state at ${path} has a non-array skippedSlots`);
+    }
+    if (state.skippedSlots?.some((slot) => !Number.isInteger(slot))) {
+        throw new Error(`tick state at ${path} has a non-integer entry in skippedSlots`);
+    }
+    return {
+        scheduleId,
+        ...(state.lastEmittedSlot === undefined ? {} : { lastEmittedSlot: state.lastEmittedSlot }),
+        ...(state.lastEmittedAtMs === undefined ? {} : { lastEmittedAtMs: state.lastEmittedAtMs }),
+        skippedSlots: state.skippedSlots ?? [],
+    };
+}
+/**
+ * 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 async function saveTickState(path, state) {
+    await mkdir(dirname(path), { recursive: true });
+    const temp = `${path}.tmp`;
+    await writeFile(temp, `${JSON.stringify(state, null, 2)}\n`, 'utf8');
+    const { rename } = await import('node:fs/promises');
+    await rename(temp, path);
+}
+/**
+ * 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 async function runTickRunner(args, io) {
+    const now = args.now ?? Date.now;
+    const pollIntervalMs = args.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+    // Refuse a bad grid BEFORE connecting. A runner that attaches and only then
+    // discovers `--interval-ms` was 1.5 has already told the operator it started.
+    try {
+        assertTickScheduleValid(args.schedule, now());
+    }
+    catch (cause) {
+        io.stderr(`REFUSED [invalid_schedule] ${cause.message}`);
+        return 1;
+    }
+    if (!Number.isInteger(pollIntervalMs) || pollIntervalMs <= 0) {
+        io.stderr('REFUSED [invalid_schedule] pollIntervalMs must be a positive integer');
+        return 1;
+    }
+    const specPath = isAbsolute(args.specPath) ? args.specPath : resolve(args.specPath);
+    const statePath = args.statePath ?? tickStatePath(args.dataDir, args.schedule.scheduleId);
+    let spec;
+    let state;
+    try {
+        spec = JSON.parse(await readFile(specPath, 'utf8'));
+        state = await loadTickState(statePath, args.schedule.scheduleId);
+    }
+    catch (cause) {
+        io.stderr(`REFUSED [invalid_state] ${cause.message}`);
+        return 1;
+    }
+    const resuming = state.lastEmittedSlot !== undefined;
+    const cursor = resuming ? { lastEmittedSlot: state.lastEmittedSlot } : {};
+    const socketPath = join(args.dataDir, 'relayflowd.sock');
+    let client;
+    try {
+        client = args.connectClient
+            ? await args.connectClient(socketPath)
+            : await defaultConnectClient(socketPath);
+    }
+    catch (cause) {
+        io.stderr(`TICK_RUNNER_FAILED ${cause.constructor.name}: ${cause.message}`);
+        return 1;
+    }
+    let exitCode = 0;
+    try {
+        const startSlot = slotFor(args.schedule, now());
+        io.stdout(resuming
+            ? `TICK_RUNNER schedule=${args.schedule.scheduleId} resuming from slot ${String(state.lastEmittedSlot)}; current slot ${startSlot}`
+            : `TICK_RUNNER schedule=${args.schedule.scheduleId} first run; starting at slot ${startSlot}`);
+        let polls = 0;
+        while (!(args.signal?.aborted ?? false)) {
+            if (args.maxPolls !== undefined && polls >= args.maxPolls)
+                break;
+            polls += 1;
+            const report = await pollOnce(spec, client, args.schedule, cursor, now());
+            // Persist before reporting. The cursor is the thing a restart depends
+            // on; losing it costs slots, whereas losing a log line costs a message.
+            if (report.emittedSlots.length > 0) {
+                state.lastEmittedSlot = cursor.lastEmittedSlot;
+                state.lastEmittedAtMs = now();
+            }
+            if (report.skippedSlots.length > 0) {
+                state.skippedSlots.push(...report.skippedSlots);
+            }
+            if (report.emittedSlots.length > 0 || report.skippedSlots.length > 0) {
+                await saveTickState(statePath, state);
+            }
+            for (const slot of report.skippedSlots) {
+                // Loud, per slot, with the instant it stood for. A count would let a
+                // reader skim past "3 skipped"; an instant is a thing an operator can
+                // go and look for in the journal and fail to find.
+                io.stderr(`TICK_SKIPPED schedule=${args.schedule.scheduleId} slot=${slot} scheduled_for_ms=${scheduledForMs(args.schedule, slot)} — past maxCatchUp=${args.schedule.maxCatchUp ?? DEFAULT_MAX_CATCH_UP}; this scheduled work did NOT run`);
+            }
+            for (const slot of report.emittedSlots) {
+                io.stdout(`TICK_EMITTED schedule=${args.schedule.scheduleId} slot=${slot} scheduled_for_ms=${scheduledForMs(args.schedule, slot)}`);
+            }
+            if (report.failure !== undefined) {
+                const failure = report.failure;
+                const name = failure instanceof Error ? failure.constructor.name : typeof failure;
+                const message = failure instanceof Error ? failure.message : String(failure);
+                io.stderr(`TICK_RUNNER_FAILED ${name}: ${message}`);
+                return 1;
+            }
+            if (args.signal?.aborted ?? false)
+                break;
+            if (args.maxPolls !== undefined && polls >= args.maxPolls)
+                break;
+            await sleepInterruptible(pollIntervalMs, args.signal);
+        }
+        io.stdout(`TICK_RUNNER_STOPPED schedule=${args.schedule.scheduleId} polls=${polls}`);
+    }
+    catch (cause) {
+        const name = cause instanceof Error ? cause.constructor.name : typeof cause;
+        io.stderr(`TICK_RUNNER_FAILED ${name}: ${cause.message}`);
+        exitCode = 1;
+    }
+    finally {
+        client.close();
+    }
+    return exitCode;
+}
+/**
+ * One poll. Normalises the two shapes `emitDueTicks` can produce — a result,
+ * or a `TickEmitError` carrying the partial result — into one report, so the
+ * caller has exactly one accounting path and cannot handle the success case
+ * and forget the failure case.
+ */
+async function pollOnce(spec, sink, schedule, cursor, nowMs) {
+    try {
+        const result = await emitDueTicks(spec, sink, { schedule, cursor, nowMs });
+        return { emittedSlots: result.emittedSlots, skippedSlots: result.skippedSlots };
+    }
+    catch (cause) {
+        if (cause instanceof TickEmitError) {
+            // The partial accounting travelled with the failure. Surface it, then
+            // let the caller treat the failure as fatal — the unemitted slots are
+            // still due, because `emitDueTicks` only advances on success.
+            return {
+                emittedSlots: cause.emittedSlots,
+                skippedSlots: cause.skippedSlots,
+                failure: cause.cause ?? cause,
+            };
+        }
+        return { emittedSlots: [], skippedSlots: [], failure: cause };
+    }
+}
+//# sourceMappingURL=tick-runner.js.map

package/dist/cli/tick-runner.js.map

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

package/dist/cli-adapter.d.ts

@@ -0,0 +1,29 @@
+export type CliAdapterKind = 'claude' | 'codex' | 'relayflows-wrapper-v1';
+export interface CliInvocation {
+    args: string[];
+    timeoutMs: number;
+    /** Set only for wrapper readiness probes; raw providers receive a model flag. */
+    modelEnv?: string;
+}
+export interface CliAdapterIdentification {
+    invocation: CliInvocation;
+    expectedStdout?: string;
+}
+export declare const WRAPPER_IDENTIFY_ARG = "--relayflows-adapter-v1";
+export declare const WRAPPER_IDENTIFY_TOKEN = "relayflows-agent-cli-v1";
+export declare const WRAPPER_EXECUTE_TOKEN = "relayflows-agent-cli-v1-execute";
+/** Select a closed adapter from the resolved executable's basename. */
+export declare function cliAdapterKind(executable: string): CliAdapterKind;
+/** Prove the adapter command shape before classifying an auth failure. */
+export declare function adapterIdentification(kind: CliAdapterKind): CliAdapterIdentification;
+export declare function authenticationProbe(kind: CliAdapterKind): CliInvocation;
+/**
+ * A provider model probe is a real, noninteractive model round trip. The
+ * wrapper protocol keeps its established auth-status shape and receives the
+ * exact model through its explicitly identified environment contract.
+ */
+export declare function modelReadinessProbe(kind: CliAdapterKind, model: string): CliInvocation;
+/** Build the actual worker argv; this is shared contract, not probe-only lore. */
+export declare function agentExecution(kind: CliAdapterKind, instruction: string, model?: string): CliInvocation;
+export declare function displayInvocation(cli: string, invocation: CliInvocation): string;
+//# sourceMappingURL=cli-adapter.d.ts.map

package/dist/cli-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-adapter.d.ts","sourceRoot":"","sources":["../src/cli-adapter.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,OAAO,GAAG,uBAAuB,CAAC;AAE1E,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,iFAAiF;IACjF,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,wBAAwB;IACvC,UAAU,EAAE,aAAa,CAAC;IAC1B,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,eAAO,MAAM,oBAAoB,4BAA4B,CAAC;AAC9D,eAAO,MAAM,sBAAsB,4BAA4B,CAAC;AAChE,eAAO,MAAM,qBAAqB,oCAAoC,CAAC;AAIvE,uEAAuE;AACvE,wBAAgB,cAAc,CAAC,UAAU,EAAE,MAAM,GAAG,cAAc,CAKjE;AAED,0EAA0E;AAC1E,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,cAAc,GAAG,wBAAwB,CAWpF;AAED,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,cAAc,GAAG,aAAa,CAGvE;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,cAAc,EAAE,KAAK,EAAE,MAAM,GAAG,aAAa,CAwBtF;AAED,kFAAkF;AAClF,wBAAgB,cAAc,CAC5B,IAAI,EAAE,cAAc,EACpB,WAAW,EAAE,MAAM,EACnB,KAAK,CAAC,EAAE,MAAM,GACb,aAAa,CAkBf;AAED,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,UAAU,EAAE,aAAa,GAAG,MAAM,CAKhF"}

package/dist/cli-adapter.js

@@ -0,0 +1,92 @@
+import { basename } from 'node:path';
+export const WRAPPER_IDENTIFY_ARG = '--relayflows-adapter-v1';
+export const WRAPPER_IDENTIFY_TOKEN = 'relayflows-agent-cli-v1';
+export const WRAPPER_EXECUTE_TOKEN = 'relayflows-agent-cli-v1-execute';
+const MODEL_PROBE_PROMPT = 'Reply with exactly RELAYFLOWS_MODEL_READY and nothing else.';
+/** Select a closed adapter from the resolved executable's basename. */
+export function cliAdapterKind(executable) {
+    const name = basename(executable).replace(/\.exe$/i, '');
+    if (name === 'claude')
+        return 'claude';
+    if (name === 'codex')
+        return 'codex';
+    return 'relayflows-wrapper-v1';
+}
+/** Prove the adapter command shape before classifying an auth failure. */
+export function adapterIdentification(kind) {
+    if (kind === 'claude') {
+        return { invocation: { args: ['auth', 'status', '--help'], timeoutMs: 10_000 } };
+    }
+    if (kind === 'codex') {
+        return { invocation: { args: ['login', 'status', '--help'], timeoutMs: 10_000 } };
+    }
+    return {
+        invocation: { args: [WRAPPER_IDENTIFY_ARG], timeoutMs: 10_000 },
+        expectedStdout: WRAPPER_IDENTIFY_TOKEN,
+    };
+}
+export function authenticationProbe(kind) {
+    if (kind === 'codex')
+        return { args: ['login', 'status'], timeoutMs: 10_000 };
+    return { args: ['auth', 'status'], timeoutMs: 10_000 };
+}
+/**
+ * A provider model probe is a real, noninteractive model round trip. The
+ * wrapper protocol keeps its established auth-status shape and receives the
+ * exact model through its explicitly identified environment contract.
+ */
+export function modelReadinessProbe(kind, model) {
+    if (kind === 'claude') {
+        return {
+            args: [
+                '-p', '--model', model, '--tools', '', '--no-session-persistence',
+                MODEL_PROBE_PROMPT,
+            ],
+            timeoutMs: 60_000,
+        };
+    }
+    if (kind === 'codex') {
+        return {
+            args: [
+                'exec', '--ephemeral', '--sandbox', 'read-only', '--skip-git-repo-check',
+                '--model', model, MODEL_PROBE_PROMPT,
+            ],
+            timeoutMs: 60_000,
+        };
+    }
+    return {
+        args: ['auth', 'status'],
+        timeoutMs: 60_000,
+        modelEnv: model,
+    };
+}
+/** Build the actual worker argv; this is shared contract, not probe-only lore. */
+export function agentExecution(kind, instruction, model) {
+    if (kind === 'claude') {
+        return {
+            args: ['-p', ...(model === undefined ? [] : ['--model', model]), instruction],
+            timeoutMs: 0,
+        };
+    }
+    if (kind === 'codex') {
+        return {
+            args: [
+                'exec', '--ephemeral', '--skip-git-repo-check',
+                ...(model === undefined ? [] : ['--model', model]),
+                instruction,
+            ],
+            timeoutMs: 0,
+        };
+    }
+    throw new Error('custom wrapper execution requires the runAgentCli same-process session');
+}
+export function displayInvocation(cli, invocation) {
+    const command = [cli, ...invocation.args].map(shellDisplayWord).join(' ');
+    return invocation.modelEnv === undefined
+        ? command
+        : `RELAYFLOW_MODEL=${shellDisplayWord(invocation.modelEnv)} ${command}`;
+}
+function shellDisplayWord(word) {
+    return /^[A-Za-z0-9_./:-]+$/.test(word) ? word : JSON.stringify(word);
+}
+//# sourceMappingURL=cli-adapter.js.map

package/dist/cli-adapter.js.map

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

package/dist/cli-executable.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli-executable.d.ts.map

package/dist/cli-executable.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-executable.d.ts","sourceRoot":"","sources":["../src/cli-executable.ts"],"names":[],"mappings":""}

package/dist/cli-executable.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+import { runCli } from './cli.js';
+async function main() {
+    process.exitCode = await runCli(process.argv.slice(2));
+}
+void main().catch((error) => {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+    process.exitCode = 1;
+});
+//# sourceMappingURL=cli-executable.js.map

package/dist/cli-executable.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-executable.js","sourceRoot":"","sources":["../src/cli-executable.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAElC,KAAK,UAAU,IAAI;IACjB,OAAO,CAAC,QAAQ,GAAG,MAAM,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;AACzD,CAAC;AAED,KAAK,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;IACnC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IACpF,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;AACvB,CAAC,CAAC,CAAC"}

package/dist/cli.d.ts

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+export type { CheckInputDiagnostic, CheckReport } from './cli/check.js';
+export interface CliIo {
+    stdout(line: string): void;
+    stderr(line: string): void;
+}
+type CliExitCode = 0 | 1 | 2 | 3;
+export declare function runCli(args: readonly string[], io?: CliIo): Promise<CliExitCode>;
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAoBA,YAAY,EAAE,oBAAoB,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAExE,MAAM,WAAW,KAAK;IACpB,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B;AAED,KAAK,WAAW,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;AA0BjC,wBAAsB,MAAM,CAC1B,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,EAAE,GAAE,KAAkB,GACrB,OAAO,CAAC,WAAW,CAAC,CAoEtB"}