lua-cli 3.32.2 → 3.32.4

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

@@ -1,22 +1,35 @@
 // 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).
+// From workflows-spec 03 §3.2 (e) (WF-215 / WF-223 — the spec is normative). LUA-751: the step after the approval reads the
+// approval node's REAL output — `WorkflowApprovalOutput` (@lua/shared-types): `{ approved, decision, text, note?, editedPayload?,
+// editRevision?, decidedBy?, timedOut?, escalations? }`, the ONE shape the engine emits and `lua workflows run --approve` emits
+// offline. The listing's `input: <preceding output>` pass-through (04 §4.2.3) was never implemented — the original payload is not
+// echoed back; the step reads the request back with `getStepResult('refundRequest')` (docs/workflows/approvals.md). The `refundRequest`
+// map ahead of the approval makes the payload the approver sees and edits exactly what `editedPayloadSchema` describes
+// (`{ ticketId, amount }`, not the whole run input): an edit is judged on the pointers that changed against that payload.
 import { z } from 'zod';
-import { createStep, createWorkflow, template, Integrations } from 'lua-cli';
+import { createStep, createWorkflow, fromInit, template, Integrations } from 'lua-cli';
+
+const refundRequest = z.object({ ticketId: z.string(), amount: z.number() });
 
 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)
+  // The approval node's output (`WorkflowApprovalOutput`): the members this step reads; `.passthrough()` admits the rest of the
+  // envelope (`decision`, `text`, `note`, `editRevision`, `decidedBy`, `timedOut`, `escalations`) — the engine validates a step's
+  // input with `additionalProperties:false` otherwise.
+  inputSchema: z
+    .object({
+      approved: z.boolean(),
+      editedPayload: refundRequest.optional(), // only when the approver edited the amount (`editablePaths` below)
+    })
+    .passthrough(),
   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;
+  async execute({ inputData, getStepResult, occurrenceId }) {
+    if (!inputData.approved) return { refundId: null }; // denied, or timed out under the chain's terminal 'deny' — data, never an exception (§06 §6.4.11)
+    // The edited details when the approver lowered the amount, else the request the approver saw (the `refundRequest` map). The output never echoes it.
+    const r = inputData.editedPayload ?? getStepResult<z.infer<typeof refundRequest>>('refundRequest');
     // `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', {
@@ -36,6 +49,7 @@ export const refund = createWorkflow({
   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)
 })
+  .map({ ticketId: fromInit('ticketId'), amount: fromInit('amount') }, { id: 'refundRequest' }) // the payload the approver reviews — and may edit — is the refund request, not the whole run input
   .approval('approveRefund', {
     title: 'Refund request',
     details: template('Refund ${initData.amount} for ticket ${initData.ticketId}'),
@@ -48,10 +62,10 @@ export const refund = createWorkflow({
       { 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)
+    ], // …the node completes {approved:false, decision:'timed_out', text:'timed_out', 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)
+  .then(postRefund) // its input IS the approval's output (the default previous-output rule, §05 §5.5.1.1)
   .commit();

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

@@ -1,5 +1,6 @@
 // Sequential + parallel research, typed end to end.
-// Verbatim from workflows-spec 03 §3.2 (a) (WF-215 / WF-223 — the spec is normative).
+// Verbatim from workflows-spec 03 §3.2 (a) (WF-215 / WF-223 — the spec is normative), with the workflow EXPORTED
+// like every other example — a non-exported `const` cannot be registered on a LuaAgent without editing the file.
 import { z } from 'zod';
 import { createStep, createWorkflow, stepOf, fromStep, template, gt, lit } from 'lua-cli';
 
@@ -19,24 +20,36 @@ const fetchSources = createStep({
 
 const angle = z.object({ summary: z.string(), confidence: z.number() });
 
-const wf = createWorkflow({
+export const researchBrief = 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
+  .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/package.json

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