lua-cli 3.29.1 → 3.31.0

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,38 @@
+// One review iteration; runs as a child of ticket-to-pr with the SAME workspace.
+// Verbatim from workflows-spec 03 §3.2 (f) (WF-215 / WF-223 — the spec is normative).
+// 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 };
+  },
+});
+
+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([[eq(step('review').path('payload.state'), lit('changes_requested')), 'addressReview']], '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() }),
+  })
+  .then(pushFix)
+  .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,18 @@
+// Nested workflow + sleep + signal.
+// Verbatim from workflows-spec 03 §3.2 (c) (WF-215 / WF-223 — the spec is normative).
+import { z } from 'zod';
+import { createStep, createWorkflow, step, eq, lit, fromInit } from 'lua-cli';
+
+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')
+  .then(createStep({ id: 'finalize', inputSchema: z.any(), outputSchema: z.object({ ready: z.boolean() }), execute: async () => ({ ready: true }) }))
+  .then(createStep({ id: 'rollback', inputSchema: z.any(), outputSchema: z.object({ ready: z.boolean() }), execute: async () => ({ ready: false }) }))
+  .commit();

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

@@ -0,0 +1,44 @@
+// 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'],                          // 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)
+})
+  .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,44 @@
+// Support triage from a customer channel — knowledge grounding, toolScope, dataset ref, ctx.artefacts.
+// Verbatim from workflows-spec 03 §3.2 (g) (WF-215 / WF-223 — the spec is normative).
+import { createWorkflow, createStep, fromInit, 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() });
+
+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,
+  })
+  .approval('refundGate', { title: template('Refund ${stepResults.classify.orderId}?'), approver: 'org-admins',   // NOT 'creator': `approver-is-run-principal` on a customer-channel workflow
+    details: template('${stepResults.classify.intent} @ ${stepResults.classify.confidence}'), timeoutHours: 24,
+    onTimeout: [{ escalateTo: 'org-admins', timeoutHours: 24 }, 'deny'] })                              // approvers re-resolved at suspend AND decision (§06 §6.11); the card previews `orders.csv` (name/size/rowCount + an R32 link)
+  .conditional([
+    { when: gt(stepOf<typeof classifyOut>('classify').path('confidence'), lit(0.8)), branch: 'refundGate' },
+    { when: lit(true), branch: 'handoff' },
+  ])
+  .agentStep('handoff', { agentId: 'support-agent', prompt: template('Summarise ${initData.message} for a human agent.'), toolScope: {} })
+  .commit();

package/template/examples/workflows/ticket-to-pr.ts

@@ -0,0 +1,65 @@
+// Linear label -> clone -> parallel worktree arms -> merge -> tests -> PR -> review loop -> approval -> merge.
+// Verbatim from workflows-spec 03 §3.2 (f) (WF-215 / WF-223 — the spec is normative).
+// src/workflows/ticket-to-pr.ts — Linear label → clone → parallel worktree arms → merge → test suite → PR → review loop → approval → merge
+import { z } from 'zod';
+import { createStep, createWorkflow, step, fromInit, fromStep, template, eq, lit } from 'lua-cli';
+import { prReviewRound } from './pr-review-round';
+
+const runTests = createStep({
+  id: 'runTests',
+  inputSchema: z.any(), outputSchema: z.object({ passed: z.boolean(), summary: z.string() }),
+  tier: 'job', workspace: { mount: 'rw' }, timeoutSeconds: 3600, jobResources: 'large',   // a 15–40 min monorepo suite fits one 4 h segment (D19-r1); up to 86 400 s is legal since D19-r2 — see §3.2 (h) for a step that crosses the segment boundary
+  async execute({ workspace, log }) {
+    const r = await $`cd ${workspace!.path} && npm ci && npm test -- --maxWorkers=2`.nothrow();   // untracked node_modules were rebuilt on restore (05 §5.17.5, E12); `--maxWorkers=2` keeps a mongodb-memory-server-per-file suite inside `large`'s 8 GiB — over it the container is OOM-killed and the step fails `job_oom_killed` (customer fault, 05 §5.17.4; §3.12 note)
+    log(r.stdout.slice(-4000));
+    return { passed: r.exitCode === 0, summary: r.stdout.slice(-2000) };
+  },
+});
+
+const openPr = createStep({
+  id: 'openPr',
+  inputSchema: z.object({ ticketId: z.string(), title: z.string() }), outputSchema: z.object({ prNumber: z.number(), url: z.string() }),
+  tier: 'job', workspace: { mount: 'ro' },
+  sideEffects: 'external', onError: 'park',                                                 // a PR is an external effect: a platform fault PARKS (06 §6.3.5); `gh` is idempotent on the branch anyway
+  async execute({ workspace, inputData, runId }) {
+    const out = await $`cd ${workspace!.path} && gh pr create --fill --title ${inputData.title} --body ${`Closes ${inputData.ticketId}\n\n<!-- lua-run:${runId} -->`}`;   // the run id in the PR body is what the GitHub webhook uses to route review signals (§3.7)
+    const url = out.stdout.trim(); return { prNumber: Number(url.split('/').pop()), url };
+  },
+});
+
+const mergePr = createStep({
+  id: 'mergePr', inputSchema: z.object({ approved: z.boolean(), input: z.object({ prNumber: z.number() }) }), outputSchema: z.object({ merged: z.boolean() }),
+  tier: 'job', workspace: { mount: 'ro' }, jobTools: ['gh'], sideEffects: 'external', onError: 'park',   // `jobTools:['gh']` is what mints GH_TOKEN for a code step (11 §11.5.6: pull_requests:write + contents:write + issues:read, repo-scoped — merge is a contents write on GitHub)
+  async execute({ workspace, inputData }) {
+    if (!inputData.approved) return { merged: false };
+    await $`cd ${workspace!.path} && gh pr merge ${inputData.input.prNumber} --squash --delete-branch`;   // succeeds only if the base branch's ruleset lets the App merge — human-only-merge orgs keep contents:write off the App (11 T21)
+    return { merged: true };
+  },
+});
+
+export const ticketToPr = createWorkflow({
+  name: 'ticket-to-pr',
+  description: 'Linear label → implement/tests/docs in parallel worktrees → merge → test suite → PR → review rounds → approval → merge',
+  inputSchema: z.object({ ticketId: z.string(), title: z.string(), spec: z.string(), repo: z.string(), baseRef: z.string().default('main') }),
+  outputSchema: z.object({ merged: z.boolean(), prUrl: z.string().optional(), rounds: z.number() }),
+  workspace: { kind: 'git', repo: template('${initData.repo}'), ref: template('${initData.baseRef}'), credentialsRef: 'github-app', sizeGb: 20, verify: 'npm test' },   // `github-app` = the org's GitHub connection id (a template would use `connections[].key`, §13 §13.3.3)
+  budget: { maxCredits: 400, maxDurationSeconds: 21 * 24 * 3600 },                         // review rounds may wait a week each. Job seconds (wall, claim → terminal) worst case: 7200+5400+1800 arms + 3600 merge + 3600 tests + 3600 fixTests + 3600 openPr + 8 × (7200+600) rounds + 3600 merge ≈ 94 800 s — fits the org default maxJobSecondsPerRun 172 800 (48 h) with margin; the push-time `job-seconds-exceed-cap` BLOCKER (10 §10.7.6) refuses this file on an org that lowered the cap below the sum, and prints the R23 raise path. Declare `maxJobSeconds` explicitly only to narrow.
+})
+  .parallel(['implement', 'writeTests', 'updateDocs'], { merge: { strategy: 'rebase', onConflict: 'agent' } })   // three coding turns on three clone volumes + branches; the merge row rebases them onto the run branch and lets one resolver turn fix conflicts (05 §5.17.5)
+  .agentStep('implement', { agentId: 'swe-implementer', tier: 'job', workspace: { mount: 'rw', isolation: 'worktree' }, timeoutSeconds: 7200,
+    prompt: template('Implement ${initData.spec} for ticket ${initData.ticketId}. Do not touch tests or docs; commit as you go.'),
+    toolScope: { jobTools: ['shell', 'read', 'write', 'edit', 'glob', 'grep', 'git'] } })
+  .agentStep('writeTests', { agentId: 'swe-tester', tier: 'job', workspace: { mount: 'rw', isolation: 'worktree' }, timeoutSeconds: 5400,
+    prompt: template('Write tests for the behaviour described in ${initData.spec}; they may fail until implementation lands. Only touch test files.') })
+  .agentStep('updateDocs', { agentId: 'swe-writer', tier: 'job', workspace: { mount: 'rw', isolation: 'worktree' }, timeoutSeconds: 1800, jobResources: 'small',
+    prompt: template('Update docs/ for ${initData.spec}. Only touch markdown files.') })
+  .then(runTests)                                                                          // shared mount, sequential — the merged run branch
+  .switch([[eq(step('runTests').path('passed'), lit(false)), 'fixTests']], 'openPr')
+  .agentStep('fixTests', { agentId: 'swe-implementer', tier: 'job', workspace: { mount: 'rw' }, timeoutSeconds: 3600,
+    prompt: template('The test suite failed:\n${stepResults.runTests.summary}\nFix the code (not the tests unless they are wrong) and re-run `npm test` until green.') })
+  .then(openPr)
+  .dowhile('reviewRound', eq(step('reviewRound').path('state'), lit('changes_requested')), { maxIterations: 8 })   // ≤ 8 review rounds (the SWE_REVIEW_MAX_ROUNDS lesson)
+  .workflow('reviewRound', prReviewRound, { prNumber: fromStep('openPr', 'prNumber'), repo: fromInit('repo') }, { workspace: 'inherit' })   // each round is a child run on the SAME workspace; the parent's PVC is released while a round waits for the webhook (E12)
+  .approval('mergeGate', { title: template('Merge PR ${stepResults.openPr.url}?'), approver: { role: 'eng-lead' }, excludeInitiator: true, timeoutHours: 72, onTimeout: 'deny' })
+  .then(mergePr)
+  .commit();

package/template/examples/workflows/vendor-invoices.ts

@@ -0,0 +1,30 @@
+// Per-item review with an env overlay, a restricted output pane and a slack reply (Cluster K).
+// Verbatim from workflows-spec 03 §3.2 (j) (WF-215 / WF-223 — the spec is normative).
+import { z } from 'zod';
+import { createStep, createWorkflow, env, fromInit, fromKnowledge, fromStep, template } from 'lua-cli';
+
+const invoiceSchema = z.object({ vendorId: z.string(), approverEmail: z.string().email(), amount: z.number(), pdf: z.object({ __artefactRef: z.string() }) });
+
+const loadInvoices = createStep({ id: 'loadInvoices', inputSchema: z.object({ batchId: z.string() }), outputSchema: z.object({ invoices: z.array(invoiceSchema) }),
+  async execute(ctx) {
+    const src = await ctx.artefacts.get(ctx.inputData.batchId);                                   // B40: a multi-GB NDJSON batch — page it, never buffer it
+    const invoices = []; for (let offset = 0; ; offset += 1000) { const page = await src.rows({ offset, limit: 1000 }); invoices.push(...page.rows); if (page.nextOffset == null) break; }
+    return { invoices };
+  } });
+
+export const vendorInvoices = createWorkflow({
+  name: 'vendor-invoices', inputSchema: z.object({ batchId: z.string() }),
+  outputVisibility: { roles: ['finance', 'org-admin'] },                                          // B44: invoice payloads are readable by finance only; owner bypass on (default)
+  schedule: { cron: '0 6 * * 1-5', timezone: env.template('FINANCE_TZ') },                        // B33: one file, per-env timezone resolved at push
+})
+  .then(loadInvoices, { batchId: fromInit('batchId') })
+  .agentStep('policyCheck', { agentId: env.template('FINANCE_AGENT_ID'),                          // B33: staging and prod route to different sub-agents; same graphHash
+    prompt: template('Flag any invoice that breaks policy.\n${knowledge.policy}\n${stepResults.loadInvoices.invoices}'),
+    outputSchema: z.object({ flagged: z.array(z.string()) }),
+    input: { policy: fromKnowledge({ source: 'connection', connectionId: env.template('FINANCE_DRIVE_CONNECTION'), query: 'vendor payment policy', maxChars: 6000 }) },   // B41
+    toolScope: { connectionIds: [] } })                                                           // tainted by the connection knowledge ⇒ `toolScope` mandatory (P1-16); the knowledge connection is added by the compiler's overlay pass
+  .approval('reviewInvoices', { title: template('${stepResults.loadInvoices.invoices.length} vendor invoices'), details: template('Flagged: ${stepResults.policyCheck.flagged}'),
+    approver: { role: 'finance' }, itemsPath: 'invoices', itemApprover: { fromItem: 'approverEmail' },   // B20: every invoice goes to ITS approver; the parent link is the finance role's overview
+    itemTimeout: { timeoutHours: 48 }, editable: true, editablePaths: ['invoices[*].amount'], timeoutHours: 96 })
+  .foreach('pay', 'payInvoice', { items: fromStep('reviewInvoices', 'items'), concurrency: 4 })   // consumes `resumeData.items[]` — approved rows only
+  .commit();

package/template/lua.skill.yaml

@@ -6,6 +6,7 @@ agent:
 skills: []
 webhooks: []
 jobs: []
+workflows: []
 preprocessors: []
 postprocessors: []
 mcpServers: []

package/template/package.json

@@ -20,7 +20,7 @@
     "inquirer": "^12.9.6",
     "stripe": "^17.5.0",
     "js-yaml": "^4.1.0",
-    "lua-cli": "^3.29.1",
+    "lua-cli": "^3.31.0",
     "openai": "^5.23.0",
     "uuid": "^13.0.0",
     "zod": "^3.24.1"