@boardwalk-labs/workflow 0.1.3 → 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/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

@@ -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.3",
+  "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": {