lua-cli 3.30.0 → 3.32.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lua-cli",
-  "version": "3.30.0",
+  "version": "3.32.1",
   "description": "Build, test, and deploy AI agents with custom tools, webhooks, and scheduled jobs. Features LuaAgent unified configuration, streaming chat, and batch deployment.",
   "readmeFilename": "README.md",
   "main": "dist/api-exports.js",
@@ -21,6 +21,10 @@
     "./voice/test": {
       "types": "./dist/voice/test/index.d.ts",
       "default": "./dist/voice/test/index.js"
+    },
+    "./workflow-builder": {
+      "types": "./dist/workflow-builder.d.ts",
+      "default": "./dist/workflow-builder.js"
     }
   },
   "keywords": [
@@ -109,9 +113,10 @@
     "stripe": "^19.2.0",
     "ts-node": "^10.9.2",
     "tsup": "^8.5.1",
+    "@lua/shared-sandbox": "0.0.1",
+    "@lua/workflow-graph": "0.0.1",
     "@lua/shared-source-sync": "0.0.1",
-    "@lua/shared-types": "0.0.1",
-    "@lua/shared-sandbox": "0.0.1"
+    "@lua/shared-types": "0.0.1"
   },
   "scripts": {
     "clean": "rm -rf dist temp",

package/scripts/run-api-extractor.mjs

@@ -41,7 +41,7 @@ const configDir = path.join(packageRoot, 'api-extractor');
 const tempDtsDir = path.join(packageRoot, 'temp', 'dts');
 const distDir = path.join(packageRoot, 'dist');
 
-const rolledEntries = ['api-exports', 'voice-test'];
+const rolledEntries = ['api-exports', 'voice-test', 'workflow-builder'];
 
 const rawEntries = [
   { src: 'index.d.ts', dest: 'index.d.ts' },

package/template/.gitignore

@@ -19,3 +19,5 @@ node_modules/
 # OS files
 .DS_Store
 Thumbs.db
+# Workflows v1 (wave-5 gate): the script-form example IS tracked (WB-09, WF-527)
+!examples/workflows/*.workflow.script.js

package/template/examples/workflows/CLAUDE.md

@@ -0,0 +1,27 @@
+# Workflow examples
+
+Worked examples from workflows-spec 03 §3.2 (the spec is normative — do not restyle them). A file whose header carries a
+`LUA-635:` note departs from the spec's listing on purpose: the compiler is what ships, and the listing was wrong against
+it (a `.then(createStep)` placement used as a string-ref target; a `template(…)` approval title). The note says what
+changed and why; `tests/__tests__/compile.workflow.examples.test.ts` compiles every file here, so a drift cannot return.
+
+| File                                                                                              | Shows                                                                                                                                           |
+| ------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| `research-brief.ts`                                                                               | (a) sequential + parallel research, typed predicates (`stepOf`/`gt`/`lit`), switch + otherwise                                                  |
+| `outreach.ts`                                                                                     | (b) `foreach` + editable approval + an exactly-once send (`ctx.once`), cron schedule, `concurrencyPolicy`                                       |
+| `provision-tenant.ts`                                                                             | (c) nested workflow + `sleep` + `waitForSignal`                                                                                                 |
+| `reviewed-brief.ts`                                                                               | (d) `specialistStep` — an ephemeral reviewer role on the owning agent (D25)                                                                     |
+| `refund-approval.ts`                                                                              | (e) maker-checker + four-eyes + business-hours escalation chain + a recoverable external step (`onError:'park'`)                                |
+| `ticket-to-pr.ts` + `pr-review-round.ts` + `linear-ready.trigger.ts` + `github-review.webhook.ts` | (f) the SWE headline: Job tier, worktree arms + merge, review loop over a child workflow, trigger `startWorkflow`, webhook → `Workflows.signal` |
+| `support-triage.ts`                                                                               | (g) knowledge grounding, mandatory `toolScope` on external content, dataset rows, `ctx.artefacts`                                               |
+| `adversarial-verify.workflow.script.js`                                                           | (i) script form — `step()` inline effect + a library `role:{ref}`                                                                               |
+| `vendor-invoices.ts`                                                                              | (j) per-item approvals (`itemsPath`), `env.template()` overlays, `outputVisibility`                                                             |
+
+Recipes:
+
+- Run any of these offline: `lua test workflow <name>` (steering flags in `docs/api/Workflows.md` → "Testing locally").
+- Give a predicate BOTH truth values under `--agents fake` with `--step-output <id>=<json>` — the fake stub alone
+  cannot reach the `gt(confidence, 0.6)` arm of `research-brief`.
+- Every doc rule worth repeating: _execute re-runs from the top after resume; execution is at-least-once — dedupe
+  on `occurrenceId`_ (`${lineageId}:${stepId}`); an effect unique across independent runs needs your own business
+  key (`refund:${ticketId}`).

package/template/examples/workflows/adversarial-verify.workflow.script.js

@@ -0,0 +1,48 @@
+// Example (i) — adversarial verify: spawn finders until two consecutive rounds add nothing
+// new, then have an independent verifier confirm each finding. Script form (04 §4.3);
+// push with `lua push workflow`, run offline with `lua test workflow adversarial-verify`.
+export const meta = {
+  name: 'adversarial-verify',
+  description: 'Find candidate issues from several angles, verify each independently, report the confirmed set',
+  phases: [{ title: 'Find' }, { title: 'Verify' }, { title: 'Report' }],
+  concurrency: 4,
+  sampleArgs: { subject: 'The attached design doc', angles: ['security', 'performance', 'clarity'] },
+};
+
+const found = new Map();
+let quietRounds = 0;
+for (let round = 1; round <= 5 && quietRounds < 2; round++) {
+  const batch = await parallel(
+    args.angles.map((angle) =>
+      agent(`Round ${round}: list concrete issues in ${args.subject} from the ${angle} angle. One per line.`, {
+        phase: 'Find',
+        label: `find-${angle}-${round}`,
+      })
+    )
+  );
+  // step(): a pure reduction journaled once — its closure may use anything, it never re-runs on replay.
+  const added = await step(`dedupe-${round}`, () => {
+    let fresh = 0;
+    for (const text of batch) {
+      for (const line of String(text).split('\n')) {
+        const key = line.trim().toLowerCase();
+        if (key && !found.has(key)) {
+          found.set(key, line.trim());
+          fresh++;
+        }
+      }
+    }
+    return fresh;
+  });
+  quietRounds = added === 0 ? quietRounds + 1 : 0;
+  log(`round ${round}: ${added} new finding(s)`);
+}
+
+const verdicts = await foreach(
+  [...found.values()],
+  (issue) =>
+    agent(`Independently verify: "${issue}". Answer CONFIRMED or REJECTED with one sentence.`, { phase: 'Verify' }),
+  { concurrency: 4 }
+);
+const confirmed = [...found.values()].filter((_, i) => String(verdicts[i]).toUpperCase().startsWith('CONFIRMED'));
+return { confirmed, rejected: found.size - confirmed.length, rounds: quietRounds };

package/template/examples/workflows/github-review.webhook.ts

@@ -0,0 +1,19 @@
+// Routes a PR review to the run named in the PR body (Workflows.signal).
+// Verbatim from workflows-spec 03 §3.2 (f) (WF-215 / WF-223 — the spec is normative).
+// src/webhooks/github-review.ts — routes a PR review to the run named in the PR body (§3.7 `Workflows.signal`; 06 §6.5.3 step 2b descends it into the waiting review-round child)
+import { LuaWebhook, Workflows } from 'lua-cli';
+
+export default new LuaWebhook({
+  name: 'github-pr-review',
+  description: 'GitHub pull_request_review → github.review signal',
+  async execute({ headers, body }) {
+    if (headers['x-github-event'] !== 'pull_request_review') return { ignored: true };
+    const runId = /<!-- lua-run:(wfr_[A-Za-z0-9_-]+) -->/.exec(body.pull_request?.body ?? '')?.[1];   // the marker `openPr` wrote (above); absent ⇒ not one of ours
+    if (!runId) return { ignored: true };
+    const state = body.review.state === 'approved' ? 'approved' : body.review.state === 'changes_requested' ? 'changes_requested' : 'commented';
+    const r = await Workflows.signal(runId, 'github.review',
+      { state, comments: [{ body: body.review.body ?? '' }] },                              // matches the wait's `schema`; inline review comments arrive on `pull_request_review_comment` and are folded the same way
+      { dedupeKey: `review:${body.review.id}` });                                            // GitHub redelivers: one signal per review id (06 §6.5)
+    return { runId, accepted: r.accepted, reason: r.reason };                               // `accepted:false, reason:'source_not_accepted'` would mean the wait's acceptedSources exclude 'webhook' — it does not (above)
+  },
+});

package/template/examples/workflows/linear-ready.trigger.ts

@@ -0,0 +1,21 @@
+// The Linear label trigger that starts ticket-to-pr (07 §7.2.1 TriggerStartWorkflow).
+// Verbatim from workflows-spec 03 §3.2 (f) (WF-215 / WF-223 — the spec is normative).
+// src/triggers/linear-ready.ts — the Linear label that starts a run (07 §7.2.1 `TriggerStartWorkflow`; LuaTrigger has no execute — filter + transform only)
+import { LuaTrigger } from 'lua-cli';
+
+export default new LuaTrigger({
+  name: 'linear-ready-for-agent',
+  description: 'Linear "issue labeled" webhook → start ticket-to-pr',
+  source: 'webhook',
+  filter: (ctx) => ctx.payload?.type === 'Issue' && ctx.payload?.action === 'update'
+    && (ctx.payload.data?.labels ?? []).some((l: { name: string }) => l.name === 'ready-for-agent'),   // any other label edit: the trigger's ordinary "filtered" verdict, no run
+  transform: (ctx) => {
+    const issue = ctx.payload.data;
+    return { startWorkflow: {
+      name: 'ticket-to-pr',
+      input: { ticketId: issue.identifier, title: issue.title, spec: issue.description ?? '', repo: 'https://github.com/acme/backend', baseRef: 'main' },
+      idempotencyKey: `linear:${issue.identifier}:ready-for-agent`,   // a redelivered webhook or a label toggled twice returns the SAME run (§3.7; 07 §7.2.3 step 2)
+      // no `notify`: a trigger start runs as the system principal, and `notify` addresses the creator only (07 §7.4.1 — inert here); the human-facing surface is the PR itself + the approval inbox
+    } };
+  },
+});

package/template/examples/workflows/outreach.ts

@@ -0,0 +1,55 @@
+// foreach + approval + an exactly-once send (`ctx.once`).
+// Verbatim from workflows-spec 03 §3.2 (b) (WF-215 / WF-223 — the spec is normative).
+import { z } from 'zod';
+import { createStep, createWorkflow, fromInit, fromStep, template, AI, Channels } from 'lua-cli';
+
+const lead = z.object({ email: z.string().email(), name: z.string() });
+const draft = z.object({ to: z.string(), body: z.string() });
+
+const draftEmail = createStep({
+  id: 'draftEmail',
+  inputSchema: lead,                                       // foreach passes the RAW item — `{ email, name }`, not `{ lead: {…} }` (§3.2.1 check 4)
+  outputSchema: draft,
+  async execute({ inputData }) {
+    // string overload → Promise<string> (`api-exports.ts:768`); the object overload returns `AiGenerateOutput{ text, … }` (`:786`, shared-types `ai-generate.types.ts:78-86`)
+    const text = await AI.generate(`Write a 3-line intro email to ${inputData.name}`);
+    return { to: inputData.email, body: text };
+  },
+});
+const sendEmails = createStep({
+  id: 'sendEmails',
+  inputSchema: z.object({ drafts: z.array(draft) }),
+  outputSchema: z.object({ sent: z.number() }),
+  sideEffects: 'external',                                  // never auto-retried on platform-fault reclaim
+  onError: 'park',                                          // an EFFECT_IN_DOUBT parks the step for R37 instead of failing the run
+  async execute({ inputData, once }) {
+    let sent = 0;
+    for (const d of inputData.drafts) {
+      // exactly-once per {occurrenceId, key}: a retry, resume, repair run or migrated run that reaches this line again gets the stored
+      // result back and never re-sends (I27 claim/settle). No hand-rolled Data check-then-act — that pattern was non-atomic.
+      const r = await once(d.to, () => Channels.email.send({ to: { email: d.to }, subject: 'Hello', body: d.body }));   // `EmailSendInput.to` is `{ userId?, email? }`
+      // The whole `Channels` facade is callable in-step — incl. `Channels.whatsapp.send({ threadId: ctx.runtime.replyTo!.threadId, text })` on a customer-channel run (07 §7.0-L / §7.4.5): a step MAY answer the customer
+      // itself (e.g. the refund outcome right after the Stripe step, before a QA step that must not delay it); `once()` covers it exactly like email, and the platform's terminal reply then lands as a
+      // duplicate-safe fallback (same threadId; the customer sees two lines only if the step's text differs). Outside WhatsApp's session the in-step send needs a template too — `Channels.whatsapp.sendTemplate` (closing pass 2026-08-27).
+      if (r) sent++;
+    }
+    return { sent };
+  },
+});
+
+export const outreach = createWorkflow({
+  name: 'outreach',
+  inputSchema: z.object({ leads: z.array(lead) }),
+  outputSchema: z.object({ sent: z.number() }),
+  schedule: { type: 'cron', expression: '0 9 * * 1', timezone: 'Europe/London' },
+  scheduleInput: { leads: [] },
+  concurrencyPolicy: 'forbid',
+})
+  .map({ leads: fromInit('leads') }, { id: 'leads' })                        // entry 1 — three maps in this workflow ⇒ every id explicit (`map-id-required`)
+  .map({ '': fromStep('leads', 'leads') }, { id: 'items' })                  // entry 2 — '' key = "output IS this value" (Lua extension, §3.4): foreach needs a raw array upstream
+  .foreach(draftEmail, { concurrency: 8, maxItems: 500 })                   // entry 3 — items are `lead`s, output is `draft[]`
+  .map({ drafts: fromStep('draftEmail') }, { id: 'drafts' })                 // entry 4 — `{ drafts: draft[] }`, the approval's editable payload
+  .approval('reviewDrafts', { title: 'Approve outreach batch', details: template('${stepResults.drafts.drafts.length} drafts ready'),
+    approver: 'org-admins', timeoutHours: 48, onTimeout: 'cancel-run', editable: true, editablePaths: ['drafts', 'drafts[*].body'] })   // entry 5
+  .then(sendEmails)                                                          // entry 6 — reads `stepResults.drafts` (the approval passes its edited payload through)
+  .commit();

package/template/examples/workflows/pr-review-round.ts

@@ -0,0 +1,75 @@
+// One review iteration; runs as a child of ticket-to-pr with the SAME workspace.
+// From workflows-spec 03 §3.2 (f) (WF-215 / WF-223 — the spec is normative). LUA-635: a switch arm is ONE step and a
+// string arm names an agentStep / specialistStep / toolStep / map / workflow declaration (03 §3.2.0) — the listing's
+// `otherwise: 'done'` over a later `.then(createStep({ id: 'done' }))` was a goto the placement rule never had.
+// src/workflows/pr-review-round.ts — one review iteration; runs as a child of ticket-to-pr with the SAME workspace
+import { z } from 'zod';
+import { createStep, createWorkflow, step, eq, lit, template } from 'lua-cli';
+
+const pushFix = createStep({
+  id: 'pushFix',
+  inputSchema: z.any(),
+  outputSchema: z.object({ headSha: z.string() }),
+  tier: 'job',
+  workspace: { mount: 'rw' },
+  timeoutSeconds: 600,
+  async execute({ workspace }) {
+    // git runs through the credential proxy — no token in this container (05 §5.17.3)
+    const sha = (await $`git -C ${workspace!.path} rev-parse HEAD`).stdout.trim(); // `$` = the Job image's shell helper (`@lua/coding-harness/shell`); a plain child_process spawn works too — the Job site has no REQUIRE_BLOCKLIST for `child_process`
+    return { headSha: sha };
+  },
+});
+
+const changesRequested = eq(step('review').path('payload.state'), lit('changes_requested'));
+
+export const prReviewRound = createWorkflow({
+  name: 'pr-review-round',
+  inputSchema: z.object({ prNumber: z.number(), repo: z.string() }),
+  outputSchema: z.object({
+    state: z.enum(['approved', 'changes_requested', 'timed_out']),
+    round: z.number().optional(),
+  }),
+})
+  .waitForSignal('review', {
+    signal: 'github.review',
+    timeoutHours: 168, // delivered by the GitHub webhook (§3.7) — to the PARENT run; the engine descends it into this child (06 §6.5.3 step 2b)
+    schema: z.object({
+      state: z.enum(['approved', 'changes_requested', 'commented']),
+      comments: z.array(z.object({ path: z.string().optional(), body: z.string() })),
+    }),
+    acceptedSources: ['webhook'],
+    onTimeout: 'continue',
+  })
+  .switch([[changesRequested, 'addressReview']]) // no `otherwise`: approved / commented / timed out falls through to `done`
+  .agentStep('addressReview', {
+    // a CODING TURN: Claude Code headless with git/gh/shell/edit on the mounted checkout (05 §5.17.6)
+    agentId: 'swe-implementer',
+    tier: 'job',
+    workspace: { mount: 'rw' },
+    timeoutSeconds: 7200,
+    jobResources: 'medium',
+    prompt: template(
+      'Address every review comment in ${stepResults.review.payload.comments} on the current branch. Run the relevant tests. Commit with a message that references the comment you addressed. Do not force-push.'
+    ),
+    toolScope: { jobTools: ['shell', 'read', 'write', 'edit', 'glob', 'grep', 'git'] }, // no `gh`: the push + PR update is the next code step
+    outputSchema: z.object({ summary: z.string() }),
+  })
+  .switch([[changesRequested, pushFix]]) // the fix path's second step — same predicate, an inline createStep as the arm
+  .then(
+    createStep({
+      id: 'done',
+      inputSchema: z.any(),
+      outputSchema: z.object({ state: z.enum(['approved', 'changes_requested', 'timed_out']) }),
+      async execute({ getStepResult }) {
+        const r = getStepResult<{ received: boolean; timedOut?: boolean; payload?: { state: string } }>('review');
+        return {
+          state: r?.received
+            ? r.payload!.state === 'changes_requested'
+              ? 'changes_requested'
+              : 'approved'
+            : 'timed_out',
+        };
+      },
+    })
+  )
+  .commit();

package/template/examples/workflows/provision-tenant.ts

@@ -0,0 +1,35 @@
+// Nested workflow + sleep + signal.
+// From workflows-spec 03 §3.2 (c) (WF-215 / WF-223 — the spec is normative). LUA-635: the switch arms are the
+// createStep objects themselves — a STRING arm names an agentStep / specialistStep / toolStep / map / workflow
+// declaration elsewhere in the chain (03 §3.2.0); `.then(createStep({ id }))` places a step, it never declares one.
+import { z } from 'zod';
+import { createStep, createWorkflow, step, eq, lit, fromInit } from 'lua-cli';
+
+const finalize = createStep({
+  id: 'finalize',
+  inputSchema: z.any(),
+  outputSchema: z.object({ ready: z.boolean() }),
+  execute: async () => ({ ready: true }),
+});
+const rollback = createStep({
+  id: 'rollback',
+  inputSchema: z.any(),
+  outputSchema: z.object({ ready: z.boolean() }),
+  execute: async () => ({ ready: false }),
+});
+
+export const provision = createWorkflow({
+  name: 'provision-tenant',
+  inputSchema: z.object({ tenantId: z.string() }),
+  outputSchema: z.object({ ready: z.boolean() }),
+})
+  .workflow('createResources', 'research-brief', { topic: fromInit('tenantId') }) // nested by name (same agent) or LuaWorkflow ref
+  .sleep(5 * 60 * 1000) // engine-side; holds no compute
+  .waitForSignal('vendorReady', {
+    signal: 'vendor.ready',
+    schema: z.object({ ok: z.boolean() }),
+    timeoutHours: 72,
+    acceptedSources: ['webhook', 'api'],
+  })
+  .switch([[eq(step('vendorReady').path('ok'), lit(true)), finalize]], rollback) // inline code steps; the last entry is a conditional, so the taken arm's output is the run output
+  .commit();

package/template/examples/workflows/refund-approval.ts

@@ -0,0 +1,57 @@
+// Maker-checker refund with escalation, business-hours deadlines and a recoverable external step.
+// Verbatim from workflows-spec 03 §3.2 (e) (WF-215 / WF-223 — the spec is normative).
+import { z } from 'zod';
+import { createStep, createWorkflow, template, Integrations } from 'lua-cli';
+
+const postRefund = createStep({
+  id: 'postRefund',
+  inputSchema: z.object({
+    approved: z.boolean(),
+    editedPayload: z.object({ ticketId: z.string(), amount: z.number() }).optional(),
+    input: z.object({ ticketId: z.string(), amount: z.number() }),
+  }), // the approval node's output shape (04 §4.2.3)
+  outputSchema: z.object({ refundId: z.string().nullable() }),
+  sideEffects: 'external', // a platform-fault reclaim PARKS this step (never auto-retried); the run gates `exception` (§06 §6.3.5)
+  onError: 'park', // a final customer-fault failure parks too — the operator retries / skips / supplies the refundId / fails it
+  requiredConnections: ['stripe'], // the declared key below — resolved on the owner agent at run time (LUA-623); no connection of that type ⇒ failed{credentials_unresolved}, unmountable ⇒ failed{credentials_revoked, reason:'required_connection_unmountable'} → parked via onError:'park' (§11 §11.5.5)
+  async execute({ inputData, occurrenceId }) {
+    if (!inputData.approved) return { refundId: null };
+    const r = inputData.editedPayload ?? inputData.input;
+    // `occurrenceId` is `${lineageId}:${stepId}`: the same key on retry-step, on resume and on a REPAIR RUN — the refund collapses to one (§06 §6.3.3 (e)).
+    // A key that must hold across INDEPENDENT runs (two runs for the same ticket) is the caller's: `refund:${r.ticketId}` (§06 §6.3.3 (f)).
+    const res = await Integrations.passthrough('stripe', {
+      method: 'POST',
+      path: '/v1/refunds',
+      headers: { 'Idempotency-Key': `refund:${r.ticketId}` },
+      body: { charge: r.ticketId, amount: r.amount },
+    });
+    return { refundId: res.body.id };
+  },
+});
+
+export const refund = createWorkflow({
+  name: 'refund-approval',
+  inputSchema: z.object({ ticketId: z.string(), amount: z.number(), requesterId: z.string() }),
+  outputSchema: z.object({ refundId: z.string().nullable() }),
+  budget: { maxDurationSeconds: 14 * 24 * 3600 }, // long enough for two business-hours escalation hops (the compiler warns `deadline-clamped` otherwise)
+  connections: [{ key: 'stripe', integrationType: 'stripe', required: true }], // the Stripe connection the refund step acts through, declared once by key — never a frozen connection id (LUA-623)
+})
+  .approval('approveRefund', {
+    title: 'Refund request',
+    details: template('Refund ${initData.amount} for ticket ${initData.ticketId}'),
+    approver: { role: 'support-lead' }, // org role, template-portable; `{users:[…]}` / `{group:'finance'}` are org data (§13 §13.3.3)
+    excludeInitiator: true, // the requester who started the run can never approve it (maker-checker)
+    fourEyes: { edit: { role: 'support-lead' }, approve: { role: 'finance-controller' } }, // whoever edits the amount cannot be the one who approves it
+    timeoutHours: 8,
+    businessHours: { tz: 'Europe/London', calendar: 'mon-fri' }, // 8 business hours, then…
+    onTimeout: [
+      { escalateTo: { role: 'finance-controller' }, timeoutHours: 16 }, // …hop 1: finance, 16 business hours, then…
+      { escalateTo: 'org-admins', timeoutHours: 24 }, // …hop 2: org admins, then…
+      'deny',
+    ], // …the node completes {approved:false, timedOut:true, escalations:2} — branchable data (§06 §6.4.11)
+    editable: true,
+    editablePaths: ['amount'], // the approver may lower the amount; the approve call echoes the fingerprint of the revision it saw (§06 §6.4.9)
+    editedPayloadSchema: z.object({ ticketId: z.string(), amount: z.number().positive().max(500) }),
+  })
+  .then(postRefund)
+  .commit();

package/template/examples/workflows/research-brief.ts

@@ -0,0 +1,42 @@
+// Sequential + parallel research, typed end to end.
+// Verbatim from workflows-spec 03 §3.2 (a) (WF-215 / WF-223 — the spec is normative).
+import { z } from 'zod';
+import { createStep, createWorkflow, stepOf, fromStep, template, gt, lit } from 'lua-cli';
+
+const fetchSources = createStep({
+  id: 'fetchSources',
+  inputSchema: z.object({ topic: z.string() }),
+  outputSchema: z.object({ urls: z.array(z.string().url()) }),
+  timeoutSeconds: 60,
+  async execute({ inputData, log }) {
+    const res = await fetch(`https://api.example.com/search?q=${encodeURIComponent(inputData.topic)}`);
+    if (!res.ok) throw new Error(`search failed: ${res.status}`);
+    const json = (await res.json()) as { url: string }[];
+    log(`found ${json.length} sources`);
+    return { urls: json.slice(0, 10).map((r) => r.url) };
+  },
+});
+
+const angle = z.object({ summary: z.string(), confidence: z.number() });
+
+const wf = createWorkflow({
+  name: 'research-brief',
+  description: 'Fetch sources, summarise from two angles in parallel, merge — or fall back when confidence is low.',
+  inputSchema: z.object({ topic: z.string() }),
+  outputSchema: z.object({ brief: z.string() }),
+  budget: { maxCredits: 40 },
+})
+  .then(fetchSources)                                                          // entry 1: step
+  .parallel(['techAngle', 'marketAngle'])                                      // entry 2: parallel — 2 arms, both declared BELOW (§3.2.0: "declare here, inside me")
+  .agentStep('techAngle', { agentId: 'analyst', prompt: template('Summarise the technical angle of ${initData.topic} using ${stepResults.fetchSources.urls}'),
+    outputSchema: angle })                                                     // no top-level entry — placed by the parallel above
+  .agentStep('marketAngle', { agentId: 'analyst', prompt: template('Summarise the market angle of ${initData.topic} using ${stepResults.fetchSources.urls}'),
+    outputSchema: angle })                                                     // same
+  .switch(                                                                     // entry 3: conditional{exclusive}
+    [[gt(stepOf<typeof angle>('techAngle').path('confidence'), lit(0.6)), 'merge']],   // TypedRef<number> vs Literal<number> — `lit('a')` would not compile
+    'lowConfidence')
+  .map({ brief: fromStep('techAngle', 'summary'), market: fromStep('marketAngle', 'summary') }, { id: 'merge' })   // placed INSIDE the switch arm (string ref above) — one entry, not two
+  .agentStep('lowConfidence', { agentId: 'analyst',                            // placed as the switch's `otherwise`
+    prompt: template('Confidence was low. Write a cautious brief on ${initData.topic} from ${stepResults.techAngle.summary} and ${stepResults.marketAngle.summary}'),
+    outputSchema: z.object({ brief: z.string() }) })
+  .commit();                                                                   // the conditional is the last entry: the taken arm's output IS the run output

package/template/examples/workflows/reviewed-brief.ts

@@ -0,0 +1,19 @@
+// Ephemeral reviewer on the owning agent (D25).
+// Verbatim from workflows-spec 03 §3.2 (d) (WF-215 / WF-223 — the spec is normative).
+import { z } from 'zod';
+import { createWorkflow, template } from 'lua-cli';
+
+export const reviewedBrief = createWorkflow({
+  name: 'reviewed-brief',
+  inputSchema: z.object({ company: z.string() }),
+  outputSchema: z.object({ findings: z.array(z.string()), verdict: z.enum(['pass', 'revise']) }),
+})
+  .agentStep('draft', { agentId: 'web-researcher', prompt: template('Draft a one-page brief on ${initData.company}.') })
+  .specialistStep('review', {
+    role: { name: 'Reviewer',
+            instructions: 'You are a sceptical reviewer. Check every claim in the draft against a source you can cite; flag anything unsupported. Never rewrite the draft — return findings only.',
+            tools: ['searchWeb', 'fetchUrl'] },                       // ⊆ the owning agent's toolset; delegation tools (`agent-*`) are never allowlistable (04 §4.2.7)
+    prompt: template('Review the draft: ${stepResults.draft.text}'),
+    outputSchema: z.object({ findings: z.array(z.string()), verdict: z.enum(['pass', 'revise']) }),
+  })
+  .commit();

package/template/examples/workflows/support-triage.ts

@@ -0,0 +1,81 @@
+// Support triage from a customer channel — knowledge grounding, toolScope, dataset ref, ctx.artefacts.
+// From workflows-spec 03 §3.2 (g) (WF-215 / WF-223 — the spec is normative). LUA-635: the listing's `.conditional([{ when, branch }])`
+// is not in the builder (03 §3.1 has `switch` / `branch` over `[predicate, StepRef]` arms) and it named an approval as an arm, which
+// v1 forbids (approvals are top-level only) — the gate is a `switch` whose confident arm is (e)'s `refund-approval` as a child run.
+// (The listing's `template(…)` approval title was the other drift: the grammar is `title: string`, bindings ride `details`.)
+import {
+  createWorkflow,
+  createStep,
+  fromInit,
+  fromStep,
+  fromKnowledge,
+  rows,
+  template,
+  stepOf,
+  gt,
+  lit,
+} from 'lua-cli';
+import { z } from 'zod';
+
+const pullHistory = createStep({
+  // array-typed output ⇒ oversize (> 8 MB) becomes a `{__datasetRef}` (NDJSON on CDN), never OUTPUT_TOO_LARGE
+  id: 'pullHistory',
+  inputSchema: z.object({ customerId: z.string() }),
+  outputSchema: z.object({ orders: z.array(z.object({ id: z.string(), total: z.number(), status: z.string() })) }),
+  execute: async (ctx) => {
+    const orders = await Orders.list({ customerId: ctx.inputData.customerId, limit: 50_000 });
+    const csv = ['id,total,status', ...orders.map((o) => `${o.id},${o.total},${o.status}`)].join('\n');
+    const { artefactId } = await ctx.artefacts.put('orders.csv', csv, {
+      // P1-8: journaled in script form; ≤ 50 per step
+      contentType: 'text/csv',
+      kind: 'dataset',
+      datasetSchema: {
+        type: 'object',
+        properties: { id: { type: 'string' }, total: { type: 'number' }, status: { type: 'string' } },
+      },
+    });
+    ctx.log(`orders.csv → ${artefactId}`);
+    return { orders };
+  },
+});
+
+const classifyOut = z.object({
+  intent: z.enum(['refund', 'status', 'other']),
+  confidence: z.number(),
+  orderId: z.string().optional(),
+  amount: z.number().optional(),
+}); // `amount`: the order total a confident refund carries into (e)
+
+export default createWorkflow({
+  name: 'support-triage',
+  inputSchema: z.object({ ticketId: z.string(), customerId: z.string(), message: z.string() }),
+})
+  .then(pullHistory)
+  .map(
+    {
+      refund: fromKnowledge({ source: 'org-docs', query: 'refund policy', maxChars: 4000, topK: 3 }), // rendered at S2 with a provenance header per chunk
+      recent: rows('pullHistory', 'orders', { offset: 0, limit: 20 }), // paged rows; the bare ref would be the {__datasetRef} object
+    },
+    { id: 'classifyInputs' }
+  )
+  .agentStep('classify', {
+    agentId: 'support-agent',
+    // `${initData.message}` is customer-channel content and `refund` is a {knowledge} binding: this step is EXTERNAL-CONTENT — `toolScope` is mandatory.
+    prompt: template(
+      'Ticket ${initData.ticketId}: ${initData.message}\n\nRefund policy:\n${stepResults.classifyInputs.refund}\n\nRecent orders (first page):\n${stepResults.classifyInputs.recent}'
+    ),
+    toolScope: {}, // `{}` = no tools; `defaultToolScopeMode:'deny'` would imply this when absent
+    outputSchema: classifyOut,
+  })
+  .switch([[gt(stepOf<typeof classifyOut>('classify').path('confidence'), lit(0.8)), 'refundGate']], 'handoff') // a confident refund goes to the gate, anything else to a human. An approval is TOP-LEVEL only (03 §3.1), so the gated one is a child run whose approval sits at its own top level — the same shape as a wait inside a loop (03 §3.2 (f))
+  .workflow('refundGate', 'refund-approval', {
+    ticketId: fromInit('ticketId'),
+    amount: fromStep('classify', 'amount'),
+    requesterId: fromInit('customerId'),
+  }) // (e)'s maker-checker run, nested by name on the same agent; declared here, placed inside the switch arm by the string ref above. Its approver is a role, NOT 'creator': `approver-is-run-principal` on a customer-channel workflow
+  .agentStep('handoff', {
+    agentId: 'support-agent',
+    prompt: template('Summarise ${initData.message} for a human agent.'),
+    toolScope: {},
+  }) // the switch's `otherwise`
+  .commit();