@boardwalk-labs/engine 0.1.0

package/dist/ids.d.ts

@@ -0,0 +1,7 @@
+export declare const ULID_LENGTH: number;
+/** Generate a ULID for the given timestamp (defaults to now). */
+export declare function ulid(timeMs?: number): string;
+/** True when `value` is a well-formed ULID (shape check only, not provenance). */
+export declare function isUlid(value: string): boolean;
+/** Recover the millisecond timestamp encoded in a ULID's time component. */
+export declare function ulidTime(id: string): number;

package/dist/ids.js

@@ -0,0 +1,42 @@
+// ULIDs — the engine's primary-key format (CODE_QUALITY §2.2): time-sortable, URL-safe,
+// no auto-increment integers. Implemented in-house: 26 chars of Crockford base32 over
+// 48 bits of timestamp + 80 bits of crypto randomness. Zero dependencies on purpose —
+// every dependency in a public package is supply-chain surface.
+import { randomBytes } from "node:crypto";
+const ENCODING = "0123456789ABCDEFGHJKMNPQRSTVWXYZ"; // Crockford base32 (no I, L, O, U)
+const TIME_LEN = 10;
+const RANDOM_LEN = 16;
+export const ULID_LENGTH = TIME_LEN + RANDOM_LEN;
+/** Generate a ULID for the given timestamp (defaults to now). */
+export function ulid(timeMs = Date.now()) {
+    if (!Number.isInteger(timeMs) || timeMs < 0 || timeMs > 2 ** 48 - 1) {
+        throw new RangeError(`ulid timestamp out of range: ${String(timeMs)}`);
+    }
+    let time = "";
+    let t = timeMs;
+    for (let i = 0; i < TIME_LEN; i++) {
+        time = ENCODING.charAt(t % 32) + time;
+        t = Math.floor(t / 32);
+    }
+    let rand = "";
+    for (const byte of randomBytes(RANDOM_LEN)) {
+        // Why modulo a byte: 256 % 32 === 0, so each character stays uniformly distributed.
+        rand += ENCODING.charAt(byte % 32);
+    }
+    return time + rand;
+}
+const ULID_RE = /^[0-9A-HJKMNP-TV-Z]{26}$/;
+/** True when `value` is a well-formed ULID (shape check only, not provenance). */
+export function isUlid(value) {
+    return ULID_RE.test(value);
+}
+/** Recover the millisecond timestamp encoded in a ULID's time component. */
+export function ulidTime(id) {
+    if (!isUlid(id))
+        throw new RangeError(`not a ULID: ${id}`);
+    let t = 0;
+    for (let i = 0; i < TIME_LEN; i++) {
+        t = t * 32 + ENCODING.indexOf(id.charAt(i));
+    }
+    return t;
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { Engine, type EngineOptions, type DeployArgs, type AuthorizeMcpServerOptions, } from "./engine.js";
+export type { InferenceConfig, ProviderConfig } from "./agent/resolve.js";
+export type { EventRow, RunRow, WorkflowRow, ArtifactRow, RunStatus, TriggerKind, RunErrorShape, } from "./store/store.js";
+export { EngineError, type EngineErrorCode } from "./errors.js";
+export { isTerminal } from "./run/supervisor.js";
+export { createEngineServer } from "./server/server.js";

package/dist/index.js

@@ -0,0 +1,8 @@
+// @boardwalk-labs/engine — the open-source single-node runtime.
+//
+// Two consumers, one implementation (SPEC §1): the CLI embeds it for `boardwalk dev`
+// (construct → runOnce → close), the server binary runs it long-lived (construct → start).
+export { Engine, } from "./engine.js";
+export { EngineError } from "./errors.js";
+export { isTerminal } from "./run/supervisor.js";
+export { createEngineServer } from "./server/server.js";

package/dist/json_value.d.ts

@@ -0,0 +1,7 @@
+import type { JsonValue } from "@boardwalk-labs/workflow";
+/** True when `value` is a plain JSON tree (no functions, symbols, bigints, class instances). */
+export declare function isJsonValue(value: unknown): value is JsonValue;
+/** Narrow to a plain object (prototype Object.prototype or null — no class instances). */
+export declare function isPlainObject(value: unknown): value is Record<string, unknown>;
+/** Narrow to JsonValue or throw — used where a JSON shape is a protocol requirement. */
+export declare function asJsonValue(value: unknown, what: string): JsonValue;

package/dist/json_value.js

@@ -0,0 +1,29 @@
+// Runtime narrowing for JsonValue. Values arriving over the run process's JSON-serialized IPC
+// channel are JSON by construction, but "by construction" is exactly what trust boundaries
+// don't get to assume (CODE_QUALITY §2.1) — so narrow structurally instead of casting.
+import { EngineError } from "./errors.js";
+/** True when `value` is a plain JSON tree (no functions, symbols, bigints, class instances). */
+export function isJsonValue(value) {
+    if (value === null || typeof value === "string" || typeof value === "boolean")
+        return true;
+    if (typeof value === "number")
+        return Number.isFinite(value);
+    if (Array.isArray(value))
+        return value.every(isJsonValue);
+    if (isPlainObject(value))
+        return Object.values(value).every(isJsonValue);
+    return false;
+}
+/** Narrow to a plain object (prototype Object.prototype or null — no class instances). */
+export function isPlainObject(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return false;
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+}
+/** Narrow to JsonValue or throw — used where a JSON shape is a protocol requirement. */
+export function asJsonValue(value, what) {
+    if (isJsonValue(value))
+        return value;
+    throw new EngineError("VALIDATION", `${what} must be a JSON-serializable value.`);
+}

package/dist/mcp/client.d.ts

@@ -0,0 +1,39 @@
+import { type McpTransport } from "./jsonrpc.js";
+/**
+ * Protocol revisions this client speaks, newest first. We OFFER the newest; a server may
+ * answer with any revision it prefers, and these three are wire-compatible for the subset we
+ * use (initialize / tools/list / tools/call). Anything else is rejected loudly — guessing at
+ * an unknown revision's semantics would be a silent-degradation bug.
+ */
+export declare const SUPPORTED_PROTOCOL_VERSIONS: readonly ["2025-06-18", "2025-03-26", "2024-11-05"];
+/** A tool the server advertises, normalized for the agent loop's ToolSpec shape. */
+export interface McpToolInfo {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+}
+/** A tools/call outcome: flattened text for model context + the server's error flag. */
+export interface McpCallResult {
+    content: string;
+    isError: boolean;
+}
+export interface McpConnectionOptions {
+    /** The server's name from the agent() call — prefixes its tools, names it in errors. */
+    serverName: string;
+    /** Per-request timeout override (tests use short ones). */
+    timeoutMs?: number;
+}
+export declare class McpConnection {
+    private readonly rpc;
+    private readonly transport;
+    readonly serverName: string;
+    constructor(transport: McpTransport, opts: McpConnectionOptions);
+    /** The MCP handshake: version negotiation, then the initialized notification. */
+    initialize(): Promise<void>;
+    /** Every tool the server advertises, following nextCursor pagination to the end. */
+    listTools(): Promise<McpToolInfo[]>;
+    /** Invoke a server tool; content is flattened to model-bound text (non-text summarized). */
+    callTool(name: string, args: Record<string, unknown>): Promise<McpCallResult>;
+    /** Tear the connection down (rejects anything in flight; kills/deletes transport state). */
+    close(): Promise<void>;
+}

package/dist/mcp/client.js

@@ -0,0 +1,112 @@
+// The MCP connection: the protocol conversation (initialize handshake, tools/list pagination,
+// tools/call) over any transport. Lives in the RUN PROCESS — tool execution must happen where
+// the program runs — while OAuth token state stays parent-side (the transport's hook brokers
+// it over IPC). Every server response is Zod-validated: an MCP server's output is untrusted
+// input like any provider's (CODE_QUALITY §2.1).
+import { z } from "zod";
+import { EngineError } from "../errors.js";
+import { JsonRpcClient } from "./jsonrpc.js";
+/**
+ * Protocol revisions this client speaks, newest first. We OFFER the newest; a server may
+ * answer with any revision it prefers, and these three are wire-compatible for the subset we
+ * use (initialize / tools/list / tools/call). Anything else is rejected loudly — guessing at
+ * an unknown revision's semantics would be a silent-degradation bug.
+ */
+export const SUPPORTED_PROTOCOL_VERSIONS = ["2025-06-18", "2025-03-26", "2024-11-05"];
+const initializeResultSchema = z.looseObject({ protocolVersion: z.string().min(1) });
+const listToolsResultSchema = z.looseObject({
+    tools: z.array(z.looseObject({
+        name: z.string().min(1),
+        description: z.string().optional(),
+        inputSchema: z.record(z.string(), z.unknown()).optional(),
+    })),
+    nextCursor: z.string().nullish(),
+});
+const callToolResultSchema = z.looseObject({
+    content: z.array(z.looseObject({ type: z.string(), text: z.string().optional() })).optional(),
+    isError: z.boolean().nullish(),
+});
+/** Pagination runaway guard — a server endlessly re-issuing cursors must not hang the run. */
+const MAX_TOOL_PAGES = 100;
+export class McpConnection {
+    rpc;
+    transport;
+    serverName;
+    constructor(transport, opts) {
+        this.transport = transport;
+        this.serverName = opts.serverName;
+        this.rpc = new JsonRpcClient(transport, {
+            label: opts.serverName,
+            ...(opts.timeoutMs !== undefined ? { timeoutMs: opts.timeoutMs } : {}),
+        });
+    }
+    /** The MCP handshake: version negotiation, then the initialized notification. */
+    async initialize() {
+        const raw = await this.rpc.request("initialize", {
+            protocolVersion: SUPPORTED_PROTOCOL_VERSIONS[0],
+            capabilities: {},
+            clientInfo: { name: "boardwalk-engine", version: "0.1.0" },
+        });
+        const parsed = initializeResultSchema.safeParse(raw);
+        if (!parsed.success) {
+            throw new EngineError("PROVIDER_ERROR", `MCP server "${this.serverName}" returned a malformed initialize response.`);
+        }
+        const version = parsed.data.protocolVersion;
+        if (!SUPPORTED_PROTOCOL_VERSIONS.some((v) => v === version)) {
+            throw new EngineError("PROVIDER_ERROR", `MCP server "${this.serverName}" negotiated protocol version "${version}", which this ` +
+                `engine does not speak.`, `Supported versions: ${SUPPORTED_PROTOCOL_VERSIONS.join(", ")}.`);
+        }
+        // The HTTP transport replays the negotiated version as a header on every later request
+        // (spec requirement); stdio has no headers — hence the optional structural probe.
+        if (hasVersionHook(this.transport))
+            this.transport.setProtocolVersion(version);
+        await this.rpc.notify("notifications/initialized");
+    }
+    /** Every tool the server advertises, following nextCursor pagination to the end. */
+    async listTools() {
+        const tools = [];
+        let cursor;
+        for (let page = 0; page < MAX_TOOL_PAGES; page++) {
+            const raw = await this.rpc.request("tools/list", cursor !== undefined ? { cursor } : {});
+            const parsed = listToolsResultSchema.safeParse(raw);
+            if (!parsed.success) {
+                throw new EngineError("PROVIDER_ERROR", `MCP server "${this.serverName}" returned a malformed tools/list response.`);
+            }
+            for (const tool of parsed.data.tools) {
+                tools.push({
+                    name: tool.name,
+                    description: tool.description ?? "",
+                    // A missing schema means "takes anything" — advertise the loosest valid object schema.
+                    inputSchema: tool.inputSchema ?? { type: "object" },
+                });
+            }
+            if (parsed.data.nextCursor === undefined || parsed.data.nextCursor === null)
+                return tools;
+            cursor = parsed.data.nextCursor;
+        }
+        throw new EngineError("PROVIDER_ERROR", `MCP server "${this.serverName}" paginated tools/list past ${String(MAX_TOOL_PAGES)} pages.`);
+    }
+    /** Invoke a server tool; content is flattened to model-bound text (non-text summarized). */
+    async callTool(name, args) {
+        const raw = await this.rpc.request("tools/call", { name, arguments: args });
+        const parsed = callToolResultSchema.safeParse(raw);
+        if (!parsed.success) {
+            throw new EngineError("PROVIDER_ERROR", `MCP server "${this.serverName}" returned a malformed tools/call response for "${name}".`);
+        }
+        const content = (parsed.data.content ?? [])
+            .map((item) => item.type === "text" && item.text !== undefined ? item.text : `[${item.type}]`)
+            .join("\n");
+        return { content, isError: parsed.data.isError ?? false };
+    }
+    /** Tear the connection down (rejects anything in flight; kills/deletes transport state). */
+    async close() {
+        await this.rpc.close();
+    }
+}
+/**
+ * Structurally probe for the HTTP transport's version hook without importing it — keeps this
+ * file transport-agnostic so test fakes (and the stdio transport) need no stub method.
+ */
+function hasVersionHook(transport) {
+    return typeof Reflect.get(transport, "setProtocolVersion") === "function";
+}

package/dist/mcp/jsonrpc.d.ts

@@ -0,0 +1,57 @@
+/** A frame this client sends: a request, a notification, or an error reply to a server request. */
+export type JsonRpcOutbound = {
+    jsonrpc: "2.0";
+    id: number;
+    method: string;
+    params?: unknown;
+} | {
+    jsonrpc: "2.0";
+    method: string;
+    params?: unknown;
+} | {
+    jsonrpc: "2.0";
+    id: string | number;
+    error: {
+        code: number;
+        message: string;
+    };
+};
+/**
+ * What a transport must provide: framing only — no protocol knowledge. Both implementations
+ * (stdio child process, streamable HTTP) fit behind this so the client and every test fake
+ * are transport-agnostic.
+ */
+export interface McpTransport {
+    send(message: JsonRpcOutbound): Promise<void>;
+    /** Deliver every inbound frame (already JSON-parsed, still untrusted) to the client. */
+    onMessage(cb: (message: unknown) => void): void;
+    /** Invoked at most once if the transport dies out from under the client (process exit). */
+    onClose(cb: (err: Error) => void): void;
+    close(): Promise<void>;
+}
+/** Default per-request timeout — a hung MCP server must fail the call, not hold the run. */
+export declare const DEFAULT_REQUEST_TIMEOUT_MS = 60000;
+export interface JsonRpcClientOptions {
+    /** Names the peer in every error message (the MCP server's name from the agent() call). */
+    label: string;
+    timeoutMs?: number;
+}
+export declare class JsonRpcClient {
+    private readonly transport;
+    private readonly label;
+    private readonly timeoutMs;
+    private readonly pending;
+    private nextId;
+    private closed;
+    constructor(transport: McpTransport, opts: JsonRpcClientOptions);
+    /** Send a request and resolve with its (still-unknown) result; the caller Zod-narrows it. */
+    request(method: string, params?: unknown): Promise<unknown>;
+    /** Fire-and-forget notification (e.g. `notifications/initialized`). */
+    notify(method: string, params?: unknown): Promise<void>;
+    /** Close the transport and reject everything in flight — callers must never hang. */
+    close(): Promise<void>;
+    private handleInbound;
+    private settle;
+    private failAllPending;
+    private connectionError;
+}

package/dist/mcp/jsonrpc.js

@@ -0,0 +1,117 @@
+// JSON-RPC 2.0 request/notification correlation for the hand-rolled MCP client (the
+// @modelcontextprotocol/sdk dependency tree was rejected for the flagship — zero new deps).
+// The transport moves frames; this layer owns ids, correlation, timeouts, and the trust
+// boundary: every inbound frame is Zod-validated before anything dereferences it
+// (CODE_QUALITY §2.1 — an MCP server is as untrusted as any provider).
+import { z } from "zod";
+import { EngineError } from "../errors.js";
+// One loose schema for every inbound frame; classification happens after validation. A frame
+// is a server request/notification (has `method`) or a response (has `id` + result/error).
+const inboundFrameSchema = z.looseObject({
+    jsonrpc: z.literal("2.0"),
+    id: z.union([z.string(), z.number()]).nullish(),
+    method: z.string().optional(),
+    result: z.unknown().optional(),
+    error: z.looseObject({ code: z.number(), message: z.string() }).optional(),
+});
+/** Default per-request timeout — a hung MCP server must fail the call, not hold the run. */
+export const DEFAULT_REQUEST_TIMEOUT_MS = 60_000;
+export class JsonRpcClient {
+    transport;
+    label;
+    timeoutMs;
+    pending = new Map();
+    nextId = 1;
+    closed = false;
+    constructor(transport, opts) {
+        this.transport = transport;
+        this.label = opts.label;
+        this.timeoutMs = opts.timeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
+        transport.onMessage((message) => this.handleInbound(message));
+        transport.onClose((err) => this.failAllPending(err));
+    }
+    /** Send a request and resolve with its (still-unknown) result; the caller Zod-narrows it. */
+    request(method, params) {
+        if (this.closed) {
+            return Promise.reject(this.connectionError(`cannot call ${method} — connection is closed`));
+        }
+        const id = this.nextId++;
+        const promise = new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.pending.delete(id);
+                reject(this.connectionError(`"${method}" timed out after ${String(this.timeoutMs / 1000)}s — the server never answered`));
+            }, this.timeoutMs);
+            this.pending.set(id, { method, resolve, reject, timer });
+        });
+        this.transport
+            .send({ jsonrpc: "2.0", id, method, ...(params !== undefined ? { params } : {}) })
+            .catch((err) => {
+            this.settle(id, (pending) => pending.reject(err instanceof Error ? err : this.connectionError(String(err))));
+        });
+        return promise;
+    }
+    /** Fire-and-forget notification (e.g. `notifications/initialized`). */
+    async notify(method, params) {
+        await this.transport.send({
+            jsonrpc: "2.0",
+            method,
+            ...(params !== undefined ? { params } : {}),
+        });
+    }
+    /** Close the transport and reject everything in flight — callers must never hang. */
+    async close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        this.failAllPending(this.connectionError("connection closed"));
+        await this.transport.close();
+    }
+    handleInbound(message) {
+        const parsed = inboundFrameSchema.safeParse(message);
+        if (!parsed.success)
+            return; // not a JSON-RPC 2.0 frame — drop, never crash on peer noise
+        const frame = parsed.data;
+        if (frame.method !== undefined) {
+            // A server→client request (sampling, roots, …): this minimal client implements none, so
+            // answer "method not found" rather than leaving the server hanging. Notifications
+            // (no id) are dropped — nothing here consumes them yet.
+            if (frame.id !== undefined && frame.id !== null) {
+                void this.transport
+                    .send({
+                    jsonrpc: "2.0",
+                    id: frame.id,
+                    error: { code: -32601, message: "This client supports no server-initiated requests" },
+                })
+                    .catch(() => {
+                    // The reply is best-effort courtesy; a dead transport already failed the pending map.
+                });
+            }
+            return;
+        }
+        if (typeof frame.id !== "number")
+            return; // our ids are numeric; anything else isn't ours
+        const id = frame.id;
+        if (frame.error !== undefined) {
+            const { code, message } = frame.error;
+            this.settle(id, (pending) => pending.reject(this.connectionError(`"${pending.method}" failed: ${message} (code ${String(code)})`)));
+            return;
+        }
+        this.settle(id, (pending) => pending.resolve(frame.result));
+    }
+    settle(id, fn) {
+        const pending = this.pending.get(id);
+        if (pending === undefined)
+            return; // already timed out / unknown id — nothing to do
+        this.pending.delete(id);
+        clearTimeout(pending.timer);
+        fn(pending);
+    }
+    failAllPending(err) {
+        for (const [id] of [...this.pending]) {
+            this.settle(id, (pending) => pending.reject(err));
+        }
+    }
+    connectionError(detail) {
+        return new EngineError("PROVIDER_ERROR", `MCP server "${this.label}": ${detail}.`);
+    }
+}

package/dist/mcp/oauth.d.ts

@@ -0,0 +1,72 @@
+import { type McpTokenStore } from "./token_store.js";
+export interface OAuthIo {
+    fetchImpl?: typeof fetch | undefined;
+}
+export interface PkcePair {
+    verifier: string;
+    challenge: string;
+}
+/** A fresh high-entropy verifier and its S256 challenge. */
+export declare function createPkcePair(): PkcePair;
+/** The S256 transform, exported so tests can verify the challenge against the verifier. */
+export declare function s256Challenge(verifier: string): string;
+/**
+ * Extract the parameters of a Bearer challenge (`resource_metadata`, `error`, …). Returns an
+ * empty record for non-Bearer or malformed headers — discovery then falls back to the
+ * well-known path, so a sloppy header degrades gracefully instead of failing authorization.
+ */
+export declare function parseBearerChallenge(header: string): Record<string, string>;
+export interface AuthorizationDiscovery {
+    authorizationEndpoint: string;
+    tokenEndpoint: string;
+    registrationEndpoint: string | undefined;
+    /** The RFC 8707 resource indicator to bind grants to (canonical server URL by default). */
+    resource: string;
+}
+/**
+ * Find the authorization server for an MCP server: probe it unauthenticated, follow the 401's
+ * `resource_metadata` hint (RFC 9728), fall back to the well-known protected-resource path,
+ * and finally — for pre-9728 servers — treat the server's own origin as the issuer (the
+ * 2025-03-26 MCP default). Failing any later step is loud: authorization can't be guessed.
+ */
+export declare function discoverAuthorization(serverUrl: string, io?: OAuthIo): Promise<AuthorizationDiscovery>;
+/** Register a public client (no secret — token_endpoint_auth_method "none", per OAuth 2.1 CLI practice). */
+export declare function registerClient(registrationEndpoint: string, redirectUri: string, io?: OAuthIo): Promise<string>;
+export interface TokenGrant {
+    accessToken: string;
+    refreshToken: string | undefined;
+    /** Epoch ms, derived from expires_in at grant time. Undefined when the AS declared none. */
+    expiresAt: number | undefined;
+}
+export interface ExchangeCodeArgs {
+    tokenEndpoint: string;
+    clientId: string;
+    code: string;
+    redirectUri: string;
+    codeVerifier: string;
+    resource: string;
+}
+export declare function exchangeAuthorizationCode(args: ExchangeCodeArgs, io?: OAuthIo): Promise<TokenGrant>;
+export interface RefreshTokenArgs {
+    tokenEndpoint: string;
+    clientId: string;
+    refreshToken: string;
+    resource: string | undefined;
+}
+export declare function refreshAccessToken(args: RefreshTokenArgs, io?: OAuthIo): Promise<TokenGrant>;
+export interface AuthorizeFlowArgs {
+    serverUrl: string;
+    store: McpTokenStore;
+    /** Hands the URL a human must open to the caller (CLI prints it, a UI links it). */
+    onAuthorizationUrl: (url: string) => void;
+    /** How long to wait for the human. Default 5 minutes. */
+    timeoutMs?: number;
+    fetchImpl?: typeof fetch;
+}
+/**
+ * The one-time interactive step: discovery → dynamic registration → PKCE authorization-code
+ * grant with a loopback redirect → tokens persisted to the store. Resolves when the grant is
+ * stored; rejects on state mismatch, an AS `error` redirect, or timeout. After this, runs use
+ * the server headlessly (silent refresh included) until the grant dies.
+ */
+export declare function runAuthorizationFlow(args: AuthorizeFlowArgs): Promise<void>;