@boardwalk-labs/workflow 0.1.1 → 0.1.3

package/README.md

@@ -27,7 +27,7 @@ A workflow is **a script**: the `meta` export is a **pure literal** (engines der
 
 | 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`         | 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                                                                                                      |
 

package/dist/events.js

@@ -1,3 +1,4 @@
+// SPDX-License-Identifier: MIT
 // 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

package/dist/extract.js

@@ -1,3 +1,4 @@
+// SPDX-License-Identifier: MIT
 // @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.
@@ -36,6 +37,13 @@ const DEFAULT_FILE_NAME = "index.ts";
 export function extractMetaLiteral(source, options = {}) {
     const fileName = options.fileName ?? DEFAULT_FILE_NAME;
     const sf = ts.createSourceFile(fileName, source, ts.ScriptTarget.Latest, /*setParentNodes*/ true);
+    // A syntax error otherwise falls through to "No `meta` declaration found" (the parser produced no
+    // usable `meta` node) — misleading. Report the real syntax error, with position, first.
+    const syntaxError = firstSyntaxError(sf);
+    if (syntaxError !== undefined) {
+        const text = ts.flattenDiagnosticMessageText(syntaxError.messageText, "\n");
+        throw failAt(`syntax error: ${text}`, sf, syntaxError.start);
+    }
     const initializer = findMetaInitializer(sf);
     if (initializer === null) {
         throw fail("No `meta` declaration found — a workflow program must export a pure-literal " +
@@ -190,3 +198,32 @@ function fail(message, node, sf) {
     }
     return new MetaExtractionError(message);
 }
+/** Like {@link fail}, but positioned at a raw source offset (a diagnostic's `start`). */
+function failAt(message, sf, start) {
+    if (start === undefined)
+        return new MetaExtractionError(message);
+    const { line, character } = sf.getLineAndCharacterOfPosition(start);
+    return new MetaExtractionError(`${sf.fileName}:${String(line + 1)}:${String(character + 1)} — ${message}`);
+}
+/**
+ * The first syntax error TS recorded while parsing, or undefined. The parser stores these on the
+ * source file's `parseDiagnostics` (an internal field), so read it through `Reflect` + a runtime
+ * guard rather than a cast — a future TS that drops/renames it simply yields "no error".
+ */
+function firstSyntaxError(sf) {
+    const raw = Reflect.get(sf, "parseDiagnostics");
+    if (!Array.isArray(raw))
+        return undefined;
+    for (const d of raw) {
+        if (isErrorDiagnostic(d))
+            return d;
+    }
+    return undefined;
+}
+function isErrorDiagnostic(d) {
+    return (typeof d === "object" &&
+        d !== null &&
+        "messageText" in d &&
+        "category" in d &&
+        d.category === ts.DiagnosticCategory.Error);
+}

package/dist/host.js

@@ -1,14 +1,4 @@
-// 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`.
+// SPDX-License-Identifier: MIT
 let currentHost = null;
 /**
  * The trigger payload for the current run, exposed to the program as

package/dist/index.d.ts

@@ -1,19 +1,26 @@
-import type { AgentOptions, ArtifactBody, ArtifactRef, CallOptions, JsonValue, PhaseOptions, SleepArg } from "./types.js";
+import type { AgentOptions, ArtifactBody, ArtifactRef, CallOptions, JsonSchema, 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
+ * 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;
+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.
+ * Run an agent leaf to completion. Two typed forms, by whether you pass a `schema`:
+ *  - `agent(prompt, opts?)` (no `schema`) → the leaf's final text (`Promise<string>`).
+ *  - `agent<Shape>(prompt, { schema })` → the schema-validated object (`Promise<Shape>`); name the
+ *    expected type. The run fails if the model's output doesn't validate.
+ *
+ * Asking for a typed result WITHOUT a schema (`agent<Shape>(prompt)`) is a type error: there would
+ * be nothing to validate against, so the value would really be a string. 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>;
+export declare function agent<T>(prompt: string, opts: AgentOptions & {
+    schema: JsonSchema;
+}): Promise<T>;
+export declare function agent(prompt: string, opts?: AgentOptions): Promise<string>;
 /** Cross-workflow composition: `call` (await the result) and `run` (fire-and-forget). */
 export declare const workflows: {
     /**

package/dist/index.js

@@ -1,3 +1,4 @@
+// SPDX-License-Identifier: MIT
 // @boardwalk-labs/workflow — the author-facing API a workflow program imports.
 //
 //   import { agent, workflows, sleep, secrets, input, type WorkflowMeta } from "@boardwalk-labs/workflow"
@@ -13,25 +14,20 @@
 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
+ * 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) {
+export function phase(name, opts) {
     const host = requireHost();
     if (host.setPhase === undefined) {
-        throw new Error("Phase is not supported by the installed engine");
+        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) {
+    // The host returns `unknown`; the overloads above are the public contract. With a `schema` the
+    // host validated the value (best-effort; the run fails on mismatch) → `T`; without one it is the
+    // leaf's final text → `string` (the `T = string` default). The cast is confined to this boundary.
     return (await requireHost().agent(prompt, opts));
 }
 /** Cross-workflow composition: `call` (await the result) and `run` (fire-and-forget). */

package/dist/manifest.js

@@ -1,3 +1,4 @@
+// SPDX-License-Identifier: MIT
 // workflowManifestSchema — the validator of record for a workflow's `meta`.
 //
 // One Zod schema, consumed by every engine (local `dev`, the self-hosted server, Boardwalk

package/dist/meta.js

@@ -1,8 +1,2 @@
-// 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.
+// SPDX-License-Identifier: MIT
 export {};

package/dist/runtime.js

@@ -1,3 +1,4 @@
+// SPDX-License-Identifier: MIT
 // @boardwalk-labs/workflow/runtime — the ENGINE-facing API.
 //
 // An engine imports this to install the host adapter and the trigger payload BEFORE

package/dist/types.d.ts

@@ -97,7 +97,7 @@ export type SleepArg = number | {
 } | {
     until: string | Date;
 };
-/** Options for {@link import("./index.js").Phase}, the run-timeline marker. */
+/** 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.

package/dist/types.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@boardwalk-labs/workflow",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Author Boardwalk workflows in TypeScript: agent(), sleep(), workflows.call(), secrets, the manifest schema, and the run-event wire format.",
   "license": "MIT",
   "repository": {
@@ -37,7 +37,7 @@
     "lint": "eslint . --max-warnings 0",
     "format": "prettier --write .",
     "format:check": "prettier --check .",
-    "test": "vitest run",
+    "test": "vitest run --coverage",
     "test:watch": "vitest"
   },
   "dependencies": {
@@ -47,6 +47,7 @@
   "devDependencies": {
     "@eslint/js": "^9.18.0",
     "@types/node": "^24.0.0",
+    "@vitest/coverage-v8": "^3.2.6",
     "eslint": "^9.18.0",
     "prettier": "^3.4.0",
     "typescript-eslint": "^8.20.0",