@addai/node 0.24.0 → 0.25.0

package/dist/flows/engine-loader.js

@@ -0,0 +1,40 @@
+"use strict";
+// Loading an ESM package from a CommonJS daemon.
+//
+// @addai/node-flows is ESM and its sandbox does a top-level `await
+// import('isolated-vm')` — the optional native isolate, probed at load. This
+// daemon compiles to CommonJS, and `require()` refuses an ESM graph with
+// top-level await outright (ERR_REQUIRE_ASYNC_MODULE). So the engine can only
+// ever be loaded asynchronously.
+//
+// The `new Function` is not a trick for its own sake: TypeScript with
+// `module: CommonJS` rewrites a plain `import()` into `require()`, which is
+// precisely the call that fails. Hiding the import inside a function body the
+// compiler will not touch is what keeps it a real dynamic import at runtime.
+//
+// Loading is also lazy on purpose. A machine that never runs flows should
+// never pay to load the engine, and on a machine where the native sandbox
+// failed to build, the failure should surface when someone turns flows on —
+// not as a daemon that will not start.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadEngine = loadEngine;
+exports.engineLoaded = engineLoaded;
+const dynamicImport = new Function('specifier', 'return import(specifier);');
+let cached = null;
+/** Load the engine once and reuse it. The promise is cached rather than the
+ *  module, so concurrent first calls share one load instead of racing. */
+function loadEngine() {
+    if (!cached) {
+        cached = dynamicImport('@addai/node-flows').catch((err) => {
+            // Clear the cache so a later attempt can retry — a transient failure
+            // (a half-written install, say) must not poison the process for good.
+            cached = null;
+            throw new Error(`The flows engine could not be loaded: ${err.message}. `
+                + 'Reinstall @addai/node, or turn flows off for this machine.');
+        });
+    }
+    return cached;
+}
+/** Has the engine been loaded already? Lets the capabilities probe report the
+ *  sandbox without forcing a load on a machine that does not run flows. */
+function engineLoaded() { return cached !== null; }

package/dist/flows/host.d.ts

@@ -0,0 +1,40 @@
+import type { HandlerRegistry } from '@addai/node-flows';
+/** One flow run, as the claim RPC hands it over. */
+export interface FlowRunRow {
+    id: string;
+    flow_id: string | null;
+    aiflow_version_id: string | null;
+    workspace_id: string | null;
+    status: string;
+    nodes: any[] | null;
+    edges: any[] | null;
+    trigger_data: Record<string, unknown> | null;
+    node_outputs: Record<string, unknown> | null;
+    current_node_id: string | null;
+    execution_target: string;
+    is_test: boolean | null;
+    /** Set when the cloud handed back a run that had paused. Null on a fresh
+     *  run, which starts at its trigger. */
+    resume_from_node_id: string | null;
+    priority: number | null;
+    resolved_variables: unknown;
+}
+/**
+ * The handler registry this machine runs a flow with.
+ *
+ * Built once per run so the proxy closes over that run's id — the server
+ * authorises each proxied node by checking this daemon still holds the claim
+ * on it.
+ */
+export declare function buildRegistry(run: FlowRunRow): Promise<HandlerRegistry>;
+/**
+ * Write one node event to the same place a cloud run writes it.
+ *
+ * Not optional polish. If a run on this machine is not as legible in the run
+ * viewer as a cloud run, self-hosting becomes the option nobody can debug, and
+ * people go back to the cloud for reasons that have nothing to do with where
+ * the work belongs.
+ *
+ * Fire-and-forget on purpose: a lost log line must never fail a flow.
+ */
+export declare function reportNodeLog(run: FlowRunRow, node: any, status: 'success' | 'error', output: unknown): void;

package/dist/flows/host.js

@@ -0,0 +1,125 @@
+"use strict";
+// What the shared engine needs from this machine, and what it must ask the
+// server for.
+//
+// The engine itself is host-agnostic: it walks the graph and calls handlers.
+// This file is the half of the contract that only makes sense here — the
+// twenty-five local handlers run in this process, and the fifteen privileged
+// ones become a round trip to flow-node-host, because they need a
+// service-role Supabase client or the credential encryption key and this
+// machine has neither.
+//
+// It is worth being precise about why that split is not a limitation we are
+// working around. `httpRequest` and `code` running HERE is the entire feature:
+// they reach this machine's LAN, its VPN, its filesystem and its IP address,
+// which is the thing no amount of cloud capacity substitutes for. Everything
+// else is bookkeeping the server was always going to be better at.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildRegistry = buildRegistry;
+exports.reportNodeLog = reportNodeLog;
+const engine_loader_1 = require("./engine-loader");
+const supabase_client_1 = require("../supabase-client");
+const store_1 = require("../store");
+const config_1 = require("../config");
+const PROXY_TIMEOUT_MS = 5 * 60_000;
+/**
+ * Ask the server to run one privileged node.
+ *
+ * Deliberately NOT retried in here. A privileged node is very often a write —
+ * enqueueing an agent request, creating a review task, sending a notification —
+ * and a transparent retry on a timeout would do it twice. The engine's own
+ * error handling decides what happens next, in the open, where the flow author
+ * can see it on the node.
+ */
+async function proxyOne(runId, node, inputs, parentOutputs, inputData, viaReturnEdge) {
+    const pairing = (0, store_1.readPairing)();
+    if (!pairing)
+        throw new Error('not paired — cannot reach flow-node-host');
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), PROXY_TIMEOUT_MS);
+    try {
+        const res = await fetch(`${config_1.SUPABASE_URL}/functions/v1/flow-node-host`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'Authorization': `Bearer ${config_1.SUPABASE_ANON_KEY}`,
+                'apikey': config_1.SUPABASE_ANON_KEY,
+                'x-daemon-token': pairing.daemonToken,
+            },
+            body: JSON.stringify({
+                run_id: runId,
+                node,
+                inputs,
+                parent_outputs: parentOutputs,
+                input_data: inputData,
+                via_return_edge: viaReturnEdge,
+            }),
+            signal: controller.signal,
+        });
+        const text = await res.text();
+        let body = null;
+        try {
+            body = text ? JSON.parse(text) : null;
+        }
+        catch { /* non-JSON below */ }
+        if (!res.ok || body?.success === false) {
+            // Carry the server's own message through. It is what lands on the failed
+            // node in the run view, and "proxy failed (500)" is the difference
+            // between a five-minute fix and an afternoon.
+            throw new Error(body?.error || `flow-node-host returned ${res.status}: ${text.slice(0, 300)}`);
+        }
+        return body?.output ?? {};
+    }
+    catch (err) {
+        if (err.name === 'AbortError') {
+            throw new Error(`"${node.type}" did not finish on the server within ${PROXY_TIMEOUT_MS / 60000} minutes.`);
+        }
+        throw err;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * The handler registry this machine runs a flow with.
+ *
+ * Built once per run so the proxy closes over that run's id — the server
+ * authorises each proxied node by checking this daemon still holds the claim
+ * on it.
+ */
+async function buildRegistry(run) {
+    const { createHandlerRegistry, findNodeInputs } = await (0, engine_loader_1.loadEngine)();
+    return createHandlerRegistry({
+        proxyFactory: (type) => async (args) => {
+            const node = args?.node ?? {};
+            const parentOutputs = args?.parentOutputs ?? {};
+            // The server's handlers take the `from_<sourceId>` input map that
+            // Engine A builds, not the whole outputs bag. Computing it here with the
+            // engine's own function is what keeps a proxied node seeing exactly what
+            // it would see running inline.
+            const inputs = findNodeInputs(node.id, run.edges || [], parentOutputs);
+            return proxyOne(run.id, { ...node, type }, inputs, parentOutputs, args?.inputData ?? {}, args?.context?.viaReturnEdge === true);
+        },
+    });
+}
+/**
+ * Write one node event to the same place a cloud run writes it.
+ *
+ * Not optional polish. If a run on this machine is not as legible in the run
+ * viewer as a cloud run, self-hosting becomes the option nobody can debug, and
+ * people go back to the cloud for reasons that have nothing to do with where
+ * the work belongs.
+ *
+ * Fire-and-forget on purpose: a lost log line must never fail a flow.
+ */
+function reportNodeLog(run, node, status, output) {
+    void (0, supabase_client_1.rpc)('insert_node_log', {
+        p_run_id: run.id,
+        p_node_id: node?.id ?? null,
+        p_node_type: node?.type ?? null,
+        p_node_label: node?.data?.label ?? null,
+        p_status: status,
+        p_output: output ?? null,
+        p_workspace_id: run.workspace_id,
+    }).catch(() => { });
+}

package/dist/flows/pump.d.ts

@@ -0,0 +1,31 @@
+export declare const DEFAULT_MAX_CONCURRENT_FLOWS = 4;
+/** Clamp whatever the server sent into something the pump can act on. */
+export declare function clampMaxConcurrentFlows(value: unknown): number;
+/** Called by the heartbeat. Lowering it never interrupts a run in flight —
+ *  those finish; the pump just stops claiming until it is back under the line. */
+export declare function setMaxConcurrentFlows(value: unknown): void;
+/** Called by the heartbeat. Turning flows on starts claiming immediately;
+ *  turning it off stops claiming but lets what is running finish. */
+export declare function setFlowsEnabled(value: unknown): void;
+export declare function flowsEnabled(): boolean;
+export declare function maxConcurrentFlows(): number;
+export declare function inflightFlowCount(): number;
+/** Runs this daemon is holding right now. Reported every 30s so the server's
+ *  reclaim never requeues a healthy run that simply has nothing to say — a
+ *  flow parked in a slow HTTP call is quiet, not dead. */
+export declare function activeFlowRunIds(): string[];
+export declare function start(): void;
+export declare function stop(): void;
+/**
+ * Claim right now, because something said there is work.
+ *
+ * Deliberately does not clear the backoff window: if the pump is backing off
+ * because Supabase is unhealthy, a nudge is no reason to start hammering it.
+ */
+export declare function pumpNow(): void;
+/** Wait for in-flight runs, with a ceiling so a wedged run cannot block
+ *  shutdown forever. */
+export declare function drain(timeoutMs: number): Promise<{
+    drained: number;
+    timedOut: number;
+}>;

package/dist/flows/pump.js

@@ -0,0 +1,264 @@
+"use strict";
+// Claims +Ai Flows runs targeted at this machine and executes them.
+//
+// A deliberate sibling of request-pump, not a variation on it. The two solve
+// the same problem — claim work from Supabase, hold a bounded number of it,
+// heartbeat what you are holding, drain on shutdown — and every difference
+// between them would be a difference in how the box behaves under load that
+// nobody chose. Where the shapes match, they match on purpose.
+//
+// The one thing that is genuinely different is the ceiling. Flow runs and
+// agent runs count separately, because they compete for the same machine but
+// answer to different people: a burst of flows must never mean a chat goes
+// unanswered, and a long agent session must never stall the flows queue.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_MAX_CONCURRENT_FLOWS = void 0;
+exports.clampMaxConcurrentFlows = clampMaxConcurrentFlows;
+exports.setMaxConcurrentFlows = setMaxConcurrentFlows;
+exports.setFlowsEnabled = setFlowsEnabled;
+exports.flowsEnabled = flowsEnabled;
+exports.maxConcurrentFlows = maxConcurrentFlows;
+exports.inflightFlowCount = inflightFlowCount;
+exports.activeFlowRunIds = activeFlowRunIds;
+exports.start = start;
+exports.stop = stop;
+exports.pumpNow = pumpNow;
+exports.drain = drain;
+const supabase_client_1 = require("../supabase-client");
+const store_1 = require("../store");
+const node_health_1 = require("../node-health");
+const diskguard_1 = require("../diskguard");
+const run_1 = require("./run");
+// Same 2s cadence as request-pump, for the same reason: 250ms polling from a
+// handful of daemons was enough to saturate the project's connection pool.
+// Successful claims re-tick immediately so a queued burst still drains fast.
+const POLL_INTERVAL_MS = 2_000;
+// How many flow runs this machine holds at once. Mirrors max_concurrent_runs:
+// the server's number, pushed in by the heartbeat, defaulting to 4 and
+// specifically to 4 when the server says NOTHING. A server without the
+// migration must read as "the behaviour you had yesterday", never as 0 (a node
+// that accepts nothing) or unbounded.
+exports.DEFAULT_MAX_CONCURRENT_FLOWS = 4;
+const MAX_MAX_CONCURRENT_FLOWS = 32;
+let maxConcurrent = exports.DEFAULT_MAX_CONCURRENT_FLOWS;
+// Off until the server says otherwise. Unlike desktops — where "can this
+// machine?" is answered by whether Docker is installed — the engine ships
+// inside the daemon, so capability is never the question and consent is.
+let enabled = false;
+/** Clamp whatever the server sent into something the pump can act on. */
+function clampMaxConcurrentFlows(value) {
+    // Absent is NOT zero. Number(null) and Number('') are both 0, which would
+    // quietly throttle the node to a single run — or with a naive clamp, shut it.
+    if (typeof value !== 'number' && typeof value !== 'string')
+        return exports.DEFAULT_MAX_CONCURRENT_FLOWS;
+    if (typeof value === 'string' && value.trim() === '')
+        return exports.DEFAULT_MAX_CONCURRENT_FLOWS;
+    const n = typeof value === 'number' ? value : Number(value);
+    if (!Number.isFinite(n))
+        return exports.DEFAULT_MAX_CONCURRENT_FLOWS;
+    return Math.min(MAX_MAX_CONCURRENT_FLOWS, Math.max(1, Math.floor(n)));
+}
+/** Called by the heartbeat. Lowering it never interrupts a run in flight —
+ *  those finish; the pump just stops claiming until it is back under the line. */
+function setMaxConcurrentFlows(value) {
+    const next = clampMaxConcurrentFlows(value);
+    if (next === maxConcurrent)
+        return;
+    console.log(`[flows-pump] flows at once: ${maxConcurrent} -> ${next}`);
+    maxConcurrent = next;
+    // Raising it should take effect now, not in two seconds — the usual reason
+    // to raise it is that work is queued up behind it.
+    if (enabled && !stopped && inflight < maxConcurrent)
+        queueMicrotask(() => { void tick(); });
+}
+/** Called by the heartbeat. Turning flows on starts claiming immediately;
+ *  turning it off stops claiming but lets what is running finish. */
+function setFlowsEnabled(value) {
+    const next = value === true;
+    if (next === enabled)
+        return;
+    enabled = next;
+    console.log(`[flows-pump] flows ${next ? 'enabled' : 'disabled'} for this machine`);
+    if (next && !stopped)
+        queueMicrotask(() => { void tick(); });
+}
+function flowsEnabled() { return enabled; }
+function maxConcurrentFlows() { return maxConcurrent; }
+function inflightFlowCount() { return inflight; }
+/** Runs this daemon is holding right now. Reported every 30s so the server's
+ *  reclaim never requeues a healthy run that simply has nothing to say — a
+ *  flow parked in a slow HTTP call is quiet, not dead. */
+function activeFlowRunIds() { return [...activeRunIds]; }
+// Anti-leak backstop ONLY: how long the pump holds a slot for a run whose
+// promise never settles. It does not stop the run and is not a time limit.
+const SLOT_LEAK_BACKSTOP_MS = 12 * 60 * 60 * 1000;
+let timer = null;
+let stopped = false;
+let inflight = 0;
+const activeRunIds = new Set();
+const inflightPromises = new Set();
+// Failure backoff, deduped logging — same shape as request-pump so an outage
+// produces ten log lines rather than a quarter of a million.
+let consecutiveFailures = 0;
+let lastLoggedError = '';
+let lastLoggedAt = 0;
+let nextClaimAllowedAt = 0;
+let lastHealthBlock = '';
+let lastHealthBlockAt = 0;
+async function tick() {
+    if (stopped || !enabled)
+        return;
+    if (inflight >= maxConcurrent)
+        return;
+    if (Date.now() < nextClaimAllowedAt)
+        return;
+    // The daemon-wide circuit breaker: when Supabase is in distress every poller
+    // pauses, not just this one.
+    if ((0, supabase_client_1.rpcShouldSkip)())
+        return;
+    const pairing = (0, store_1.readPairing)();
+    if (!pairing)
+        return;
+    // Don't accept work this machine cannot finish. A full scratch disk fails
+    // every code node and every attachment write; refusing the claim leaves the
+    // run queued for a healthy machine instead of burning one of its three
+    // attempts here.
+    const health = (0, node_health_1.evaluateNodeHealth)({ diskUsedPct: (0, node_health_1.readDiskUsedPct)((0, diskguard_1.getDiskGuard)().config.tempRoot) });
+    if (!health.healthy) {
+        const msg = health.blockers.map(b => b.message).join('; ');
+        const now = Date.now();
+        if (msg !== lastHealthBlock || (now - lastHealthBlockAt) > 60_000) {
+            console.warn(`[flows-pump] refusing claim — node unhealthy: ${msg}`);
+            lastHealthBlock = msg;
+            lastHealthBlockAt = now;
+        }
+        void (0, diskguard_1.getDiskGuard)().sweep('flows-health-gate').catch(() => { });
+        return;
+    }
+    let row = null;
+    try {
+        const result = await (0, supabase_client_1.rpc)('flow_run_claim_next', {
+            p_token: pairing.daemonToken,
+        });
+        row = (result && result.id) ? result : null;
+        if (consecutiveFailures > 0) {
+            console.log(`[flows-pump] recovered after ${consecutiveFailures} consecutive failures`);
+            consecutiveFailures = 0;
+            lastLoggedError = '';
+        }
+    }
+    catch (err) {
+        if (err instanceof supabase_client_1.RpcError && err.status === 401) {
+            console.error('[flows-pump] unauthorized; will retry on next heartbeat.');
+            return;
+        }
+        consecutiveFailures++;
+        const backoffMs = Math.min(60_000, POLL_INTERVAL_MS * Math.pow(2, Math.min(consecutiveFailures, 8)));
+        nextClaimAllowedAt = Date.now() + backoffMs;
+        const msg = err.message;
+        const now = Date.now();
+        if (msg !== lastLoggedError || (now - lastLoggedAt) > 60_000) {
+            console.error(`[flows-pump] claim failed (#${consecutiveFailures}, backing off ${backoffMs}ms):`, msg);
+            lastLoggedError = msg;
+            lastLoggedAt = now;
+        }
+        return;
+    }
+    if (!row)
+        return;
+    // Never run the same run twice at once. The claim RPC should make this
+    // impossible, but a duplicate execution of a flow means duplicate writes to
+    // whatever it touches — the one failure here that is not recoverable by
+    // trying again.
+    if (activeRunIds.has(row.id)) {
+        console.warn(`[flows-pump] skipping re-claim of in-flight run [run=${row.id}]`);
+        return;
+    }
+    inflight++;
+    const runId = row.id;
+    activeRunIds.add(runId);
+    // Per-run liveness, on its own timer. The 30s fleet heartbeat covers the
+    // normal case; this one exists so a single run that outlives a heartbeat
+    // hiccup still refreshes its own claim.
+    const touch = setInterval(() => {
+        void (0, supabase_client_1.rpc)('flow_run_touch', {
+            p_token: pairing.daemonToken,
+            p_run_id: runId,
+        }).catch(() => { });
+    }, 60_000);
+    touch.unref?.();
+    let resolveInflight;
+    const inflightPromise = new Promise((r) => { resolveInflight = r; });
+    inflightPromises.add(inflightPromise);
+    let backstopFired = false;
+    const backstop = new Promise((resolve) => {
+        const t = setTimeout(() => {
+            backstopFired = true;
+            console.error(`[flows-pump] run exceeded the ${SLOT_LEAK_BACKSTOP_MS / 3600000}h slot backstop `
+                + `[run=${runId}] — freeing the slot. The run continues; the server's reclaim `
+                + 'handles the row only if it really is dead.');
+            resolve();
+        }, SLOT_LEAK_BACKSTOP_MS);
+        t.unref?.();
+    });
+    const runPromise = (0, run_1.runFlow)(row).catch(err => console.error(`[flows-pump] runFlow threw [run=${runId}]: ${err.message}`));
+    // Drain tracking follows the REAL run, not the slot: a run that outlives its
+    // backstop must still hold up a graceful shutdown, or a restart would hand
+    // over mid-flow.
+    void runPromise.finally(() => {
+        clearInterval(touch);
+        activeRunIds.delete(runId);
+        inflightPromises.delete(inflightPromise);
+        resolveInflight();
+    });
+    Promise.race([runPromise, backstop]).finally(() => {
+        inflight = backstopFired ? Math.max(0, inflight - 1) : inflight - 1;
+        if (!stopped && enabled && inflight < maxConcurrent) {
+            queueMicrotask(() => { void tick(); });
+        }
+    });
+    // Back-to-back claims should not wait for the next interval.
+    if (!stopped && enabled && inflight < maxConcurrent) {
+        queueMicrotask(() => { void tick(); });
+    }
+}
+function start() {
+    if (timer || stopped)
+        return;
+    void tick();
+    timer = setInterval(() => { void tick(); }, POLL_INTERVAL_MS);
+}
+function stop() {
+    stopped = true;
+    if (timer) {
+        clearInterval(timer);
+        timer = null;
+    }
+}
+/**
+ * Claim right now, because something said there is work.
+ *
+ * Deliberately does not clear the backoff window: if the pump is backing off
+ * because Supabase is unhealthy, a nudge is no reason to start hammering it.
+ */
+function pumpNow() {
+    if (stopped || !enabled)
+        return;
+    void tick();
+}
+/** Wait for in-flight runs, with a ceiling so a wedged run cannot block
+ *  shutdown forever. */
+async function drain(timeoutMs) {
+    if (inflightPromises.size === 0)
+        return { drained: 0, timedOut: 0 };
+    const started = inflightPromises.size;
+    const deadline = new Promise((resolve) => {
+        const t = setTimeout(resolve, timeoutMs);
+        t.unref?.();
+    });
+    await Promise.race([
+        Promise.allSettled([...inflightPromises]).then(() => undefined),
+        deadline,
+    ]);
+    return { drained: started - inflightPromises.size, timedOut: inflightPromises.size };
+}

package/dist/flows/run.d.ts

@@ -0,0 +1,7 @@
+import { type FlowRunRow } from './host';
+/**
+ * Run it. Resolves when the run has reached a terminal or paused state and
+ * that state has been reported; never throws, because the pump's slot
+ * accounting is built on this settling exactly once.
+ */
+export declare function runFlow(run: FlowRunRow): Promise<void>;