@nodetool-ai/websocket 0.7.0-rc.22 → 0.8.1

package/dist/triggers/boot.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Boot wiring for the trigger subsystem.
+ *
+ * Everything the other trigger modules build is inert until this runs: the
+ * database-backed stores, the `TriggerWakeupService` every ingestion adapter
+ * appends through, the dispatcher that turns stored inputs into runs, and the
+ * scheduler and file-watch adapters. Extracted from `server.ts` so it can be
+ * started, stopped, and tested without booting the whole HTTP server — and so
+ * embedded hosts (CLI harnesses, tests) can leave it out entirely.
+ *
+ * The wakeup service is installed as the process-wide singleton
+ * (`setTriggerWakeupService`) so the manual-fire API and the webhook route
+ * reach the same DB-backed instance rather than a lazily created memory
+ * default. This is what makes `trigger_inputs` rows — and therefore
+ * restart-safe dedupe and the boot backlog — real.
+ *
+ * The webhook route is a Fastify plugin and must be registered before
+ * `app.listen`, i.e. before this module's services exist. It therefore reaches
+ * the service and dispatcher through the module accessors instead of captured
+ * references (`createTriggerWebhookRoute`).
+ */
+import { TriggerWakeupService } from "@nodetool-ai/kernel";
+import type { NodeRegistry } from "@nodetool-ai/node-sdk";
+import type { FastifyPluginAsync } from "fastify";
+import { type StartTriggerJob } from "./dispatcher.js";
+/**
+ * Whether the host should run trigger ingestion. Set
+ * `NODETOOL_DISABLE_TRIGGERS=1` to opt a process out — a second server sharing
+ * one database, or an embedded/CLI server that must not start background work.
+ */
+export declare function triggersEnabled(): boolean;
+interface StartTriggerServicesOptions {
+    /** Overrides the `NODETOOL_DISABLE_TRIGGERS` env check. */
+    enabled?: boolean;
+    /** Run the schedule adapter. Defaults to true. */
+    scheduler?: boolean;
+    /** Run the file-watch adapter. Defaults to true. */
+    fileWatch?: boolean;
+    /** Node registry handed to the job starter. */
+    registry?: NodeRegistry;
+    /** Job starter; defaults to the dispatcher's `startHeadlessJob`. */
+    startJob?: StartTriggerJob;
+    dispatcherIntervalMs?: number;
+    schedulerIntervalMs?: number;
+    fileWatchIntervalMs?: number;
+}
+interface TriggerServicesHandle {
+    /** False when the subsystem was opted out; every member is then inert. */
+    readonly enabled: boolean;
+    /** The wired DB-backed service, or `null` when disabled. */
+    readonly wakeupService: TriggerWakeupService | null;
+    /** Hint the dispatcher that new inputs exist. */
+    notify(): void;
+    /** Await the dispatcher's current pass (tests, graceful shutdown). */
+    drain(): Promise<void>;
+    /** Stop the dispatcher timer, both adapters, and clear the singleton. */
+    stop(): Promise<void>;
+}
+/**
+ * The webhook ingestion plugin, bound to whatever service and dispatcher are
+ * installed when a request arrives. Register it with the server's other routes;
+ * `POST /api/webhooks/:token` is on the public-route allowlist and
+ * authenticates per registration secret.
+ */
+export declare function createTriggerWebhookRoute(): FastifyPluginAsync;
+/**
+ * Start the trigger subsystem. Safe to call on a host without a usable
+ * database: construction failures are logged and yield an inert handle rather
+ * than taking the server down with them.
+ */
+export declare function startTriggerServices(options?: StartTriggerServicesOptions): TriggerServicesHandle;
+export {};
+//# sourceMappingURL=boot.d.ts.map

package/dist/triggers/boot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"boot.d.ts","sourceRoot":"","sources":["../../src/triggers/boot.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAGH,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAC1D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAClD,OAAO,EAML,KAAK,eAAe,EACrB,MAAM,iBAAiB,CAAC;AAYzB;;;;GAIG;AACH,wBAAgB,eAAe,IAAI,OAAO,CAIzC;AAED,UAAU,2BAA2B;IACnC,2DAA2D;IAC3D,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,kDAAkD;IAClD,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,oDAAoD;IACpD,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,+CAA+C;IAC/C,QAAQ,CAAC,EAAE,YAAY,CAAC;IACxB,oEAAoE;IACpE,QAAQ,CAAC,EAAE,eAAe,CAAC;IAC3B,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED,UAAU,qBAAqB;IAC7B,0EAA0E;IAC1E,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,4DAA4D;IAC5D,QAAQ,CAAC,aAAa,EAAE,oBAAoB,GAAG,IAAI,CAAC;IACpD,iDAAiD;IACjD,MAAM,IAAI,IAAI,CAAC;IACf,sEAAsE;IACtE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,yEAAyE;IACzE,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACvB;AAUD;;;;;GAKG;AACH,wBAAgB,yBAAyB,IAAI,kBAAkB,CAU9D;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,GAAE,2BAAgC,GACxC,qBAAqB,CA2FvB"}

package/dist/triggers/boot.js

@@ -0,0 +1,149 @@
+/**
+ * Boot wiring for the trigger subsystem.
+ *
+ * Everything the other trigger modules build is inert until this runs: the
+ * database-backed stores, the `TriggerWakeupService` every ingestion adapter
+ * appends through, the dispatcher that turns stored inputs into runs, and the
+ * scheduler and file-watch adapters. Extracted from `server.ts` so it can be
+ * started, stopped, and tested without booting the whole HTTP server — and so
+ * embedded hosts (CLI harnesses, tests) can leave it out entirely.
+ *
+ * The wakeup service is installed as the process-wide singleton
+ * (`setTriggerWakeupService`) so the manual-fire API and the webhook route
+ * reach the same DB-backed instance rather than a lazily created memory
+ * default. This is what makes `trigger_inputs` rows — and therefore
+ * restart-safe dedupe and the boot backlog — real.
+ *
+ * The webhook route is a Fastify plugin and must be registered before
+ * `app.listen`, i.e. before this module's services exist. It therefore reaches
+ * the service and dispatcher through the module accessors instead of captured
+ * references (`createTriggerWebhookRoute`).
+ */
+import { createLogger } from "@nodetool-ai/config";
+import { TriggerWakeupService } from "@nodetool-ai/kernel";
+import { getActiveDispatcher, getTriggerWakeupService, setTriggerWakeupService, startDispatcher } from "./dispatcher.js";
+import { startFileWatch } from "./file-watch.js";
+import { startScheduler } from "./scheduler.js";
+import { DrizzleDurableInboxStore, DrizzleTriggerInputStore } from "./stores.js";
+import { createWebhookRoute } from "./webhook-route.js";
+// Stryker disable next-line StringLiteral: logger name is a diagnostic label, not a behavioural contract
+const log = createLogger("nodetool.websocket.triggers.boot");
+/**
+ * Whether the host should run trigger ingestion. Set
+ * `NODETOOL_DISABLE_TRIGGERS=1` to opt a process out — a second server sharing
+ * one database, or an embedded/CLI server that must not start background work.
+ */
+export function triggersEnabled() {
+    const raw = process.env["NODETOOL_DISABLE_TRIGGERS"];
+    if (!raw)
+        return true;
+    return !["1", "true", "yes", "on"].includes(raw.toLowerCase());
+}
+const DISABLED = {
+    enabled: false,
+    wakeupService: null,
+    notify: () => undefined,
+    drain: () => Promise.resolve(),
+    stop: () => Promise.resolve()
+};
+/**
+ * The webhook ingestion plugin, bound to whatever service and dispatcher are
+ * installed when a request arrives. Register it with the server's other routes;
+ * `POST /api/webhooks/:token` is on the public-route allowlist and
+ * authenticates per registration secret.
+ */
+export function createTriggerWebhookRoute() {
+    return createWebhookRoute({
+        wakeupService: {
+            deliverTriggerInput: (opts) => getTriggerWakeupService().deliverTriggerInput(opts)
+        },
+        notify: () => {
+            getActiveDispatcher()?.notify();
+        }
+    });
+}
+/**
+ * Start the trigger subsystem. Safe to call on a host without a usable
+ * database: construction failures are logged and yield an inert handle rather
+ * than taking the server down with them.
+ */
+export function startTriggerServices(options = {}) {
+    const enabled = options.enabled ?? triggersEnabled();
+    if (!enabled) {
+        log.info("Trigger ingestion disabled — no dispatcher or adapters started");
+        return DISABLED;
+    }
+    const inputStore = new DrizzleTriggerInputStore();
+    const wakeupService = new TriggerWakeupService(new DrizzleDurableInboxStore(), inputStore);
+    setTriggerWakeupService(wakeupService);
+    let dispatcher = null;
+    let scheduler = null;
+    let fileWatch = null;
+    try {
+        // Starting the dispatcher also runs one immediate pass, which is the
+        // boot-backlog drain: any input a previous process life stored but never
+        // dispatched goes out now.
+        const dispatcherOptions = {
+            store: inputStore
+        };
+        if (options.startJob) {
+            dispatcherOptions.startJob = options.startJob;
+        }
+        if (options.registry) {
+            dispatcherOptions.registry = options.registry;
+        }
+        if (options.dispatcherIntervalMs !== undefined) {
+            dispatcherOptions.intervalMs = options.dispatcherIntervalMs;
+        }
+        dispatcher = startDispatcher(dispatcherOptions);
+        const notify = dispatcher.notify;
+        if (options.scheduler !== false) {
+            const schedulerOptions = {
+                wakeupService,
+                notify
+            };
+            if (options.schedulerIntervalMs !== undefined) {
+                schedulerOptions.intervalMs = options.schedulerIntervalMs;
+            }
+            scheduler = startScheduler(schedulerOptions);
+        }
+        if (options.fileWatch !== false) {
+            const fileWatchOptions = {
+                wakeupService,
+                notify
+            };
+            if (options.fileWatchIntervalMs !== undefined) {
+                fileWatchOptions.intervalMs = options.fileWatchIntervalMs;
+            }
+            fileWatch = startFileWatch(fileWatchOptions);
+        }
+    }
+    catch (err) {
+        log.warn("Trigger services failed to start — triggers are inactive for this process", err instanceof Error ? err : new Error(String(err)));
+    }
+    log.info("Trigger services started", {
+        scheduler: scheduler !== null,
+        fileWatch: fileWatch !== null
+    });
+    let stopped = false;
+    return {
+        enabled: true,
+        wakeupService,
+        notify: () => dispatcher?.notify(),
+        drain: () => dispatcher?.drain() ?? Promise.resolve(),
+        stop: async () => {
+            if (stopped)
+                return;
+            stopped = true;
+            scheduler?.();
+            dispatcher?.();
+            // The file-watch teardown persists each registration's catch-up cursor,
+            // so it is awaited rather than fired and forgotten.
+            await fileWatch?.();
+            if (getTriggerWakeupService() === wakeupService) {
+                setTriggerWakeupService(null);
+            }
+        }
+    };
+}
+//# sourceMappingURL=boot.js.map

package/dist/triggers/boot.js.map

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

package/dist/triggers/dispatcher.d.ts

@@ -0,0 +1,234 @@
+/**
+ * Trigger dispatcher — turns durable `trigger_inputs` into runs.
+ *
+ * Ingestion adapters (webhook route, scheduler, file watcher) only *store*
+ * events. This is the single consumer: for every enabled `trigger_registrations`
+ * row it drains the unprocessed inputs addressed to that registration's
+ * (workflow, node) and starts one headless run per input, handing the payload
+ * to the trigger node as the run's `trigger_event`.
+ *
+ * Two paths feed it, following the `startReaper` shape
+ * (`@nodetool-ai/compute`): a coarse poll timer, and an in-process `notify()`
+ * that adapters call right after appending. `notify()` is what makes a
+ * same-process event dispatch immediately; the poll is only the
+ * crash-recovery path (a server that died mid-dispatch, or an input written by
+ * another process).
+ *
+ * ## Delivered vs. failed
+ *
+ * `startJob` **rejecting** means the run was never accepted (workflow missing,
+ * DB/infra hiccup): the input stays unprocessed so the next tick redelivers it,
+ * and the reason lands in `registration.last_error`.
+ *
+ * `startJob` **resolving with `status: "failed"`** is a different thing — the
+ * run was accepted and executed, and the *graph* failed. That is a delivered
+ * event: the input is marked processed (retrying a deterministic graph failure
+ * would loop forever) and the run error is still written to
+ * `registration.last_error` so the UI shows the last outcome.
+ *
+ * ## Acceptance vs. completion
+ *
+ * `startJob` resolves on *terminal* status — it does not come back until the
+ * workflow has finished. A pass that awaited that would hold every other
+ * registration behind the slowest run in flight: a webhook arriving one second
+ * into a ten-minute triggered run waited ten minutes for its own dispatch.
+ *
+ * So a pass awaits **acceptance**, not completion. `startHeadlessJob` reports
+ * acceptance through `onAccepted` the moment the workflow resolves and the
+ * `Job` row exists; the run itself settles later, on its own. `drain()` is what
+ * awaits the runs, for shutdown and for tests.
+ *
+ * A `startJob` that never calls `onAccepted` (the test fakes, any other job
+ * starter) still works: acceptance then resolves when the job promise does,
+ * which is exactly the old behaviour.
+ *
+ * ## Idempotency and the crash window
+ *
+ * An input is marked processed **when the run is accepted**, never before. In
+ * process, `inflight` (keyed by `inputId`) makes overlapping passes and
+ * concurrent `dispatchInput` calls join the same dispatch instead of starting a
+ * second run.
+ *
+ * The uncovered window is a crash *between* run acceptance and
+ * `markProcessed`: the input is still unprocessed on restart, so it is
+ * redelivered and the run happens twice. This is deliberate — at-least-once
+ * delivery. Dropping an event is worse than repeating one, and marking first
+ * would turn any crash before acceptance into a silently lost event.
+ *
+ * A run that was never accepted (`startJob` rejected) leaves `last_fired_at`
+ * alone: nothing fired, and stamping it made the editor report a delivery that
+ * never happened.
+ *
+ * ## Who writes `last_fired_at`
+ *
+ * A kind whose ingestion adapter runs in this process stamps the column when
+ * it delivers the event: `schedule` (where the column doubles as the
+ * scheduler's due-computation cursor, so moving it again here would shift the
+ * schedule) and `file_watch`. The dispatcher leaves those rows alone.
+ *
+ * `webhook` and `manual` arrive from outside and have no such owner, and
+ * leaving the column untouched made a webhook that had been delivering all
+ * week still report "Never" in the editor. For those the dispatcher stamps it
+ * on a delivered dispatch — the same write that records the run's outcome.
+ */
+import { TriggerWakeupService } from "@nodetool-ai/kernel";
+import type { TriggerInputStore } from "@nodetool-ai/kernel";
+import type { NodeRegistry } from "@nodetool-ai/node-sdk";
+import { type HeadlessJobStatus, type StartHeadlessJobOptions } from "../headless-job-runner.js";
+/**
+ * How a registration handles an event that arrives while one of its runs is
+ * still in flight. `parallel` (the default) starts a second run, `queue` waits
+ * for the current one, `skip` drops the event (marking it processed).
+ */
+export type ConcurrencyPolicy = "parallel" | "queue" | "skip";
+/** The part of a started job the dispatcher cares about. */
+export interface DispatchedJob {
+    jobId: string;
+    status?: HeadlessJobStatus;
+    error?: string | null;
+}
+/** Job-start function; defaults to `startHeadlessJob`. */
+export type StartTriggerJob = (options: StartHeadlessJobOptions) => Promise<DispatchedJob>;
+/**
+ * Adapter hint that new inputs exist. The argument is optional and ignored:
+ * every notify kicks one dispatch pass, which keeps the signature compatible
+ * with both the webhook route's `() => void` and the scheduler's
+ * `(event) => void`.
+ */
+export type DispatcherNotify = (event?: {
+    registrationId?: string;
+    inputId?: string;
+}) => void;
+interface TriggerDispatcherOptions {
+    /** Where unprocessed inputs are read from. Wire the Drizzle store at boot. */
+    store: TriggerInputStore;
+    startJob?: StartTriggerJob;
+    /** Node registry handed to `startJob`; defaults to the runner's own. */
+    registry?: NodeRegistry;
+    /** Max inputs drained per registration per pass. Defaults to 100. */
+    batchSize?: number;
+}
+interface StartDispatcherOptions extends TriggerDispatcherOptions {
+    /** Poll period for the crash-recovery path. Defaults to 15s. */
+    intervalMs?: number;
+}
+/** What a single input's dispatch settled as. */
+export type DispatchOutcome = {
+    status: "dispatched";
+    jobId: string;
+} | {
+    status: "skipped";
+    reason: string;
+};
+/** Stops the poll timer; also carries `notify`/`drain` for adapters and tests. */
+export interface DispatcherHandle {
+    (): void;
+    notify: DispatcherNotify;
+    drain(): Promise<void>;
+    dispatchInput(inputId: string): Promise<{
+        jobId: string;
+    }>;
+}
+/**
+ * Consumes stored trigger inputs. One instance owns the per-registration
+ * concurrency state and the per-input in-flight map, so both survive across
+ * passes.
+ */
+export declare class TriggerDispatcher {
+    private readonly store;
+    private readonly startJob;
+    private readonly registry?;
+    private readonly batchSize;
+    private readonly states;
+    private readonly inflight;
+    /** Runs a pass handed off but that have not finished. `drain()` awaits these. */
+    private readonly outstanding;
+    private pass;
+    private pending;
+    private stopped;
+    constructor(options: TriggerDispatcherOptions);
+    /**
+     * Drain every enabled registration's unprocessed inputs once. Resolves when
+     * every input this pass picked up has been *accepted* — not when its run has
+     * finished, so one slow workflow cannot hold up the next pass (see the
+     * acceptance-vs-completion note above). Use `drain()` to await the runs. A
+     * single input's failure does not abort the pass.
+     */
+    runOnce(): Promise<void>;
+    /** Adapter hint: run a pass now, coalescing concurrent notifies. */
+    notify: DispatcherNotify;
+    /**
+     * Await the currently running pass (and any pass it coalesced) *and* every
+     * run those passes handed off. A settling run can enqueue nothing new, but a
+     * pass can, so both are re-checked until the two are quiet together.
+     */
+    drain(): Promise<void>;
+    stop(): void;
+    /**
+     * Deliver one already-stored input immediately. The synchronous-dispatch
+     * contract used by the manual-fire API: resolves with the started job id,
+     * rejects with an `Error` whose message starts with `"input not found"` or
+     * `"registration disabled"` for those two cases. A concurrent call for the
+     * same input joins the in-flight dispatch rather than starting a second run.
+     */
+    dispatchInput(inputId: string): Promise<{
+        jobId: string;
+    }>;
+    private dispatchStoredInput;
+    /**
+     * Look an input up by id. The `TriggerInputStore` interface addresses inputs
+     * by (run, node) only, so the by-id read goes through the model — the same
+     * table the Drizzle store writes.
+     */
+    private findInput;
+    private runPasses;
+    private stateFor;
+    /**
+     * Start (or join) the dispatch of one input under its registration's
+     * concurrency policy.
+     */
+    private enqueue;
+    private dispatchOne;
+    /** Append the audit event. Never lets a logging failure block a dispatch. */
+    private emitReceived;
+    /**
+     * Record what the run did to the registration: its outcome, the failure
+     * counters, and — for the kinds no ingestion adapter stamps — the fire time
+     * the editor shows as "Last fired".
+     *
+     * `fired: false` marks an outcome where no run ever started, so there is no
+     * fire time to record however the kind is owned.
+     */
+    private settle;
+}
+/** Construct a dispatcher without starting its poll timer (tests, boot code). */
+export declare function createTriggerDispatcher(options: TriggerDispatcherOptions): TriggerDispatcher;
+/**
+ * The process's `TriggerWakeupService`. Boot wiring installs the DB-backed
+ * instance via `setTriggerWakeupService`; until then a default (memory inbox)
+ * instance is created lazily so callers always get a usable service.
+ */
+export declare function getTriggerWakeupService(): TriggerWakeupService;
+/** Install (or clear, with `null`) the process-wide wakeup service. */
+export declare function setTriggerWakeupService(service: TriggerWakeupService | null): void;
+/** The running dispatcher, or `null` before boot wiring / after shutdown. */
+export declare function getActiveDispatcher(): TriggerDispatcher | null;
+/**
+ * Deliver one already-stored input immediately through the running dispatcher.
+ * Resolves with the started job id; rejects with an `Error` whose message
+ * starts with `"input not found"` or `"registration disabled"` for those cases.
+ *
+ * Note that the promise settles when the run *finishes*, because the headless
+ * runner resolves on terminal status.
+ */
+export declare function dispatchInput(inputId: string): Promise<{
+    jobId: string;
+}>;
+/**
+ * Start the dispatcher: one unref'd poll timer for crash recovery plus an
+ * immediate backlog pass. The returned handle stops the timer and also exposes
+ * `notify` (for adapters) and `drain`/`dispatchInput`.
+ */
+export declare function startDispatcher(options: StartDispatcherOptions): DispatcherHandle;
+export {};
+//# sourceMappingURL=dispatcher.d.ts.map

package/dist/triggers/dispatcher.d.ts.map

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