@boardwalk-labs/engine 0.1.0

package/dist/server/routes/hooks.js

@@ -0,0 +1,88 @@
+// POST /hooks/:workflow/:triggerIndex — the webhook trigger endpoint, and this engine's v0
+// answer to MASTER_SPEC §10's open webhook-auth question (documented in SPEC §2.4):
+// per-workflow credentials live in *server* environment variables —
+//   token auth:     BOARDWALK_WEBHOOK_TOKEN__<NAME>   vs  `Authorization: Bearer <token>`
+//   signature auth: BOARDWALK_WEBHOOK_SECRET__<NAME>  vs  `X-Boardwalk-Signature: sha256=<hex>`
+//                   (HMAC-SHA256 over the raw request body)
+// where <NAME> is the workflow name upper-cased with `-` → `_`. Missing variable = 503 (fail
+// closed, hint names the variable); bad credential = 401. These are server config, not
+// workflow secrets, so they resolve from process.env — never from the engine's env map.
+import { createHash, createHmac, timingSafeEqual } from "node:crypto";
+import { HttpError, MAX_BODY_BYTES, jsonValueSchema, parseJsonBody, readBody, sendJson, } from "../http.js";
+export async function handleWebhook(ctx, workflowName, triggerIndexRaw) {
+    // The raw body is read up front: signature auth signs the exact bytes on the wire, before
+    // any JSON parsing can normalize them away.
+    const rawBody = await readBody(ctx.req, MAX_BODY_BYTES);
+    // One identical 404 for "no workflow", "no such trigger index", and "not a webhook
+    // trigger" — an unauthenticated caller learns nothing about what is deployed here.
+    const notFound = new HttpError(404, "NOT_FOUND", `No webhook trigger at /hooks/${workflowName}/${triggerIndexRaw}.`);
+    const workflow = ctx.engine.store.getWorkflow(workflowName);
+    if (workflow === null)
+        throw notFound;
+    if (!/^\d+$/.test(triggerIndexRaw))
+        throw notFound;
+    const trigger = workflow.manifest.triggers[Number(triggerIndexRaw)];
+    if (trigger === undefined || trigger.kind !== "webhook")
+        throw notFound;
+    if (trigger.auth === "token")
+        authorizeToken(ctx.req, workflowName);
+    else
+        authorizeSignature(ctx.req, workflowName, rawBody);
+    const input = rawBody.length === 0 ? null : parseJsonBody(rawBody, jsonValueSchema, "webhook payload");
+    const run = ctx.engine.startRun(workflowName, { input, triggerKind: "webhook" });
+    sendJson(ctx.res, 201, { run: { id: run.id, status: run.status } });
+}
+/** `BOARDWALK_WEBHOOK_<kind>__<NAME>`: the workflow name upper-cased, hyphens → underscores. */
+function webhookEnvVarName(kind, workflowName) {
+    return `BOARDWALK_WEBHOOK_${kind}__${workflowName.toUpperCase().replaceAll("-", "_")}`;
+}
+/**
+ * Read the trigger's credential from the server environment, failing CLOSED when unset: a
+ * webhook that nobody configured must never become an open trigger. Read lazily per request
+ * so an operator can fix the environment without redeploying workflows.
+ */
+function requiredCredential(kind, workflowName) {
+    const name = webhookEnvVarName(kind, workflowName);
+    const value = process.env[name];
+    if (value === undefined || value === "") {
+        throw new HttpError(503, "WEBHOOK_UNCONFIGURED", `Webhook auth for workflow "${workflowName}" is not configured on this server.`, `Set the environment variable ${name} and restart the server.`);
+    }
+    return value;
+}
+/** One generic 401 for every credential failure — no oracle for which part was wrong. */
+function unauthorized() {
+    return new HttpError(401, "UNAUTHORIZED", "Invalid webhook credentials.");
+}
+function authorizeToken(req, workflowName) {
+    const expected = requiredCredential("TOKEN", workflowName);
+    const header = req.headers.authorization;
+    if (header === undefined || !header.startsWith("Bearer "))
+        throw unauthorized();
+    if (!constantTimeEquals(header.slice("Bearer ".length), expected))
+        throw unauthorized();
+}
+function authorizeSignature(req, workflowName, rawBody) {
+    const secret = requiredCredential("SECRET", workflowName);
+    const header = req.headers["x-boardwalk-signature"];
+    if (typeof header !== "string")
+        throw unauthorized();
+    const match = /^sha256=([0-9a-f]{64})$/i.exec(header);
+    const presentedHex = match?.[1];
+    if (presentedHex === undefined)
+        throw unauthorized();
+    const presented = Buffer.from(presentedHex, "hex");
+    const computed = createHmac("sha256", secret).update(rawBody).digest();
+    // The regex pins 64 hex chars = 32 bytes = SHA-256 output, so the lengths already match;
+    // the explicit check keeps timingSafeEqual's equal-length precondition locally provable.
+    if (presented.length !== computed.length || !timingSafeEqual(presented, computed)) {
+        throw unauthorized();
+    }
+}
+/**
+ * Constant-time string equality. Why hash-then-compare: timingSafeEqual demands equal-length
+ * inputs, and comparing fixed-size digests both satisfies that and avoids leaking the
+ * expected token's length through an early length check.
+ */
+function constantTimeEquals(a, b) {
+    return timingSafeEqual(createHash("sha256").update(a).digest(), createHash("sha256").update(b).digest());
+}

package/dist/server/routes/router.d.ts

@@ -0,0 +1,15 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { Engine } from "../../engine.js";
+/** Everything a route handler may touch. The server only calls engine/store methods. */
+export interface RouteContext {
+    engine: Engine;
+    req: IncomingMessage;
+    res: ServerResponse;
+    url: URL;
+    log: (line: string) => void;
+}
+/**
+ * Resolve and run the handler for one request. Throws HttpError for routing failures; the
+ * server's top-level catch renders them, so handlers never touch error formatting.
+ */
+export declare function dispatchRequest(engine: Engine, req: IncomingMessage, res: ServerResponse, log: (line: string) => void): Promise<void>;

package/dist/server/routes/router.js

@@ -0,0 +1,75 @@
+// URL → handler resolution for the engine server. One flat match over decoded path segments —
+// the route table is small enough that a real trie/middleware stack would be pure ceremony.
+// Method mismatches on a known path get 405 + Allow (not 404), so clients can tell "wrong
+// verb" from "no such thing".
+import { HttpError } from "../http.js";
+import { handleCancelRun, handleGetRun, handleListEvents, handleListRuns, handleListWorkflows, handleStartRun, } from "./api.js";
+import { handleWebhook } from "./hooks.js";
+import { handleStreamRun } from "./stream.js";
+import { handleUiPage } from "./ui.js";
+/**
+ * Resolve and run the handler for one request. Throws HttpError for routing failures; the
+ * server's top-level catch renders them, so handlers never touch error formatting.
+ */
+export async function dispatchRequest(engine, req, res, log) {
+    const method = req.method ?? "GET";
+    // The base never matters — routes only read pathname + searchParams.
+    const url = new URL(req.url ?? "/", "http://localhost");
+    const methods = matchRoute(decodePathSegments(url.pathname));
+    if (methods === null) {
+        throw new HttpError(404, "NOT_FOUND", `No such route: ${url.pathname}`);
+    }
+    const handler = methods[method];
+    if (handler === undefined) {
+        // Allow rides on setHeader so the shared error renderer needs no special 405 case.
+        res.setHeader("allow", Object.keys(methods).join(", "));
+        throw new HttpError(405, "METHOD_NOT_ALLOWED", `${method} is not allowed for ${url.pathname}.`);
+    }
+    await handler({ engine, req, res, url, log });
+}
+function decodePathSegments(pathname) {
+    return pathname
+        .split("/")
+        .filter((segment) => segment !== "")
+        .map((segment) => {
+        try {
+            return decodeURIComponent(segment);
+        }
+        catch {
+            throw new HttpError(400, "VALIDATION", "Malformed percent-encoding in URL path.");
+        }
+    });
+}
+/** The route table: path segments → method → handler. Null means no such resource (404). */
+function matchRoute(segments) {
+    const [first, second, third, fourth] = segments;
+    if (segments.length === 0)
+        return { GET: handleUiPage };
+    if (first === "api" && second === "workflows") {
+        if (segments.length === 2)
+            return { GET: handleListWorkflows };
+        if (segments.length === 4 && third !== undefined && fourth === "runs") {
+            return { POST: (ctx) => handleStartRun(ctx, third) };
+        }
+    }
+    if (first === "api" && second === "runs") {
+        if (segments.length === 2)
+            return { GET: handleListRuns };
+        if (third === undefined)
+            return null;
+        if (segments.length === 3)
+            return { GET: (ctx) => handleGetRun(ctx, third) };
+        if (segments.length === 4) {
+            if (fourth === "events")
+                return { GET: (ctx) => handleListEvents(ctx, third) };
+            if (fourth === "cancel")
+                return { POST: (ctx) => handleCancelRun(ctx, third) };
+            if (fourth === "stream")
+                return { GET: (ctx) => handleStreamRun(ctx, third) };
+        }
+    }
+    if (first === "hooks" && segments.length === 3 && second !== undefined && third !== undefined) {
+        return { POST: (ctx) => handleWebhook(ctx, second, third) };
+    }
+    return null;
+}

package/dist/server/routes/stream.d.ts

@@ -0,0 +1,2 @@
+import type { RouteContext } from "./router.js";
+export declare function handleStreamRun(ctx: RouteContext, runId: string): void;

package/dist/server/routes/stream.js

@@ -0,0 +1,79 @@
+// GET /api/runs/:id/stream — the SSE live tail (SPEC §2.4, MASTER_SPEC §2.5): replay
+// persisted events after the resume cursor, then follow live ones. Every frame carries
+// `id: <cursor>`, so a dropped client reconnects with Last-Event-ID and misses nothing —
+// cursors are run-global and independent of channel filtering, which keeps filtered resumes
+// gap-free.
+import { matchesChannels } from "@boardwalk-labs/workflow";
+import { HttpError, parseChannelSelection, parseNonNegativeInt } from "../http.js";
+/** SSE comment frames keep intermediaries from idling out a quiet tail. */
+const PING_INTERVAL_MS = 15_000;
+export function handleStreamRun(ctx, runId) {
+    // All validation happens before headers go out — after writeHead the JSON error contract
+    // is unreachable.
+    if (ctx.engine.store.getRun(runId) === null) {
+        throw new HttpError(404, "NOT_FOUND", `Unknown run: ${runId}`);
+    }
+    const channels = parseChannelSelection(ctx.url);
+    const afterCursor = resolveResumeCursor(ctx.req, ctx.url);
+    ctx.res.writeHead(200, {
+        "content-type": "text/event-stream",
+        "cache-control": "no-cache",
+        connection: "keep-alive",
+    });
+    // High-water mark of cursors already handled. It advances even for events the channel
+    // filter drops: a filtered-out cursor is "covered", and skipping it is not a gap.
+    let delivered = afterCursor;
+    const deliver = (row) => {
+        if (row.cursor <= delivered)
+            return;
+        delivered = row.cursor;
+        if (!matchesChannels(row.event, channels))
+            return;
+        if (ctx.res.writableEnded || ctx.res.destroyed)
+            return;
+        ctx.res.write(`id: ${String(row.cursor)}\ndata: ${JSON.stringify(row.event)}\n\n`);
+    };
+    // Why subscribe BEFORE reading the store: an event appended between "read store" and
+    // "subscribe" would be lost forever. Subscribing first means such events land in the
+    // backlog instead, and the high-water mark dedupes any the replay also saw.
+    let replaying = true;
+    const backlog = [];
+    const unsubscribe = ctx.engine.onEvent((row) => {
+        if (row.runId !== runId)
+            return;
+        if (replaying)
+            backlog.push(row);
+        else
+            deliver(row);
+    });
+    for (const row of ctx.engine.store.listEvents(runId, { afterCursor }))
+        deliver(row);
+    replaying = false;
+    for (const row of backlog.splice(0))
+        deliver(row);
+    const ping = setInterval(() => {
+        ctx.res.write(": ping\n\n");
+    }, PING_INTERVAL_MS);
+    // Why unref: a lingering tail must never hold the process open past server close.
+    ping.unref();
+    ctx.res.on("close", () => {
+        clearInterval(ping);
+        unsubscribe();
+    });
+}
+/**
+ * Where to resume from: the SSE-standard Last-Event-ID header wins (it is what browsers send
+ * on automatic reconnect), then `?after=`, then 0 (everything).
+ */
+function resolveResumeCursor(req, url) {
+    const header = req.headers["last-event-id"];
+    const value = Array.isArray(header) ? header[0] : header;
+    if (value !== undefined) {
+        const cursor = Number(value);
+        if (value.trim() === "" || !Number.isInteger(cursor) || cursor < 0) {
+            throw new HttpError(400, "VALIDATION", `Last-Event-ID must be a non-negative integer cursor (got "${value}").`);
+        }
+        return cursor;
+    }
+    return parseNonNegativeInt(url, "after", 0);
+}

package/dist/server/routes/ui.d.ts

@@ -0,0 +1,2 @@
+import type { RouteContext } from "./router.js";
+export declare function handleUiPage(ctx: RouteContext): void;

package/dist/server/routes/ui.js

@@ -0,0 +1,120 @@
+// GET / — the local run-log page (SPEC §2.4): one self-contained HTML document, no build
+// step, no external assets. It is a log viewer, not a console: list workflows, list recent
+// runs, click a run to tail it over the SSE endpoint. All rendering uses textContent — no
+// markup is ever built from API data, so nothing a workflow prints can inject into the page.
+export function handleUiPage(ctx) {
+    ctx.res.writeHead(200, { "content-type": "text/html; charset=utf-8" });
+    ctx.res.end(RUN_LOG_PAGE);
+}
+const RUN_LOG_PAGE = `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<title>Boardwalk run log</title>
+<style>
+  :root { color-scheme: light dark; }
+  body { font-family: system-ui, sans-serif; margin: 0; display: grid; grid-template-columns: 17rem 1fr; height: 100vh; }
+  aside { border-right: 1px solid #8884; padding: 1rem; overflow-y: auto; }
+  main { padding: 1rem; overflow-y: auto; display: flex; flex-direction: column; gap: 1rem; }
+  h1 { font-size: 1rem; margin: 0 0 0.75rem; }
+  h2 { font-size: 0.8rem; margin: 0 0 0.5rem; text-transform: uppercase; letter-spacing: 0.05em; opacity: 0.7; }
+  button.row { display: block; width: 100%; text-align: left; background: none; border: none; padding: 0.3rem 0.4rem; cursor: pointer; border-radius: 0.25rem; font: inherit; }
+  button.row:hover { background: #8882; }
+  #log { font-family: ui-monospace, monospace; font-size: 0.8rem; white-space: pre-wrap; flex: 1; border: 1px solid #8884; border-radius: 0.25rem; padding: 0.5rem; overflow-y: auto; min-height: 10rem; }
+  .muted { opacity: 0.6; }
+</style>
+</head>
+<body>
+<aside>
+  <h1>boardwalk</h1>
+  <h2>Workflows</h2>
+  <div id="workflows" class="muted">loading…</div>
+</aside>
+<main>
+  <section>
+    <h2>Recent runs</h2>
+    <div id="runs" class="muted">loading…</div>
+  </section>
+  <section style="display: flex; flex-direction: column; flex: 1;">
+    <h2 id="tail-title">Run log</h2>
+    <div id="log" class="muted">select a run to tail it</div>
+  </section>
+</main>
+<script>
+"use strict";
+let source = null;
+let selectedWorkflow = null;
+const el = (id) => document.getElementById(id);
+
+async function getJson(path) {
+  const res = await fetch(path);
+  if (!res.ok) throw new Error(path + " -> " + res.status);
+  return res.json();
+}
+
+function rowButton(label, onClick) {
+  const button = document.createElement("button");
+  button.className = "row";
+  button.textContent = label;
+  button.addEventListener("click", onClick);
+  return button;
+}
+
+async function loadWorkflows() {
+  const { workflows } = await getJson("/api/workflows");
+  const box = el("workflows");
+  box.replaceChildren();
+  box.className = "";
+  if (workflows.length === 0) {
+    box.className = "muted";
+    box.textContent = "none deployed";
+    return;
+  }
+  box.append(rowButton("all workflows", () => { selectedWorkflow = null; loadRuns(); }));
+  for (const workflow of workflows) {
+    box.append(rowButton(workflow.name, () => { selectedWorkflow = workflow.name; loadRuns(); }));
+  }
+}
+
+async function loadRuns() {
+  const filter = selectedWorkflow === null ? "" : "&workflow=" + encodeURIComponent(selectedWorkflow);
+  const { runs } = await getJson("/api/runs?limit=50" + filter);
+  const box = el("runs");
+  box.replaceChildren();
+  box.className = runs.length === 0 ? "muted" : "";
+  if (runs.length === 0) box.textContent = "no runs yet";
+  for (const run of runs) {
+    const when = new Date(run.createdAt).toLocaleString();
+    box.append(rowButton(run.status + " · " + when + " · " + run.id, () => tail(run.id)));
+  }
+}
+
+function describeEvent(event) {
+  if (event.kind === "run_status") {
+    return "status: " + event.status + (event.error ? " (" + event.error.code + ": " + event.error.message + ")" : "");
+  }
+  if (event.kind === "phase") return "phase: " + event.name;
+  if (event.kind === "output") return "output: " + JSON.stringify(event.value);
+  if (event.kind === "program_output") return "[" + event.stream + "] " + event.text.replace(/\\n$/, "");
+  return event.kind;
+}
+
+function tail(runId) {
+  if (source !== null) source.close();
+  el("tail-title").textContent = "Run " + runId;
+  const log = el("log");
+  log.replaceChildren();
+  log.className = "";
+  source = new EventSource("/api/runs/" + encodeURIComponent(runId) + "/stream?verbose=true");
+  source.onmessage = (message) => log.append(describeEvent(JSON.parse(message.data)) + "\\n");
+  source.onerror = () => log.append("(stream interrupted; retrying)\\n");
+}
+
+loadWorkflows();
+loadRuns();
+setInterval(loadRuns, 5000);
+</script>
+</body>
+</html>
+`;

package/dist/server/server.d.ts

@@ -0,0 +1,25 @@
+import type { Engine } from "../engine.js";
+export interface EngineServerOptions {
+    /** Default bind host when `listen` doesn't name one. Default 127.0.0.1. */
+    host?: string;
+    /** Server diagnostics (bind warnings, internal errors kept off the wire). Default: stderr. */
+    log?: (line: string) => void;
+}
+export interface EngineServer {
+    /** Bind and start serving. `port` 0 picks a free port; the resolved value reports it. */
+    listen(port: number, host?: string): Promise<{
+        port: number;
+    }>;
+    /** Stop accepting and drop open connections (SSE tails would otherwise hold close forever). */
+    close(): Promise<void>;
+}
+/**
+ * Hosts only the local machine can reach. Exported for direct testing — the bind warning
+ * hinges on this judgement.
+ */
+export declare function isLoopbackHost(host: string): boolean;
+/**
+ * Build (but do not bind) the HTTP server for an engine. Separate from the Engine itself so
+ * embedded consumers (`boardwalk dev`) never pay for an HTTP layer they don't use.
+ */
+export declare function createEngineServer(engine: Engine, opts?: EngineServerOptions): EngineServer;

package/dist/server/server.js

@@ -0,0 +1,67 @@
+// The engine's HTTP surface (SPEC §2.4): JSON API + SSE live tail + webhook triggers + the
+// local run-log page, on bare node:http. This file owns the socket lifecycle only — routing
+// lives in routes/router.ts, and every handler goes through engine/store methods, never SQL.
+//
+// Security posture (v1): bound to localhost by default; there is NO auth on this surface
+// beyond webhook auth, so binding wider logs a prominent warning and is the operator's call.
+import { createServer } from "node:http";
+import { sendError } from "./http.js";
+import { dispatchRequest } from "./routes/router.js";
+/**
+ * Hosts only the local machine can reach. Exported for direct testing — the bind warning
+ * hinges on this judgement.
+ */
+export function isLoopbackHost(host) {
+    return (host === "127.0.0.1" || host === "::1" || host === "localhost" || host === "::ffff:127.0.0.1");
+}
+/**
+ * Build (but do not bind) the HTTP server for an engine. Separate from the Engine itself so
+ * embedded consumers (`boardwalk dev`) never pay for an HTTP layer they don't use.
+ */
+export function createEngineServer(engine, opts = {}) {
+    const log = opts.log ??
+        ((line) => {
+            process.stderr.write(`${line}\n`);
+        });
+    const server = createServer((req, res) => {
+        // One catch for every route: handlers just throw, and the error contract stays uniform.
+        void dispatchRequest(engine, req, res, log).catch((err) => {
+            sendError(res, err, log);
+        });
+    });
+    return {
+        listen(port, host) {
+            const bindHost = host ?? opts.host ?? "127.0.0.1";
+            if (!isLoopbackHost(bindHost)) {
+                log(`WARNING: engine server binding to ${bindHost} — this surface has NO authentication ` +
+                    `beyond webhook auth (SPEC §2.4). Anyone who can reach it can start, cancel, and ` +
+                    `read runs. Only bind beyond loopback on a network you trust.`);
+            }
+            return new Promise((resolve, reject) => {
+                server.once("error", reject);
+                server.listen(port, bindHost, () => {
+                    server.removeListener("error", reject);
+                    const address = server.address();
+                    // A TCP listen always yields an AddressInfo; a string means a pipe, which would be
+                    // a programming error here.
+                    if (address === null || typeof address === "string") {
+                        reject(new Error("engine server did not bind to a TCP port"));
+                        return;
+                    }
+                    resolve({ port: address.port });
+                });
+            });
+        },
+        close() {
+            return new Promise((resolve, reject) => {
+                if (!server.listening) {
+                    resolve();
+                    return;
+                }
+                server.close((err) => (err !== undefined ? reject(err) : resolve()));
+                // SSE tails are long-lived by design; without this, close() never settles.
+                server.closeAllConnections();
+            });
+        },
+    };
+}

package/dist/server_main.d.ts

@@ -0,0 +1,46 @@
+import type { InferenceConfig } from "./agent/resolve.js";
+/** Fully-resolved server configuration — every field present, defaults applied. */
+export interface ServerConfig {
+    /** Where everything lives (SQLite DB, run dirs, artifacts). Created on boot if missing. */
+    dataDir: string;
+    /** Bind address. Loopback by default — the surface has no auth beyond webhook auth. */
+    host: string;
+    /** Listen port. 0 binds an ephemeral port (the resolved port is logged). */
+    port: number;
+    /** Default model + provider table for agent() leaves; undefined when none configured. */
+    inference: InferenceConfig | undefined;
+    /** Explicit BOARDWALK_ENV_FILE path; undefined means "use <dataDir>/.env if it exists". */
+    envFile: string | undefined;
+}
+/**
+ * Parse server config from an environment map. Pure (no filesystem, no process globals) so
+ * every default and failure mode is unit-testable; `main()` passes `process.env`.
+ */
+export declare function loadServerConfig(env: Record<string, string | undefined>): ServerConfig;
+/**
+ * Resolve the engine's secret/env source (SPEC §2.3 `secrets.get`): the configured
+ * BOARDWALK_ENV_FILE, else `<dataDir>/.env` when present. An explicitly named file that does
+ * not exist fails closed — a typo'd path silently falling back to process.env would make
+ * `secrets.get` read the wrong values with no warning.
+ */
+export declare function resolveEngineEnv(config: Pick<ServerConfig, "envFile" | "dataDir">): {
+    env: Record<string, string>;
+    envLabel: string;
+} | null;
+/** A booted server: the resolved port plus an idempotent teardown for signal handlers/tests. */
+export interface RunningServer {
+    port: number;
+    /** Stop accepting connections, then release the engine (scheduler loop + DB handle). */
+    shutdown(): Promise<void>;
+}
+/**
+ * Boot the engine + HTTP surface from a resolved config. Split from `main()` so the whole
+ * boot path (sweep, listen, startup logging, teardown) is testable without touching process
+ * signals or `process.exit`.
+ */
+export declare function startServer(config: ServerConfig, log: (line: string) => void): Promise<RunningServer>;
+/**
+ * The `boardwalk-server` entrypoint (invoked by bin/boardwalk-server.js). Owns the only
+ * process-global concerns in the package: process.env, signal handlers, and exit codes.
+ */
+export declare function main(): Promise<void>;