@boardwalk-labs/workflow 0.1.3 → 0.1.5

package/README.md

@@ -6,10 +6,11 @@ Author **Boardwalk workflows** in plain TypeScript — agent loops, schedules, d
 import { agent, output, secrets, type WorkflowMeta } from "@boardwalk-labs/workflow";
 
 export const meta = {
-  name: "morning-digest",
+  slug: "morning-digest",
+  title: "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");
@@ -35,8 +36,8 @@ 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.
+- **`workflows.call(slug, input)`** — durably invoke another workflow by its slug and await its result; idempotent across restarts. `workflows.run` is the fire-and-forget sibling.
+- **`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/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

@@ -38,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>;
@@ -67,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

@@ -57,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

@@ -1,6 +1,7 @@
 import { z } from "zod";
 export declare const workflowManifestSchema: z.ZodObject<{
-    name: z.ZodString;
+    slug: z.ZodString;
+    title: z.ZodOptional<z.ZodString>;
     description: z.ZodOptional<z.ZodString>;
     triggers: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
         kind: z.ZodLiteral<"cron">;
@@ -15,9 +16,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 +79,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

@@ -12,12 +12,21 @@ import { z } from "zod";
 // ============================================================================
 // Shared scalars
 // ============================================================================
-const NAME_RE = /^[a-zA-Z0-9-]+$/;
-const workflowName = z
+const SLUG_RE = /^[a-zA-Z0-9-]+$/;
+/** The workflow's identity: a URL-safe slug, stable across the program's life (referenced by the
+ *  CLI, `workflows.call`, and the API). The human-readable label is `title`, not this. */
+const workflowSlug = z
     .string()
     .min(1)
     .max(100)
-    .regex(NAME_RE, "name must be alphanumeric with hyphens");
+    .regex(SLUG_RE, "slug must be alphanumeric with hyphens");
+/** The workflow's display label — free text, author-controlled. Falls back to a title-cased slug
+ *  in UIs when omitted. One line only. */
+const workflowTitle = z
+    .string()
+    .min(1)
+    .max(200)
+    .refine((s) => !s.includes("\n"), "title must be a single line");
 /** 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). */
@@ -115,15 +124,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,16 +149,20 @@ 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) }),
-    z.strictObject({ workflows: z.array(workflowName).min(1) }),
+    z.strictObject({ workflows: z.array(workflowSlug).min(1) }),
     z.enum(["anyone_in_org", "users_only", "workflows_only"]),
 ]);
 const egressSchema = z.union([
@@ -186,10 +190,12 @@ const notificationSchema = z.union([
 // The manifest
 // ============================================================================
 export const workflowManifestSchema = z.strictObject({
-    name: workflowName,
+    slug: workflowSlug,
+    title: workflowTitle.optional(),
     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" | {
@@ -144,11 +141,15 @@ export interface Workspace {
  * the program. Validated by `workflowManifestSchema`; unknown fields are errors.
  */
 export interface WorkflowMeta {
-    name: string;
+    /** The workflow's identity: a URL-safe slug (alphanumeric + hyphens), stable across the program's
+     *  life. Referenced by the CLI, `workflows.call`, and the API. The human label is `title`. */
+    slug: string;
+    /** Optional human-readable display label (free text, one line). UIs fall back to a title-cased
+     *  slug when this is omitted, so set it only when the slug doesn't read well. */
+    title?: 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>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@boardwalk-labs/workflow",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Author Boardwalk workflows in TypeScript: agent(), sleep(), workflows.call(), secrets, the manifest schema, and the run-event wire format.",
   "license": "MIT",
   "repository": {