@boardwalk-labs/engine 0.1.0

package/dist/cron/cron.js

@@ -0,0 +1,331 @@
+// Cron parsing + next-fire computation for the scheduler (SPEC §2.1).
+//
+// One-validator philosophy: the SDK manifest schema only checks a cron trigger shallowly
+// (5 or 6 whitespace-separated fields; timezone = a non-empty string). This module is the
+// deep validator of record — anything `parseCron`/`nextFire` reject must be rejected at
+// deploy time, so a stored manifest can never contain a schedule the engine can't fire.
+//
+// Semantics are Vixie cron's where Vixie has an opinion:
+// - dom/dow: when NEITHER field starts with `*`, a day matches if EITHER matches (the
+//   classic OR rule); when at least one starts with `*`, both must match (the star field
+//   matches everything, so effectively the other decides). Vixie keys this off the literal
+//   leading `*` (its DOM_STAR/DOW_STAR flags), so `*/2` counts as a star field — we match.
+// - dow 0 and 7 are both Sunday.
+// Plus the modern (cronie/Quartz/AWS) extension `N/step` = `N-max/step`, because it is what
+// authors coming from any contemporary cron expect and accepting it loses nothing.
+//
+// Timezones use Intl only — this package takes no runtime dependency for cron (CODE_QUALITY
+// §10: every dependency is supply-chain surface). DST policy: a wall time erased by
+// spring-forward is skipped (it never occurs, so it never fires); a wall time repeated by
+// fall-back fires once, at its first (earlier-UTC) occurrence.
+import { EngineError } from "../errors.js";
+const SECOND = { label: "second", min: 0, max: 59 };
+const MINUTE = { label: "minute", min: 0, max: 59 };
+const HOUR = { label: "hour", min: 0, max: 23 };
+const DOM = { label: "day-of-month", min: 1, max: 31 };
+const MONTH = {
+    label: "month",
+    min: 1,
+    max: 12,
+    names: {
+        JAN: 1,
+        FEB: 2,
+        MAR: 3,
+        APR: 4,
+        MAY: 5,
+        JUN: 6,
+        JUL: 7,
+        AUG: 8,
+        SEP: 9,
+        OCT: 10,
+        NOV: 11,
+        DEC: 12,
+    },
+};
+const DOW = {
+    label: "day-of-week",
+    min: 0,
+    max: 7, // 7 accepted as Sunday, folded to 0 below
+    names: { SUN: 0, MON: 1, TUE: 2, WED: 3, THU: 4, FRI: 5, SAT: 6 },
+    normalize: (v) => (v === 7 ? 0 : v),
+};
+function fieldError(spec, detail) {
+    return new EngineError("VALIDATION", `cron: invalid ${spec.label} field: ${detail}`);
+}
+/** Resolve one endpoint of a range: a decimal number or a three-letter name. */
+function parseValue(raw, spec) {
+    if (/^\d+$/.test(raw)) {
+        const value = Number.parseInt(raw, 10);
+        if (value < spec.min || value > spec.max) {
+            throw fieldError(spec, `value ${String(value)} out of range ${String(spec.min)}-${String(spec.max)}`);
+        }
+        return value;
+    }
+    const named = spec.names?.[raw.toUpperCase()];
+    if (named !== undefined)
+        return named;
+    throw fieldError(spec, `unrecognized value "${raw}"`);
+}
+/** Expand one comma-separated item (`*`, `N`, `A-B`, with optional `/step`) into values. */
+function parseItem(item, spec, into) {
+    const slashParts = item.split("/");
+    if (slashParts.length > 2)
+        throw fieldError(spec, `too many "/" in "${item}"`);
+    const body = slashParts[0] ?? "";
+    const stepRaw = slashParts[1];
+    const hasStep = slashParts.length === 2;
+    if (body === "")
+        throw fieldError(spec, `empty value in "${item}"`);
+    let step = 1;
+    if (hasStep) {
+        if (stepRaw === undefined || !/^\d+$/.test(stepRaw)) {
+            throw fieldError(spec, `step in "${item}" must be a positive integer`);
+        }
+        step = Number.parseInt(stepRaw, 10);
+        if (step === 0)
+            throw fieldError(spec, `step in "${item}" must be at least 1`);
+    }
+    let lo;
+    let hi;
+    if (body === "*") {
+        lo = spec.min;
+        hi = spec.max;
+    }
+    else {
+        const dashParts = body.split("-");
+        if (dashParts.length > 2)
+            throw fieldError(spec, `too many "-" in "${item}"`);
+        const loRaw = dashParts[0] ?? "";
+        const hiRaw = dashParts.length === 2 ? (dashParts[1] ?? "") : undefined;
+        if (loRaw === "" || hiRaw === "")
+            throw fieldError(spec, `malformed range "${item}"`);
+        lo = parseValue(loRaw, spec);
+        if (hiRaw !== undefined) {
+            hi = parseValue(hiRaw, spec);
+        }
+        else if (hasStep) {
+            // Why: `N/step` means N-through-max by step (cronie/Quartz/AWS extension) — what
+            // contemporary cron authors expect; original Vixie simply errored here.
+            hi = spec.max;
+        }
+        else {
+            hi = lo;
+        }
+        if (lo > hi) {
+            throw fieldError(spec, `range ${String(lo)}-${String(hi)} is reversed in "${item}"`);
+        }
+    }
+    for (let v = lo; v <= hi; v += step) {
+        into.add(spec.normalize ? spec.normalize(v) : v);
+    }
+}
+function parseField(text, spec) {
+    const values = new Set();
+    for (const item of text.split(",")) {
+        if (item === "")
+            throw fieldError(spec, `empty list entry in "${text}"`);
+        parseItem(item, spec, values);
+    }
+    return values;
+}
+/**
+ * Parse a 5-field (min hour dom mon dow) or 6-field (sec min hour dom mon dow) cron
+ * expression. Throws `EngineError("VALIDATION", …)` naming the bad field, so deploy-time
+ * errors point the author at exactly what to fix in their `meta` trigger.
+ */
+export function parseCron(expr) {
+    const fields = expr.trim().split(/\s+/);
+    // Why mirror the SDK's field-count check exactly: the manifest schema's only cron
+    // validation is "5 or 6 fields" — the two validators must agree on that boundary.
+    if (fields.length !== 5 && fields.length !== 6) {
+        throw new EngineError("VALIDATION", `cron: expression "${expr}" has ${String(fields.length)} field(s); ` +
+            `expected 5 (min hour dom mon dow) or 6 (sec min hour dom mon dow)`);
+    }
+    const six = fields.length === 6;
+    // The length check above guarantees every index below exists; `?? ""` (which parseField
+    // rejects) keeps the narrowing honest under noUncheckedIndexedAccess without a cast.
+    const field = (i) => fields[i] ?? "";
+    const domText = field(six ? 3 : 2);
+    const dowText = field(six ? 5 : 4);
+    return {
+        seconds: six ? sorted(parseField(field(0), SECOND)) : [0],
+        minutes: sorted(parseField(field(six ? 1 : 0), MINUTE)),
+        hours: sorted(parseField(field(six ? 2 : 1), HOUR)),
+        daysOfMonth: parseField(domText, DOM),
+        months: parseField(field(six ? 4 : 3), MONTH),
+        daysOfWeek: parseField(dowText, DOW),
+        domIsStar: domText.startsWith("*"),
+        dowIsStar: dowText.startsWith("*"),
+    };
+}
+const asc = (a, b) => a - b;
+const sorted = (values) => [...values].sort(asc);
+// ============================================================================
+// Next-fire computation
+// ============================================================================
+const DAY_MS = 86_400_000;
+// Why ~5 years: long enough that any schedule with a real fire (worst case: a dom/month
+// combo that only exists in leap years) is found, short enough that an impossible schedule
+// (Feb 30) returns null after a bounded, fast day scan instead of looping forever.
+const HORIZON_DAYS = 366 * 5 + 7;
+/**
+ * Why a cached formatter per timezone: constructing Intl.DateTimeFormat is the expensive
+ * part (locale + tz data resolution); formatToParts on a cached instance is cheap enough
+ * to call a handful of times per candidate fire.
+ */
+const formatterCache = new Map();
+function getFormatter(timezone) {
+    const cached = formatterCache.get(timezone);
+    if (cached)
+        return cached;
+    let fmt;
+    try {
+        fmt = new Intl.DateTimeFormat("en-US", {
+            timeZone: timezone,
+            // Why h23: guarantees hours 00-23 (h24 would render midnight as "24").
+            hourCycle: "h23",
+            year: "numeric",
+            month: "2-digit",
+            day: "2-digit",
+            hour: "2-digit",
+            minute: "2-digit",
+            second: "2-digit",
+        });
+    }
+    catch {
+        throw new EngineError("VALIDATION", `cron: unknown timezone "${timezone}"`, 'use an IANA zone name like "America/New_York" or "UTC"');
+    }
+    formatterCache.set(timezone, fmt);
+    return fmt;
+}
+/** Read the wall-clock reading of a UTC instant in the formatter's timezone. */
+function wallTimeAt(fmt, epochMs) {
+    let year = 0;
+    let month = 0;
+    let day = 0;
+    let hour = 0;
+    let minute = 0;
+    let second = 0;
+    for (const part of fmt.formatToParts(epochMs)) {
+        switch (part.type) {
+            case "year":
+                year = Number.parseInt(part.value, 10);
+                break;
+            case "month":
+                month = Number.parseInt(part.value, 10);
+                break;
+            case "day":
+                day = Number.parseInt(part.value, 10);
+                break;
+            case "hour":
+                hour = Number.parseInt(part.value, 10);
+                break;
+            case "minute":
+                minute = Number.parseInt(part.value, 10);
+                break;
+            case "second":
+                second = Number.parseInt(part.value, 10);
+                break;
+            default:
+                break;
+        }
+    }
+    return { year, month, day, hour, minute, second };
+}
+/** UTC-offset of the zone at `epochMs`, in ms (positive east of UTC). */
+function offsetAt(fmt, epochMs) {
+    const w = wallTimeAt(fmt, epochMs);
+    return Date.UTC(w.year, w.month - 1, w.day, w.hour, w.minute, w.second) - epochMs;
+}
+/**
+ * All UTC instants (sorted ascending) at which the zone's wall clock reads exactly the given
+ * time: 0 instants in a spring-forward gap, 1 normally, 2 across a fall-back overlap.
+ *
+ * Why probe offsets a day either side of the naive guess: the zone's offset at the target
+ * instant is unknown until we pick an instant. Sampling the offset at guess±24h brackets any
+ * single transition (real-world DST shifts are well under 24h), and each candidate offset is
+ * then verified by reading the wall clock back — a stale or irrelevant offset simply fails
+ * verification, so over-probing is harmless.
+ */
+function wallTimeToEpochs(fmt, target) {
+    const guess = Date.UTC(target.year, target.month - 1, target.day, target.hour, target.minute, target.second);
+    const candidateOffsets = new Set([
+        offsetAt(fmt, guess - DAY_MS),
+        offsetAt(fmt, guess),
+        offsetAt(fmt, guess + DAY_MS),
+    ]);
+    const epochs = [];
+    for (const offset of candidateOffsets) {
+        const epoch = guess - offset;
+        const readBack = wallTimeAt(fmt, epoch);
+        if (readBack.year === target.year &&
+            readBack.month === target.month &&
+            readBack.day === target.day &&
+            readBack.hour === target.hour &&
+            readBack.minute === target.minute &&
+            readBack.second === target.second) {
+            epochs.push(epoch);
+        }
+    }
+    return epochs.sort(asc);
+}
+/** Vixie's day-match rule — see the module header for why the star flags (not set contents) decide. */
+function dayMatches(schedule, year, month, day) {
+    const dow = new Date(Date.UTC(year, month - 1, day)).getUTCDay();
+    const domHit = schedule.daysOfMonth.has(day);
+    const dowHit = schedule.daysOfWeek.has(dow);
+    return schedule.domIsStar || schedule.dowIsStar ? domHit && dowHit : domHit || dowHit;
+}
+/**
+ * The next fire time STRICTLY AFTER `afterMs`, computed in the given IANA timezone (default
+ * "UTC"), as epoch ms. Returns null when no fire occurs within the ~5-year search horizon
+ * (an impossible schedule like Feb 30). Throws `EngineError("VALIDATION", …)` on an invalid
+ * timezone.
+ *
+ * Why day-first enumeration instead of stepping minute-by-minute: a sparse schedule (e.g.
+ * `0 0 29 2 *`) would otherwise scan millions of minutes across years; scanning calendar
+ * days needs only ~1.8k cheap iterations, and Intl is consulted only on days that match.
+ */
+export function nextFire(schedule, afterMs, timezone = "UTC") {
+    const fmt = getFormatter(timezone);
+    const start = wallTimeAt(fmt, afterMs);
+    // Why iterate wall dates via UTC date arithmetic: calendar succession (Jun 30 → Jul 1) is
+    // timezone-independent, so a UTC day cursor never needs Intl; noon keeps the cursor clear
+    // of any midnight-adjacent DST weirdness when adding 24h.
+    let dayCursor = Date.UTC(start.year, start.month - 1, start.day, 12);
+    for (let i = 0; i < HORIZON_DAYS; i++) {
+        const cursor = new Date(dayCursor);
+        const year = cursor.getUTCFullYear();
+        const month = cursor.getUTCMonth() + 1;
+        const day = cursor.getUTCDate();
+        if (schedule.months.has(month) && dayMatches(schedule, year, month, day)) {
+            // Why lower-bounding by wall time is safe on the first day: the earliest-occurrence
+            // wall→epoch mapping is monotonic, and the first occurrence of afterMs's own wall
+            // reading is ≤ afterMs — so earlier wall times can never yield an epoch > afterMs.
+            const first = i === 0;
+            for (const hour of schedule.hours) {
+                if (first && hour < start.hour)
+                    continue;
+                for (const minute of schedule.minutes) {
+                    if (first && hour === start.hour && minute < start.minute)
+                        continue;
+                    for (const second of schedule.seconds) {
+                        if (first && hour === start.hour && minute === start.minute && second < start.second) {
+                            continue;
+                        }
+                        const epochs = wallTimeToEpochs(fmt, { year, month, day, hour, minute, second });
+                        // `epochs[0]` is undefined in a spring-forward gap (the wall time never occurs,
+                        // so it never fires); otherwise it is the FIRST (earlier-UTC) occurrence, which
+                        // makes a fall-back-repeated wall time fire exactly once. The strict `>` also
+                        // enforces the STRICTLY-after contract.
+                        const epoch = epochs[0];
+                        if (epoch !== undefined && epoch > afterMs)
+                            return epoch;
+                    }
+                }
+            }
+        }
+        dayCursor += DAY_MS;
+    }
+    return null;
+}

package/dist/engine.d.ts

@@ -0,0 +1,106 @@
+import type { JsonValue } from "@boardwalk-labs/workflow";
+import type { InferenceConfig } from "./agent/resolve.js";
+import type { Clock } from "./clock.js";
+import { Store, type EventRow, type RunRow, type TriggerKind, type WorkflowRow } from "./store/store.js";
+export interface EngineOptions {
+    /** Everything lives under here: `engine.db`, `runs/<id>/`. Created if missing. */
+    dataDir: string;
+    /** The local secret/env source (parsed .env contents). process.env is the fallback. */
+    env?: Record<string, string>;
+    /** Where secrets come from, for error hints (e.g. the .env path). Never values. */
+    envLabel?: string;
+    /** Default model + provider table for agent() leaves. */
+    inference?: InferenceConfig;
+    clock?: Clock;
+    /** Engine diagnostics (scheduler notices). Default: stderr. */
+    log?: (line: string) => void;
+    /** Crash restarts per run. Default 2. */
+    maxRestarts?: number;
+    /** Cooperative-cancellation window before SIGKILL. Default 10s. */
+    cancelGraceMs?: number;
+    /** Override the spawned run-process entry (tests point this at a built dist). */
+    childEntryPath?: string;
+    /** Scheduler loop cadence. Default 1s. */
+    tickIntervalMs?: number;
+}
+export interface AuthorizeMcpServerOptions {
+    /**
+     * Receives the authorization URL a HUMAN must open in a browser. The engine never opens a
+     * browser itself — the consumer (CLI prints it, a UI links it) owns that interaction.
+     */
+    onAuthorizationUrl: (url: string) => void;
+    /** How long to wait for the human to complete authorization. Default 5 minutes. */
+    timeoutMs?: number;
+}
+export interface DeployArgs {
+    /** The bundled workflow program (ESM, `@boardwalk-labs/workflow` external, pure-literal meta). */
+    program: string;
+    /** Engine-side deploy config (e.g. catch_up). Replaced wholesale on redeploy. */
+    config?: Record<string, JsonValue>;
+    /**
+     * Skill markdown deployed alongside the program, keyed by skill name (the CLI ships the
+     * project's skills/ dir this way). Every name declared in meta.skills must be present;
+     * replaced wholesale on redeploy.
+     */
+    skills?: Record<string, string>;
+}
+export declare class Engine {
+    readonly store: Store;
+    private readonly dataDir;
+    private readonly supervisor;
+    private readonly scheduler;
+    private started;
+    private closed;
+    constructor(opts: EngineOptions);
+    /**
+     * Server-mode boot: finalize/restart whatever a dead engine left behind, then run the cron
+     * loop. Embedded consumers never call this.
+     */
+    start(): {
+        resumed: string[];
+        cancelled: string[];
+    };
+    /** Stop scheduling, signal children (next boot's sweep recovers them), release the DB. */
+    close(): void;
+    /** Subscribe to every stamped run event (feeds SSE, the CLI renderer, the log UI). */
+    onEvent(listener: (row: EventRow) => void): () => void;
+    /**
+     * Deploy (or redeploy, by manifest name) a workflow from its bundled program source. The
+     * manifest is DERIVED from the program's pure-literal `meta` — the program file is the
+     * author's source of truth, manifest drift is impossible by construction.
+     */
+    deployWorkflow(args: DeployArgs): WorkflowRow;
+    /**
+     * Queue a run and dispatch it through the concurrency gate. Returns the queued row
+     * immediately; `waitForRun` for the terminal row.
+     */
+    startRun(workflowName: string, opts?: {
+        input?: JsonValue;
+        triggerKind?: TriggerKind;
+    }): RunRow;
+    /**
+     * One scheduler pass (fire due crons, dispatch queued runs through the concurrency gate).
+     * The background loop calls this every tick; expose it so embedders and tests can drive
+     * dispatch deterministically without the loop.
+     */
+    tick(): void;
+    /** Resolve when the run reaches a terminal status (idempotent; safe to call repeatedly). */
+    waitForRun(runId: string): Promise<RunRow>;
+    cancelRun(runId: string): Promise<void>;
+    /**
+     * The ONE-TIME interactive step for an OAuth-protected MCP server: discovery (RFC 9728 +
+     * 8414), dynamic client registration (RFC 7591), and the authorization-code + PKCE grant
+     * over a loopback redirect. Tokens land in `<dataDir>/mcp_tokens.json` (0600); after this,
+     * runs use the server headlessly (the engine refreshes silently). A headless run that needs
+     * authorization never prompts — it fails with a hint naming this method.
+     */
+    authorizeMcpServer(serverUrl: string, opts: AuthorizeMcpServerOptions): Promise<void>;
+    /**
+     * Embedded one-shot (the `boardwalk dev` path): deploy, run, await terminal. The workflow
+     * persists in the data dir like any other — dev reuses a throwaway dir per invocation.
+     */
+    runOnce(args: DeployArgs & {
+        input?: JsonValue;
+    }): Promise<RunRow>;
+    private assertOpen;
+}

package/dist/engine.js

@@ -0,0 +1,183 @@
+// The engine facade — the one object both consumers construct (SPEC §1):
+//   - SERVER mode: `start()` boots the recovery sweep + the cron scheduler loop and the
+//     process stays up (the HTTP surface sits on top of this object).
+//   - EMBEDDED mode: construct, `runOnce()`, `close()` — what `boardwalk dev` does. No
+//     scheduler loop, no recovery thread; one run, in-process supervision, exit.
+//
+// Layering: this file only wires store + supervisor + scheduler together and translates
+// program source → manifest at the deploy boundary. No business logic lives here.
+import { mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { extractManifest } from "@boardwalk-labs/workflow/extract";
+import { EngineError } from "./errors.js";
+import { runAuthorizationFlow } from "./mcp/oauth.js";
+import { McpTokenStore, MCP_TOKENS_FILENAME } from "./mcp/token_store.js";
+import { Scheduler } from "./scheduler/scheduler.js";
+import { Store, } from "./store/store.js";
+import { isTerminal, RunSupervisor } from "./run/supervisor.js";
+export class Engine {
+    store;
+    dataDir;
+    supervisor;
+    scheduler;
+    started = false;
+    closed = false;
+    constructor(opts) {
+        mkdirSync(opts.dataDir, { recursive: true });
+        this.dataDir = opts.dataDir;
+        this.store = new Store(join(opts.dataDir, "engine.db"));
+        this.supervisor = new RunSupervisor({
+            store: this.store,
+            dataDir: opts.dataDir,
+            childEntryPath: opts.childEntryPath ?? defaultChildEntryPath(),
+            env: new Map(Object.entries(opts.env ?? {})),
+            envLabel: opts.envLabel ?? "the engine environment",
+            ...(opts.clock !== undefined ? { clock: opts.clock } : {}),
+            ...(opts.maxRestarts !== undefined ? { maxRestarts: opts.maxRestarts } : {}),
+            ...(opts.cancelGraceMs !== undefined ? { cancelGraceMs: opts.cancelGraceMs } : {}),
+            ...(opts.inference !== undefined ? { inference: opts.inference } : {}),
+        });
+        this.scheduler = new Scheduler({
+            store: this.store,
+            dispatch: (runId) => void this.supervisor.supervise(runId),
+            emitQueued: (runId) => this.supervisor.emitQueued(runId),
+            ...(opts.clock !== undefined ? { clock: opts.clock } : {}),
+            ...(opts.log !== undefined ? { log: opts.log } : {}),
+            ...(opts.tickIntervalMs !== undefined ? { tickIntervalMs: opts.tickIntervalMs } : {}),
+        });
+    }
+    /**
+     * Server-mode boot: finalize/restart whatever a dead engine left behind, then run the cron
+     * loop. Embedded consumers never call this.
+     */
+    start() {
+        this.assertOpen();
+        if (this.started)
+            return { resumed: [], cancelled: [] };
+        this.started = true;
+        const swept = this.supervisor.recoverOnBoot();
+        this.scheduler.start();
+        return swept;
+    }
+    /** Stop scheduling, signal children (next boot's sweep recovers them), release the DB. */
+    close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        this.scheduler.stop();
+        this.supervisor.shutdown();
+        this.store.close();
+    }
+    /** Subscribe to every stamped run event (feeds SSE, the CLI renderer, the log UI). */
+    onEvent(listener) {
+        return this.supervisor.onEvent(listener);
+    }
+    /**
+     * Deploy (or redeploy, by manifest name) a workflow from its bundled program source. The
+     * manifest is DERIVED from the program's pure-literal `meta` — the program file is the
+     * author's source of truth, manifest drift is impossible by construction.
+     */
+    deployWorkflow(args) {
+        this.assertOpen();
+        const manifest = extractManifest(args.program, { fileName: "index.mjs" });
+        const workflow = this.store.upsertWorkflow({
+            name: manifest.name,
+            manifest,
+            program: args.program,
+            ...(args.config !== undefined ? { config: args.config } : {}),
+        });
+        // Skills are deploy artifacts, replaced wholesale: stale files from a previous deploy must
+        // not survive a redeploy that dropped them. (Skills are per-agent — no manifest field —
+        // so an agent() selecting an undeployed skill fails at call time, not here.)
+        const skills = Object.entries(args.skills ?? {});
+        const skillsDir = join(this.dataDir, "skills", workflow.id);
+        rmSync(skillsDir, { recursive: true, force: true });
+        if (skills.length > 0) {
+            mkdirSync(skillsDir, { recursive: true });
+            for (const [name, markdown] of skills) {
+                writeFileSync(join(skillsDir, `${name}.md`), markdown, "utf8");
+            }
+        }
+        return workflow;
+    }
+    /**
+     * Queue a run and dispatch it through the concurrency gate. Returns the queued row
+     * immediately; `waitForRun` for the terminal row.
+     */
+    startRun(workflowName, opts = {}) {
+        this.assertOpen();
+        const workflow = this.store.getWorkflow(workflowName);
+        if (workflow === null) {
+            throw new EngineError("NOT_FOUND", `Workflow "${workflowName}" is not deployed on this engine.`);
+        }
+        const { run } = this.store.createRun({
+            workflowId: workflow.id,
+            triggerKind: opts.triggerKind ?? "manual",
+            ...(opts.input !== undefined ? { input: opts.input } : {}),
+        });
+        this.supervisor.emitQueued(run.id);
+        // Why a synchronous tick: run-now should not wait for the next loop iteration, and manual
+        // runs go through the same dispatch gate as cron fires so concurrency modes hold uniformly.
+        this.scheduler.tick();
+        return run;
+    }
+    /**
+     * One scheduler pass (fire due crons, dispatch queued runs through the concurrency gate).
+     * The background loop calls this every tick; expose it so embedders and tests can drive
+     * dispatch deterministically without the loop.
+     */
+    tick() {
+        this.assertOpen();
+        this.scheduler.tick();
+    }
+    /** Resolve when the run reaches a terminal status (idempotent; safe to call repeatedly). */
+    waitForRun(runId) {
+        this.assertOpen();
+        const run = this.store.getRun(runId);
+        if (run === null)
+            throw new EngineError("NOT_FOUND", `Unknown run: ${runId}`);
+        if (isTerminal(run.status))
+            return Promise.resolve(run);
+        return this.supervisor.supervise(runId);
+    }
+    cancelRun(runId) {
+        this.assertOpen();
+        return this.supervisor.cancel(runId);
+    }
+    /**
+     * The ONE-TIME interactive step for an OAuth-protected MCP server: discovery (RFC 9728 +
+     * 8414), dynamic client registration (RFC 7591), and the authorization-code + PKCE grant
+     * over a loopback redirect. Tokens land in `<dataDir>/mcp_tokens.json` (0600); after this,
+     * runs use the server headlessly (the engine refreshes silently). A headless run that needs
+     * authorization never prompts — it fails with a hint naming this method.
+     */
+    async authorizeMcpServer(serverUrl, opts) {
+        this.assertOpen();
+        await runAuthorizationFlow({
+            serverUrl,
+            store: new McpTokenStore(join(this.dataDir, MCP_TOKENS_FILENAME)),
+            onAuthorizationUrl: opts.onAuthorizationUrl,
+            ...(opts.timeoutMs !== undefined ? { timeoutMs: opts.timeoutMs } : {}),
+        });
+    }
+    /**
+     * Embedded one-shot (the `boardwalk dev` path): deploy, run, await terminal. The workflow
+     * persists in the data dir like any other — dev reuses a throwaway dir per invocation.
+     */
+    async runOnce(args) {
+        const workflow = this.deployWorkflow(args);
+        const run = this.startRun(workflow.name, {
+            ...(args.input !== undefined ? { input: args.input } : {}),
+        });
+        return await this.waitForRun(run.id);
+    }
+    assertOpen() {
+        if (this.closed)
+            throw new EngineError("INTERNAL", "This engine has been closed.");
+    }
+}
+/** The compiled child entry that ships next to this module in dist/. */
+function defaultChildEntryPath() {
+    return fileURLToPath(new URL("./run/child.js", import.meta.url));
+}

package/dist/errors.d.ts

@@ -0,0 +1,15 @@
+export declare const ENGINE_ERROR_CODES: readonly ["VALIDATION", "NOT_FOUND", "CONFLICT", "SECRET_MISSING", "SECRET_UNDECLARED", "MODEL_UNRESOLVED", "PROVIDER_ERROR", "BUDGET_EXCEEDED", "PROGRAM_ERROR", "CRASHED", "CANCELLED", "UNSUPPORTED", "INTERNAL"];
+export type EngineErrorCode = (typeof ENGINE_ERROR_CODES)[number];
+/** Narrow a string (e.g. an error code off the IPC wire) to a known engine code. */
+export declare function isEngineErrorCode(code: string): code is EngineErrorCode;
+export declare class EngineError extends Error {
+    readonly code: EngineErrorCode;
+    /** A one-line pointer at the fix (file to edit, config to set) — safe to show anywhere. */
+    readonly hint: string | undefined;
+    constructor(code: EngineErrorCode, message: string, hint?: string);
+}
+/** Narrow an unknown thrown value to a safe { code, message } for events/API responses. */
+export declare function toErrorShape(err: unknown): {
+    code: string;
+    message: string;
+};

package/dist/errors.js

@@ -0,0 +1,40 @@
+// Engine errors carry a stable machine-readable code (surfaced in run_status `failed` events
+// and API responses) plus an actionable message. Messages NEVER contain secret values.
+export const ENGINE_ERROR_CODES = [
+    "VALIDATION", // bad manifest/config/input at a trust boundary
+    "NOT_FOUND", // unknown workflow/run
+    "CONFLICT", // duplicate name, concurrent state conflict
+    "SECRET_MISSING", // declared secret has no value in this environment
+    "SECRET_UNDECLARED", // program read a secret not in meta.secrets
+    "MODEL_UNRESOLVED", // agent() with no model and no configured default
+    "PROVIDER_ERROR", // upstream inference provider failure
+    "BUDGET_EXCEEDED", // run terminated by budget.*
+    "PROGRAM_ERROR", // the workflow program threw
+    "CRASHED", // run process died and restarts were exhausted
+    "CANCELLED",
+    "UNSUPPORTED", // capability not present on this engine (MASTER_SPEC §4)
+    "INTERNAL",
+];
+/** Narrow a string (e.g. an error code off the IPC wire) to a known engine code. */
+export function isEngineErrorCode(code) {
+    return ENGINE_ERROR_CODES.some((c) => c === code);
+}
+export class EngineError extends Error {
+    code;
+    /** A one-line pointer at the fix (file to edit, config to set) — safe to show anywhere. */
+    hint;
+    constructor(code, message, hint) {
+        super(message);
+        this.name = "EngineError";
+        this.code = code;
+        this.hint = hint;
+    }
+}
+/** Narrow an unknown thrown value to a safe { code, message } for events/API responses. */
+export function toErrorShape(err) {
+    if (err instanceof EngineError)
+        return { code: err.code, message: err.message };
+    if (err instanceof Error)
+        return { code: "PROGRAM_ERROR", message: err.message };
+    return { code: "PROGRAM_ERROR", message: String(err) };
+}