@boardwalk-labs/workflow 0.1.0

package/dist/extract.js

@@ -0,0 +1,192 @@
+// @boardwalk-labs/workflow/extract — static extraction of a workflow program's `meta` → manifest.
+//
+// A workflow is a TS/JS program file whose `export const meta = { … }` is a PURE LITERAL.
+// Engines and tooling must derive the manifest WITHOUT executing the program, so this module
+// parses the file's AST and reads the literal statically:
+//
+//   source text → TS AST → unwrap `satisfies`/`as` → evaluate the pure object literal
+//                → validate against workflowManifestSchema → WorkflowManifest
+//
+// "Pure literal" means: object/array literals, string/number/boolean/null literals, and
+// no-substitution template strings ONLY. Any variable reference, function call (incl.
+// `defineMeta(...)`), spread, shorthand, computed key, or template interpolation is
+// rejected — those would require executing the file to know the value. (`defineMeta` is
+// deliberately unsupported; type the literal with `satisfies WorkflowMeta` instead.)
+//
+// This module executes none of the program. It is pure logic — tested exhaustively. It is a
+// subpath export (`@boardwalk-labs/workflow/extract`) consumed by engines and the CLI; author
+// programs never import it.
+import ts from "typescript";
+import { validateMeta } from "./manifest.js";
+/** Thrown when a program's `meta` cannot be statically extracted as a pure literal. */
+export class MetaExtractionError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "MetaExtractionError";
+    }
+}
+const DEFAULT_FILE_NAME = "index.ts";
+/**
+ * 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 function extractMetaLiteral(source, options = {}) {
+    const fileName = options.fileName ?? DEFAULT_FILE_NAME;
+    const sf = ts.createSourceFile(fileName, source, ts.ScriptTarget.Latest, /*setParentNodes*/ true);
+    const initializer = findMetaInitializer(sf);
+    if (initializer === null) {
+        throw fail("No `meta` declaration found — a workflow program must export a pure-literal " +
+            "`export const meta = { … }`");
+    }
+    const unwrapped = unwrapTypeOnly(initializer);
+    // Targeted message for the one mistake the design explicitly forbids.
+    if (ts.isCallExpression(unwrapped)) {
+        throw fail("`meta` must be a plain object literal, not a function call — `defineMeta(...)` is " +
+            "not supported; type the literal with `satisfies WorkflowMeta` instead", unwrapped, sf);
+    }
+    if (!ts.isObjectLiteralExpression(unwrapped)) {
+        throw fail("`meta` must be an object literal (`export const meta = { … }`)", unwrapped, sf);
+    }
+    return evalObjectLiteral(unwrapped, sf);
+}
+/**
+ * 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 function extractManifest(source, options = {}) {
+    return validateMeta(extractMetaLiteral(source, options));
+}
+// ============================================================================
+// AST walking
+// ============================================================================
+/** Find the initializer of the first top-level `const meta = …` (exported or not). */
+function findMetaInitializer(sf) {
+    for (const stmt of sf.statements) {
+        if (!ts.isVariableStatement(stmt))
+            continue;
+        for (const decl of stmt.declarationList.declarations) {
+            if (ts.isIdentifier(decl.name) &&
+                decl.name.text === "meta" &&
+                decl.initializer !== undefined) {
+                return decl.initializer;
+            }
+        }
+    }
+    return null;
+}
+/**
+ * Strip type-only wrappers that are erased at compile time and don't affect the value:
+ * `expr satisfies T`, `expr as T`, `<T>expr`, and `(expr)`. Applied repeatedly so
+ * `({ … } satisfies WorkflowMeta)` unwraps fully.
+ */
+function unwrapTypeOnly(node) {
+    let current = node;
+    for (;;) {
+        if (ts.isSatisfiesExpression(current) || ts.isAsExpression(current)) {
+            current = current.expression;
+        }
+        else if (ts.isParenthesizedExpression(current)) {
+            current = current.expression;
+        }
+        else if (ts.isTypeAssertionExpression(current)) {
+            current = current.expression;
+        }
+        else {
+            return current;
+        }
+    }
+}
+// ============================================================================
+// Pure-literal evaluation
+// ============================================================================
+function evalObjectLiteral(node, sf) {
+    const out = {};
+    for (const prop of node.properties) {
+        if (ts.isShorthandPropertyAssignment(prop)) {
+            throw fail("shorthand properties reference a variable, which is not a pure literal — " +
+                "write `key: value` with a literal value", prop, sf);
+        }
+        if (ts.isSpreadAssignment(prop)) {
+            throw fail("spread (`...`) is not allowed in a `meta` literal", prop, sf);
+        }
+        if (!ts.isPropertyAssignment(prop)) {
+            // Method / get / set declarations.
+            throw fail("methods and accessors are not allowed in a `meta` literal", prop, sf);
+        }
+        const key = propertyKey(prop.name, sf);
+        out[key] = evalLiteral(prop.initializer, sf);
+    }
+    return out;
+}
+/** Resolve a property name to a string, allowing identifier / string / numeric / `["x"]`. */
+function propertyKey(name, sf) {
+    if (ts.isIdentifier(name))
+        return name.text;
+    if (ts.isStringLiteral(name))
+        return name.text;
+    if (ts.isNumericLiteral(name))
+        return name.text;
+    if (ts.isComputedPropertyName(name) && ts.isStringLiteral(name.expression)) {
+        return name.expression.text;
+    }
+    throw fail("property keys must be plain identifiers or string/number literals (no computed keys)", name, sf);
+}
+/** Evaluate any value node, rejecting anything that isn't a pure literal. */
+function evalLiteral(node, sf) {
+    const n = unwrapTypeOnly(node);
+    if (ts.isObjectLiteralExpression(n))
+        return evalObjectLiteral(n, sf);
+    if (ts.isArrayLiteralExpression(n))
+        return evalArrayLiteral(n, sf);
+    if (ts.isStringLiteral(n))
+        return n.text;
+    if (ts.isNoSubstitutionTemplateLiteral(n))
+        return n.text;
+    if (ts.isNumericLiteral(n))
+        return parseNumber(n.text);
+    if (n.kind === ts.SyntaxKind.TrueKeyword)
+        return true;
+    if (n.kind === ts.SyntaxKind.FalseKeyword)
+        return false;
+    if (n.kind === ts.SyntaxKind.NullKeyword)
+        return null;
+    // Negative numbers parse as `-` applied to a numeric literal.
+    if (ts.isPrefixUnaryExpression(n) &&
+        n.operator === ts.SyntaxKind.MinusToken &&
+        ts.isNumericLiteral(n.operand)) {
+        return -parseNumber(n.operand.text);
+    }
+    throw fail("unsupported expression in `meta` — only pure literals are allowed", n, sf);
+}
+function evalArrayLiteral(node, sf) {
+    const out = [];
+    for (const el of node.elements) {
+        if (ts.isSpreadElement(el)) {
+            throw fail("spread (`...`) is not allowed in a `meta` literal array", el, sf);
+        }
+        if (el.kind === ts.SyntaxKind.OmittedExpression) {
+            throw fail("array holes (`[1, , 3]`) are not allowed in a `meta` literal", el, sf);
+        }
+        out.push(evalLiteral(el, sf));
+    }
+    return out;
+}
+/** Parse a numeric-literal source token (handles separators, hex/oct/bin, floats, exponents). */
+function parseNumber(text) {
+    return Number(text.replace(/_/g, ""));
+}
+// ============================================================================
+// Errors
+// ============================================================================
+function fail(message, node, sf) {
+    if (node !== undefined && sf !== undefined) {
+        const { line, character } = sf.getLineAndCharacterOfPosition(node.getStart(sf));
+        return new MetaExtractionError(`${sf.fileName}:${String(line + 1)}:${String(character + 1)} — ${message}`);
+    }
+    return new MetaExtractionError(message);
+}

package/dist/host.d.ts

@@ -0,0 +1,62 @@
+import type { AgentOptions, ArtifactBody, ArtifactRef, CallOptions, JsonValue, PhaseOptions, SleepArg } from "./types.js";
+/** The engine contract a host supplies. The author-facing hooks delegate to this. */
+export interface WorkflowHost {
+    /**
+     * Mark the current run phase. Everything after this marker belongs to the phase until the next
+     * marker or run end. Observability-only: this is not a checkpoint/resume boundary.
+     */
+    setPhase?(name: string, opts: PhaseOptions | undefined): void;
+    /**
+     * Run an agent leaf to completion; resolve to its text (or schema-validated object).
+     * `opts.model` may be omitted — the provider routes automatically (default provider =
+     * `boardwalk` on every engine; BYO keys only when a provider is explicitly named).
+     */
+    agent(prompt: string, opts: AgentOptions | undefined): Promise<unknown>;
+    /** Dispatch a durable child run and resolve to its output (parent holds while it runs). */
+    callWorkflow(slug: string, input: unknown, opts: CallOptions | undefined): Promise<unknown>;
+    /** Hold the run for the requested duration (the run stays held while it waits; locals survive). */
+    sleep(arg: SleepArg): Promise<void>;
+    /** Resolve a granted secret to its plaintext value (fail-closed against `meta.secrets`). */
+    getSecret(name: string): Promise<string>;
+    /**
+     * Fire-and-forget trigger of another workflow; resolve to the new run's id WITHOUT holding for
+     * its result (the sibling of {@link callWorkflow}). Optional — an engine that doesn't support it
+     * makes the `workflows.run` hook throw a clear error.
+     */
+    runWorkflow?(slug: string, input: unknown, opts: CallOptions | undefined): Promise<string>;
+    /**
+     * Store a file under the run's artifact prefix and resolve to its id + download URL.
+     * Optional — an engine that doesn't support it makes the `artifacts.write` hook throw a clear error.
+     */
+    writeArtifact?(name: string, contentType: string, body: ArtifactBody, metadata: Record<string, unknown> | undefined): Promise<ArtifactRef>;
+}
+/**
+ * The trigger payload for the current run, exposed to the program as
+ * `import { input } from "@boardwalk-labs/workflow"`. It is an ES live binding: the engine assigns
+ * it via {@link installInput} before the program evaluates, so the import reflects the value.
+ * `unknown` by contract — narrow it (e.g. with a schema) in your program.
+ */
+export declare let input: unknown;
+/**
+ * The run's deploy-time configuration, exposed as `import { config } from "@boardwalk-labs/workflow"`.
+ * `{}` unless the deployment supplies one. Read it to vary behavior WITHOUT editing code — e.g.
+ * `agent(prompt, { model: config.model ?? undefined })`. Like {@link input}, an ES live binding
+ * the engine installs before the program evaluates. Frozen so a program can't mutate it.
+ */
+export declare let config: Readonly<Record<string, JsonValue>>;
+/** Record the run's output (last write wins). Author-facing as `output(...)` (re-exported by index). */
+export declare function recordOutput(value: JsonValue): void;
+/** The engine reads the program's declared output after the body finishes; null ⇒ never declared. */
+export declare function takeDeclaredOutput(): {
+    value: JsonValue;
+} | null;
+/** Install the host adapter. Called by the engine (hosted or local) before the program evaluates. */
+export declare function installHost(host: WorkflowHost): void;
+/** Set the run's trigger payload (the value `import { input }` resolves to). */
+export declare function installInput(value: unknown): void;
+/** Set the run's deploy-time config (the value `import { config }` resolves to). Frozen on install. */
+export declare function installConfig(value: Record<string, JsonValue>): void;
+/** Clear all installed runtime state. Primarily for tests and reused local-dev processes. */
+export declare function resetRuntime(): void;
+/** The installed host, or a clear error if a hook was called outside a Boardwalk engine. */
+export declare function requireHost(): WorkflowHost;

package/dist/host.js

@@ -0,0 +1,70 @@
+// The host seam — the engine-implementation boundary of the SDK.
+//
+// `@boardwalk-labs/workflow` is a host-backed package: the hooks authors import (agent, sleep,
+// workflows.call, secrets.get, input) are thin facades over a `WorkflowHost` the *engine*
+// installs at runtime. hosted Boardwalk installs its hosted adapter; the local engine installs
+// one backed by the developer's environment. The author's program is identical either way —
+// explicit hooks instead of injected globals.
+//
+// State is a module-level singleton. Node ESM caches a module by resolved path, so the
+// program (which imports the hooks) and the engine (which installs the host) share ONE
+// instance of this module and therefore one host + one `input`.
+let currentHost = null;
+/**
+ * The trigger payload for the current run, exposed to the program as
+ * `import { input } from "@boardwalk-labs/workflow"`. It is an ES live binding: the engine assigns
+ * it via {@link installInput} before the program evaluates, so the import reflects the value.
+ * `unknown` by contract — narrow it (e.g. with a schema) in your program.
+ */
+export let input = undefined;
+/**
+ * The run's deploy-time configuration, exposed as `import { config } from "@boardwalk-labs/workflow"`.
+ * `{}` unless the deployment supplies one. Read it to vary behavior WITHOUT editing code — e.g.
+ * `agent(prompt, { model: config.model ?? undefined })`. Like {@link input}, an ES live binding
+ * the engine installs before the program evaluates. Frozen so a program can't mutate it.
+ */
+export let config = {};
+/**
+ * The run's declared output — what `output(value)` recorded, or null if the program never called
+ * it. Wrapped in a `{ value }` box so an explicit `output(null)` is distinguishable from "never
+ * set". The engine reads this AFTER the program body finishes (see {@link takeDeclaredOutput});
+ * it's the value persisted as the run's output, returned to a `workflows.call` parent, and the
+ * `output` event in the run's stream.
+ */
+let declaredOutput = null;
+/** Record the run's output (last write wins). Author-facing as `output(...)` (re-exported by index). */
+export function recordOutput(value) {
+    declaredOutput = { value };
+}
+/** The engine reads the program's declared output after the body finishes; null ⇒ never declared. */
+export function takeDeclaredOutput() {
+    return declaredOutput;
+}
+/** Install the host adapter. Called by the engine (hosted or local) before the program evaluates. */
+export function installHost(host) {
+    currentHost = host;
+}
+/** Set the run's trigger payload (the value `import { input }` resolves to). */
+export function installInput(value) {
+    input = value;
+}
+/** Set the run's deploy-time config (the value `import { config }` resolves to). Frozen on install. */
+export function installConfig(value) {
+    config = Object.freeze({ ...value });
+}
+/** Clear all installed runtime state. Primarily for tests and reused local-dev processes. */
+export function resetRuntime() {
+    currentHost = null;
+    input = undefined;
+    config = {};
+    declaredOutput = null;
+}
+/** The installed host, or a clear error if a hook was called outside a Boardwalk engine. */
+export function requireHost() {
+    if (currentHost === null) {
+        throw new Error("@boardwalk-labs/workflow hooks were called with no host installed. Under a Boardwalk engine " +
+            "the host is installed automatically; in tests call installHost(...) " +
+            'from "@boardwalk-labs/workflow/runtime" first.');
+    }
+    return currentHost;
+}

package/dist/index.d.ts

@@ -0,0 +1,66 @@
+import type { AgentOptions, ArtifactBody, ArtifactRef, CallOptions, JsonValue, PhaseOptions, SleepArg } from "./types.js";
+/**
+ * Mark the current run phase for live-tail and run-log grouping. Everything after this call
+ * belongs to the named phase until the next `Phase(...)` marker or the run ends. This is
+ * observability-only; it does not checkpoint or skip code on restart.
+ */
+export declare function Phase(name: string, opts?: PhaseOptions): void;
+/**
+ * Run an agent leaf to completion. Without `opts.schema`, resolves to the leaf's final text
+ * (`T` defaults to `string`); with a schema, resolves to the validated object — pass the
+ * expected type, e.g. `await agent<Groups>(prompt, { schema })`. Omit `opts.model` to let the
+ * provider route automatically (the default `boardwalk` provider on every engine; your own
+ * keys only via an explicit provider). Capabilities (`tools`, `mcp`, `skills`, `memory`) are
+ * PER-AGENT — each call brings its own; the manifest declares none of them.
+ */
+export declare function agent<T = string>(prompt: string, opts?: AgentOptions): Promise<T>;
+/** Cross-workflow composition: `call` (await the result) and `run` (fire-and-forget). */
+export declare const workflows: {
+    /**
+     * Call another workflow as a durable child run. The parent HOLDS while the child runs and
+     * resolves to the child's output; the call is idempotent, so a restarted parent re-attaches
+     * instead of re-spawning. Use when you need the child's result to continue.
+     */
+    readonly call: (slug: string, input: unknown, opts?: CallOptions) => Promise<unknown>;
+    /**
+     * Trigger another workflow as a fire-and-forget run. Returns the new run's id WITHOUT
+     * holding for its result. Idempotent on (parent, target, input) like {@link call}, so a
+     * restarted parent doesn't double-fire. Use when you want to kick something off and move on.
+     */
+    readonly run: (slug: string, input: unknown, opts?: CallOptions) => Promise<string>;
+};
+/** Hold the run for a duration or until a timestamp (the run stays held while it waits; locals survive). */
+export declare function sleep(arg: SleepArg): Promise<void>;
+/** Granted secrets, resolved lazily and fail-closed against `meta.secrets`. */
+export declare const secrets: {
+    /** Resolve a granted secret to its plaintext value. */
+    readonly get: (name: string) => Promise<string>;
+};
+/** Files (artifacts) that persist with the run. */
+export declare const artifacts: {
+    /**
+     * Store a file under the run's artifact prefix. `body` is UTF-8 text or raw bytes; pass the
+     * MIME `contentType` (e.g. "text/plain", "application/json"). Resolves to the artifact's id,
+     * name, and a download URL.
+     */
+    readonly write: (name: string, contentType: string, body: ArtifactBody, metadata?: Record<string, unknown>) => Promise<ArtifactRef>;
+};
+/**
+ * Run thunks concurrently and resolve to their results in order. A barrier: awaits all of
+ * them. Rejects on the first thunk that throws (standard `Promise.all` semantics) — wrap a
+ * thunk in your own try/catch if you want failures tolerated.
+ */
+export declare function parallel<T>(thunks: readonly (() => Promise<T>)[]): Promise<T[]>;
+/**
+ * Declare the run's output — its final result. Since a workflow program is top-level module
+ * code (it can't `return`), this is how you set what the run produced: the value a
+ * `workflows.call` parent receives, what the run log shows as the result, and the `output`
+ * event in the run's stream. Last call wins; never calling it leaves the output null. The
+ * value must be JSON-serializable and is validated against `meta.output_schema` when declared.
+ */
+export declare function output(value: JsonValue): void;
+export { input, config } from "./host.js";
+export type { WorkflowMeta, Trigger, CronTrigger, WebhookTrigger, ManualTrigger, ToolGrant, McpServerRef, Concurrency, CallableBy, OrgRole, RunsOn, HostedRunsOn, HostedRunsOnObject, HostedRunnerSize, SelfHostedRunsOn, Container, SecretRef, EnvVars, EgressPolicy, RunPermissions, RunPermissionAccess, Budget, Notification, Workspace, } from "./meta.js";
+export type { AgentOptions, ToolDef, ArtifactBody, ArtifactRef, CallOptions, PhaseOptions, SleepArg, JsonSchema, JsonValue, } from "./types.js";
+export { workflowManifestSchema, validateMeta, MetaValidationError, type WorkflowManifest, } from "./manifest.js";
+export { type RunEvent, type RunEventKind, type RunStatus, type Channel, type EventEnvelope, type TokenUsage, type ToolReturn, runEventSchema, CHANNELS, DEFAULT_CHANNELS, channelOf, matchesChannels, makeCursor, TURN_CURSOR_STRIDE, } from "./events.js";

package/dist/index.js

@@ -0,0 +1,106 @@
+// @boardwalk-labs/workflow — the author-facing API a workflow program imports.
+//
+//   import { agent, workflows, sleep, secrets, input, type WorkflowMeta } from "@boardwalk-labs/workflow"
+//
+//   export const meta = { name: "x", triggers: [{ kind: "manual" }] } satisfies WorkflowMeta
+//
+//   const groups = await agent("group failures", { schema: GROUPS })
+//   await parallel(groups.map((g) => () => workflows.call("file-issue", g)))
+//   await sleep({ until: "2026-07-01T00:00:00Z" })
+//
+// These hooks are facades over the installed host (see host.ts). Author programs never
+// install a host — the engine running the program does.
+import { requireHost, recordOutput } from "./host.js";
+/**
+ * Mark the current run phase for live-tail and run-log grouping. Everything after this call
+ * belongs to the named phase until the next `Phase(...)` marker or the run ends. This is
+ * observability-only; it does not checkpoint or skip code on restart.
+ */
+export function Phase(name, opts) {
+    const host = requireHost();
+    if (host.setPhase === undefined) {
+        throw new Error("Phase is not supported by the installed engine");
+    }
+    host.setPhase(name, opts);
+}
+/**
+ * Run an agent leaf to completion. Without `opts.schema`, resolves to the leaf's final text
+ * (`T` defaults to `string`); with a schema, resolves to the validated object — pass the
+ * expected type, e.g. `await agent<Groups>(prompt, { schema })`. Omit `opts.model` to let the
+ * provider route automatically (the default `boardwalk` provider on every engine; your own
+ * keys only via an explicit provider). Capabilities (`tools`, `mcp`, `skills`, `memory`) are
+ * PER-AGENT — each call brings its own; the manifest declares none of them.
+ */
+export async function agent(prompt, opts) {
+    return (await requireHost().agent(prompt, opts));
+}
+/** Cross-workflow composition: `call` (await the result) and `run` (fire-and-forget). */
+export const workflows = {
+    /**
+     * Call another workflow as a durable child run. The parent HOLDS while the child runs and
+     * resolves to the child's output; the call is idempotent, so a restarted parent re-attaches
+     * instead of re-spawning. Use when you need the child's result to continue.
+     */
+    async call(slug, input, opts) {
+        return await requireHost().callWorkflow(slug, input, opts);
+    },
+    /**
+     * Trigger another workflow as a fire-and-forget run. Returns the new run's id WITHOUT
+     * holding for its result. Idempotent on (parent, target, input) like {@link call}, so a
+     * restarted parent doesn't double-fire. Use when you want to kick something off and move on.
+     */
+    async run(slug, input, opts) {
+        const host = requireHost();
+        if (host.runWorkflow === undefined) {
+            throw new Error("workflows.run is not supported by the installed engine");
+        }
+        return await host.runWorkflow(slug, input, opts);
+    },
+};
+/** Hold the run for a duration or until a timestamp (the run stays held while it waits; locals survive). */
+export async function sleep(arg) {
+    await requireHost().sleep(arg);
+}
+/** Granted secrets, resolved lazily and fail-closed against `meta.secrets`. */
+export const secrets = {
+    /** Resolve a granted secret to its plaintext value. */
+    async get(name) {
+        return await requireHost().getSecret(name);
+    },
+};
+/** Files (artifacts) that persist with the run. */
+export const artifacts = {
+    /**
+     * Store a file under the run's artifact prefix. `body` is UTF-8 text or raw bytes; pass the
+     * MIME `contentType` (e.g. "text/plain", "application/json"). Resolves to the artifact's id,
+     * name, and a download URL.
+     */
+    async write(name, contentType, body, metadata) {
+        const host = requireHost();
+        if (host.writeArtifact === undefined) {
+            throw new Error("artifacts.write is not supported by the installed engine");
+        }
+        return await host.writeArtifact(name, contentType, body, metadata);
+    },
+};
+/**
+ * Run thunks concurrently and resolve to their results in order. A barrier: awaits all of
+ * them. Rejects on the first thunk that throws (standard `Promise.all` semantics) — wrap a
+ * thunk in your own try/catch if you want failures tolerated.
+ */
+export async function parallel(thunks) {
+    return Promise.all(thunks.map((thunk) => thunk()));
+}
+/**
+ * Declare the run's output — its final result. Since a workflow program is top-level module
+ * code (it can't `return`), this is how you set what the run produced: the value a
+ * `workflows.call` parent receives, what the run log shows as the result, and the `output`
+ * event in the run's stream. Last call wins; never calling it leaves the output null. The
+ * value must be JSON-serializable and is validated against `meta.output_schema` when declared.
+ */
+export function output(value) {
+    recordOutput(value);
+}
+export { input, config } from "./host.js";
+export { workflowManifestSchema, validateMeta, MetaValidationError, } from "./manifest.js";
+export { runEventSchema, CHANNELS, DEFAULT_CHANNELS, channelOf, matchesChannels, makeCursor, TURN_CURSOR_STRIDE, } from "./events.js";

package/dist/manifest.d.ts

@@ -0,0 +1,143 @@
+import { z } from "zod";
+export declare const workflowManifestSchema: z.ZodObject<{
+    name: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    triggers: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"cron">;
+        expr: z.ZodString;
+        timezone: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"webhook">;
+        auth: z.ZodEnum<{
+            token: "token";
+            signature: "signature";
+        }>;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"manual">;
+    }, z.core.$strict>], "kind">>;
+    secrets: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+    }, z.core.$strict>>>;
+    env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    input_schema: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    output_schema: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    workspace: z.ZodOptional<z.ZodObject<{
+        persist: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodArray<z.ZodString>]>>;
+    }, z.core.$strict>>;
+    budget: z.ZodOptional<z.ZodObject<{
+        max_tokens: z.ZodOptional<z.ZodNumber>;
+        max_usd: z.ZodOptional<z.ZodNumber>;
+        max_duration_seconds: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>;
+    concurrency: z.ZodDefault<z.ZodUnion<readonly [z.ZodObject<{
+        mode: z.ZodLiteral<"serial_by_key">;
+        key: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        mode: z.ZodLiteral<"serial">;
+    }, z.core.$strict>, z.ZodObject<{
+        mode: z.ZodLiteral<"unlimited">;
+    }, z.core.$strict>]>>;
+    runs_on: z.ZodDefault<z.ZodUnion<readonly [z.ZodObject<{
+        kind: z.ZodLiteral<"self-hosted">;
+        pool: z.ZodString;
+        labels: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>, z.ZodObject<{
+        label: z.ZodEnum<{
+            "boardwalk/linux": "boardwalk/linux";
+            "boardwalk/linux-node": "boardwalk/linux-node";
+            "boardwalk/linux-python": "boardwalk/linux-python";
+            "boardwalk/linux-large": "boardwalk/linux-large";
+        }>;
+        size: z.ZodOptional<z.ZodEnum<{
+            small: "small";
+            medium: "medium";
+            large: "large";
+            xlarge: "xlarge";
+        }>>;
+    }, z.core.$strict>, z.ZodEnum<{
+        "boardwalk/linux": "boardwalk/linux";
+        "boardwalk/linux-node": "boardwalk/linux-node";
+        "boardwalk/linux-python": "boardwalk/linux-python";
+        "boardwalk/linux-large": "boardwalk/linux-large";
+    }>]>>;
+    container: z.ZodOptional<z.ZodObject<{
+        image: z.ZodString;
+    }, z.core.$strict>>;
+    permissions: z.ZodOptional<z.ZodObject<{
+        id_token: z.ZodOptional<z.ZodEnum<{
+            none: "none";
+            write: "write";
+        }>>;
+        artifacts: z.ZodOptional<z.ZodEnum<{
+            none: "none";
+            read: "read";
+            write: "write";
+        }>>;
+        contents: z.ZodOptional<z.ZodEnum<{
+            none: "none";
+            read: "read";
+            write: "write";
+        }>>;
+        secrets: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+        }, z.core.$strict>>>;
+        tools: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            config: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+            scope: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$strict>>>;
+    }, z.core.$strict>>;
+    callable_by: z.ZodDefault<z.ZodUnion<readonly [z.ZodObject<{
+        roles: z.ZodArray<z.ZodEnum<{
+            owner: "owner";
+            admin: "admin";
+            member: "member";
+            viewer: "viewer";
+        }>>;
+    }, z.core.$strict>, z.ZodObject<{
+        workflows: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>, z.ZodEnum<{
+        anyone_in_org: "anyone_in_org";
+        users_only: "users_only";
+        workflows_only: "workflows_only";
+    }>]>>;
+    egress: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
+        level: z.ZodLiteral<"custom">;
+        allow: z.ZodArray<z.ZodString>;
+        include_defaults: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>, z.ZodObject<{
+        level: z.ZodEnum<{
+            none: "none";
+            trusted: "trusted";
+            full: "full";
+        }>;
+    }, z.core.$strict>]>>;
+    notifications: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+        on: z.ZodEnum<{
+            cancelled: "cancelled";
+            completion: "completion";
+            failure: "failure";
+        }>;
+        channel: z.ZodEnum<{
+            webhook: "webhook";
+            email: "email";
+        }>;
+        target: z.ZodString;
+        template: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>, z.ZodObject<{
+        on: z.ZodLiteral<"budget_exceeded">;
+        channel: z.ZodLiteral<"email">;
+        target: z.ZodString;
+    }, z.core.$strict>]>>>;
+}, z.core.$strict>;
+/** The fully-defaulted, validated manifest — the contract every engine consumes. */
+export type WorkflowManifest = z.infer<typeof workflowManifestSchema>;
+/**
+ * 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 declare function validateMeta(meta: unknown): WorkflowManifest;
+/** Thrown by {@link validateMeta} when a `meta` object violates the manifest schema. */
+export declare class MetaValidationError extends Error {
+    constructor(message: string);
+}