@boardwalk-labs/workflow 0.1.0

package/LICENSE

@@ -0,0 +1,18 @@
+MIT License
+
+Copyright (c) 2026 Boardwalk
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and
+associated documentation files (the "Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the
+following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial
+portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT
+LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO
+EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
+USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,51 @@
+# @boardwalk-labs/workflow
+
+Author **Boardwalk workflows** in plain TypeScript — agent loops, schedules, durable sleeps, and cross-workflow composition, in a single program file that runs identically on your laptop, your own server, or the hosted Boardwalk platform.
+
+```ts
+import { agent, output, secrets, type WorkflowMeta } from "@boardwalk-labs/workflow";
+
+export const meta = {
+  name: "morning-digest",
+  description: "Summarize my open issues every weekday at 9am",
+  triggers: [{ kind: "cron", expr: "0 9 * * 1-5" }],
+  secrets: [{ name: "GITHUB_TOKEN" }],
+} satisfies WorkflowMeta;
+
+const token = await secrets.get("GITHUB_TOKEN");
+const issues = await fetch("https://api.github.com/issues", {
+  headers: { Authorization: `Bearer ${token}` },
+}).then((r) => r.text());
+
+const summary = await agent(`Summarize for a morning digest:\n${issues}`);
+output(summary);
+```
+
+A workflow is **a script**: the `meta` export is a **pure literal** (engines derive the manifest from it statically, without executing your code), and the module body is the program — importing the file is running it. Top-level `await` is the norm; `output(value)` declares the result. Ordinary TypeScript throughout: any import, any control flow, any npm dependency.
+
+## What's in this package
+
+| Import                             | What it is                                                                                                                                                                                                    |
+| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `@boardwalk-labs/workflow`         | The author API: `agent()`, `sleep()`, `workflows.call()`, `secrets.get()`, `artifacts.write()`, `parallel()`, `input` / `output()` / `config`, `Phase()` — plus the manifest schema and run-event wire format |
+| `@boardwalk-labs/workflow/runtime` | The **engine-facing** API: install a `WorkflowHost` before evaluating a program. Authors never import this                                                                                                    |
+| `@boardwalk-labs/workflow/extract` | Static `meta` → manifest extraction (AST-based, never executes the program). Used by engines and tooling                                                                                                      |
+
+## The primitives, in one minute
+
+- **`agent(prompt, opts?)`** — run an agent loop and get its final text (or `schema`-validated JSON). `model` is optional: name one explicitly, or let the engine resolve it. Loops can use **tools** (built-in or program-defined), **MCP servers**, **skills**, and **memory** — each brought **per call** on `agent()`; the manifest declares none of them.
+- **`sleep(ms | { until })`** — durable wait; the run holds, locals survive.
+- **`workflows.call(name, input)`** — durably invoke another workflow and await its result; idempotent across restarts. `workflows.run` is the fire-and-forget sibling.
+- **`secrets.get(name)`** — read a secret declared in `meta.secrets`. Resolved from your `.env` locally, from the encrypted vault on hosted Boardwalk. Secret values never reach model context — the SDK contract requires engines to redact them.
+- **`output(value)`** — declare the run's result.
+- **Memory = a persistent directory, per agent.** `agent(prompt, { memory: "memory/triager" })` names any workspace-relative directory; the engine auto-persists it across runs — no declaration needed. The loop gets read/write file tools scoped to it, and your code can read and write the same files. (`workspace.persist` is the separate knob for non-memory state your program manages directly.)
+
+## Where workflows run
+
+One file, three engines: `boardwalk dev` (run it now, locally, no account), the self-hosted Boardwalk engine (your server), or [the Boardwalk platform](https://boardwalk.sh) (`boardwalk deploy` — hosted, scheduled, with automatic model routing). The same manifest schema and event stream everywhere; engine differences are limited to documented resolution behavior.
+
+The full authoring contract — every primitive, the manifest field inventory, and the run-event wire format — is in [`SPEC.md`](./SPEC.md).
+
+## License
+
+MIT

package/dist/events.d.ts

@@ -0,0 +1,191 @@
+import { z } from "zod";
+/** Cursor stride per turn: `cursor = turnNumber * STRIDE + seq`. seq is 1-based per turn. */
+export declare const TURN_CURSOR_STRIDE = 1000000;
+/** Compute the run-global cursor for an event. `turnNumber` is 0-based; `seq` is 1-based. */
+export declare function makeCursor(turnNumber: number, seq: number): number;
+export declare const tokenUsageSchema: z.ZodObject<{
+    inputTokens: z.ZodOptional<z.ZodNumber>;
+    outputTokens: z.ZodOptional<z.ZodNumber>;
+    cacheCreationTokens: z.ZodOptional<z.ZodNumber>;
+    cacheReadTokens: z.ZodOptional<z.ZodNumber>;
+    totalTokens: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>;
+export type TokenUsage = z.infer<typeof tokenUsageSchema>;
+export declare const toolReturnSchema: z.ZodObject<{
+    kind: z.ZodOptional<z.ZodString>;
+    humanSummary: z.ZodOptional<z.ZodString>;
+    data: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strict>;
+export type ToolReturn = z.infer<typeof toolReturnSchema>;
+declare const runStatusValues: readonly ["queued", "pending", "running", "completed", "failed", "cancelled", "cancelling"];
+export declare const runEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"run_status">;
+    status: z.ZodEnum<{
+        queued: "queued";
+        pending: "pending";
+        running: "running";
+        completed: "completed";
+        failed: "failed";
+        cancelled: "cancelled";
+        cancelling: "cancelling";
+    }>;
+    error: z.ZodOptional<z.ZodObject<{
+        code: z.ZodString;
+        message: z.ZodString;
+    }, z.core.$strict>>;
+    runId: z.ZodString;
+    turnId: z.ZodString;
+    seq: z.ZodNumber;
+    t: z.ZodNumber;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"phase">;
+    name: z.ZodString;
+    id: z.ZodString;
+    runId: z.ZodString;
+    turnId: z.ZodString;
+    seq: z.ZodNumber;
+    t: z.ZodNumber;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"output">;
+    value: z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>;
+    runId: z.ZodString;
+    turnId: z.ZodString;
+    seq: z.ZodNumber;
+    t: z.ZodNumber;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"program_output">;
+    stream: z.ZodEnum<{
+        stdout: "stdout";
+        stderr: "stderr";
+    }>;
+    text: z.ZodString;
+    runId: z.ZodString;
+    turnId: z.ZodString;
+    seq: z.ZodNumber;
+    t: z.ZodNumber;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"turn_started">;
+    runId: z.ZodString;
+    turnId: z.ZodString;
+    seq: z.ZodNumber;
+    t: z.ZodNumber;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"turn_ended">;
+    reason: z.ZodEnum<{
+        error: "error";
+        cancelled: "cancelled";
+        complete: "complete";
+    }>;
+    usage: z.ZodOptional<z.ZodObject<{
+        inputTokens: z.ZodOptional<z.ZodNumber>;
+        outputTokens: z.ZodOptional<z.ZodNumber>;
+        cacheCreationTokens: z.ZodOptional<z.ZodNumber>;
+        cacheReadTokens: z.ZodOptional<z.ZodNumber>;
+        totalTokens: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>;
+    error: z.ZodOptional<z.ZodObject<{
+        code: z.ZodString;
+        message: z.ZodString;
+    }, z.core.$strict>>;
+    runId: z.ZodString;
+    turnId: z.ZodString;
+    seq: z.ZodNumber;
+    t: z.ZodNumber;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"text_start">;
+    blockId: z.ZodString;
+    runId: z.ZodString;
+    turnId: z.ZodString;
+    seq: z.ZodNumber;
+    t: z.ZodNumber;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"text_delta">;
+    blockId: z.ZodString;
+    text: z.ZodString;
+    runId: z.ZodString;
+    turnId: z.ZodString;
+    seq: z.ZodNumber;
+    t: z.ZodNumber;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"text_end">;
+    blockId: z.ZodString;
+    runId: z.ZodString;
+    turnId: z.ZodString;
+    seq: z.ZodNumber;
+    t: z.ZodNumber;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"tool_call_start">;
+    toolCallId: z.ZodString;
+    toolName: z.ZodString;
+    runId: z.ZodString;
+    turnId: z.ZodString;
+    seq: z.ZodNumber;
+    t: z.ZodNumber;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"tool_call_input_delta">;
+    toolCallId: z.ZodString;
+    partialJson: z.ZodString;
+    runId: z.ZodString;
+    turnId: z.ZodString;
+    seq: z.ZodNumber;
+    t: z.ZodNumber;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"tool_call_input_complete">;
+    toolCallId: z.ZodString;
+    input: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    runId: z.ZodString;
+    turnId: z.ZodString;
+    seq: z.ZodNumber;
+    t: z.ZodNumber;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"tool_call_executing">;
+    toolCallId: z.ZodString;
+    runId: z.ZodString;
+    turnId: z.ZodString;
+    seq: z.ZodNumber;
+    t: z.ZodNumber;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"tool_call_result">;
+    toolCallId: z.ZodString;
+    result: z.ZodObject<{
+        kind: z.ZodOptional<z.ZodString>;
+        humanSummary: z.ZodOptional<z.ZodString>;
+        data: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strict>;
+    runId: z.ZodString;
+    turnId: z.ZodString;
+    seq: z.ZodNumber;
+    t: z.ZodNumber;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"tool_call_error">;
+    toolCallId: z.ZodString;
+    error: z.ZodObject<{
+        code: z.ZodString;
+        message: z.ZodString;
+    }, z.core.$strict>;
+    runId: z.ZodString;
+    turnId: z.ZodString;
+    seq: z.ZodNumber;
+    t: z.ZodNumber;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"reasoning_delta">;
+    text: z.ZodString;
+    runId: z.ZodString;
+    turnId: z.ZodString;
+    seq: z.ZodNumber;
+    t: z.ZodNumber;
+}, z.core.$strict>], "kind">;
+export type RunEvent = z.infer<typeof runEventSchema>;
+export type RunEventKind = RunEvent["kind"];
+export type EventEnvelope = Pick<RunEvent, "runId" | "turnId" | "seq" | "t">;
+export type RunStatus = (typeof runStatusValues)[number];
+/** Subscription channels. Every event kind maps to exactly one channel. */
+export declare const CHANNELS: readonly ["lifecycle", "phase", "output", "log", "agent"];
+export type Channel = (typeof CHANNELS)[number];
+/** The default subscription — quiet and readable. `verbose` = all of {@link CHANNELS}. */
+export declare const DEFAULT_CHANNELS: readonly Channel[];
+/** The channel an event belongs to. */
+export declare function channelOf(event: Pick<RunEvent, "kind">): Channel;
+/** Server-side subscription filter: does this event belong to one of the subscribed channels? */
+export declare function matchesChannels(event: Pick<RunEvent, "kind">, channels: readonly Channel[]): boolean;
+export {};

package/dist/events.js

@@ -0,0 +1,213 @@
+// The run-event wire format — one typed, ordered stream per run, identical in every engine.
+//
+// Every event carries an envelope (runId, turnId, per-turn 1-based seq, server timestamp) and
+// a RUN-GLOBAL MONOTONIC CURSOR derived from (turn number, seq). Consumers resume from a
+// cursor (SSE `Last-Event-ID` semantics). Every event kind maps to exactly ONE subscription
+// channel; filtering happens server-side, and cursors stay globally consistent so a filtered
+// subscription resumes correctly.
+import { z } from "zod";
+// ============================================================================
+// Cursor
+// ============================================================================
+/** Cursor stride per turn: `cursor = turnNumber * STRIDE + seq`. seq is 1-based per turn. */
+export const TURN_CURSOR_STRIDE = 1_000_000;
+/** Compute the run-global cursor for an event. `turnNumber` is 0-based; `seq` is 1-based. */
+export function makeCursor(turnNumber, seq) {
+    if (!Number.isInteger(turnNumber) || turnNumber < 0) {
+        throw new RangeError(`turnNumber must be a non-negative integer (got ${String(turnNumber)})`);
+    }
+    if (!Number.isInteger(seq) || seq < 1 || seq >= TURN_CURSOR_STRIDE) {
+        throw new RangeError(`seq must be an integer in [1, ${String(TURN_CURSOR_STRIDE)}) (got ${String(seq)})`);
+    }
+    return turnNumber * TURN_CURSOR_STRIDE + seq;
+}
+// ============================================================================
+// Envelope + shared shapes
+// ============================================================================
+const envelopeShape = {
+    /** The run this event belongs to. */
+    runId: z.string().min(1),
+    /** Identifies one logical stream segment (a new id per agent turn; run-level frames reuse the run's). */
+    turnId: z.string().min(1),
+    /** Monotonic 1-based sequence within the turn. */
+    seq: z.number().int().min(1),
+    /** Server time at emission, ms since epoch. */
+    t: z.number().int().nonnegative(),
+};
+export const tokenUsageSchema = z.strictObject({
+    inputTokens: z.number().int().nonnegative().optional(),
+    outputTokens: z.number().int().nonnegative().optional(),
+    cacheCreationTokens: z.number().int().nonnegative().optional(),
+    cacheReadTokens: z.number().int().nonnegative().optional(),
+    totalTokens: z.number().int().nonnegative().optional(),
+});
+export const toolReturnSchema = z.strictObject({
+    /** Opaque discriminator for client rendering. */
+    kind: z.string().optional(),
+    /** One-sentence summary suitable for a log line. */
+    humanSummary: z.string().optional(),
+    /** Tool-specific payload. */
+    data: z.record(z.string(), z.unknown()).optional(),
+});
+const eventErrorSchema = z.strictObject({
+    code: z.string(),
+    message: z.string(),
+});
+const jsonValueSchema = z.unknown();
+// ============================================================================
+// Event kinds
+// ============================================================================
+const runStatusValues = [
+    "queued",
+    "pending",
+    "running",
+    "completed",
+    "failed",
+    "cancelled",
+    "cancelling",
+];
+// -- lifecycle channel --------------------------------------------------------
+const runStatusEvent = z.strictObject({
+    ...envelopeShape,
+    kind: z.literal("run_status"),
+    status: z.enum(runStatusValues),
+    /** Present on `failed` — why the run failed. */
+    error: eventErrorSchema.optional(),
+});
+// -- phase channel -------------------------------------------------------------
+const phaseEvent = z.strictObject({
+    ...envelopeShape,
+    kind: z.literal("phase"),
+    name: z.string().min(1),
+    /** Stable phase identifier (author-supplied or engine-assigned in marker order). */
+    id: z.string().min(1),
+});
+// -- output channel -------------------------------------------------------------
+const outputEvent = z.strictObject({
+    ...envelopeShape,
+    kind: z.literal("output"),
+    value: jsonValueSchema,
+});
+// -- log channel ----------------------------------------------------------------
+const programOutputEvent = z.strictObject({
+    ...envelopeShape,
+    kind: z.literal("program_output"),
+    stream: z.enum(["stdout", "stderr"]),
+    text: z.string(),
+});
+// -- agent channel ----------------------------------------------------------------
+const turnStarted = z.strictObject({ ...envelopeShape, kind: z.literal("turn_started") });
+const turnEnded = z.strictObject({
+    ...envelopeShape,
+    kind: z.literal("turn_ended"),
+    reason: z.enum(["complete", "cancelled", "error"]),
+    usage: tokenUsageSchema.optional(),
+    error: eventErrorSchema.optional(),
+});
+const textStart = z.strictObject({
+    ...envelopeShape,
+    kind: z.literal("text_start"),
+    blockId: z.string(),
+});
+const textDelta = z.strictObject({
+    ...envelopeShape,
+    kind: z.literal("text_delta"),
+    blockId: z.string(),
+    text: z.string(),
+});
+const textEnd = z.strictObject({
+    ...envelopeShape,
+    kind: z.literal("text_end"),
+    blockId: z.string(),
+});
+const toolCallStart = z.strictObject({
+    ...envelopeShape,
+    kind: z.literal("tool_call_start"),
+    toolCallId: z.string(),
+    toolName: z.string(),
+});
+const toolCallInputDelta = z.strictObject({
+    ...envelopeShape,
+    kind: z.literal("tool_call_input_delta"),
+    toolCallId: z.string(),
+    partialJson: z.string(),
+});
+const toolCallInputComplete = z.strictObject({
+    ...envelopeShape,
+    kind: z.literal("tool_call_input_complete"),
+    toolCallId: z.string(),
+    input: z.record(z.string(), z.unknown()),
+});
+const toolCallExecuting = z.strictObject({
+    ...envelopeShape,
+    kind: z.literal("tool_call_executing"),
+    toolCallId: z.string(),
+});
+const toolCallResult = z.strictObject({
+    ...envelopeShape,
+    kind: z.literal("tool_call_result"),
+    toolCallId: z.string(),
+    result: toolReturnSchema,
+});
+const toolCallError = z.strictObject({
+    ...envelopeShape,
+    kind: z.literal("tool_call_error"),
+    toolCallId: z.string(),
+    error: eventErrorSchema,
+});
+const reasoningDelta = z.strictObject({
+    ...envelopeShape,
+    kind: z.literal("reasoning_delta"),
+    text: z.string(),
+});
+export const runEventSchema = z.discriminatedUnion("kind", [
+    runStatusEvent,
+    phaseEvent,
+    outputEvent,
+    programOutputEvent,
+    turnStarted,
+    turnEnded,
+    textStart,
+    textDelta,
+    textEnd,
+    toolCallStart,
+    toolCallInputDelta,
+    toolCallInputComplete,
+    toolCallExecuting,
+    toolCallResult,
+    toolCallError,
+    reasoningDelta,
+]);
+// ============================================================================
+// Channels
+// ============================================================================
+/** Subscription channels. Every event kind maps to exactly one channel. */
+export const CHANNELS = ["lifecycle", "phase", "output", "log", "agent"];
+/** The default subscription — quiet and readable. `verbose` = all of {@link CHANNELS}. */
+export const DEFAULT_CHANNELS = ["lifecycle", "phase", "output"];
+const KIND_TO_CHANNEL = {
+    run_status: "lifecycle",
+    phase: "phase",
+    output: "output",
+    program_output: "log",
+    turn_started: "agent",
+    turn_ended: "agent",
+    text_start: "agent",
+    text_delta: "agent",
+    text_end: "agent",
+    tool_call_start: "agent",
+    tool_call_input_delta: "agent",
+    tool_call_input_complete: "agent",
+    tool_call_executing: "agent",
+    tool_call_result: "agent",
+    tool_call_error: "agent",
+    reasoning_delta: "agent",
+};
+/** The channel an event belongs to. */
+export function channelOf(event) {
+    return KIND_TO_CHANNEL[event.kind];
+}
+/** Server-side subscription filter: does this event belong to one of the subscribed channels? */
+export function matchesChannels(event, channels) {
+    return channels.includes(channelOf(event));
+}

package/dist/extract.d.ts

@@ -0,0 +1,27 @@
+import { type WorkflowManifest } from "./manifest.js";
+/** Thrown when a program's `meta` cannot be statically extracted as a pure literal. */
+export declare class MetaExtractionError extends Error {
+    constructor(message: string);
+}
+export interface MetaExtractionOptions {
+    /**
+     * Logical file name. Drives TS-vs-JS parsing (the `.ts`/`.js` extension) and the
+     * `file:line:col` prefix in error messages. Defaults to `index.ts`.
+     */
+    fileName?: string;
+}
+/**
+ * Statically extract the raw `meta` pure-literal object from a workflow program's source.
+ *
+ * Returns the plain JS object exactly as written (no schema defaults applied). Throws
+ * {@link MetaExtractionError} when there is no `meta` declaration, when it is not an object
+ * literal, or when any part of it is not a pure literal.
+ */
+export declare function extractMetaLiteral(source: string, options?: MetaExtractionOptions): Record<string, unknown>;
+/**
+ * Statically extract `meta` and validate it against the manifest schema, returning the
+ * fully-defaulted, validated manifest (the contract every engine consumes). Throws
+ * {@link MetaExtractionError} on an unextractable literal, or `MetaValidationError` (from
+ * `validateMeta`) on a schema violation.
+ */
+export declare function extractManifest(source: string, options?: MetaExtractionOptions): WorkflowManifest;