@cat-factory/node-server 0.6.0

package/dist/execution/pgBossRunner.js

@@ -0,0 +1,163 @@
+import { reenqueueStaleBootstrap } from './bootstrapRunner.js';
+import { driveExecution } from './drive.js';
+// Durable execution on pg-boss: the analogue of the Worker's Cloudflare Workflows
+// driver. `startRun` enqueues an advance job (deduped per run via singletonKey); a
+// registered worker drives the run to a standstill via `driveExecution`. A resolved
+// decision re-enqueues an advance to resume a parked run. State lives in Postgres,
+// so a crash mid-run is recovered two ways: pg-boss retries an expired/failed advance
+// job, and the stale-run sweeper re-enqueues runs still `running` in storage.
+const QUEUE = 'execution.advance';
+// A separate, delayed queue that fails a run still parked on a decision after the
+// `decisionTimeout` window — the Node analogue of the Cloudflare driver's
+// `waitForEvent(..., { timeout })`. Kept off the advance queue so the delay never holds
+// up real drives, and `exclusive` so at most one pending timeout exists per (run, decision).
+const DECISION_TIMEOUT_QUEUE = 'execution.decision-timeout';
+// The queue MUST be created with the `exclusive` policy for the dedup below to hold.
+// Under pg-boss's default `standard` policy, `singletonKey` alone enforces NO uniqueness
+// (the singleton unique indexes are policy-gated, and the policy-independent one requires
+// `singletonSeconds`, which we don't set). `exclusive` makes (name, singletonKey) unique
+// across the `created`/`retry`/`active` states, so at most one advance job per run is
+// alive at a time and a duplicate `send` is an `ON CONFLICT DO NOTHING` no-op.
+const QUEUE_POLICY = 'exclusive';
+function sendOptions(executionId, opts) {
+    return {
+        singletonKey: executionId,
+        expireInSeconds: opts.expireInSeconds,
+        heartbeatSeconds: opts.heartbeatSeconds,
+        retryLimit: opts.retryLimit,
+        retryDelay: opts.retryDelaySeconds,
+        retryBackoff: true,
+    };
+}
+export class PgBossWorkRunner {
+    boss;
+    queueOptions;
+    constructor(boss, queueOptions) {
+        this.boss = boss;
+        this.queueOptions = queueOptions;
+    }
+    async startRun(workspaceId, executionId) {
+        await this.boss.send(QUEUE, { workspaceId, executionId }, sendOptions(executionId, this.queueOptions));
+    }
+    async signalDecision(workspaceId, executionId, _decisionId, _choice) {
+        // The decision is already persisted by resolveDecision; re-enqueue an advance so
+        // the parked run resumes. The DB write is the source of truth either way.
+        await this.boss.send(QUEUE, { workspaceId, executionId }, sendOptions(executionId, this.queueOptions));
+    }
+    async cancelRun(_workspaceId, _executionId) {
+        // Best-effort: the run is finalized via ExecutionService.stopRun; any in-flight
+        // advance job is a no-op once the run is terminal (advanceInstance returns noop).
+    }
+}
+/**
+ * Create the execution queue and start the worker that drives runs.
+ *
+ * `concurrency` (pg-boss `localConcurrency`) spawns that many INDEPENDENT workers for
+ * the queue on this node: each polls, fetches one job (`batchSize` stays 1) and acks /
+ * retries it on its own, so up to `concurrency` runs drive in parallel. This is the key
+ * to throughput — a single drive parks for the whole of a step's poll budget (sleeping
+ * between polls), so without parallel workers one slow run would block every other run
+ * behind it. We deliberately keep `batchSize: 1` rather than raising it: a batch handler
+ * completes/fails all its jobs together, which would couple unrelated runs' retries;
+ * independent workers keep per-run retry semantics intact. The `exclusive` queue policy
+ * still prevents the SAME run being driven by two workers at once (one live advance job per
+ * run id; duplicate sends no-op). Scale `concurrency` with the DB pool
+ * (each active drive borrows a connection only for its brief reads/writes between sleeps).
+ */
+export async function startExecutionWorker(boss, container, cfg, log, options = {}) {
+    const concurrency = options.concurrency ?? 10;
+    const decisionTimeoutSeconds = options.decisionTimeoutSeconds ?? 0;
+    await boss.createQueue(QUEUE, { policy: QUEUE_POLICY });
+    await boss.work(QUEUE, { localConcurrency: Math.max(1, concurrency) }, async (jobs) => {
+        for (const job of jobs) {
+            const { workspaceId, executionId } = job.data;
+            try {
+                const outcome = await driveExecution(container.executionService, workspaceId, executionId, cfg, { log });
+                // Arm a decision timeout when the run parked awaiting a human. There is no
+                // event to cancel it on resolution (unlike Cloudflare's waitForEvent), so the
+                // timeout job re-checks state and `expireDecision` no-ops if it was resolved.
+                if (outcome.parkedDecisionId && decisionTimeoutSeconds > 0) {
+                    await boss.send(DECISION_TIMEOUT_QUEUE, { workspaceId, executionId, decisionId: outcome.parkedDecisionId }, {
+                        startAfter: decisionTimeoutSeconds,
+                        singletonKey: `${executionId}:${outcome.parkedDecisionId}`,
+                    });
+                }
+            }
+            catch (error) {
+                log.error({
+                    workspaceId,
+                    executionId,
+                    err: error instanceof Error ? error.message : String(error),
+                }, 'execution driver failed');
+                throw error;
+            }
+        }
+    });
+}
+/**
+ * Start the worker that expires overdue decisions. A delayed job (armed by
+ * {@link startExecutionWorker} when a run parks on a decision) fires after the
+ * `decisionTimeout`; `expireDecision` fails the run as `decision_timeout` ONLY if it is
+ * still parked on that exact decision, so a decision resolved meanwhile is a safe no-op
+ * (no driving — that stays on the advance queue). This is the Node analogue of the
+ * Cloudflare driver's `waitForEvent` timeout. Create the queue before the advance worker
+ * so the advance worker's `boss.send` to it always has a target.
+ */
+export async function startDecisionTimeoutWorker(boss, container, log) {
+    await boss.createQueue(DECISION_TIMEOUT_QUEUE, { policy: QUEUE_POLICY });
+    await boss.work(DECISION_TIMEOUT_QUEUE, async (jobs) => {
+        for (const job of jobs) {
+            const { workspaceId, executionId, decisionId } = job.data;
+            try {
+                await container.executionService.expireDecision(workspaceId, executionId, decisionId);
+            }
+            catch (error) {
+                log.error({
+                    workspaceId,
+                    executionId,
+                    decisionId,
+                    err: error instanceof Error ? error.message : String(error),
+                }, 'decision-timeout check failed');
+                throw error;
+            }
+        }
+    });
+}
+/**
+ * Backstop for runs that are still `running` in storage but whose advance job is gone
+ * (the worker crashed/was evicted before the job retried). Mirrors the Worker's cron
+ * `sweepStuckRuns`: on each tick it re-enqueues every stale `running` execution run.
+ * The re-enqueue carries the run's `singletonKey` and the queue is `exclusive`, so a run
+ * that IS still being driven (its advance job active/retrying) is a silent no-op — only
+ * genuinely orphaned runs re-drive.
+ * Decision-parked (`blocked`) and spend-paused (`paused`) runs aren't `running`, so the
+ * sweeper leaves them alone. Returns a stop function (clears the interval).
+ */
+export function startStaleRunSweeper(boss, container, cfg, queueOptions, log) {
+    const tick = async () => {
+        try {
+            const stale = await container.agentRunRepository.listStale(Date.now() - cfg.leaseMs);
+            for (const ref of stale) {
+                // Both durable kinds are re-driven: an orphaned execution back onto the advance
+                // queue, an orphaned bootstrap onto the bootstrap drive queue (parity with the
+                // Worker's sweepStuckRuns, which covers execution + bootstrap).
+                if (ref.kind === 'bootstrap') {
+                    log.warn({ workspaceId: ref.workspaceId, jobId: ref.id }, 're-driving stale bootstrap');
+                    await reenqueueStaleBootstrap(boss, ref.workspaceId, ref.id, queueOptions);
+                    continue;
+                }
+                if (ref.kind !== 'execution')
+                    continue;
+                log.warn({ workspaceId: ref.workspaceId, executionId: ref.id }, 're-driving stale run');
+                await boss.send(QUEUE, { workspaceId: ref.workspaceId, executionId: ref.id }, sendOptions(ref.id, queueOptions));
+            }
+        }
+        catch (error) {
+            log.error({ err: error instanceof Error ? error.message : String(error) }, 'stale-run sweep failed');
+        }
+    };
+    const timer = setInterval(() => void tick(), cfg.intervalMs);
+    timer.unref?.(); // never keep the process alive on the sweep timer alone
+    return () => clearInterval(timer);
+}
+//# sourceMappingURL=pgBossRunner.js.map

package/dist/execution/pgBossRunner.js.map

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

package/dist/gateways.d.ts

@@ -0,0 +1,4 @@
+import { type RuntimeGateways } from '@cat-factory/server';
+/** Build the Node runtime gateways from process env. */
+export declare function createNodeGateways(env: NodeJS.ProcessEnv): RuntimeGateways;
+//# sourceMappingURL=gateways.d.ts.map

package/dist/gateways.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gateways.d.ts","sourceRoot":"","sources":["../src/gateways.ts"],"names":[],"mappings":"AAOA,OAAO,EAML,KAAK,eAAe,EAErB,MAAM,qBAAqB,CAAA;AAmF5B,wDAAwD;AACxD,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,GAAG,eAAe,CAU1E"}

package/dist/gateways.js

@@ -0,0 +1,91 @@
+import { DEEPSEEK_BASE_URL, MOONSHOT_BASE_URL, OPENAI_BASE_URL, OPENROUTER_BASE_URL, QWEN_BASE_URL, } from '@cat-factory/agents';
+import { createWebSearchUpstreamFromEnv, } from '@cat-factory/server';
+// Node implementations of the runtime gateway seams. Async GitHub ingest still falls
+// back to the "inline / not enabled" paths the shared controllers handle, and the LLM
+// proxy forwards to OpenAI-compatible providers over HTTP (no in-process binding).
+//
+// Real-time delivery, by contrast, IS implemented — but NOT through this gateway seam.
+// The seam returns a Hono `Response` (the Cloudflare model: a 101 from the per-workspace
+// Durable Object). `@hono/node-server` can't complete a WebSocket upgrade from a
+// `Response`, so the Node facade intercepts the `/workspaces/:ws/events` upgrade on the
+// HTTP server directly (see `attachRealtime` in `realtime.ts`) before it reaches this
+// controller. This gateway therefore stays a no-op: it is never invoked for an actual
+// upgrade on Node, and the shared events route only ever falls through to its 426/501.
+//
+// Production swap-in for a multi-replica deployment (follow-up): front the in-process
+// `NodeRealtimeHub` with a shared bus (Postgres LISTEN/NOTIFY); single-process Node and
+// local mode need nothing more. Async GitHub ingest: pg-boss `githubBackfill` / `githubWebhook`.
+/**
+ * No-op: Node handles the WebSocket upgrade at the HTTP-server level (`attachRealtime`),
+ * not through this Response-returning seam — see the file header. Returning null keeps
+ * the shared controller's contract intact for the (unreachable on Node) delegation path.
+ */
+class NodeRealtimeGateway {
+    upgrade() {
+        return Promise.resolve(null);
+    }
+}
+/** No async backfill scheduler yet: report "not scheduled" so the caller runs it inline. */
+class InlineGitHubBackfillScheduler {
+    scheduleBackfill() {
+        return Promise.resolve(false);
+    }
+}
+/** No async queue yet: report "not queued" so the caller handles webhooks/resyncs inline. */
+class InlineGitHubWebhookIngest {
+    enqueueWebhook() {
+        return Promise.resolve(false);
+    }
+    queueRepoResync() {
+        return Promise.resolve(false);
+    }
+}
+// `baseUrl` is the built-in default; LiteLLM has none (operator-hosted), so it relies
+// purely on its env override and resolves to null until LITELLM_BASE_URL is set.
+const OPENAI_COMPATIBLE = {
+    qwen: { baseUrl: QWEN_BASE_URL, baseUrlEnv: 'QWEN_BASE_URL' },
+    deepseek: { baseUrl: DEEPSEEK_BASE_URL, baseUrlEnv: 'DEEPSEEK_BASE_URL' },
+    moonshot: { baseUrl: MOONSHOT_BASE_URL, baseUrlEnv: 'MOONSHOT_BASE_URL' },
+    openai: { baseUrl: OPENAI_BASE_URL, baseUrlEnv: 'OPENAI_BASE_URL' },
+    openrouter: { baseUrl: OPENROUTER_BASE_URL, baseUrlEnv: 'OPENROUTER_BASE_URL' },
+    litellm: { baseUrlEnv: 'LITELLM_BASE_URL' },
+};
+/**
+ * Forwards the container LLM proxy to OpenAI-compatible providers over HTTP. Only the
+ * base URL is resolved here (overridable per provider via env); the API key is leased
+ * per call from the DB-backed pool by the proxy. There is no in-process path on Node,
+ * so `runInProcess` returns null (a `workers-ai`-pinned model is unavailable here; use
+ * a direct provider, or enable the Cloudflare REST flavour).
+ */
+class HttpLlmUpstream {
+    env;
+    constructor(env) {
+        this.env = env;
+    }
+    resolveOpenAiCompatible(provider) {
+        const entry = OPENAI_COMPATIBLE[provider];
+        if (!entry)
+            return null;
+        // `||` not `??`: a set-but-blank base-URL env must fall back to the default, not
+        // collapse to an empty URL the SDK then chokes on. For a provider with no default
+        // (LiteLLM), an unset env yields null so the proxy reports "not available" cleanly.
+        const baseURL = this.env[entry.baseUrlEnv] || entry.baseUrl;
+        return baseURL ? { baseURL } : null;
+    }
+    runInProcess() {
+        return null;
+    }
+}
+/** Build the Node runtime gateways from process env. */
+export function createNodeGateways(env) {
+    return {
+        realtime: new NodeRealtimeGateway(),
+        githubBackfill: new InlineGitHubBackfillScheduler(),
+        githubWebhook: new InlineGitHubWebhookIngest(),
+        llmUpstream: new HttpLlmUpstream(env),
+        // Container web-search proxy upstream (Brave / self-hosted SearXNG from env);
+        // absent ⇒ the `/v1/web-search` route 503s and container web search stays off.
+        webSearch: createWebSearchUpstreamFromEnv(env),
+    };
+}
+//# sourceMappingURL=gateways.js.map

package/dist/gateways.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gateways.js","sourceRoot":"","sources":["../src/gateways.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,iBAAiB,EACjB,iBAAiB,EACjB,eAAe,EACf,mBAAmB,EACnB,aAAa,GACd,MAAM,qBAAqB,CAAA;AAC5B,OAAO,EAOL,8BAA8B,GAC/B,MAAM,qBAAqB,CAAA;AAE5B,qFAAqF;AACrF,sFAAsF;AACtF,mFAAmF;AACnF,EAAE;AACF,uFAAuF;AACvF,yFAAyF;AACzF,iFAAiF;AACjF,wFAAwF;AACxF,sFAAsF;AACtF,sFAAsF;AACtF,uFAAuF;AACvF,EAAE;AACF,sFAAsF;AACtF,wFAAwF;AACxF,iGAAiG;AAEjG;;;;GAIG;AACH,MAAM,mBAAmB;IACvB,OAAO;QACL,OAAO,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,CAAA;IAC9B,CAAC;CACF;AAED,4FAA4F;AAC5F,MAAM,6BAA6B;IACjC,gBAAgB;QACd,OAAO,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,CAAA;IAC/B,CAAC;CACF;AAED,6FAA6F;AAC7F,MAAM,yBAAyB;IAC7B,cAAc;QACZ,OAAO,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,CAAA;IAC/B,CAAC;IAED,eAAe;QACb,OAAO,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,CAAA;IAC/B,CAAC;CACF;AAED,sFAAsF;AACtF,iFAAiF;AACjF,MAAM,iBAAiB,GAA6D;IAClF,IAAI,EAAE,EAAE,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,eAAe,EAAE;IAC7D,QAAQ,EAAE,EAAE,OAAO,EAAE,iBAAiB,EAAE,UAAU,EAAE,mBAAmB,EAAE;IACzE,QAAQ,EAAE,EAAE,OAAO,EAAE,iBAAiB,EAAE,UAAU,EAAE,mBAAmB,EAAE;IACzE,MAAM,EAAE,EAAE,OAAO,EAAE,eAAe,EAAE,UAAU,EAAE,iBAAiB,EAAE;IACnE,UAAU,EAAE,EAAE,OAAO,EAAE,mBAAmB,EAAE,UAAU,EAAE,qBAAqB,EAAE;IAC/E,OAAO,EAAE,EAAE,UAAU,EAAE,kBAAkB,EAAE;CAC5C,CAAA;AAED;;;;;;GAMG;AACH,MAAM,eAAe;IACU,GAAG;IAAhC,YAA6B,GAAsB;mBAAtB,GAAG;IAAsB,CAAC;IAEvD,uBAAuB,CAAC,QAAgB;QACtC,MAAM,KAAK,GAAG,iBAAiB,CAAC,QAAQ,CAAC,CAAA;QACzC,IAAI,CAAC,KAAK;YAAE,OAAO,IAAI,CAAA;QACvB,iFAAiF;QACjF,kFAAkF;QAClF,oFAAoF;QACpF,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,UAAU,CAAC,IAAI,KAAK,CAAC,OAAO,CAAA;QAC3D,OAAO,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,IAAI,CAAA;IACrC,CAAC;IAED,YAAY;QACV,OAAO,IAAI,CAAA;IACb,CAAC;CACF;AAED,wDAAwD;AACxD,MAAM,UAAU,kBAAkB,CAAC,GAAsB;IACvD,OAAO;QACL,QAAQ,EAAE,IAAI,mBAAmB,EAAE;QACnC,cAAc,EAAE,IAAI,6BAA6B,EAAE;QACnD,aAAa,EAAE,IAAI,yBAAyB,EAAE;QAC9C,WAAW,EAAE,IAAI,eAAe,CAAC,GAAG,CAAC;QACrC,8EAA8E;QAC9E,+EAA+E;QAC/E,SAAS,EAAE,8BAA8B,CAAC,GAAG,CAAC;KAC/C,CAAA;AACH,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+export { createApp, createServer, start, type CreateServerOptions } from './server.js';
+export { buildNodeContainer, type NodeContainerOptions } from './container.js';
+export { loadNodeConfig } from './config.js';
+export { createNodeGateways } from './gateways.js';
+export { createNodeModelProviderResolver } from './modelProvider.js';
+export { registerAgentKind, registerAgentKinds, clearRegisteredAgentKinds, type AgentKindDefinition, } from '@cat-factory/agents';
+export { registerPipeline, registerPipelines, clearRegisteredPipelines } from '@cat-factory/kernel';
+export { createDbClient, type DbClient, type DrizzleDb } from './db/client.js';
+export { migrate } from './db/migrate.js';
+export { createDrizzleRepositories, type CoreRepositories } from './repositories/drizzle.js';
+export { DrizzleGitHubInstallationRepository } from './repositories/containerExecution.js';
+export * as schema from './db/schema.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,KAAK,EAAE,KAAK,mBAAmB,EAAE,MAAM,aAAa,CAAA;AACtF,OAAO,EAAE,kBAAkB,EAAE,KAAK,oBAAoB,EAAE,MAAM,gBAAgB,CAAA;AAC9E,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AAC5C,OAAO,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAA;AAClD,OAAO,EAAE,+BAA+B,EAAE,MAAM,oBAAoB,CAAA;AAMpE,OAAO,EACL,iBAAiB,EACjB,kBAAkB,EAClB,yBAAyB,EACzB,KAAK,mBAAmB,GACzB,MAAM,qBAAqB,CAAA;AAC5B,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,wBAAwB,EAAE,MAAM,qBAAqB,CAAA;AACnG,OAAO,EAAE,cAAc,EAAE,KAAK,QAAQ,EAAE,KAAK,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAC9E,OAAO,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAA;AACzC,OAAO,EAAE,yBAAyB,EAAE,KAAK,gBAAgB,EAAE,MAAM,2BAA2B,CAAA;AAC5F,OAAO,EAAE,mCAAmC,EAAE,MAAM,sCAAsC,CAAA;AAC1F,OAAO,KAAK,MAAM,MAAM,gBAAgB,CAAA"}

package/dist/index.js

@@ -0,0 +1,22 @@
+// @cat-factory/node-server — the Node.js runtime facade. Serves the shared
+// @cat-factory/server Hono app via @hono/node-server, wiring Node implementations of
+// the runtime ports over a Drizzle/Postgres persistence layer (the single store used
+// in dev, test and prod). `start()` boots an HTTP server; `createServer()` returns the
+// app (for embedding/tests); `buildNodeContainer()` is the composition root.
+export { createApp, createServer, start } from './server.js';
+export { buildNodeContainer } from './container.js';
+export { loadNodeConfig } from './config.js';
+export { createNodeGateways } from './gateways.js';
+export { createNodeModelProviderResolver } from './modelProvider.js';
+// Installation-level extension points (mirroring the Worker facade): a deployment —
+// typically a proprietary org package — registers custom agent kinds and predefined
+// pipelines at startup (before `start()`), and the shared prompt catalog / workspace
+// seeding pick them up. Bedrock-style model providers mix in via createNodeModelProvider.
+export { registerAgentKind, registerAgentKinds, clearRegisteredAgentKinds, } from '@cat-factory/agents';
+export { registerPipeline, registerPipelines, clearRegisteredPipelines } from '@cat-factory/kernel';
+export { createDbClient } from './db/client.js';
+export { migrate } from './db/migrate.js';
+export { createDrizzleRepositories } from './repositories/drizzle.js';
+export { DrizzleGitHubInstallationRepository } from './repositories/containerExecution.js';
+export * as schema from './db/schema.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,2EAA2E;AAC3E,qFAAqF;AACrF,qFAAqF;AACrF,uFAAuF;AACvF,6EAA6E;AAC7E,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,KAAK,EAA4B,MAAM,aAAa,CAAA;AACtF,OAAO,EAAE,kBAAkB,EAA6B,MAAM,gBAAgB,CAAA;AAC9E,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AAC5C,OAAO,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAA;AAClD,OAAO,EAAE,+BAA+B,EAAE,MAAM,oBAAoB,CAAA;AAEpE,oFAAoF;AACpF,oFAAoF;AACpF,qFAAqF;AACrF,0FAA0F;AAC1F,OAAO,EACL,iBAAiB,EACjB,kBAAkB,EAClB,yBAAyB,GAE1B,MAAM,qBAAqB,CAAA;AAC5B,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,wBAAwB,EAAE,MAAM,qBAAqB,CAAA;AACnG,OAAO,EAAE,cAAc,EAAiC,MAAM,gBAAgB,CAAA;AAC9E,OAAO,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAA;AACzC,OAAO,EAAE,yBAAyB,EAAyB,MAAM,2BAA2B,CAAA;AAC5F,OAAO,EAAE,mCAAmC,EAAE,MAAM,sCAAsC,CAAA;AAC1F,OAAO,KAAK,MAAM,MAAM,gBAAgB,CAAA"}

package/dist/main.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=main.d.ts.map

package/dist/main.d.ts.map

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

package/dist/main.js

@@ -0,0 +1,9 @@
+import { logger } from '@cat-factory/server';
+import { start } from './server.js';
+// Default entrypoint: `pnpm build` then `node dist/main.js`. Requires DATABASE_URL;
+// set PORT to override the listen port.
+start().catch((err) => {
+    logger.error({ err: err instanceof Error ? err.message : String(err) }, 'failed to start');
+    process.exit(1);
+});
+//# sourceMappingURL=main.js.map

package/dist/main.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"main.js","sourceRoot":"","sources":["../src/main.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAA;AAC5C,OAAO,EAAE,KAAK,EAAE,MAAM,aAAa,CAAA;AAEnC,oFAAoF;AACpF,wCAAwC;AACxC,KAAK,EAAE,CAAC,KAAK,CAAC,CAAC,GAAY,EAAE,EAAE;IAC7B,MAAM,CAAC,KAAK,CAAC,EAAE,GAAG,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,EAAE,iBAAiB,CAAC,CAAA;IAC1F,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;AACjB,CAAC,CAAC,CAAA"}

package/dist/modelProvider.d.ts

@@ -0,0 +1,6 @@
+import type { ApiKeyService, LocalModelEndpointService } from '@cat-factory/integrations';
+import type { ModelProviderResolver } from '@cat-factory/kernel';
+/** The base URL for a direct provider: env override (e.g. QWEN_BASE_URL), else default. */
+export declare function baseUrlForNode(provider: string, env: NodeJS.ProcessEnv): string | undefined;
+export declare function createNodeModelProviderResolver(env: NodeJS.ProcessEnv, apiKeys: ApiKeyService | undefined, localModelEndpoints?: LocalModelEndpointService): ModelProviderResolver;
+//# sourceMappingURL=modelProvider.d.ts.map

package/dist/modelProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"modelProvider.d.ts","sourceRoot":"","sources":["../src/modelProvider.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,aAAa,EAAE,yBAAyB,EAAE,MAAM,2BAA2B,CAAA;AACzF,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAA;AAuBhE,2FAA2F;AAC3F,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,CAAC,UAAU,GAAG,MAAM,GAAG,SAAS,CAG3F;AAED,wBAAgB,+BAA+B,CAC7C,GAAG,EAAE,MAAM,CAAC,UAAU,EACtB,OAAO,EAAE,aAAa,GAAG,SAAS,EAClC,mBAAmB,CAAC,EAAE,yBAAyB,GAC9C,qBAAqB,CAqDvB"}

package/dist/modelProvider.js

@@ -0,0 +1,72 @@
+import {} from '@cat-factory/agents';
+import { DEEPSEEK_BASE_URL, MOONSHOT_BASE_URL, OPENAI_BASE_URL, OPENROUTER_BASE_URL, QWEN_BASE_URL, } from '@cat-factory/agents';
+import { bedrockRegistry } from '@cat-factory/provider-bedrock';
+import { cloudflareRestRegistry } from '@cat-factory/provider-cloudflare';
+import { createLangfuseSink } from '@cat-factory/observability-langfuse';
+import { createScopedModelProviderResolver } from '@cat-factory/server';
+// The Node deployment's ModelProvider RESOLVER: builds a per-scope provider from the
+// DB-backed API-key pool (account/workspace/user), plus opt-in registries that need no
+// per-scope key — AWS Bedrock (when AWS creds/region are set) and Cloudflare Workers AI
+// over REST (when CLOUDFLARE_ACCOUNT_ID + CLOUDFLARE_API_TOKEN are set). There is no
+// Workers AI binding on Node, so `workers-ai` is served via the Cloudflare REST flavour.
+// Inline calls are wrapped for Langfuse exactly like the proxied path when configured.
+const NODE_BASE_URLS = {
+    openai: OPENAI_BASE_URL,
+    qwen: QWEN_BASE_URL,
+    deepseek: DEEPSEEK_BASE_URL,
+    moonshot: MOONSHOT_BASE_URL,
+    openrouter: OPENROUTER_BASE_URL,
+    // `litellm` has no default: its base URL is the operator's own gateway, supplied via
+    // LITELLM_BASE_URL (honored automatically by baseUrlForNode's `${PROVIDER}_BASE_URL`).
+};
+/** The base URL for a direct provider: env override (e.g. QWEN_BASE_URL), else default. */
+export function baseUrlForNode(provider, env) {
+    // `||` not `??`: a set-but-blank override must fall back to the default.
+    return env[`${provider.toUpperCase()}_BASE_URL`] || NODE_BASE_URLS[provider];
+}
+export function createNodeModelProviderResolver(env, apiKeys, localModelEndpoints) {
+    const extraRegistries = [];
+    // Opt-in Cloudflare Workers AI over REST.
+    if (env.CLOUDFLARE_ACCOUNT_ID && env.CLOUDFLARE_API_TOKEN) {
+        extraRegistries.push(cloudflareRestRegistry({
+            accountId: env.CLOUDFLARE_ACCOUNT_ID,
+            apiToken: env.CLOUDFLARE_API_TOKEN,
+            gateway: env.CLOUDFLARE_AI_GATEWAY,
+        }));
+    }
+    // Opt-in Bedrock: registered only when a region is configured.
+    if (env.BEDROCK_REGION) {
+        const supportedModels = env.BEDROCK_MODELS?.split(',')
+            .map((m) => m.trim())
+            .filter(Boolean);
+        extraRegistries.push(bedrockRegistry({
+            region: env.BEDROCK_REGION,
+            accessKeyId: env.AWS_ACCESS_KEY_ID,
+            secretAccessKey: env.AWS_SECRET_ACCESS_KEY,
+            sessionToken: env.AWS_SESSION_TOKEN,
+            supportedModels: supportedModels?.length ? supportedModels : undefined,
+        }));
+    }
+    const instrument = env.LANGFUSE_ENABLED?.trim() === 'true' &&
+        env.LANGFUSE_PUBLIC_KEY?.trim() &&
+        env.LANGFUSE_SECRET_KEY?.trim()
+        ? {
+            traceSink: createLangfuseSink({
+                publicKey: env.LANGFUSE_PUBLIC_KEY.trim(),
+                secretKey: env.LANGFUSE_SECRET_KEY.trim(),
+                baseUrl: env.LANGFUSE_BASE_URL?.trim() || undefined,
+            }),
+            recordPrompts: env.LLM_RECORD_PROMPTS?.trim() !== 'false',
+        }
+        : undefined;
+    return createScopedModelProviderResolver({
+        apiKeys,
+        baseUrlFor: (provider) => baseUrlForNode(provider, env),
+        extraRegistries,
+        localEndpointsFor: localModelEndpoints
+            ? (userId) => localModelEndpoints.listResolved(userId)
+            : undefined,
+        instrument,
+    });
+}
+//# sourceMappingURL=modelProvider.js.map

package/dist/modelProvider.js.map

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

package/dist/realtime.d.ts

@@ -0,0 +1,62 @@
+import type { IncomingMessage } from 'node:http';
+import type { Duplex } from 'node:stream';
+import type { Block, BootstrapJob, ConsensusSession, ClarityReview, ExecutionInstance, LlmCallActivity, Notification, RequirementReview } from '@cat-factory/contracts';
+import type { ExecutionEventPublisher } from '@cat-factory/kernel';
+import { type AuthConfig } from '@cat-factory/server';
+import { WebSocket } from 'ws';
+/** The minimal logger shape this module needs (a pino logger satisfies it). */
+interface RealtimeLogger {
+    info(obj: object, msg?: string): void;
+    warn(obj: object, msg?: string): void;
+}
+/** The subset of a Node HTTP/HTTP2 server we attach the upgrade listener to. */
+interface UpgradableServer {
+    on(event: 'upgrade', listener: (request: IncomingMessage, socket: Duplex, head: Buffer) => void): void;
+}
+/**
+ * Per-workspace subscriber registry. Every browser subscribed to a workspace's stream
+ * converges here, so a published event fans out to all of them. In-memory and
+ * single-process: the Node service runs as one process (unlike the Worker's globally
+ * addressed Durable Object), which is the right model for the self-hosted / local
+ * deployments this facade targets. A multi-replica deployment would need a shared bus
+ * (Postgres LISTEN/NOTIFY) in front of this — a follow-up, not needed for local mode.
+ */
+export declare class NodeRealtimeHub {
+    private readonly rooms;
+    /** Add a socket to a workspace's room; it is reaped on close/error. */
+    subscribe(workspaceId: string, socket: WebSocket): void;
+    private unsubscribe;
+    /** Fan a pre-serialised JSON event out to every socket on a workspace's stream. */
+    broadcast(workspaceId: string, payload: string): void;
+}
+/**
+ * Pushes execution/board events to the {@link NodeRealtimeHub}, which fans them out to
+ * subscribed browsers. The event shapes are IDENTICAL to the Worker's
+ * `DurableObjectEventPublisher`, so the SPA's stream handling is runtime-agnostic.
+ * Best-effort: a publish failure must never break a state transition (the persisted
+ * row is the source of truth and clients reconcile on reconnect), so each publish
+ * swallows its own errors.
+ */
+export declare class NodeEventPublisher implements ExecutionEventPublisher {
+    private readonly hub;
+    constructor(hub: NodeRealtimeHub);
+    executionChanged(workspaceId: string, instance: ExecutionInstance, block?: Block | null): Promise<void>;
+    boardChanged(workspaceId: string, reason: string, _blockId?: string | null): Promise<void>;
+    bootstrapChanged(workspaceId: string, job: BootstrapJob, block?: Block | null): Promise<void>;
+    notificationChanged(workspaceId: string, notification: Notification): Promise<void>;
+    llmCallObserved(workspaceId: string, activity: LlmCallActivity): Promise<void>;
+    requirementReviewChanged(workspaceId: string, review: RequirementReview): Promise<void>;
+    consensusSessionChanged(workspaceId: string, session: ConsensusSession): Promise<void>;
+    clarityReviewChanged(workspaceId: string, review: ClarityReview): Promise<void>;
+    private publish;
+}
+/**
+ * Attach the real-time WebSocket transport to a running Node HTTP server: accept
+ * `GET /workspaces/:ws/events` upgrades (authorising the `?ticket=` exactly like the
+ * shared EventsController), register each socket into the {@link NodeRealtimeHub}, and
+ * run a heartbeat that terminates dead connections. Returns a stop function that clears
+ * the heartbeat and closes the WS server (call it on graceful shutdown).
+ */
+export declare function attachRealtime(server: UpgradableServer, hub: NodeRealtimeHub, auth: AuthConfig, log: RealtimeLogger): () => void;
+export {};
+//# sourceMappingURL=realtime.d.ts.map

package/dist/realtime.d.ts.map

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