@north-light/crouter 0.3.154

package/dist/daemon/api/server.js

@@ -0,0 +1,258 @@
+// server.ts — the crtrd HTTP+WS API server (spec §4, esp. §4.1/§5). A-9.
+//
+// ONE `http.Server`, bound TWICE (the dockerd model, §4.1):
+//   - the unix socket at `apiSocketPath()` — ALWAYS bound, owner-only (mode
+//     0600 = the fs-perms-are-auth model);
+//   - an opt-in TCP listener, bound only when `--tcp <host:port>` / `CRTRD_TCP`
+//     is set (a fronting edge owns auth there).
+// crtrd applies NO auth to either listener (hard constraint, §1).
+//
+// Non-upgrade requests flow through the hand-rolled `Router` (A-6) loaded with
+// every handler route table (A-7). `GET /v1/nodes/:id/attach` upgrades are
+// handed to `handleAttachUpgrade` (A-8, the WS attach bridge with
+// attach-implies-revive); every OTHER upgrade path destroys the socket, and an
+// unhandled upgrade error destroys the socket — it NEVER throws (mirrors the web
+// server's belt-and-suspenders upgrade guard, `clients/web/server.ts`).
+//
+// The structural template is `clients/web/server.ts:566,708-747`: one
+// `createServer` + a manual `upgrade` handler routing only attach paths.
+import { createServer } from 'node:http';
+import { chmodSync, existsSync, unlinkSync } from 'node:fs';
+import { apiSocketPath } from '../../core/canvas/paths.js';
+import { emitEvent } from '../../core/events/emit.js';
+import { Router } from './router.js';
+import { handleAttachUpgrade } from './bridge.js';
+import { attachRoutes } from './handlers/attach.js';
+import { canvasRoutes } from './handlers/canvas.js';
+import { daemonRoutes } from './handlers/daemon.js';
+import { fileRoutes } from './handlers/files.js';
+import { focusRoutes } from './handlers/focus.js';
+import { healthRoutes } from './handlers/health.js';
+import { humanRoutes } from './handlers/human.js';
+import { inboxRoutes } from './handlers/inbox.js';
+import { messageRoutes } from './handlers/messages.js';
+import { modelAuthRoutes } from './handlers/modelauth.js';
+import { nodeRoutes } from './handlers/nodes.js';
+import { profileRoutes } from './handlers/profiles.js';
+import { reportRoutes } from './handlers/reports.js';
+import { subscriptionRoutes } from './handlers/subscriptions.js';
+import { cronRoutes } from './handlers/crons.js';
+import { worktreeRoutes } from './handlers/worktree.js';
+/** Build the Router loaded with every handler route table (A-7). The order is
+ *  irrelevant — the matcher is exact method+path — but `healthRoutes` (which
+ *  owns the unversioned `/healthz`) is registered first for clarity. */
+function buildRouter() {
+    return new Router()
+        .registerAll(healthRoutes)
+        .registerAll(daemonRoutes)
+        .registerAll(nodeRoutes)
+        .registerAll(worktreeRoutes)
+        .registerAll(messageRoutes)
+        .registerAll(reportRoutes)
+        .registerAll(attachRoutes)
+        .registerAll(canvasRoutes)
+        .registerAll(fileRoutes)
+        .registerAll(focusRoutes)
+        .registerAll(subscriptionRoutes)
+        .registerAll(cronRoutes)
+        .registerAll(profileRoutes)
+        .registerAll(modelAuthRoutes)
+        .registerAll(humanRoutes)
+        .registerAll(inboxRoutes);
+}
+/** Is this request an attach upgrade — `GET /v1/nodes/{id}/attach` — and if so,
+ *  what is `{id}`? Returns null for any non-attach path (the caller destroys the
+ *  socket). The id is captured raw; `handleAttachUpgrade` does the
+ *  `isSafeNodeId` + existence guards (§5.1). */
+function attachNodeId(method, pathname) {
+    if (method.toUpperCase() !== 'GET')
+        return null;
+    const segs = pathname.split('/').filter((s) => s.length > 0);
+    // /v1/nodes/:id/attach
+    if (segs.length !== 4)
+        return null;
+    if (segs[0] !== 'v1' || segs[1] !== 'nodes' || segs[3] !== 'attach')
+        return null;
+    const id = segs[2];
+    if (id === undefined || id === '')
+        return null;
+    return decodeURIComponent(id);
+}
+/** Parse a `host:port` (or `:port`) TCP spec. Returns null on a malformed spec
+ *  so a bad `CRTRD_TCP` degrades to socket-only rather than crashing boot. */
+function parseTcp(spec) {
+    const trimmed = spec.trim();
+    if (trimmed === '')
+        return null;
+    const idx = trimmed.lastIndexOf(':');
+    if (idx < 0)
+        return null;
+    const host = trimmed.slice(0, idx);
+    const portText = trimmed.slice(idx + 1);
+    const port = Number(portText);
+    if (!Number.isInteger(port) || port < 0 || port > 65535)
+        return null;
+    return { host: host === '' ? '0.0.0.0' : host, port };
+}
+/** Close one http.Server, dropping idle keep-alives so the callback fires. */
+function closeServer(server) {
+    return new Promise((resolve) => {
+        try {
+            server.closeAllConnections();
+        }
+        catch {
+            /* older runtimes lack this — best-effort */
+        }
+        server.close(() => resolve());
+    });
+}
+/** Create and start the crtrd API server (A-9). Returns immediately with a
+ *  `close()` handle; the listeners bind asynchronously (a unix socket's file is
+ *  created on `listen`, so its 0600 chmod happens in the listen callback). A
+ *  bind failure or a post-listen accept error is emitted and swallowed — it must
+ *  NEVER become an unhandled 'error' that crashes the daemon.
+ *
+ *  NOTE (correction to the plan's "one http.Server bound twice"): a Node
+ *  `net.Server`/`http.Server` binds exactly ONE handle — a second `.listen()`
+ *  on the same instance throws `ERR_SERVER_ALREADY_LISTEN`. So the two listeners
+ *  are two `http.Server` instances SHARING the same request + upgrade handler
+ *  functions (the standard way to bind one logical API to two transports). The
+ *  Router and attach bridge are process-wide singletons, so both servers route
+ *  into identical state. */
+export function createApiServer(opts = {}) {
+    const router = buildRouter();
+    const sockPath = apiSocketPath();
+    // Shared request handler. The router's `handle` is total: it never throws and
+    // turns every failure (no route, bad body, handler throw) into a JSON
+    // ErrorBody. The `void` + `.catch` is belt-and-suspenders against an
+    // unexpected rejection.
+    const onRequest = (req, res) => {
+        void router.handle(req, res).catch((err) => {
+            emitEvent({
+                event: 'api.request.failed',
+                level: 'error',
+                error: err instanceof Error ? err : new Error(String(err)),
+            });
+            try {
+                if (!res.headersSent) {
+                    res.writeHead(500, { 'content-type': 'application/json; charset=utf-8' });
+                }
+                res.end(JSON.stringify({ error: { code: 'internal', message: 'internal error' } }));
+            }
+            catch {
+                /* response already gone */
+            }
+        });
+    };
+    // Shared upgrade handler: only `GET /v1/nodes/:id/attach` is served; every
+    // other upgrade path destroys the socket, and an unhandled error destroys the
+    // socket — it never throws.
+    const onUpgrade = (req, socket, head) => {
+        // A raw upgrade socket with no 'error' listener throws on a write to a reset
+        // peer — attach one before we ever write/destroy it.
+        socket.on('error', () => {
+            /* peer reset mid-handshake — destroyed below or already destroyed */
+        });
+        try {
+            const url = new URL(req.url ?? '/', 'http://127.0.0.1');
+            const nodeId = attachNodeId(req.method ?? 'GET', url.pathname);
+            if (nodeId === null) {
+                // Not an attach upgrade — no other upgrade path is served.
+                socket.destroy();
+                return;
+            }
+            // handleAttachUpgrade owns the handshake AND never throws (it refuses with
+            // a plain HTTP error or closes the WS post-handshake). The `.catch` is a
+            // final safety net.
+            void handleAttachUpgrade(req, socket, head, nodeId).catch(() => {
+                try {
+                    socket.destroy();
+                }
+                catch {
+                    /* already gone */
+                }
+            });
+        }
+        catch {
+            // Never let an upgrade-handler throw escape and crash the daemon.
+            try {
+                socket.destroy();
+            }
+            catch {
+                /* ignore */
+            }
+        }
+    };
+    const bindErrorHandler = (server) => {
+        // A bind failure or post-listen accept error must not be an unhandled
+        // 'error' that crashes the process — emit and carry on (web server's n9).
+        server.on('error', (err) => {
+            emitEvent({ event: 'api.server.failed', level: 'error', error: err });
+        });
+    };
+    // -------------------------------------------------------------------------
+    // Unix socket — ALWAYS bound. Unlink any stale socket first (mirror
+    // broker.ts's listener setup), listen, then chmod 0600 once the file exists.
+    // -------------------------------------------------------------------------
+    const socketServer = createServer(onRequest);
+    socketServer.on('upgrade', onUpgrade);
+    bindErrorHandler(socketServer);
+    try {
+        if (existsSync(sockPath))
+            unlinkSync(sockPath);
+    }
+    catch {
+        /* a fresh listen below will surface a real problem */
+    }
+    socketServer.listen(sockPath, () => {
+        try {
+            chmodSync(sockPath, 0o600);
+        }
+        catch (err) {
+            emitEvent({
+                event: 'api.socket.chmod_failed',
+                level: 'error',
+                error: err instanceof Error ? err : new Error(String(err)),
+            });
+        }
+    });
+    // -------------------------------------------------------------------------
+    // TCP — opt-in only. A SECOND http.Server sharing the same handlers.
+    // -------------------------------------------------------------------------
+    let tcpServer;
+    const tcpSpec = opts.tcp ?? process.env['CRTRD_TCP'];
+    if (tcpSpec !== undefined && tcpSpec !== '') {
+        const parsed = parseTcp(tcpSpec);
+        if (parsed === null) {
+            emitEvent({
+                event: 'api.tcp.invalid',
+                level: 'error',
+                error: new Error(`invalid CRTRD_TCP/--tcp spec: ${tcpSpec}`),
+            });
+        }
+        else {
+            tcpServer = createServer(onRequest);
+            tcpServer.on('upgrade', onUpgrade);
+            bindErrorHandler(tcpServer);
+            tcpServer.listen(parsed.port, parsed.host);
+        }
+    }
+    let closed = false;
+    const close = async () => {
+        if (closed)
+            return;
+        closed = true;
+        await Promise.all([
+            closeServer(socketServer),
+            tcpServer !== undefined ? closeServer(tcpServer) : Promise.resolve(),
+        ]);
+        try {
+            if (existsSync(sockPath))
+                unlinkSync(sockPath);
+        }
+        catch {
+            /* best-effort cleanup */
+        }
+    };
+    return { close };
+}

package/dist/daemon/control.d.ts

@@ -0,0 +1,21 @@
+/** What crtrd exposes to handlers that act on the daemon process itself. */
+export interface DaemonControl {
+    /** This daemon's epoch id. */
+    epoch: string;
+    /** Schedule the handover: this daemon answers now, then after a bounded
+     *  grace tears its fleet down, releases its claim, spawns a successor on the
+     *  currently selected runtime generation, and exits.
+     *
+     *  Returns the grace it will wait. Idempotent — a second request while one is
+     *  already scheduled returns the same grace and schedules nothing new, so an
+     *  agent that retries cannot stack handovers. */
+    requestHandover(): {
+        graceMs: number;
+    };
+}
+/** Bind this process's control surface. Called once, by `runDaemon`. */
+export declare function bindDaemonControl(control: DaemonControl): void;
+/** Release the binding (cleanup, and test isolation). */
+export declare function clearDaemonControl(): void;
+/** The bound control surface, or null when this process is not a live daemon. */
+export declare function boundDaemonControl(): DaemonControl | null;

package/dist/daemon/control.js

@@ -0,0 +1,22 @@
+// The daemon's self-control seam — how an API handler reaches the ONE live
+// `runDaemon` closure that owns this process's epoch, fleet, and claim.
+//
+// Handlers are module-level route tables built before (and independently of)
+// `runDaemon`, so they cannot close over its internals. `bindDaemonControl` is
+// the same pattern `bindFleet` uses for the fleet registry: crtrd binds exactly
+// one control surface at startup, and a handler calls it through
+// `boundDaemonControl()`. Unbound (a test harness, or an API server hosted
+// outside crtrd) reads as null so the handler answers 503 rather than throwing.
+let bound = null;
+/** Bind this process's control surface. Called once, by `runDaemon`. */
+export function bindDaemonControl(control) {
+    bound = control;
+}
+/** Release the binding (cleanup, and test isolation). */
+export function clearDaemonControl() {
+    bound = null;
+}
+/** The bound control surface, or null when this process is not a live daemon. */
+export function boundDaemonControl() {
+    return bound;
+}

package/dist/daemon/cron-run.d.ts

@@ -0,0 +1,64 @@
+import { type Cron, type CronRunRecord } from '../core/canvas/crons.js';
+/** Output head caps for the run log (spec: "capped, e.g. 4KB"). */
+export declare const CRON_OUTPUT_HEAD_BYTES: number;
+/** One id per daemon process instance — distinguishes THIS process's own
+ *  in-flight run leases from a stale 'running' row a prior (crashed/restarted)
+ *  daemon left behind. */
+export declare const cronDaemonInstanceId: `${string}-${string}-${string}-${string}-${string}`;
+export interface RunDueCronOptions {
+    /** Invoked synchronously the instant each settlement promise is created, so
+     *  the caller can register it for a graceful-teardown drain. */
+    register?: (work: Promise<void>) => void;
+    /** Broker-capacity admission for a run that will LAUNCH OR REVIVE a node
+     *  (`cronLaunchesNode`). Returns false when the live fleet is at the
+     *  automatic-revive cap; the daemon wires in its own `hasBrokerCapacity`
+     *  (crtrd.ts), which owns the fleet count and the throttled capacity event.
+     *  Absent → every run is admitted (out-of-band/test callers own no fleet). */
+    hasBrokerCapacity?: () => boolean;
+}
+/** Will this cron's run consume broker capacity? True when its armed sink
+ *  births a node, or its command invokes a node-launching crtr verb. A cron
+ *  that merely runs a shell command or sends a message reads false and is
+ *  never gated. */
+export declare function cronLaunchesNode(c: Cron): boolean;
+/** Recover stale 'running' rows left by a PRIOR daemon instance: a pid that is
+ *  not VERIFIABLY still the process this lease launched resets straight to
+ *  idle; a confirmed-live process group past its own run_timeout_s is killed
+ *  and settled as a timeout run through the SAME failure path a live timeout
+ *  takes (pause + escalation unless silent). Rows this SAME instance owns are
+ *  genuinely in flight and left alone.
+ *
+ *  The verification is `verifyLeasedCronRun`, not `isPidAlive`, and it is
+ *  FAIL-CLOSED: this row was written by a daemon life that has since ended, so
+ *  after a host reboot its `run_pid` names a slot in a dead kernel's pid space
+ *  that the OS has probably recycled, and the timeout comparison below is
+ *  trivially satisfied by any downtime. Liveness alone would therefore SIGTERM
+ *  a stranger's process group. Only a matching launch-time identity authorizes
+ *  the signal; everything else releases the lease. */
+export declare function recoverStaleCronLeases(now: number, options?: RunDueCronOptions): void;
+/** Kick off ONE cron run and return its settlement promise, resolving with
+ *  the settled run record (null = the idle→running lease was lost, or the row
+ *  was quarantined — nothing was recorded by THIS call). The subprocess
+ *  starts synchronously (spawn + lease + recurrence advance happen before
+ *  this returns); the promise resolves only after the child has CLOSED and
+ *  every durable transition — disposition/delivery, run record, lease
+ *  release, one-shot consumption — is written.
+ *
+ *  `outOfBand` (the `cron run` verb) takes the same lease but does NOT
+ *  advance a recurrence, does NOT consume a one-shot, and never
+ *  escalates/pauses — it delivers per disposition and hands the record back
+ *  to the invoker. */
+export declare function executeCron(c: Cron, opts: {
+    outOfBand: boolean;
+}): Promise<CronRunRecord | null>;
+/** The daemon's cron pass: expire clock-bounded rows, apply overlap policies,
+ *  then kick off every due active idle cron. Each child starts synchronously
+ *  but is NEVER awaited in the tick; returns one settlement promise per
+ *  admitted run.
+ *
+ *  A run that would launch or revive a node (`cronLaunchesNode`) is admitted
+ *  only while the fleet is under its automatic-revive cap. An unadmitted run is
+ *  DEFERRED, never consumed: nothing is recorded, no recurrence advances, no
+ *  one-shot is deleted, and no failure escalates — the row keeps its past-due
+ *  `fire_at` and is retried on the next poll once capacity frees up. */
+export declare function runDueCrons(now: number, options?: RunDueCronOptions): Promise<void>[];