@boardwalk-labs/engine 0.1.0

package/dist/run/ipc.js

@@ -0,0 +1,150 @@
+// The supervisor ⇄ run-process IPC protocol.
+//
+// One run = one spawned Node process (SPEC §2.2). The child executes the user's program and
+// brokers its SDK hook calls back to the supervisor over Node's built-in IPC channel. Every
+// message is Zod-validated on receipt — the child runs user code, so everything it sends is a
+// trust boundary (CODE_QUALITY §2.1).
+//
+// Envelope authority: the child sends event BODIES (no runId/turnId/seq/t); the supervisor is
+// the single place envelopes are stamped and cursors allocated, so cursor monotonicity holds
+// across crash-restarts without the child knowing about them.
+import { z } from "zod";
+const errorShapeSchema = z.strictObject({
+    code: z.string(),
+    message: z.string(),
+    hint: z.string().optional(),
+});
+// The child validates only the discriminator + the fields it dereferences; the manifest was
+// already validated by the store and `unknown` payloads are narrowed at their use sites.
+export const parentToChildSchema = z.union([
+    z.object({
+        type: z.literal("init"),
+        runId: z.string().min(1),
+        programPath: z.string().min(1),
+        workspaceDir: z.string().min(1),
+        skillsDir: z.string().min(1).nullable(),
+        input: z.unknown(),
+        config: z.record(z.string(), z.unknown()),
+        manifest: z.record(z.string(), z.unknown()),
+    }),
+    z.object({
+        type: z.literal("host_result"),
+        callId: z.number().int().nonnegative(),
+        result: z.union([
+            z.object({ ok: z.literal(true), value: z.unknown() }),
+            z.object({ ok: z.literal(false), error: errorShapeSchema }),
+        ]),
+    }),
+]);
+// ----------------------------------------------------------------------------
+// child → parent
+// ----------------------------------------------------------------------------
+/** Host methods the child brokers to the supervisor (everything that touches engine state). */
+export const HOST_METHODS = [
+    "get_secret",
+    "call_workflow",
+    "run_workflow",
+    "write_artifact",
+    "resolve_model",
+    "mcp_token",
+];
+const tokenUsageShape = z.strictObject({
+    inputTokens: z.number().int().nonnegative().optional(),
+    outputTokens: z.number().int().nonnegative().optional(),
+    totalTokens: z.number().int().nonnegative().optional(),
+});
+export const childToParentSchema = z.union([
+    z.object({
+        type: z.literal("host_call"),
+        callId: z.number().int().nonnegative(),
+        method: z.enum(HOST_METHODS),
+        args: z.record(z.string(), z.unknown()),
+    }),
+    z.object({
+        type: z.literal("emit"),
+        // Stamped + fully validated against runEventSchema by the supervisor; here we only
+        // require an event-body shape with a kind. `turnId` scopes agent-leaf frames to their
+        // turn; absent means a run-level frame (turnId = runId).
+        body: z.looseObject({ kind: z.string().min(1) }),
+        turnId: z.string().min(1).optional(),
+    }),
+    z.object({
+        // Opens a new turn block: the supervisor bumps its cursor stride and emits turn_started.
+        // Carries the leaf's identity so the stamped turn_started names which agent is starting.
+        type: z.literal("turn_started"),
+        turnId: z.string().min(1),
+        agentId: z.string().min(1),
+        agentName: z.string().min(1).optional(),
+    }),
+    z.object({
+        // Leaf usage report — the supervisor's budget authority consumes this (tokens + max_usd).
+        type: z.literal("report_usage"),
+        modelRef: z.string().min(1),
+        usage: tokenUsageShape,
+    }),
+    z.object({
+        // An agent() call is using a memory dir — the supervisor auto-persists it at success.
+        type: z.literal("memory_used"),
+        dir: z.string().min(1),
+    }),
+    z.object({
+        type: z.literal("done"),
+        output: z.unknown(),
+        outputDeclared: z.boolean(),
+    }),
+    z.object({
+        type: z.literal("failed"),
+        error: errorShapeSchema,
+        // Output declared (output()) BEFORE the program threw still counts — a watch/check often
+        // output()s its verdict and then throws to mark the run failed. Mirrors `done`.
+        output: z.unknown(),
+        outputDeclared: z.boolean(),
+    }),
+]);
+// Host-call argument schemas, validated supervisor-side before acting.
+export const getSecretArgsSchema = z.strictObject({ name: z.string().min(1) });
+export const callWorkflowArgsSchema = z.strictObject({
+    slug: z.string().min(1),
+    input: z.unknown(),
+    idempotencyKey: z.string().min(1).optional(),
+});
+export const writeArtifactArgsSchema = z.strictObject({
+    name: z.string().min(1),
+    contentType: z.string().min(1),
+    /** Body crosses IPC as base64 — Uint8Array does not survive JSON serialization. */
+    bodyBase64: z.string(),
+    metadata: z.record(z.string(), z.unknown()).optional(),
+});
+export const resolveModelArgsSchema = z.strictObject({
+    model: z.string().min(1).optional(),
+    provider: z.string().min(1).optional(),
+});
+/** The supervisor's resolve_model response, re-validated child-side before use. */
+export const resolvedModelSchema = z.strictObject({
+    provider: z.string().min(1),
+    /** Opaque — passed verbatim to the provider; never parsed. */
+    model: z.string().min(1),
+    protocol: z.enum(["anthropic", "openai"]),
+    baseUrl: z.string().min(1),
+    apiKey: z.string().nullable(),
+    /** Extra request headers, resolved supervisor-side. */
+    headers: z.record(z.string(), z.string()),
+    /** Header names whose values are env-sourced — the leaf redacts them like the API key. */
+    secretHeaderNames: z.array(z.string()),
+});
+/**
+ * mcp_token: the child asks the engine for an OAuth bearer token for an MCP server (token
+ * state is PARENT-owned — the run process never sees refresh tokens or the store).
+ * `invalidateToken` names a token the server just rejected, so the supervisor refreshes
+ * instead of handing the same dead value back.
+ */
+export const mcpTokenArgsSchema = z.strictObject({
+    serverUrl: z.string().min(1),
+    invalidateToken: z.string().min(1).optional(),
+});
+/** The supervisor's mcp_token response. null accessToken ⇒ interaction would be required —
+ *  the hint names the `engine.authorizeMcpServer(...)` call that fixes it. */
+export const mcpTokenResultSchema = z.strictObject({
+    accessToken: z.string().nullable(),
+    hint: z.string().optional(),
+});

package/dist/run/run_dir.d.ts

@@ -0,0 +1,31 @@
+export interface RunDirs {
+    root: string;
+    programPath: string;
+    workspaceDir: string;
+    artifactsDir: string;
+}
+/** Lay out (or re-lay-out, on restart) the run directory for a program bundle. Idempotent. */
+export declare function prepareRunDir(dataDir: string, runId: string, program: string): RunDirs;
+/** Remove a run directory (terminal-run cleanup; never called on active runs). */
+export declare function removeRunDir(dataDir: string, runId: string): void;
+export type PersistSelection = boolean | readonly string[] | undefined;
+/** The workflow's durable persistence root. */
+export declare function persistRoot(dataDir: string, workflowId: string): string;
+/**
+ * Copy persisted state into a fresh run workspace (first attempt only — see above). The whole
+ * durable root is hydrated: it only ever contains what a previous successful run persisted
+ * (declared dirs + memory dirs), so all of it belongs in the workspace.
+ */
+export declare function hydrateWorkspace(root: string, workspaceDir: string): void;
+/**
+ * Replace the durable store with the run's final state (successful runs only). `memoryDirs`
+ * are the per-agent memory directories used this run — persisted in addition to the
+ * manifest's selection (deduplicated; a memory dir inside `persist: true` costs nothing).
+ */
+export declare function persistWorkspace(root: string, persist: PersistSelection, memoryDirs: ReadonlySet<string>, workspaceDir: string): void;
+/**
+ * The engine's installed `@boardwalk-labs/workflow` package root. Resolved from the package's main
+ * entry and walked up to its package.json — the exports map doesn't expose "./package.json",
+ * so `require.resolve("@boardwalk-labs/workflow/package.json")` would throw.
+ */
+export declare function sdkPackageDir(): string;

package/dist/run/run_dir.js

@@ -0,0 +1,106 @@
+// Per-run on-disk layout + the SDK-sharing symlink.
+//
+//   <dataDir>/runs/<runId>/
+//     program/index.mjs                          — the deployed bundle (SDK left external)
+//     program/node_modules/@boardwalk-labs/workflow   — symlink to the ENGINE's installed SDK
+//     workspace/                                 — the run's cwd (isolated per run)
+//     artifacts/                                 — artifacts.write targets
+//
+// Why the symlink: the SDK's host state is a module-level singleton, so the program and the
+// child entry (engine code) must load the SAME module instance for installHost() to be visible
+// to the program's hooks. The program bundle imports `@boardwalk-labs/workflow` bare; this symlink
+// makes that specifier resolve — and Node's default symlink realpathing collapses it onto the
+// engine's own copy, giving one shared instance with no bundler in the engine at all.
+import { cpSync, existsSync, mkdirSync, readFileSync, rmSync, symlinkSync, writeFileSync, } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+import { z } from "zod";
+import { EngineError } from "../errors.js";
+// A file from disk is a trust boundary — parse, don't cast (CODE_QUALITY §2.1).
+const packageNameSchema = z.looseObject({ name: z.string().optional() });
+/** Lay out (or re-lay-out, on restart) the run directory for a program bundle. Idempotent. */
+export function prepareRunDir(dataDir, runId, program) {
+    const root = join(dataDir, "runs", runId);
+    const programDir = join(root, "program");
+    const workspaceDir = join(root, "workspace");
+    const artifactsDir = join(root, "artifacts");
+    mkdirSync(programDir, { recursive: true });
+    mkdirSync(workspaceDir, { recursive: true });
+    mkdirSync(artifactsDir, { recursive: true });
+    const programPath = join(programDir, "index.mjs");
+    writeFileSync(programPath, program, "utf8");
+    const linkParent = join(programDir, "node_modules", "@boardwalk-labs");
+    const linkPath = join(linkParent, "workflow");
+    if (!existsSync(linkPath)) {
+        mkdirSync(linkParent, { recursive: true });
+        symlinkSync(sdkPackageDir(), linkPath, "dir");
+    }
+    return { root, programPath, workspaceDir, artifactsDir };
+}
+/** Remove a run directory (terminal-run cleanup; never called on active runs). */
+export function removeRunDir(dataDir, runId) {
+    rmSync(join(dataDir, "runs", runId), { recursive: true, force: true });
+}
+/** The workflow's durable persistence root. */
+export function persistRoot(dataDir, workflowId) {
+    return join(dataDir, "persist", workflowId);
+}
+/**
+ * Copy persisted state into a fresh run workspace (first attempt only — see above). The whole
+ * durable root is hydrated: it only ever contains what a previous successful run persisted
+ * (declared dirs + memory dirs), so all of it belongs in the workspace.
+ */
+export function hydrateWorkspace(root, workspaceDir) {
+    if (existsSync(root))
+        cpSync(root, workspaceDir, { recursive: true });
+}
+/**
+ * Replace the durable store with the run's final state (successful runs only). `memoryDirs`
+ * are the per-agent memory directories used this run — persisted in addition to the
+ * manifest's selection (deduplicated; a memory dir inside `persist: true` costs nothing).
+ */
+export function persistWorkspace(root, persist, memoryDirs, workspaceDir) {
+    if (persist === true) {
+        rmSync(root, { recursive: true, force: true });
+        cpSync(workspaceDir, root, { recursive: true });
+        return;
+    }
+    const declared = persist === undefined || persist === false ? [] : persist;
+    const dirs = new Set([...declared, ...memoryDirs]);
+    for (const dir of dirs) {
+        const source = join(workspaceDir, dir);
+        const target = join(root, dir);
+        rmSync(target, { recursive: true, force: true });
+        if (existsSync(source)) {
+            mkdirSync(dirname(target), { recursive: true });
+            cpSync(source, target, { recursive: true });
+        }
+    }
+}
+let cachedSdkDir = null;
+/**
+ * The engine's installed `@boardwalk-labs/workflow` package root. Resolved from the package's main
+ * entry and walked up to its package.json — the exports map doesn't expose "./package.json",
+ * so `require.resolve("@boardwalk-labs/workflow/package.json")` would throw.
+ */
+export function sdkPackageDir() {
+    if (cachedSdkDir !== null)
+        return cachedSdkDir;
+    const require = createRequire(import.meta.url);
+    let dir = dirname(require.resolve("@boardwalk-labs/workflow"));
+    for (let depth = 0; depth < 10; depth++) {
+        const pkgPath = join(dir, "package.json");
+        if (existsSync(pkgPath)) {
+            const pkg = packageNameSchema.safeParse(JSON.parse(readFileSync(pkgPath, "utf8")));
+            if (pkg.success && pkg.data.name === "@boardwalk-labs/workflow") {
+                cachedSdkDir = dir;
+                return dir;
+            }
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    throw new EngineError("INTERNAL", "Could not locate the installed @boardwalk-labs/workflow package root.");
+}

package/dist/run/supervisor.d.ts

@@ -0,0 +1,107 @@
+import type { RunStatus } from "../store/store.js";
+import { type InferenceConfig } from "../agent/resolve.js";
+import { type Clock } from "../clock.js";
+import type { EventRow, RunRow, Store } from "../store/store.js";
+export interface SupervisorOptions {
+    store: Store;
+    /** Engine data directory; run dirs live under `<dataDir>/runs/<runId>`. */
+    dataDir: string;
+    /** Absolute path to the compiled child entry (dist/run/child.js). */
+    childEntryPath: string;
+    /** The local secret/env source (.env contents); process.env is the fallback. */
+    env: ReadonlyMap<string, string>;
+    /** Where secrets come from, for actionable error messages (never values). */
+    envLabel: string;
+    clock?: Clock;
+    /** Crash restarts per run before `failed`/CRASHED. Default 2 (three attempts total). */
+    maxRestarts?: number;
+    /** Cooperative-cancellation window before SIGKILL. Default 10s. */
+    cancelGraceMs?: number;
+    /** Default model + provider table for agent() leaves. Default: built-ins only, no default model. */
+    inference?: InferenceConfig;
+}
+/** True when a run can no longer change state. */
+export declare function isTerminal(status: RunStatus): boolean;
+export declare class RunSupervisor {
+    private readonly store;
+    private readonly dataDir;
+    private readonly childEntryPath;
+    private readonly env;
+    private readonly envLabel;
+    private readonly clock;
+    private readonly maxRestarts;
+    private readonly cancelGraceMs;
+    private readonly inference;
+    private readonly mcpTokens;
+    private readonly active;
+    private readonly listeners;
+    constructor(opts: SupervisorOptions);
+    /** Subscribe to every stamped run event (the local feed for SSE/log UIs). */
+    onEvent(listener: (row: EventRow) => void): () => void;
+    /**
+     * Drive a run to terminal status; idempotent per run id (a second call while active returns
+     * the same promise; a call on a terminal run resolves immediately). Never rejects for run
+     * failures — failure is a status, not an exception. Rejects only on caller bugs (unknown id).
+     */
+    supervise(runId: string): Promise<RunRow>;
+    /** Emit the `queued` lifecycle event for a freshly created run (the creator calls this once). */
+    emitQueued(runId: string): void;
+    /**
+     * Cancel a run: cooperative SIGTERM, SIGKILL after the grace window. A queued/unsupervised
+     * run is cancelled directly; a terminal run is a no-op.
+     */
+    cancel(runId: string): Promise<void>;
+    /**
+     * Boot recovery sweep (SPEC §2.2): runs a dead engine left active are re-dispatched
+     * (restart-from-the-top — the child died with the engine); interrupted cancellations are
+     * finalized (the orphan child exits on IPC disconnect, so the kill already happened).
+     * Engine restarts do not consume the run's crash-restart budget.
+     */
+    recoverOnBoot(): {
+        resumed: string[];
+        cancelled: string[];
+    };
+    /** SIGTERM all children and stop. In-flight runs are recovered by the next boot's sweep. */
+    shutdown(): void;
+    private execute;
+    private spawnOnce;
+    /**
+     * Accumulate a leaf's usage into the run row and enforce token/USD budgets — the supervisor
+     * is the single budget authority, so a multi-leaf run can't out-run its caps by parallelism.
+     */
+    private recordUsage;
+    private handleHostCall;
+    /** Find-or-create the durable child run for workflows.call/run (idempotent re-attach). */
+    private startChildRun;
+    /**
+     * The engine side of MCP OAuth: hand the child a usable access token, refreshing SILENTLY
+     * when the stored one is expired (clock + skew) or the child reports the server rejected it
+     * (`invalidateToken` — the child retries at most once, so a second rejection lands back here
+     * as a failure). When only a human could fix it, answer null + a hint naming
+     * engine.authorizeMcpServer — a headless run must fail loudly, never prompt.
+     */
+    private resolveMcpToken;
+    private resolveSecret;
+    /**
+     * The child's environment: the parent env plus manifest.env with whole-value
+     * `${{ secrets.NAME }}` interpolation resolved (fail-closed against meta.secrets).
+     */
+    private childEnv;
+    private setStatus;
+    /** Terminal transition: persist status + output/error, emit the lifecycle event, return the row. */
+    private finishRun;
+    /** Stamp a child-emitted body. A malformed body is dropped with a diagnostic, never fatal. */
+    private emitBody;
+    /**
+     * The single envelope-stamping path: allocate cursor, validate, persist, fan out. The body
+     * is typed loosely because child-emitted bodies are untrusted — runEventSchema.parse below
+     * is the validation, not the type. Run-level frames carry the run id as turnId; agent-leaf
+     * frames carry their turn's id.
+     */
+    private stampAndStore;
+    /** Resume the envelope past everything already persisted (crash/boot safe). */
+    private resumeEnvelope;
+    private mustGetRun;
+    /** Deployed skills live at <dataDir>/skills/<workflowId>/<name>.md (written at deploy). */
+    private skillsDirFor;
+}