@boardwalk-labs/workflow 0.1.2 → 0.1.4

package/README.md

@@ -9,7 +9,7 @@ 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" }],
+  permissions: { secrets: [{ name: "GITHUB_TOKEN" }] },
 } satisfies WorkflowMeta;
 
 const token = await secrets.get("GITHUB_TOKEN");
@@ -36,7 +36,7 @@ A workflow is **a script**: the `meta` export is a **pure literal** (engines der
 - **`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.
+- **`secrets.get(name)`** — read a secret declared in `permissions.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.)
 

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/host.d.ts

@@ -16,7 +16,7 @@ export interface WorkflowHost {
     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`). */
+    /** Resolve a granted secret to its plaintext value (fail-closed against `permissions.secrets`). */
     getSecret(name: string): Promise<string>;
     /**
      * Fire-and-forget trigger of another workflow; resolve to the new run's id WITHOUT holding for

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: {
     /**
@@ -31,7 +38,7 @@ export declare const workflows: {
 };
 /** 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`. */
+/** Granted secrets, resolved lazily and fail-closed against `permissions.secrets`. */
 export declare const secrets: {
     /** Resolve a granted secret to its plaintext value. */
     readonly get: (name: string) => Promise<string>;
@@ -60,7 +67,7 @@ export declare function parallel<T>(thunks: readonly (() => Promise<T>)[]): Prom
  */
 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 { WorkflowMeta, Trigger, CronTrigger, WebhookTrigger, ManualTrigger, 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

@@ -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). */
@@ -62,7 +57,7 @@ export const workflows = {
 export async function sleep(arg) {
     await requireHost().sleep(arg);
 }
-/** Granted secrets, resolved lazily and fail-closed against `meta.secrets`. */
+/** Granted secrets, resolved lazily and fail-closed against `permissions.secrets`. */
 export const secrets = {
     /** Resolve a granted secret to its plaintext value. */
     async get(name) {

package/dist/manifest.d.ts

@@ -15,9 +15,6 @@ export declare const workflowManifestSchema: z.ZodObject<{
     }, 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>>;
@@ -81,11 +78,6 @@ export declare const workflowManifestSchema: z.ZodObject<{
         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<{

package/dist/manifest.js

@@ -115,15 +115,6 @@ const concurrencySchema = z.union([
     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([
@@ -149,12 +140,16 @@ const runsOnSchema = z.union([
 // ============================================================================
 const containerSchema = z.strictObject({ image: z.string().min(1).max(512) });
 const permissionAccess = z.enum(["none", "read", "write"]);
+// `permissions` is the run's access-grant surface: what the workflow is ALLOWED to access or do.
+// Access-level knobs (id_token/artifacts/contents) plus the SECRET allowlist — a secret a program
+// may read is a grant, so it lives here, not as a top-level field (a top-level `secrets` next to
+// `env` reads like injection; it isn't). There is NO `tools` grant: tool selection is per-agent
+// (AgentOptions.tools), declared on the `agent()` call that uses it — one place, no run-level ceiling.
 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) }),
@@ -189,7 +184,8 @@ export const workflowManifestSchema = z.strictObject({
     name: workflowName,
     description: z.string().max(1000).optional(),
     triggers: z.array(triggerSchema).min(1),
-    secrets: z.array(secretRefSchema).optional(),
+    // NO top-level `secrets` — the secret allowlist is `permissions.secrets` (a secret you may read
+    // is an access grant). `env` is for value injection (incl. `${{ secrets.NAME }}` of a permitted secret).
     env: envVarsSchema.optional(),
     input_schema: jsonSchemaObject.optional(),
     output_schema: jsonSchemaObject.optional(),

package/dist/meta.d.ts

@@ -14,15 +14,6 @@ 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`
@@ -66,8 +57,9 @@ export interface Container {
 }
 /**
  * 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.
+ * Declared in `permissions.secrets` (a readable secret is an access grant). 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;
@@ -75,8 +67,8 @@ export interface SecretRef {
 /**
  * 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.
+ * A referenced secret must also be declared in `permissions.secrets` (env injection is the
+ * delivery, the permission is the grant). Reserved `BOARDWALK_*` / `AWS_*` keys are not allowed.
  */
 export type EnvVars = Record<string, string>;
 export type EgressPolicy = {
@@ -91,12 +83,17 @@ export type EgressPolicy = {
     include_defaults?: boolean;
 };
 export type RunPermissionAccess = "none" | "read" | "write";
+/**
+ * The run's access-grant surface — what the workflow is allowed to access or do. Access-level
+ * knobs (`id_token`/`artifacts`/`contents`) plus the secret allowlist (`secrets`). No `tools`
+ * grant: tool selection is per-agent (`AgentOptions.tools`), never a manifest-level ceiling.
+ */
 export interface RunPermissions {
     id_token?: "none" | "write";
     artifacts?: RunPermissionAccess;
     contents?: RunPermissionAccess;
+    /** Names of secrets the program may read with `secrets.get` — an allowlist, not values. */
     secrets?: readonly SecretRef[];
-    tools?: readonly ToolGrant[];
 }
 export type OrgRole = "owner" | "admin" | "member" | "viewer";
 export type CallableBy = "anyone_in_org" | "users_only" | "workflows_only" | {
@@ -148,7 +145,6 @@ export interface WorkflowMeta {
     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>;

package/package.json

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