lua-cli 3.42.0-beta.1 → 3.42.0-beta.2

package/docs/api/LuaWebhook.md

@@ -12,6 +12,7 @@ import { z } from 'zod';
 ## Overview
 
 Webhooks enable:
+
 - Receive HTTP requests from external services
 - Validate query parameters, headers, and body
 - Process events from third-party platforms
@@ -94,11 +95,22 @@ interface LuaWebhookEvent {
   /** Request body (JSON or raw data) */
   body?: any;
 
+  /** Exact unparsed request bytes (utf8) — for verifying vendor signatures */
+  rawBody?: string;
+
   /** ISO timestamp when the webhook was received */
   timestamp: string;
 }
 ```
 
+`rawBody` is the request exactly as it arrived on the wire, as a utf8 string.
+Vendor HMAC schemes (Stripe `t=…,v1=…`, GitHub `sha256=…`, Slack `v0:…`) are
+computed over those bytes, and `JSON.stringify(event.body)` does not reproduce
+them (whitespace, key order and escaping differ), so verify against `rawBody`.
+It is present for JSON requests (`''` for an empty body) and absent for
+form-encoded or plain-text bodies and for webhooks fired by platform events.
+Header keys arrive lowercased. See [Verify Signatures](#verify-signatures).
+
 ## Complete Examples
 
 ### GitHub Webhook
@@ -113,22 +125,24 @@ export const githubWebhook = new LuaWebhook({
 
   headerSchema: z.object({
     'x-github-event': z.string(),
-    'x-hub-signature': z.string()
+    'x-hub-signature': z.string(),
   }),
 
   bodySchema: z.object({
     repository: z.object({
       name: z.string(),
-      full_name: z.string()
+      full_name: z.string(),
     }),
     pusher: z.object({
       name: z.string(),
-      email: z.string()
+      email: z.string(),
     }),
-    commits: z.array(z.object({
-      message: z.string(),
-      url: z.string()
-    }))
+    commits: z.array(
+      z.object({
+        message: z.string(),
+        url: z.string(),
+      })
+    ),
   }),
 
   execute: async (event) => {
@@ -138,7 +152,7 @@ export const githubWebhook = new LuaWebhook({
     if (headers['x-github-event'] !== 'push') {
       return {
         success: false,
-        message: 'Only push events are supported'
+        message: 'Only push events are supported',
       };
     }
 
@@ -149,25 +163,27 @@ export const githubWebhook = new LuaWebhook({
         author: body.pusher.name,
         message: commit.message,
         url: commit.url,
-        timestamp: event.timestamp
+        timestamp: event.timestamp,
       });
     }
 
     // Notify relevant user
     const user = await User.get({ email: body.pusher.email });
     if (user) {
-      await user.send([{
-        type: 'text',
-        text: `✅ ${body.commits.length} commits pushed to ${body.repository.name}`
-      }]);
+      await user.send([
+        {
+          type: 'text',
+          text: `✅ ${body.commits.length} commits pushed to ${body.repository.name}`,
+        },
+      ]);
     }
 
     return {
       success: true,
       commits: body.commits.length,
-      repository: body.repository.name
+      repository: body.repository.name,
     };
-  }
+  },
 });
 ```
 
@@ -182,7 +198,7 @@ export const stripeWebhook = new LuaWebhook({
   description: 'Handles Stripe payment events',
 
   headerSchema: z.object({
-    'stripe-signature': z.string()
+    'stripe-signature': z.string(),
   }),
 
   bodySchema: z.object({
@@ -193,9 +209,9 @@ export const stripeWebhook = new LuaWebhook({
         amount: z.number(),
         currency: z.string(),
         customer: z.string().optional(),
-        metadata: z.record(z.any()).optional()
-      })
-    })
+        metadata: z.record(z.any()).optional(),
+      }),
+    }),
   }),
 
   execute: async (event) => {
@@ -214,23 +230,25 @@ export const stripeWebhook = new LuaWebhook({
           await order.update({
             paymentId: payment.id,
             paidAmount: payment.amount / 100,
-            paidAt: event.timestamp
+            paidAt: event.timestamp,
           });
 
           // Notify customer
           if (payment.customer) {
             const user = await User.get(payment.customer);
-            await user.send([{
-              type: 'text',
-              text: `✅ Payment received! Your order #${orderId} is being processed.`
-            }]);
+            await user.send([
+              {
+                type: 'text',
+                text: `✅ Payment received! Your order #${orderId} is being processed.`,
+              },
+            ]);
           }
         }
 
         return {
           success: true,
           event: 'payment_succeeded',
-          orderId
+          orderId,
         };
       }
 
@@ -241,16 +259,18 @@ export const stripeWebhook = new LuaWebhook({
         // Notify customer of failure
         if (payment.customer) {
           const user = await User.get(payment.customer);
-          await user.send([{
-            type: 'text',
-            text: `❌ Payment failed for order #${orderId}. Please try again.`
-          }]);
+          await user.send([
+            {
+              type: 'text',
+              text: `❌ Payment failed for order #${orderId}. Please try again.`,
+            },
+          ]);
         }
 
         return {
           success: true,
           event: 'payment_failed',
-          orderId
+          orderId,
         };
       }
 
@@ -258,10 +278,10 @@ export const stripeWebhook = new LuaWebhook({
         return {
           success: true,
           event: body.type,
-          message: 'Event received but not handled'
+          message: 'Event received but not handled',
         };
     }
-  }
+  },
 });
 ```
 
@@ -278,12 +298,14 @@ export const slackWebhook = new LuaWebhook({
   bodySchema: z.object({
     type: z.string(),
     challenge: z.string().optional(),
-    event: z.object({
-      type: z.string(),
-      user: z.string().optional(),
-      text: z.string().optional(),
-      channel: z.string()
-    }).optional()
+    event: z
+      .object({
+        type: z.string(),
+        user: z.string().optional(),
+        text: z.string().optional(),
+        channel: z.string(),
+      })
+      .optional(),
   }),
 
   execute: async (event) => {
@@ -306,10 +328,9 @@ export const slackWebhook = new LuaWebhook({
       // Process user message
       if (slackEvent.type === 'message' && slackEvent.text) {
         // Generate AI response
-        const response = await AI.generate(
-          'You are a helpful Slack bot assistant.',
-          [{ type: 'text', text: slackEvent.text }]
-        );
+        const response = await AI.generate('You are a helpful Slack bot assistant.', [
+          { type: 'text', text: slackEvent.text },
+        ]);
 
         // Store interaction
         await Data.create('slack_messages', {
@@ -317,20 +338,20 @@ export const slackWebhook = new LuaWebhook({
           channel: slackEvent.channel,
           message: slackEvent.text,
           response,
-          timestamp: event.timestamp
+          timestamp: event.timestamp,
         });
 
         // TODO: Send response back to Slack using Slack API
 
         return {
           success: true,
-          response
+          response,
         };
       }
     }
 
     return { success: true, message: 'Event received' };
-  }
+  },
 });
 ```
 
@@ -345,7 +366,7 @@ export const contactFormWebhook = new LuaWebhook({
   description: 'Handles contact form submissions',
 
   querySchema: z.object({
-    source: z.enum(['website', 'mobile_app']).optional()
+    source: z.enum(['website', 'mobile_app']).optional(),
   }),
 
   bodySchema: z.object({
@@ -354,7 +375,7 @@ export const contactFormWebhook = new LuaWebhook({
     phone: z.string().optional(),
     subject: z.string(),
     message: z.string().min(10),
-    consent: z.boolean()
+    consent: z.boolean(),
   }),
 
   execute: async (event) => {
@@ -364,7 +385,7 @@ export const contactFormWebhook = new LuaWebhook({
     if (!body.consent) {
       return {
         success: false,
-        error: 'Consent is required'
+        error: 'Consent is required',
       };
     }
 
@@ -377,7 +398,7 @@ export const contactFormWebhook = new LuaWebhook({
       message: body.message,
       source: query?.source || 'unknown',
       submittedAt: event.timestamp,
-      status: 'new'
+      status: 'new',
     });
 
     // Create or update user
@@ -387,22 +408,24 @@ export const contactFormWebhook = new LuaWebhook({
       await user.update({
         name: body.name,
         email: body.email,
-        phone: body.phone
+        phone: body.phone,
       });
     }
 
     // Send confirmation
-    await user.send([{
-      type: 'text',
-      text: `Thank you for contacting us, ${body.name}! We've received your message about "${body.subject}" and will get back to you soon.`
-    }]);
+    await user.send([
+      {
+        type: 'text',
+        text: `Thank you for contacting us, ${body.name}! We've received your message about "${body.subject}" and will get back to you soon.`,
+      },
+    ]);
 
     return {
       success: true,
       submissionId: entry.id,
-      message: 'Form submitted successfully'
+      message: 'Form submitted successfully',
     };
-  }
+  },
 });
 ```
 
@@ -418,17 +441,17 @@ export const apiWebhook = new LuaWebhook({
 
   headerSchema: z.object({
     'x-api-key': z.string(),
-    'content-type': z.literal('application/json')
+    'content-type': z.literal('application/json'),
   }),
 
   querySchema: z.object({
     action: z.enum(['create', 'update', 'delete']),
-    entity: z.string()
+    entity: z.string(),
   }),
 
   bodySchema: z.object({
     id: z.string(),
-    data: z.record(z.any())
+    data: z.record(z.any()),
   }),
 
   execute: async (event) => {
@@ -439,7 +462,7 @@ export const apiWebhook = new LuaWebhook({
     if (headers['x-api-key'] !== validApiKey) {
       return {
         success: false,
-        error: 'Invalid API key'
+        error: 'Invalid API key',
       };
     }
 
@@ -449,7 +472,7 @@ export const apiWebhook = new LuaWebhook({
         await Data.create(query.entity, {
           externalId: body.id,
           ...body.data,
-          syncedAt: event.timestamp
+          syncedAt: event.timestamp,
         });
         break;
 
@@ -458,7 +481,7 @@ export const apiWebhook = new LuaWebhook({
         if (entries.data.length > 0) {
           await Data.update(query.entity, entries.data[0].id, {
             ...body.data,
-            syncedAt: event.timestamp
+            syncedAt: event.timestamp,
           });
         }
         break;
@@ -475,9 +498,9 @@ export const apiWebhook = new LuaWebhook({
       success: true,
       action: query.action,
       entity: query.entity,
-      id: body.id
+      id: body.id,
     };
-  }
+  },
 });
 ```
 
@@ -490,6 +513,7 @@ https://api.heylua.ai/webhook/{agentId}/{webhookName}
 ```
 
 Example:
+
 ```
 https://api.heylua.ai/webhook/agent_123/github-push
 ```
@@ -551,7 +575,7 @@ export const webhook = new LuaWebhook({
   description: 'Webhook with error handling',
 
   bodySchema: z.object({
-    data: z.string()
+    data: z.string(),
   }),
 
   execute: async (event) => {
@@ -561,7 +585,7 @@ export const webhook = new LuaWebhook({
 
       return {
         success: true,
-        result
+        result,
       };
     } catch (error) {
       // Log error
@@ -569,17 +593,17 @@ export const webhook = new LuaWebhook({
         webhookName: 'robust-webhook',
         error: error.message,
         event: event.body,
-        timestamp: event.timestamp
+        timestamp: event.timestamp,
       });
 
       // Return error response
       return {
         success: false,
         error: error.message,
-        retry: true // Indicate that the sender should retry
+        retry: true, // Indicate that the sender should retry
       };
     }
-  }
+  },
 });
 ```
 
@@ -587,32 +611,51 @@ export const webhook = new LuaWebhook({
 
 ### Verify Signatures
 
+Verify a vendor's signature in `execute` against `event.rawBody` — the exact
+bytes the vendor signed — never against a re-serialized `event.body`:
+
 ```typescript
 import crypto from 'crypto';
+import { LuaWebhook, env } from 'lua-cli';
 
-function verifyGitHubSignature(
-  body: string,
-  signature: string,
-  secret: string
-): boolean {
-  const hmac = crypto.createHmac('sha256', secret);
-  const digest = 'sha256=' + hmac.update(body).digest('hex');
-  return crypto.timingSafeEqual(
-    Buffer.from(signature),
-    Buffer.from(digest)
-  );
+function verifyGitHubSignature(rawBody: string, signature: string, secret: string): boolean {
+  const digest = 'sha256=' + crypto.createHmac('sha256', secret).update(rawBody, 'utf8').digest('hex');
+  const a = Buffer.from(signature);
+  const b = Buffer.from(digest);
+  return a.length === b.length && crypto.timingSafeEqual(a, b);
 }
+
+export const githubPush = new LuaWebhook({
+  name: 'github-push-verified',
+  description: 'GitHub push events, signature-checked',
+  execute: async (event) => {
+    const signature = event.headers?.['x-hub-signature-256'];
+    const secret = env('GITHUB_WEBHOOK_SECRET');
+    if (!event.rawBody || !signature || !secret || !verifyGitHubSignature(event.rawBody, signature, secret)) {
+      return { success: false, error: 'invalid signature' };
+    }
+    // Signature OK — event.body is the parsed form of the same bytes.
+    return { success: true, ref: event.body.ref };
+  },
+});
 ```
 
+`lua test webhook` has no wire bytes, so it sets `rawBody` to the compact
+`JSON.stringify(body)` of the test input; pass an explicit one with
+`--input '{"body": {...}, "headers": {...}, "rawBody": "<exact bytes>"}'` to
+exercise a signature check against a captured delivery.
+
+To have Lua reject unsigned calls before `execute` runs, use the built-in
+`secret` instead (see [Request Verification](#request-verification)).
+
 ### API Key Validation
 
 ```typescript
 headerSchema: z.object({
-  'x-api-key': z.string()
-    .refine(key => key === process.env.WEBHOOK_API_KEY, {
-      message: 'Invalid API key'
-    })
-})
+  'x-api-key': z.string().refine((key) => key === process.env.WEBHOOK_API_KEY, {
+    message: 'Invalid API key',
+  }),
+});
 ```
 
 ## Related APIs

package/docs/api/LuaWorkflow.md

@@ -54,21 +54,21 @@ Config: `name`, `description?`, `inputSchema`, `outputSchema?`, `budget?` (`maxC
 
 **The call site places.** Every builder call — `then`, `agentStep`, `specialistStep`, `toolStep`, `map`, `approval`, `waitForSignal`, `sleep`, `sleepUntil`, `foreach`, `parallel`, `branch`, `switch`, `dowhile`, `dountil`, `workflow` — appends **exactly one** entry to the chain where it is called. Containers take `StepRef`s: an inline step object, or a **string** naming an `agentStep`/`specialistStep`/`toolStep` declared elsewhere in the same chain — a string ref inside a container means "declare here, inside me" and does not append a second top-level entry. An id declared but never placed is `WORKFLOW_UNPLACED_STEP` (warning locally, error at push); referenced but never declared is `unknown-step-ref` at `.commit()`.
 
-| Verb                                                                                                    | Entry                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
-| ------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `.then(step, input?)`                                                                                   | Sequential step                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
-| `.agentStep(id, { agentId, prompt, outputSchema?, toolScope?, tier?, … })`                              | Agent turn (`prompt` is a `template(...)`)                                                                                                                                                                                                                                                                                                                                                                                                                             |
-| `.specialistStep(id, { role, prompt, … })`                                                              | Ephemeral role on the owning agent (D25)                                                                                                                                                                                                                                                                                                                                                                                                                               |
-| `.toolStep(id, { toolId, input? })`                                                                     | One tool call — `toolId` must name a `LuaTool` the compiler can see as a tool primitive (declared in its own module and exported, or registered on the agent); a tool object defined inline in the workflow file is not detected and fails `WORKFLOW_TOOL_REF_UNRESOLVED` at compile                                                                                                                                                                                   |
-| `.map(descriptors, { id })`                                                                             | Data reshaping — `id` is **required** once the workflow has ≥ 2 maps (`map-id-required`)                                                                                                                                                                                                                                                                                                                                                                               |
-| `.parallel([...arms], { merge? })`                                                                      | Concurrent arms; a `[map, step]` pair is a legal arm — the step runs with the map as its own `input` (the arm node carries `input`, like a `toolStep` with one). Not a `foreach` / loop body: those receive their item / the previous output (`mapping-placement` at `.commit()`) — map the items before the container instead                                                                                                                                         |
-| `.switch([[predicate, armRef]...], otherwise?)` / `.branch(...)`                                        | Conditional (exclusive / inclusive)                                                                                                                                                                                                                                                                                                                                                                                                                                    |
-| `.foreach(step, { items?, concurrency?, maxItems?, chunk?, rateLimit? })`                               | Fan-out over an upstream array. `items` lowers to a `<bodyId>_items` mapping ahead of the entry and takes `fromInit(path)` / `fromStep(id, path)` or an `init(...)` / `step(...).path(...)` ref (LUA-864) — the node is byte-identical whichever form you write; any other descriptor (`value`, `template`, `fromRequest`, `rows`, `fromKnowledge`, a fan-in `fromStep([...])`) is `invalid-envelope` at build: `.map({ '': ... }, { id })` before the foreach instead |
-| `.dowhile(ref, predicate, { maxIterations, intervalSeconds? })` / `.dountil(...)`                       | Loop                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
-| `.sleep(ms)` / `.sleepUntil(template)`                                                                  | Engine-side waits — `sleepUntil` lowers to an `<id>_at` mapping + `sleepUntil{dateFrom}` (D6-r1)                                                                                                                                                                                                                                                                                                                                                                       |
-| `.approval(id, { title, approver, timeoutHours, onTimeout, editable?, editablePaths?, itemsPath?, … })` | Human gate — see [Approvals](../workflows/approvals.md)                                                                                                                                                                                                                                                                                                                                                                                                                |
-| `.waitForSignal(id, { signal, schema?, timeoutHours, acceptedSources? })`                               | External event via `Workflows.signal` — completes with `{ payload, source: { kind, id, principalId? }, signalId, receivedAt }`; payload keys named like a credential (`token`, `secret`, `apiKey`, `accessToken`, …) are persisted `[REDACTED]` (the `signal-reserved-key` warning says so at push / compose) — see [Reserved payload keys](Workflows.md#reserved-payload-keys)                                                                                        |
-| `.workflow(id, ref, input?, { workspace? })`                                                            | Child run the parent waits for                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| Verb                                                                                                                       | Entry                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| -------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `.then(step, input?)`                                                                                                      | Sequential step                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| `.agentStep(id, { agentId, prompt, outputSchema?, toolScope?, tier?, … })`                                                 | Agent turn (`prompt` is a `template(...)`)                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| `.specialistStep(id, { role, prompt, … })`                                                                                 | Ephemeral role on the owning agent (D25)                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| `.toolStep(id, { toolId, input? })`                                                                                        | One tool call — `toolId` must name a `LuaTool` the compiler can see as a tool primitive (declared in its own module and exported, or registered on the agent); a tool object defined inline in the workflow file is not detected and fails `WORKFLOW_TOOL_REF_UNRESOLVED` at compile                                                                                                                                                                                   |
+| `.map(descriptors, { id })`                                                                                                | Data reshaping — `id` is **required** once the workflow has ≥ 2 maps (`map-id-required`)                                                                                                                                                                                                                                                                                                                                                                               |
+| `.parallel([...arms], { merge? })`                                                                                         | Concurrent arms; a `[map, step]` pair is a legal arm — the step runs with the map as its own `input` (the arm node carries `input`, like a `toolStep` with one). Not a `foreach` / loop body: those receive their item / the previous output (`mapping-placement` at `.commit()`) — map the items before the container instead                                                                                                                                         |
+| `.switch([[predicate, armRef]...], otherwise?)` / `.branch(...)`                                                           | Conditional (exclusive / inclusive)                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `.foreach(step, { items?, concurrency?, maxItems?, chunk?, rateLimit? })`                                                  | Fan-out over an upstream array. `items` lowers to a `<bodyId>_items` mapping ahead of the entry and takes `fromInit(path)` / `fromStep(id, path)` or an `init(...)` / `step(...).path(...)` ref (LUA-864) — the node is byte-identical whichever form you write; any other descriptor (`value`, `template`, `fromRequest`, `rows`, `fromKnowledge`, a fan-in `fromStep([...])`) is `invalid-envelope` at build: `.map({ '': ... }, { id })` before the foreach instead |
+| `.dowhile(ref, predicate, { maxIterations, intervalSeconds? })` / `.dountil(...)`                                          | Loop                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `.sleep(ms)` / `.sleepUntil(template)`                                                                                     | Engine-side waits — `sleepUntil` lowers to an `<id>_at` mapping + `sleepUntil{dateFrom}` (D6-r1)                                                                                                                                                                                                                                                                                                                                                                       |
+| `.approval(id, { title, approver, timeoutHours, onTimeout, remindAfterHours?, editable?, editablePaths?, itemsPath?, … })` | Human gate — see [Approvals](../workflows/approvals.md)                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `.waitForSignal(id, { signal, schema?, timeoutHours, acceptedSources? })`                                                  | External event via `Workflows.signal` — completes with `{ payload, source: { kind, id, principalId? }, signalId, receivedAt }`; payload keys named like a credential (`token`, `secret`, `apiKey`, `accessToken`, …) are persisted `[REDACTED]` (the `signal-reserved-key` warning says so at push / compose) — see [Reserved payload keys](Workflows.md#reserved-payload-keys)                                                                                        |
+| `.workflow(id, ref, input?, { workspace? })`                                                                               | Child run the parent waits for                                                                                                                                                                                                                                                                                                                                                                                                                                         |
 
 ### Typed predicates
 

package/docs/api/Orders.md

@@ -30,14 +30,16 @@ The Orders API enables:
 ```typescript
 enum OrderStatus {
   PENDING = 'pending',
-  PROCESSING = 'processing',
-  SHIPPED = 'shipped',
-  DELIVERED = 'delivered',
-  CANCELLED = 'cancelled',
-  REFUNDED = 'refunded'
+  CONFIRMED = 'confirmed',
+  FULFILLED = 'fulfilled',
+  CANCELLED = 'cancelled'
 }
 ```
 
+> **Note:** the platform spells the fulfilled status `fullfilled`. `OrderStatus.FULFILLED` is sent to the platform as `fullfilled` (for both `updateStatus` and `get(status)`), and `order.common.status` reads back as `fullfilled`. Any other status value is rejected with HTTP 400, and an unknown order id answers HTTP 404; both are thrown as an `Error` carrying the server message.
+>
+> `Orders.getById`, `updateStatus` and `updateData` take the order `id` (the 24-character hex returned by `create`/`get`), not the `orderId` display string; an id that is not 24-hex answers HTTP 404. An unexpected platform failure on `Orders.create` answers HTTP 424 and a failure on the other calls answers HTTP 500; both are thrown as an `Error` with the generic message `Order request failed`.
+
 ## OrderInstance Methods
 
 Once you have an order instance, you can call these methods:

package/docs/api/Products.md

@@ -101,7 +101,7 @@ Searches products by name or description.
 
 **Parameters:**
 - `query` (string) - Search term
-- `limit` (number, optional) - Max results (default: 10)
+- `limit` (number, optional) - Max results (default: 5)
 
 **Returns:** `Promise<ProductSearchInstance>`
 

package/docs/api/Progress.md

@@ -0,0 +1,57 @@
+# Progress API
+
+Show live progress for a long-running tool in the chat that called it.
+
+## Import
+
+```typescript
+import { Progress } from 'lua-cli';
+```
+
+## `Progress.update(input?)`
+
+Shows or updates ONE progress card for the current tool call. The card closes on its own when the tool returns
+(as done, or as failed when the tool throws).
+
+**Parameters** (all optional):
+
+- `label` (string, up to 120 characters) — the card title. When you leave it out, the previous label is kept; the
+  first call without one uses the tool's name.
+- `fraction` (number) — progress from 0 to 1 (clamped). Leave it out for an indeterminate bar.
+- `phase` (string, up to 200 characters) — what the tool is doing now, e.g. `"Reading sources (3/12)"`.
+
+**Returns:** `Promise<{ emitted: boolean }>`
+
+- `emitted: true` — the card was shown. Calls closer together than 250 ms are coalesced: the latest one is shown.
+- `emitted: false` — there is nothing to show it on: the chat surface cannot render progress cards (for example
+  WhatsApp, or an API call without a live stream), the tool is not running in a chat turn (jobs, webhooks,
+  triggers), the feature is not enabled for your environment, or you are running offline in `lua test`.
+
+`Progress.update` never throws. You do not need to wrap it in `try`/`catch`.
+
+## Example
+
+```typescript
+import { Progress } from 'lua-cli';
+import { LuaTool } from 'lua-cli/skill';
+import { z } from 'zod';
+
+export default class ImportFilesTool implements LuaTool {
+  name = 'import_files';
+  description = 'Import the given files';
+  inputSchema = z.object({ urls: z.array(z.string()) });
+
+  async execute({ urls }: z.infer<typeof this.inputSchema>) {
+    for (let i = 0; i < urls.length; i++) {
+      await Progress.update({ label: 'Importing files', fraction: i / urls.length, phase: urls[i] });
+      await importOne(urls[i]);
+    }
+    return { imported: urls.length };
+  }
+}
+```
+
+## Workflow runs started from a tool
+
+When a tool starts a workflow run with `Workflows.start(...)` during a chat turn, the run's live card appears in
+that chat (the run's origin thread), the same card a run started by the model shows. No code is needed.