@boardwalk-labs/workflow 0.1.2 → 0.1.3

package/dist/extract.js

@@ -37,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 " +
@@ -191,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/index.d.ts

@@ -1,4 +1,4 @@
-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
@@ -6,14 +6,21 @@ import type { AgentOptions, ArtifactBody, ArtifactRef, CallOptions, JsonValue, P
  */
 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

@@ -24,15 +24,10 @@ export function phase(name, opts) {
     }
     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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@boardwalk-labs/workflow",
-  "version": "0.1.2",
+  "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",