ftown-bridge 0.11.2 → 0.12.0

package/dist/loop-schedule.d.ts

@@ -0,0 +1,18 @@
+import type { Loop, LoopSchedule } from './types.js';
+/**
+ * Epoch ms of the next fire strictly after fromMs.
+ *
+ * - interval: fromMs + everyMs, floored at a 1000ms minimum cadence so a
+ *   misconfigured sub-second loop cannot busy-spin the scheduler.
+ * - cron: the next occurrence strictly after `fromMs` in the loop's timezone.
+ *   Throws on a malformed cron expression (callers validate before persisting).
+ */
+export declare function computeNextRun(schedule: LoopSchedule, fromMs: number): number;
+/**
+ * Whether a loop should fire on a tick at `nowMs`.
+ *
+ * A manual run request bypasses both the enabled flag and the schedule (it is a
+ * one-shot override cleared on the next fire). Otherwise the loop must be
+ * enabled, have a computed nextRunAt, and that target must be at or before now.
+ */
+export declare function isDue(loop: Loop, nowMs: number): boolean;

package/dist/loop-schedule.js

@@ -0,0 +1,35 @@
+import cronParser from 'cron-parser';
+/**
+ * Epoch ms of the next fire strictly after fromMs.
+ *
+ * - interval: fromMs + everyMs, floored at a 1000ms minimum cadence so a
+ *   misconfigured sub-second loop cannot busy-spin the scheduler.
+ * - cron: the next occurrence strictly after `fromMs` in the loop's timezone.
+ *   Throws on a malformed cron expression (callers validate before persisting).
+ */
+export function computeNextRun(schedule, fromMs) {
+    if (schedule.kind === 'interval')
+        return fromMs + Math.max(1000, schedule.everyMs);
+    const it = cronParser.parseExpression(schedule.expression, {
+        currentDate: new Date(fromMs),
+        tz: schedule.tz,
+    });
+    return it.next().toDate().getTime();
+}
+/**
+ * Whether a loop should fire on a tick at `nowMs`.
+ *
+ * A manual run request bypasses both the enabled flag and the schedule (it is a
+ * one-shot override cleared on the next fire). Otherwise the loop must be
+ * enabled, have a computed nextRunAt, and that target must be at or before now.
+ */
+export function isDue(loop, nowMs) {
+    if (loop.runNowRequested)
+        return true; // manual fire bypasses enabled + schedule
+    if (!loop.enabled)
+        return false;
+    if (!loop.nextRunAt)
+        return false;
+    return Date.parse(loop.nextRunAt) <= nowMs;
+}
+//# sourceMappingURL=loop-schedule.js.map

package/dist/loop-schedule.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"loop-schedule.js","sourceRoot":"","sources":["../src/loop-schedule.ts"],"names":[],"mappings":"AAAA,OAAO,UAAU,MAAM,aAAa,CAAC;AAIrC;;;;;;;GAOG;AACH,MAAM,UAAU,cAAc,CAAC,QAAsB,EAAE,MAAc;IACnE,IAAI,QAAQ,CAAC,IAAI,KAAK,UAAU;QAAE,OAAO,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,QAAQ,CAAC,OAAO,CAAC,CAAC;IACnF,MAAM,EAAE,GAAG,UAAU,CAAC,eAAe,CAAC,QAAQ,CAAC,UAAU,EAAE;QACzD,WAAW,EAAE,IAAI,IAAI,CAAC,MAAM,CAAC;QAC7B,EAAE,EAAE,QAAQ,CAAC,EAAE;KAChB,CAAC,CAAC;IACH,OAAO,EAAE,CAAC,IAAI,EAAE,CAAC,MAAM,EAAE,CAAC,OAAO,EAAE,CAAC;AACtC,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,KAAK,CAAC,IAAU,EAAE,KAAa;IAC7C,IAAI,IAAI,CAAC,eAAe;QAAE,OAAO,IAAI,CAAC,CAAC,0CAA0C;IACjF,IAAI,CAAC,IAAI,CAAC,OAAO;QAAE,OAAO,KAAK,CAAC;IAChC,IAAI,CAAC,IAAI,CAAC,SAAS;QAAE,OAAO,KAAK,CAAC;IAClC,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,KAAK,CAAC;AAC7C,CAAC"}

package/dist/loop-scheduler.d.ts

@@ -0,0 +1,141 @@
+import { type LoopRuntimeMutator } from './loop-store.js';
+import type { CreateFtownSessionInput } from './create-ftown-session.js';
+import type { RemoveFtownSessionOptions } from './remove-ftown-session.js';
+import type { Loop, Session } from './types.js';
+/** Base tick cadence; also the finalize grace so a just-spawned PTY is not mistaken for exited. */
+export declare const LOOP_TICK_INTERVAL_MS = 30000;
+export interface FlightResult {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+}
+/** Preflight/postflight primitive: promisified child_process.exec (captures exit code + timeout). */
+export type RunFlight = (command: string, cwd: string | undefined, timeoutMs?: number, extraEnv?: Record<string, string>) => Promise<FlightResult>;
+/** In-process flight spawn — wraps createFtownSession(sessionDeps, input) in index.ts. */
+export type SpawnSession = (input: CreateFtownSessionInput) => Promise<Session>;
+/** In-process run removal — wraps removeFtownSession({store,runner,centrifugo,userId}, id, opts) in index.ts. */
+export type RemoveSession = (id: string, options?: RemoveFtownSessionOptions) => Promise<Session | null>;
+export interface SchedulerStore {
+    loadSession(id: string): Promise<Session | null>;
+    loadTerminalLog(id: string): Promise<string>;
+    listSessions(): Promise<Session[]>;
+}
+export interface SchedulerRunner {
+    isRunning(id: string): boolean;
+    stop(id: string): boolean;
+}
+export interface SchedulerCentrifugo {
+    publishLoopUpdate(userId: string, loop: Loop): Promise<void>;
+}
+export interface LoopStoreApi {
+    listLoops(): Loop[];
+    /** Fresh-read → mutate scheduler-owned fields → save; null when deleted concurrently. */
+    mutateLoopRuntime(id: string, fn: LoopRuntimeMutator): Loop | null;
+}
+export interface SchedulerDeps {
+    store: SchedulerStore;
+    runner: SchedulerRunner;
+    centrifugo: SchedulerCentrifugo;
+    userId: string;
+    /** Built in index.ts as (input) => createFtownSession(sessionDeps, input) — the direct in-process call. */
+    spawnSession: SpawnSession;
+    /** Built in index.ts as (id, opts) => removeFtownSession({store,runner,centrifugo,userId}, id, opts). */
+    removeSession: RemoveSession;
+    /** Loop persistence. Defaults to the real ~/.ftown/loops.json store. */
+    loops?: LoopStoreApi;
+    /** Flight runner. Defaults to the exec-based runFlightCommand. */
+    runFlight?: RunFlight;
+    /** Clock seam. Defaults to Date.now. */
+    now?: () => number;
+}
+/**
+ * Runs child_process.exec and normalizes the result to { stdout, stderr,
+ * exitCode }. Never rejects — the exit code is the signal (a timeout maps to
+ * 124, any other failure to the real exit code or 1).
+ *
+ * The hard budget is enforced by SIGKILL on the whole process GROUP, NOT by
+ * exec's built-in `timeout`. exec's timeout only sends SIGTERM to the spawned
+ * `/bin/sh`; a detached grandchild that keeps the stdout pipe open, or a child
+ * that traps SIGTERM, would keep the exec callback from ever firing — and since
+ * the scheduler awaits every flight inside a single re-entrancy-guarded tick,
+ * ONE such flight would wedge the entire scheduler permanently. Spawning
+ * `detached` makes the child its own group leader, so `kill(-pid, SIGKILL)`
+ * takes down the whole tree and the flight can never exceed its budget.
+ */
+export declare function runFlightCommand(command: string, cwd: string | undefined, timeoutMs?: number, extraEnv?: Record<string, string>): Promise<FlightResult>;
+/**
+ * The scheduled-loops engine. On each 30s tick it FINALIZES each loop's
+ * in-flight run(s) (Phase A) before deciding whether to FIRE a new one
+ * (Phase B). All side effects go through injected collaborators so it is
+ * unit-testable without a live bridge, real fs or real timers (mirrors
+ * workflow-runner.ts).
+ *
+ * Persistence rule: the scheduler NEVER writes a whole detached Loop back
+ * across an await. Every runtime-field change goes through
+ * store.mutateLoopRuntime (fresh-read → mutate → save), so a loop deleted or
+ * user-edited during a long flight is neither resurrected nor clobbered.
+ */
+export declare class LoopScheduler {
+    private readonly store;
+    private readonly runner;
+    private readonly centrifugo;
+    private readonly userId;
+    private readonly spawnSession;
+    private readonly removeSession;
+    private readonly loops;
+    private readonly runFlight;
+    private readonly now;
+    /** Re-entrancy guard: tick N+1 never overlaps N. */
+    private tickRunning;
+    /** Set once start() runs (after reconcileOnStart). kick() no-ops before this so an
+     *  early run_loop_now cannot trigger an un-reconciled tick that stampedes overdue loops. */
+    private started;
+    /** Per-loop in-memory fire lock, shared by tick + run_loop_now/kick. */
+    private readonly firingLoops;
+    /** loopId -> (runSessionId -> fire-time ms). Every run THIS process spawned, so under
+     *  overlapPolicy:'allow' each concurrent run is finalized/postflighted/maxRuntime-checked
+     *  independently — not just the newest. Rebuilt lazily from the persisted primary on restart. */
+    private readonly inFlight;
+    private timer;
+    constructor(deps: SchedulerDeps);
+    start(): void;
+    stop(): void;
+    /** Immediate, guarded, out-of-band tick (used by run_loop_now). No-op until start()
+     *  has run, so a kick that races startup cannot fire before reconcileOnStart. */
+    kick(): void;
+    /** Drop scheduler tracking for a deleted loop and stop any run it left alive, so a
+     *  just-deleted loop never leaks a live AI session with nothing left to finalize it. */
+    onLoopDeleted(loop: Loop): void;
+    /**
+     * Missed-schedule policy, run once before the first tick: for every loop whose
+     * nextRunAt is missing or already past, recompute it from now (skip missed
+     * occurrences; never stampede overdue loops). runNowRequested is preserved so a
+     * manual override survives a restart and still fires on the first tick. A loop
+     * with a corrupt persisted schedule is skipped here (logged) and reported as an
+     * error on its first fire.
+     */
+    reconcileOnStart(now?: number): Promise<void>;
+    tick(now?: number): Promise<void>;
+    private processLoop;
+    /** Phase A: finalize each in-flight run once its PTY is confirmed gone (past grace)
+     *  or over its per-run maxRuntime budget. Under 'allow' this walks every tracked run,
+     *  not just the newest, so none is orphaned. */
+    private finalizePhase;
+    /** Seed the persisted primary run into in-memory tracking after a restart (when this
+     *  process has spawned nothing yet for the loop), so a run left 'running' by a prior
+     *  process is still finalized. */
+    private ensureTracked;
+    private track;
+    /** Phase B: fire the loop if due, honoring the per-loop lock and the overlap policy. */
+    private firePhase;
+    /** Advance the schedule up front (so failures/skips never stampede), then preflight → flight. */
+    private fireLoop;
+    /** Resolve one finished run to ok/error, update the loop badge (only if this is the
+     *  loop's tracked/latest run), then run postflight + retention for it. */
+    private finalizeRun;
+    private runPostflight;
+    /** Keep the newest N run-sessions for this loop; prune older finished ones. */
+    private pruneRuns;
+    private persist;
+    private publish;
+}