@boardwalk-labs/workflow 0.1.0

package/dist/manifest.js

@@ -0,0 +1,227 @@
+// workflowManifestSchema — the validator of record for a workflow's `meta`.
+//
+// One Zod schema, consumed by every engine (local `dev`, the self-hosted server, Boardwalk
+// hosted platform) and by `extract.ts` after pure-literal extraction. The TS manifest type is derived
+// from the schema, never hand-written. Unknown fields are validation errors — no silent drift.
+//
+// Union ordering rule: most-specific-first. Zod unions are first-match-wins and strict objects
+// reject extras, but keep the discipline anyway — a less-specific variant listed first can
+// silently strip fields if an object is ever relaxed from strict.
+import { z } from "zod";
+// ============================================================================
+// Shared scalars
+// ============================================================================
+const NAME_RE = /^[a-zA-Z0-9-]+$/;
+const workflowName = z
+    .string()
+    .min(1)
+    .max(100)
+    .regex(NAME_RE, "name must be alphanumeric with hyphens");
+/** A short identifier (tool/MCP/skill/secret names). */
+const shortName = z.string().min(1).max(120);
+/** Loosely-typed JSON Schema objects (input_schema / output_schema / tool inputSchema). */
+const jsonSchemaObject = z.record(z.string(), z.unknown());
+// ============================================================================
+// Triggers
+// ============================================================================
+const cronExpr = z
+    .string()
+    .min(1)
+    .max(120)
+    .refine((expr) => {
+    const fields = expr.trim().split(/\s+/);
+    return fields.length === 5 || fields.length === 6;
+}, { message: "cron expression must have 5 fields (standard) or 6 (with seconds)" });
+const cronTriggerSchema = z.strictObject({
+    kind: z.literal("cron"),
+    expr: cronExpr,
+    timezone: z.string().min(1).max(80).optional(),
+});
+const webhookTriggerSchema = z.strictObject({
+    kind: z.literal("webhook"),
+    auth: z.enum(["token", "signature"]),
+});
+const manualTriggerSchema = z.strictObject({
+    kind: z.literal("manual"),
+});
+const triggerSchema = z.discriminatedUnion("kind", [
+    cronTriggerSchema,
+    webhookTriggerSchema,
+    manualTriggerSchema,
+]);
+// ============================================================================
+// Secrets and env
+// ============================================================================
+/** A secret ref is exactly `{ name }` — secrets + env vars are the entire credential story. */
+const secretRefSchema = z.strictObject({ name: shortName });
+const RESERVED_ENV_PREFIX_RE = /^(boardwalk_|aws_)/i;
+/** The ONLY supported interpolation: a whole-value `${{ secrets.NAME }}` reference. */
+const WHOLE_VALUE_SECRET_RE = /^\$\{\{\s*secrets\.[A-Za-z0-9_-]+\s*\}\}$/;
+const envVarsSchema = z
+    .record(z.string().min(1).max(120), z.string().max(32_768))
+    .superRefine((vars, ctx) => {
+    const keys = Object.keys(vars);
+    if (keys.length > 100) {
+        ctx.addIssue({ code: "custom", message: "at most 100 env vars are allowed" });
+    }
+    for (const key of keys) {
+        if (RESERVED_ENV_PREFIX_RE.test(key)) {
+            ctx.addIssue({
+                code: "custom",
+                path: [key],
+                message: `"${key}" uses a reserved prefix (BOARDWALK_* / AWS_*)`,
+            });
+        }
+        const value = vars[key];
+        if (value !== undefined && value.includes("${{") && !WHOLE_VALUE_SECRET_RE.test(value)) {
+            ctx.addIssue({
+                code: "custom",
+                path: [key],
+                message: "only whole-value secret references are supported — write exactly " +
+                    '"${{ secrets.NAME }}" (no partial interpolation)',
+            });
+        }
+    }
+});
+// ============================================================================
+// Workspace (program-level persistent directories; agent memory is separate + auto-persisted)
+// ============================================================================
+/** Workspace-relative, no escapes: rejects absolute paths, backslashes, `..` and `.` segments. */
+const persistPath = z
+    .string()
+    .min(1)
+    .max(512)
+    .refine((p) => !p.startsWith("/") && !p.includes("\\"), {
+    message: "persist paths must be workspace-relative (no leading / or backslashes)",
+})
+    .refine((p) => p.split("/").every((seg) => seg !== "" && seg !== "." && seg !== ".."), {
+    message: "persist paths must not contain `..`, `.` or empty segments",
+});
+const workspaceSchema = z.strictObject({
+    persist: z.union([z.boolean(), z.array(persistPath).min(1).max(50)]).optional(),
+});
+// ============================================================================
+// Budget and concurrency
+// ============================================================================
+const budgetSchema = z.strictObject({
+    max_tokens: z.number().int().positive().optional(),
+    max_usd: z.number().positive().finite().optional(),
+    max_duration_seconds: z.number().int().positive().optional(),
+});
+const concurrencySchema = z.union([
+    z.strictObject({ mode: z.literal("serial_by_key"), key: z.string().min(1).max(200) }),
+    z.strictObject({ mode: z.literal("serial") }),
+    z.strictObject({ mode: z.literal("unlimited") }),
+]);
+// ============================================================================
+// Agent capabilities: NONE on the manifest — tools/mcp/skills/memory are all per-agent
+// ============================================================================
+// Used only by the platform-extension permissions.tools (hosted run-permission scoping).
+const toolGrantSchema = z.strictObject({
+    name: shortName,
+    config: z.record(z.string(), z.unknown()).optional(),
+    scope: z.array(z.string().min(1).max(200)).optional(),
+});
+// ============================================================================
+// Runner selection
+// ============================================================================
+const hostedRunsOnLabel = z.enum([
+    "boardwalk/linux",
+    "boardwalk/linux-node",
+    "boardwalk/linux-python",
+    "boardwalk/linux-large",
+]);
+const runsOnSchema = z.union([
+    z.strictObject({
+        kind: z.literal("self-hosted"),
+        pool: z.string().min(1).max(120),
+        labels: z.array(z.string().min(1).max(120)).optional(),
+    }),
+    z.strictObject({
+        label: hostedRunsOnLabel,
+        size: z.enum(["small", "medium", "large", "xlarge"]).optional(),
+    }),
+    hostedRunsOnLabel,
+]);
+// ============================================================================
+// Platform-extension fields (validated everywhere, enforced where the capability exists)
+// ============================================================================
+const containerSchema = z.strictObject({ image: z.string().min(1).max(512) });
+const permissionAccess = z.enum(["none", "read", "write"]);
+const permissionsSchema = z.strictObject({
+    id_token: z.enum(["none", "write"]).optional(),
+    artifacts: permissionAccess.optional(),
+    contents: permissionAccess.optional(),
+    secrets: z.array(secretRefSchema).optional(),
+    tools: z.array(toolGrantSchema).optional(),
+});
+const callableBySchema = z.union([
+    z.strictObject({ roles: z.array(z.enum(["owner", "admin", "member", "viewer"])).min(1) }),
+    z.strictObject({ workflows: z.array(workflowName).min(1) }),
+    z.enum(["anyone_in_org", "users_only", "workflows_only"]),
+]);
+const egressSchema = z.union([
+    z.strictObject({
+        level: z.literal("custom"),
+        allow: z.array(z.string().min(1).max(256)).min(1),
+        include_defaults: z.boolean().optional(),
+    }),
+    z.strictObject({ level: z.enum(["none", "trusted", "full"]) }),
+]);
+const notificationSchema = z.union([
+    z.strictObject({
+        on: z.enum(["completion", "failure", "cancelled"]),
+        channel: z.enum(["email", "webhook"]),
+        target: z.string().min(1).max(2048),
+        template: z.string().max(10_000).optional(),
+    }),
+    z.strictObject({
+        on: z.literal("budget_exceeded"),
+        channel: z.literal("email"),
+        target: z.string().min(1).max(2048),
+    }),
+]);
+// ============================================================================
+// The manifest
+// ============================================================================
+export const workflowManifestSchema = z.strictObject({
+    name: workflowName,
+    description: z.string().max(1000).optional(),
+    triggers: z.array(triggerSchema).min(1),
+    secrets: z.array(secretRefSchema).optional(),
+    env: envVarsSchema.optional(),
+    input_schema: jsonSchemaObject.optional(),
+    output_schema: jsonSchemaObject.optional(),
+    workspace: workspaceSchema.optional(),
+    budget: budgetSchema.optional(),
+    concurrency: concurrencySchema.default({ mode: "unlimited" }),
+    // NO capability fields (tools/mcp/skills/memory) — all per-agent via AgentOptions.
+    runs_on: runsOnSchema.default("boardwalk/linux"),
+    // Platform-extension fields.
+    container: containerSchema.optional(),
+    permissions: permissionsSchema.optional(),
+    callable_by: callableBySchema.default("anyone_in_org"),
+    egress: egressSchema.optional(),
+    notifications: z.array(notificationSchema).optional(),
+});
+/**
+ * Validate an already-extracted `meta` object (e.g. from `extract.ts` or a test fixture) and
+ * return the manifest, or throw a `MetaValidationError` listing every issue with its path.
+ */
+export function validateMeta(meta) {
+    const result = workflowManifestSchema.safeParse(meta);
+    if (!result.success) {
+        const issues = result.error.issues
+            .map((i) => `  ${i.path.length > 0 ? i.path.join(".") : "(root)"}: ${i.message}`)
+            .join("\n");
+        throw new MetaValidationError(`Workflow \`meta\` failed manifest validation:\n${issues}`);
+    }
+    return result.data;
+}
+/** Thrown by {@link validateMeta} when a `meta` object violates the manifest schema. */
+export class MetaValidationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "MetaValidationError";
+    }
+}

package/dist/meta.d.ts

@@ -0,0 +1,164 @@
+export interface CronTrigger {
+    kind: "cron";
+    /** Cron expression (5-field standard or 6-field with seconds). */
+    expr: string;
+    /** IANA timezone (e.g. `America/Anchorage`). Defaults to UTC. */
+    timezone?: string;
+}
+/** Server engines only (the self-hosted server and the hosted Boardwalk platform) — `dev` has no listener. */
+export interface WebhookTrigger {
+    kind: "webhook";
+    auth: "token" | "signature";
+}
+export interface ManualTrigger {
+    kind: "manual";
+}
+export type Trigger = CronTrigger | WebhookTrigger | ManualTrigger;
+/**
+ * A built-in tool grant, with optional configuration. Used only by the platform-extension
+ * `permissions.tools` (hosted run-permission scoping) — agent tool selection is per-call.
+ */
+export interface ToolGrant {
+    name: string;
+    config?: Record<string, unknown>;
+    scope?: readonly string[];
+}
+/**
+ * An MCP server an `agent()` call connects to (inline in `AgentOptions.mcp` — per-agent, no
+ * meta declaration). The program is the trusted layer: put credentials in `env`/`headers`
+ * directly (e.g. from `secrets.get`) — no interpolation syntax.
+ */
+export type McpServerRef = {
+    name: string;
+    transport: "stdio";
+    command: string;
+    args?: readonly string[];
+    env?: Record<string, string>;
+} | {
+    name: string;
+    transport: "http";
+    url: string;
+    headers?: Record<string, string>;
+};
+export type Concurrency = {
+    mode: "unlimited";
+} | {
+    mode: "serial";
+} | {
+    mode: "serial_by_key";
+    key: string;
+};
+export type HostedRunsOn = "boardwalk/linux" | "boardwalk/linux-node" | "boardwalk/linux-python" | "boardwalk/linux-large";
+export type HostedRunnerSize = "small" | "medium" | "large" | "xlarge";
+export interface HostedRunsOnObject {
+    label: HostedRunsOn;
+    size?: HostedRunnerSize;
+}
+export interface SelfHostedRunsOn {
+    kind: "self-hosted";
+    pool: string;
+    labels?: readonly string[];
+}
+export type RunsOn = HostedRunsOn | HostedRunsOnObject | SelfHostedRunsOn;
+export interface Container {
+    /** Fully-qualified image reference. Hosted-platform capability. */
+    image: string;
+}
+/**
+ * A secret the program may read with `secrets.get(name)` — an allowlist entry, never a value.
+ * Resolution is engine-dependent: environment/`.env` on local engines, the encrypted vault on
+ * the Boardwalk platform. Secrets + env vars are the entire credential story.
+ */
+export interface SecretRef {
+    name: string;
+}
+/**
+ * Environment variables for the run. A value is either non-secret plaintext, or a whole-value
+ * secret reference `"${{ secrets.NAME }}"` resolved at run time (never stored in the manifest).
+ * Referencing a secret here also grants the run access to it. Reserved `BOARDWALK_*` / `AWS_*`
+ * keys are not allowed.
+ */
+export type EnvVars = Record<string, string>;
+export type EgressPolicy = {
+    level: "none";
+} | {
+    level: "trusted";
+} | {
+    level: "full";
+} | {
+    level: "custom";
+    allow: readonly string[];
+    include_defaults?: boolean;
+};
+export type RunPermissionAccess = "none" | "read" | "write";
+export interface RunPermissions {
+    id_token?: "none" | "write";
+    artifacts?: RunPermissionAccess;
+    contents?: RunPermissionAccess;
+    secrets?: readonly SecretRef[];
+    tools?: readonly ToolGrant[];
+}
+export type OrgRole = "owner" | "admin" | "member" | "viewer";
+export type CallableBy = "anyone_in_org" | "users_only" | "workflows_only" | {
+    roles: readonly OrgRole[];
+} | {
+    workflows: readonly string[];
+};
+export type Notification = {
+    on: "completion" | "failure" | "cancelled";
+    channel: "email" | "webhook";
+    target: string;
+    template?: string;
+} | {
+    on: "budget_exceeded";
+    channel: "email";
+    target: string;
+};
+/** Enforced by engines — breaching a budget terminates the run, it doesn't truncate silently. */
+export interface Budget {
+    max_tokens?: number;
+    max_usd?: number;
+    max_duration_seconds?: number;
+}
+/**
+ * Persistent directories for the PROGRAM (not the same thing as agent memory).
+ *
+ * Every run gets a writable workspace directory that exists before your program runs; without
+ * `persist` it is scratch space, discarded at run end. `persist: true` persists the whole
+ * workspace across runs; a list persists exactly those WORKSPACE-RELATIVE subdirectories
+ * (`"cache"`, `"index"`, …) — `..` or absolute paths are validation errors. Persisted
+ * directories are hydrated at run start and written back at successful run end; concurrent
+ * runs sharing one are last-writer-wins, so prefer `concurrency: { mode: "serial" }`.
+ *
+ * Agent **memory** is separate and needs no declaration here: `agent(prompt, { memory: "<dir>" })`
+ * names any workspace-relative directory and the engine auto-persists it across runs (see
+ * {@link import("./types.js").AgentOptions}.memory). Use `workspace.persist` for non-memory
+ * state your program code manages directly.
+ */
+export interface Workspace {
+    persist?: boolean | readonly string[];
+}
+/**
+ * The pure-literal contract a workflow program exports. Must be a literal — no variables,
+ * calls, spreads, or interpolation — so engines can statically extract it without executing
+ * the program. Validated by `workflowManifestSchema`; unknown fields are errors.
+ */
+export interface WorkflowMeta {
+    name: string;
+    description?: string;
+    /** At least one trigger is required. */
+    triggers: readonly Trigger[];
+    secrets?: readonly SecretRef[];
+    env?: EnvVars;
+    input_schema?: Record<string, unknown>;
+    output_schema?: Record<string, unknown>;
+    workspace?: Workspace;
+    budget?: Budget;
+    concurrency?: Concurrency;
+    runs_on?: RunsOn;
+    container?: Container;
+    permissions?: RunPermissions;
+    callable_by?: CallableBy;
+    egress?: EgressPolicy;
+    notifications?: readonly Notification[];
+}

package/dist/meta.js

@@ -0,0 +1,8 @@
+// WorkflowMeta — the TypeScript shape of a workflow's `meta` export.
+//
+// A workflow program declares `export const meta = { … } satisfies WorkflowMeta`. The
+// `satisfies` operator is type-only and erased at compile time, so it does NOT break the
+// pure-literal static extraction engines perform over the source (see extract.ts). This type
+// is the author-facing typing; `workflowManifestSchema` (manifest.ts) is the validator of
+// record — the two are kept faithful to each other.
+export {};

package/dist/runtime.d.ts

@@ -0,0 +1,3 @@
+export { installHost, installInput, installConfig, takeDeclaredOutput, resetRuntime, requireHost, } from "./host.js";
+export type { WorkflowHost } from "./host.js";
+export type { AgentOptions, ToolDef, ArtifactBody, ArtifactRef, CallOptions, JsonValue, PhaseOptions, SleepArg, JsonSchema, } from "./types.js";

package/dist/runtime.js

@@ -0,0 +1,6 @@
+// @boardwalk-labs/workflow/runtime — the ENGINE-facing API.
+//
+// An engine imports this to install the host adapter and the trigger payload BEFORE
+// evaluating a workflow program. Authors never import this — they import the hooks
+// from "@boardwalk-labs/workflow".
+export { installHost, installInput, installConfig, takeDeclaredOutput, resetRuntime, requireHost, } from "./host.js";

package/dist/types.d.ts

@@ -0,0 +1,110 @@
+import type { McpServerRef } from "./meta.js";
+/** A JSON Schema object (loosely typed — the engine validates against it). */
+export type JsonSchema = Record<string, unknown>;
+/** Any JSON value — the shape of the run's `config`, `output(...)`, and event payloads. */
+export type JsonValue = string | number | boolean | null | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+/**
+ * A program-defined tool for an {@link import("./index.js").agent} loop. `execute` runs in the
+ * program process — the trusted layer (it may read secrets); only its RETURN VALUE enters model
+ * context, subject to secret redaction.
+ */
+export interface ToolDef {
+    /** Tool name the model sees. Unique within the call's tool set. */
+    name: string;
+    /** What the tool does — the model chooses tools by this. */
+    description: string;
+    /** JSON Schema for the tool's input. */
+    inputSchema: JsonSchema;
+    /** Runs in the program process; the resolved value is returned to the model (redacted). */
+    execute: (input: unknown) => Promise<unknown>;
+}
+/**
+ * Options for an {@link import("./index.js").agent} leaf call. Capabilities are PER-AGENT:
+ * each call brings its own `tools`, `mcp` servers, `skills`, and `memory` — the manifest
+ * declares none of them. A plain `agent(prompt)` is simple inference.
+ */
+export interface AgentOptions {
+    /**
+     * The model, as an OPAQUE string passed VERBATIM to the provider — engines never parse,
+     * prefix, or rewrite it. Use whatever identifier your provider expects (e.g.
+     * `claude-sonnet-4-5` for Anthropic; `anthropic/sonnet-4.5` if that's what your local
+     * server serves it as). OPTIONAL — when omitted, the provider routes automatically (the
+     * default `boardwalk` provider's Auto lane). Fulfillment is chosen by `provider`, never
+     * by anything in this string.
+     */
+    model?: string;
+    /**
+     * Who fulfills this leaf. Defaults to `boardwalk` (Boardwalk-managed inference) on EVERY
+     * engine; your own keys are used only when this names a non-`boardwalk` provider — a
+     * built-in vendor (`anthropic`, `openai`, …) or a provider configured on the engine.
+     */
+    provider?: string;
+    /**
+     * JSON Schema for the leaf's structured output. When supplied, `agent()` resolves to the
+     * validated object (the run fails on mismatch); without it, to the leaf's final text.
+     */
+    schema?: JsonSchema;
+    /**
+     * Tools this leaf may use: engine built-in names, plus inline program-defined
+     * {@link ToolDef}s. Per-agent — no meta declaration. Defaults to none.
+     */
+    tools?: readonly (string | ToolDef)[];
+    /**
+     * MCP servers this leaf connects to, defined inline ({@link McpServerRef}). Per-agent — no
+     * meta declaration; the program supplies credentials directly (it is the trusted layer).
+     * Defaults to none.
+     */
+    mcp?: readonly McpServerRef[];
+    /**
+     * Skills loadable into this leaf's context, by name — resolved from the `skills/` directory
+     * deployed alongside the program (`skills/<name>.md`). Per-agent. Defaults to none.
+     */
+    skills?: readonly string[];
+    /**
+     * The leaf's persistent memory: a workspace-relative directory. Per-agent — the engine
+     * persists it across runs automatically (no `workspace.persist` declaration needed). The
+     * loop gets read/write file tools scoped to that directory and loads its index at turn
+     * start; the program may read/write the same files in plain code. Agents may use separate
+     * directories or deliberately share one.
+     */
+    memory?: string;
+}
+/** Options for a {@link import("./index.js").workflows}.call durable child run. */
+export interface CallOptions {
+    /**
+     * Idempotency key for the child call. Defaults to a deterministic key over
+     * `(parent_run_id, target, input)` so a restarted parent re-attaches to the existing
+     * child instead of spawning a duplicate.
+     */
+    idempotencyKey?: string;
+}
+/**
+ * How long {@link import("./index.js").sleep} holds the run. A bare number is milliseconds;
+ * the object forms are explicit.
+ */
+export type SleepArg = number | {
+    durationMs: number;
+} | {
+    until: string | Date;
+};
+/** Options for {@link import("./index.js").Phase}, the run-timeline marker. */
+export interface PhaseOptions {
+    /**
+     * Optional stable identifier for the phase. Omit for the engine to assign one in marker order.
+     * This is only an observability key; it is not a checkpoint/resume identifier.
+     */
+    id?: string;
+}
+/** Body for {@link import("./index.js").artifacts}.write — UTF-8 text or raw bytes. */
+export type ArtifactBody = string | Uint8Array;
+/** A stored artifact, returned by {@link import("./index.js").artifacts}.write. */
+export interface ArtifactRef {
+    /** Stable artifact id. */
+    id: string;
+    /** The name it was stored under. */
+    name: string;
+    /** A download URL (signed and time-limited on hosted engines; a file URL locally). */
+    url: string;
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+// Option/argument types for the workflow hooks (Phase, agent, workflows.call, sleep, secrets).
+export {};

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@boardwalk-labs/workflow",
+  "version": "0.1.0",
+  "description": "Author Boardwalk workflows in TypeScript: agent(), sleep(), workflows.call(), secrets, the manifest schema, and the run-event wire format.",
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=24"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./runtime": {
+      "types": "./dist/runtime.d.ts",
+      "default": "./dist/runtime.js"
+    },
+    "./extract": {
+      "types": "./dist/extract.d.ts",
+      "default": "./dist/extract.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint . --max-warnings 0",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "typescript": "^5.6.0",
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.18.0",
+    "@types/node": "^24.0.0",
+    "eslint": "^9.18.0",
+    "prettier": "^3.4.0",
+    "typescript-eslint": "^8.20.0",
+    "vitest": "^3.0.0"
+  }
+}