lua-cli 3.43.0 → 3.45.0

package/docs/API_REFERENCE.md

@@ -717,7 +717,7 @@ if (Lua.request.webhook) {
 
 **Properties:**
 
-- `Lua.request.channel` - Channel type (`'whatsapp'`, `'web'`, `'api'`)
+- `Lua.request.channel` - Channel type (`'whatsapp'`, `'pop'` for the embeddable chat widget, `'phone'` for voice, `'web'` for the Lua web workspace (not the widget), `'api'`, and others; unrecognised channels arrive as plain strings)
 - `Lua.request.webhook` - Webhook info (if running in webhook)
 - `Lua.request.agentId` - The agent handling this turn
 - `Lua.request.orgId` - The agent's organization, on deployed runtimes that know it (absent offline in `lua test`

package/docs/api/Agents.md

@@ -24,6 +24,13 @@ const result = await Agents.invoke('base_agent-other', { prompt: 'hi', threadId:
 - **The target knows who called.** The target's tools see `Lua.request.invokedBy = { agentId, supervisor, scopes, delegatedUserId? }`.
   - `supervisor` is true only when an org admin granted the caller `supervision:act` on the target.
   - A well-behaved target refuses writes unless `supervisor` is true.
+- **`input.signal` cancels the call.** Optional `AbortSignal`. A signal that is already aborted rejects at once and sends no request. Aborting mid-flight rejects with `signal.reason` (an `AbortError` by default) and cancels the request, which stops the target's turn best-effort: a tool call already running on the target may still finish. Under `lua test` / `lua dev` the signal is honored by closing the HTTP request. A call without a signal is unchanged.
+
+  ```typescript
+  const controller = new AbortController();
+  setTimeout(() => controller.abort(), 10_000);
+  const result = await Agents.invoke('base_agent-other', { prompt: 'hi', signal: controller.signal });
+  ```
 
 ## Supervision
 
@@ -33,7 +40,7 @@ Supervision lets one agent observe, preview or release another agent in the same
 
 | Action            | Allows                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
 | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `observe`         | `logs` (without message bodies), `runs`, `data` (only the collections named on the grant), `versions.list/get/diff`, `persona.versions`, `source`, `env.keys`, `workflows.get`                                                                                                                                                                                                                                                                                                          |
+| `observe`         | `logs` (without message bodies), `runs`, `data` (only the collections named on the grant), `versions.list/get/diff`, `persona.versions`, `source`, `env.keys`, `workflows.get`, `deployed`                                                                                                                                                                                                                                                                                              |
 | `observe-content` | Log message bodies in `logs`                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
 | `preview`         | `versions.preview`: chat a staged version                                                                                                                                                                                                                                                                                                                                                                                                                                               |
 | `release`         | `versions.promote`, `persona.activate`, `versions.delete` (a `superseded` version only), `workflows.create` (an inert, inactive workflow with no human author, so it cannot carry a schedule), `workflows.push` (a new, never-activated version of an existing workflow) and `workflows.deploy`. Promote, activate and deploy always need `expectActive`. Every release op runs only from a live workflow step of the supervisor whose workflow the grant names (`releaseWorkflowIds`). |
@@ -48,6 +55,10 @@ const errors = await Agents.logs('base_agent-tp', { level: 'error', limit: 20 })
 const runs = await Agents.runs('base_agent-tp').list({ status: 'failed' });
 const state = await Agents.data('base_agent-tp').get('pilot_state', 'config'); // collection named on the grant
 const keys = await Agents.env('base_agent-tp').keys(); // names only, never values
+// What it serves right now, even with no promoted agent version (activeAgentVersion: null): live skills and tools,
+// the published persona and processors, each with the version id an agent version snapshot would pin, and the
+// live model (live.model; compare with a version's snapshot.model, since a promote applies it).
+const live = await Agents.deployed('base_agent-tp');
 
 const versions = await Agents.versions('base_agent-tp').list();
 const diff = await Agents.versions('base_agent-tp').diff(7, 8);
@@ -64,12 +75,14 @@ await Agents.workflows('base_agent-tp').push('wf_123', definition); // the body
 // A workflow the target does not have yet: create it (inert), push, then deploy with expectActive: null.
 // const { workflowId } = await Agents.workflows('base_agent-tp').create('nightly-digest');
 await Agents.workflows('base_agent-tp').deploy('wf_123', '1.4.0', { expectActive: wf.activeVersionId });
+// Optionally name the source commit the version was built from: deploy(wf, v, { expectActive, commitHash? })
 
 // Clean up: only a superseded version can be deleted.
 await Agents.versions('base_agent-tp').delete(5);
 ```
 
 - A workflow deploy also records a new active agent version. Read `versions.list` again before a later `promote`.
+- `commitHash` on `workflows.deploy` is optional and forwarded unchanged. A call without it behaves as before, and the platform may fill it from the Job workspace.
 
 ### Platform switches
 
@@ -81,13 +94,14 @@ await Agents.versions('base_agent-tp').delete(5);
 
 ### What a supervisor can and cannot see
 
-| Surface | What is returned                                                                                                                                                                                                            |
-| ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Logs    | Timestamp, level, log source and primitive or tool name. No user ids. The window is at most 7 days and at most 100 rows. The message (truncated to 2,000 characters) is included only with `observe-content`.               |
-| Runs    | Metadata only: id, workflow, status, reason, trigger and times. No inputs or outputs.                                                                                                                                       |
-| Data    | Read-only. Only the collections the org admin named on the grant (`dataCollections`).                                                                                                                                       |
-| Env     | Variable names only.                                                                                                                                                                                                        |
-| Source  | The files in the target's source backup, each up to 512 KB. Backup exclusions and credential-like paths are never listed or returned: dotfiles, `.env*`, `*.pem`, `*.key`, `id_rsa*`, `.npmrc`, `credentials*`, `*secret*`. |
+| Surface  | What is returned                                                                                                                                                                                                            |
+| -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Logs     | Timestamp, level, log source and primitive or tool name. No user ids. The window is at most 7 days and at most 100 rows. The message (truncated to 2,000 characters) is included only with `observe-content`.               |
+| Runs     | Metadata only: id, workflow, status, reason, trigger and times. No inputs or outputs.                                                                                                                                       |
+| Data     | Read-only. Only the collections the org admin named on the grant (`dataCollections`).                                                                                                                                       |
+| Env      | Variable names only.                                                                                                                                                                                                        |
+| Deployed | Live skills (tool names, bundle hashes, whether source is attached), the published persona (id, version, content hash) and processors, with version ids. No code, tool source or persona text.                              |
+| Source   | The files in the target's source backup, each up to 512 KB. Backup exclusions and credential-like paths are never listed or returned: dotfiles, `.env*`, `*.pem`, `*.key`, `id_rsa*`, `.npmrc`, `credentials*`, `*secret*`. |
 
 ### Guarantees
 
@@ -102,7 +116,7 @@ await Agents.versions('base_agent-tp').delete(5);
 
 - **Read members** call the developer API with **your** credential and mirror the projections above: env keys only, and logs without user ids or message bodies.
 - **Refused offline:** `versions.promote`, `persona.activate`, `versions.delete`, `workflows.create`, `workflows.push`, `workflows.deploy`, `versions.preview` and `data`. A local test never changes a live agent, and readable collections live on the grant.
-- **Not available offline:** `Agents.list`, `Agents.get` and `source.get`.
+- **Not available offline:** `Agents.list`, `Agents.get`, `source.get` and `Agents.deployed` (`supervision_offline_unsupported`).
 
 ### Errors
 

package/docs/api/Baskets.md

@@ -32,10 +32,13 @@ The Baskets API enables:
 enum BasketStatus {
   ACTIVE = 'active',
   CHECKED_OUT = 'checked_out',
-  ABANDONED = 'abandoned'
+  ABANDONED = 'abandoned',
+  EXPIRED = 'expired'
 }
 ```
 
+`Baskets.get(status)` and `basket.updateStatus(status)` reject any other value (including a different letter case) with HTTP 400 `Invalid basket status '<value>'. Allowed: active, checked_out, abandoned, expired`, before anything is read or persisted. A missing basket is HTTP 404 and a failure inside the commerce service is a generic HTTP 500 (503 when it is unreachable). The SDK surfaces each as a thrown `Error`; there is no `success: false` body to branch on.
+
 ## BasketInstance Methods
 
 Once you have a basket instance, you can call these methods:
@@ -112,6 +115,13 @@ Updates the basket's status.
 
 **Returns:** `Promise<Basket>` - Updated basket data
 
+**Errors:**
+- An unknown status is rejected with HTTP 400 `Invalid basket status '<value>'. Allowed: active, checked_out, abandoned, expired`; nothing is persisted.
+- A missing basket is HTTP 404.
+- A failure inside the commerce service is a generic HTTP 500 (503 when the commerce service itself is down or unreachable).
+
+The SDK surfaces each of these as a thrown `Error`; there is no `success: false` body to branch on.
+
 **Example:**
 ```typescript
 await basket.updateStatus(BasketStatus.ABANDONED);

package/docs/api/LuaJob.md

@@ -11,6 +11,7 @@ import { LuaJob } from 'lua-cli';
 ## Overview
 
 Jobs enable:
+
 - Schedule tasks with cron expressions
 - Run one-time tasks at specific times
 - Execute tasks at fixed intervals
@@ -76,6 +77,7 @@ interface LuaJobConfig {
 ```
 
 **Cron Expression Format:**
+
 ```
 ┌───────────── minute (0 - 59)
 │ ┌───────────── hour (0 - 23)
@@ -87,6 +89,7 @@ interface LuaJobConfig {
 ```
 
 **Examples:**
+
 - `'0 9 * * *'` - Every day at 9:00 AM
 - `'0 */6 * * *'` - Every 6 hours
 - `'0 9 * * 1'` - Every Monday at 9:00 AM
@@ -131,6 +134,8 @@ interface JobInstance {
 }
 ```
 
+> **`user.send()` from a job.** `user.send()` returns a boolean and never throws: `false` means the message was not delivered, and a bare `try/catch` never fires. Check the result (log it, or retry). It goes to the user's last-interaction channel; for a webchat-only user it lands in the user's base conversation thread and is pushed live to the widget, not into a specific workspace conversation. See [`user.send`](./User.md#usersendmessages) for the targeting rules.
+
 ## Complete Examples
 
 ### Daily Cleanup Job
@@ -144,19 +149,19 @@ export const dailyCleanup = new LuaJob({
 
   schedule: {
     type: 'cron',
-    expression: '0 2 * * *',  // 2 AM every day
-    timezone: 'America/New_York'
+    expression: '0 2 * * *', // 2 AM every day
+    timezone: 'America/New_York',
   },
 
-  timeout: 600,  // 10 minutes
+  timeout: 600, // 10 minutes
 
   retry: {
     maxAttempts: 3,
-    backoffSeconds: 60
+    backoffSeconds: 60,
   },
 
   metadata: {
-    retentionDays: 30
+    retentionDays: 30,
   },
 
   execute: async (job) => {
@@ -180,15 +185,15 @@ export const dailyCleanup = new LuaJob({
     await job.updateMetadata({
       lastRun: new Date().toISOString(),
       deletedCount,
-      nextRetentionCheck: new Date(cutoffDate).toISOString()
+      nextRetentionCheck: new Date(cutoffDate).toISOString(),
     });
 
     return {
       success: true,
       deletedCount,
-      retentionDays
+      retentionDays,
     };
-  }
+  },
 });
 ```
 
@@ -203,8 +208,8 @@ export const weeklyReport = new LuaJob({
 
   schedule: {
     type: 'cron',
-    expression: '0 9 * * 1',  // Every Monday at 9 AM
-    timezone: 'UTC'
+    expression: '0 9 * * 1', // Every Monday at 9 AM
+    timezone: 'UTC',
   },
 
   execute: async (job) => {
@@ -215,30 +220,32 @@ export const weeklyReport = new LuaJob({
     const weekAgo = new Date();
     weekAgo.setDate(weekAgo.getDate() - 7);
 
-    const recentActivities = activities.filter(a =>
-      new Date(a.data.timestamp) > weekAgo
-    );
+    const recentActivities = activities.filter((a) => new Date(a.data.timestamp) > weekAgo);
 
     // Generate AI summary
-    const summary = await AI.generate(
-      'Summarize this week\'s activity in 2-3 bullet points.',
-      [{
+    const summary = await AI.generate("Summarize this week's activity in 2-3 bullet points.", [
+      {
         type: 'text',
-        text: JSON.stringify(recentActivities.map(a => a.data))
-      }]
-    );
+        text: JSON.stringify(recentActivities.map((a) => a.data)),
+      },
+    ]);
 
-    // Send report to user
-    await user.send([{
-      type: 'text',
-      text: `📊 Weekly Activity Report\n\n${summary}\n\nTotal activities: ${recentActivities.length}`
-    }]);
+    // Send report to user. user.send() never throws: check the boolean result.
+    const delivered = await user.send([
+      {
+        type: 'text',
+        text: `📊 Weekly Activity Report\n\n${summary}\n\nTotal activities: ${recentActivities.length}`,
+      },
+    ]);
+    if (!delivered) {
+      console.warn('Weekly report was not delivered');
+    }
 
     return {
-      success: true,
-      activitiesCount: recentActivities.length
+      success: delivered,
+      activitiesCount: recentActivities.length,
     };
-  }
+  },
 });
 ```
 
@@ -253,16 +260,16 @@ export const healthCheck = new LuaJob({
 
   schedule: {
     type: 'interval',
-    seconds: 300  // Every 5 minutes
+    seconds: 300, // Every 5 minutes
   },
 
-  timeout: 30,  // 30 seconds
+  timeout: 30, // 30 seconds
 
   execute: async (job) => {
     const checks = {
       database: false,
       api: false,
-      storage: false
+      storage: false,
     };
 
     // Check database
@@ -285,37 +292,42 @@ export const healthCheck = new LuaJob({
     try {
       await Data.create('health_check', {
         timestamp: new Date().toISOString(),
-        status: 'ok'
+        status: 'ok',
       });
       checks.storage = true;
     } catch (error) {
       console.error('Storage check failed:', error);
     }
 
-    const allHealthy = Object.values(checks).every(c => c);
+    const allHealthy = Object.values(checks).every((c) => c);
 
     // Log health status
     await Data.create('health_logs', {
       timestamp: new Date().toISOString(),
       checks,
-      healthy: allHealthy
+      healthy: allHealthy,
     });
 
     // Alert if unhealthy
     if (!allHealthy) {
       const user = await job.user();
-      await user.send([{
-        type: 'text',
-        text: `⚠️ System health check failed!\n${JSON.stringify(checks, null, 2)}`
-      }]);
+      const alerted = await user.send([
+        {
+          type: 'text',
+          text: `⚠️ System health check failed!\n${JSON.stringify(checks, null, 2)}`,
+        },
+      ]);
+      if (!alerted) {
+        console.warn('Health alert was not delivered');
+      }
     }
 
     return {
       success: true,
       healthy: allHealthy,
-      checks
+      checks,
     };
-  }
+  },
 });
 ```
 
@@ -330,7 +342,7 @@ export const birthdayReminder = new LuaJob({
 
   schedule: {
     type: 'cron',
-    expression: '0 9 * * *',  // Every day at 9 AM
+    expression: '0 9 * * *', // Every day at 9 AM
   },
 
   execute: async (job) => {
@@ -352,21 +364,27 @@ export const birthdayReminder = new LuaJob({
       if (birthdayStr === todayStr) {
         // Send birthday message
         const user = await User.get(userEntry.data.userId);
-        await user.send([{
-          type: 'text',
-          text: `🎉 Happy Birthday, ${userEntry.data.name}! Wishing you an amazing day!`
-        }]);
-
-        remindersSent++;
+        const sent = await user.send([
+          {
+            type: 'text',
+            text: `🎉 Happy Birthday, ${userEntry.data.name}! Wishing you an amazing day!`,
+          },
+        ]);
+
+        if (sent) {
+          remindersSent++;
+        } else {
+          console.warn(`Birthday message not delivered to ${userEntry.data.userId}`);
+        }
       }
     }
 
     return {
       success: true,
       remindersSent,
-      date: today.toISOString()
+      date: today.toISOString(),
     };
-  }
+  },
 });
 ```
 
@@ -382,17 +400,17 @@ export const dataSyncJob = new LuaJob({
 
   schedule: {
     type: 'interval',
-    seconds: 3600  // Every hour
+    seconds: 3600, // Every hour
   },
 
   retry: {
     maxAttempts: 5,
-    backoffSeconds: 300  // 5 minutes
+    backoffSeconds: 300, // 5 minutes
   },
 
   metadata: {
     lastSyncId: null,
-    totalSynced: 0
+    totalSynced: 0,
   },
 
   execute: async (job) => {
@@ -402,8 +420,8 @@ export const dataSyncJob = new LuaJob({
     try {
       // Fetch updates since last sync
       const response = await axios.get(`${apiUrl}/updates`, {
-        headers: { 'Authorization': `Bearer ${apiKey}` },
-        params: { since: job.metadata.lastSyncId }
+        headers: { Authorization: `Bearer ${apiKey}` },
+        params: { since: job.metadata.lastSyncId },
       });
 
       const updates = response.data;
@@ -414,7 +432,7 @@ export const dataSyncJob = new LuaJob({
         await Data.create('synced_data', {
           externalId: update.id,
           data: update.data,
-          syncedAt: new Date().toISOString()
+          syncedAt: new Date().toISOString(),
         });
         syncedCount++;
       }
@@ -424,19 +442,19 @@ export const dataSyncJob = new LuaJob({
       await job.updateMetadata({
         lastSyncId: lastId,
         totalSynced: job.metadata.totalSynced + syncedCount,
-        lastSyncAt: new Date().toISOString()
+        lastSyncAt: new Date().toISOString(),
       });
 
       return {
         success: true,
         syncedCount,
-        lastId
+        lastId,
       };
     } catch (error) {
       console.error('Sync failed:', error);
-      throw error;  // Will trigger retry
+      throw error; // Will trigger retry
     }
-  }
+  },
 });
 ```
 
@@ -451,30 +469,37 @@ export const sendWelcomeEmail = new LuaJob({
 
   schedule: {
     type: 'once',
-    executeAt: new Date(Date.now() + 3600000)  // 1 hour from now
+    executeAt: new Date(Date.now() + 3600000), // 1 hour from now
   },
 
   metadata: {
     userId: 'user_123',
-    userName: 'John Doe'
+    userName: 'John Doe',
   },
 
   execute: async (job) => {
     const user = await User.get(job.metadata.userId);
 
-    await user.send([{
-      type: 'text',
-      text: `Welcome to our platform, ${job.metadata.userName}! 🎉\n\nWe're excited to have you here. Here are some things you can do:\n\n• Explore our features\n• Complete your profile\n• Connect with the community\n\nIf you have any questions, just ask!`
-    }]);
+    const delivered = await user.send([
+      {
+        type: 'text',
+        text: `Welcome to our platform, ${job.metadata.userName}! 🎉\n\nWe're excited to have you here. Here are some things you can do:\n\n• Explore our features\n• Complete your profile\n• Connect with the community\n\nIf you have any questions, just ask!`,
+      },
+    ]);
+
+    if (!delivered) {
+      // Keep the job so it can be retried instead of losing the welcome message
+      return { success: false, userId: job.metadata.userId };
+    }
 
     // Delete job after execution (one-time only)
     await job.delete();
 
     return {
       success: true,
-      userId: job.metadata.userId
+      userId: job.metadata.userId,
     };
-  }
+  },
 });
 ```
 
@@ -505,34 +530,34 @@ export const sendWelcomeEmail = new LuaJob({
 
 ```typescript
 // Every minute
-'* * * * *'
+'* * * * *';
 
 // Every 5 minutes
-'*/5 * * * *'
+'*/5 * * * *';
 
 // Every hour at minute 0
-'0 * * * *'
+'0 * * * *';
 
 // Every day at midnight
-'0 0 * * *'
+'0 0 * * *';
 
 // Every day at 3:30 PM
-'30 15 * * *'
+'30 15 * * *';
 
 // Every Monday at 9 AM
-'0 9 * * 1'
+'0 9 * * 1';
 
 // Every weekday at 6 PM
-'0 18 * * 1-5'
+'0 18 * * 1-5';
 
 // First day of every month
-'0 0 1 * *'
+'0 0 1 * *';
 
 // Last day of every month (not directly supported, use workaround)
-'0 0 28-31 * *'
+'0 0 28-31 * *';
 
 // Every 6 hours
-'0 */6 * * *'
+'0 */6 * * *';
 ```
 
 ## Error Handling
@@ -544,12 +569,12 @@ export const robustJob = new LuaJob({
 
   schedule: {
     type: 'cron',
-    expression: '0 * * * *'  // Every hour
+    expression: '0 * * * *', // Every hour
   },
 
   retry: {
     maxAttempts: 3,
-    backoffSeconds: 60
+    backoffSeconds: 60,
   },
 
   execute: async (job) => {
@@ -560,12 +585,12 @@ export const robustJob = new LuaJob({
       // Update success metadata
       await job.updateMetadata({
         lastSuccess: new Date().toISOString(),
-        consecutiveFailures: 0
+        consecutiveFailures: 0,
       });
 
       return {
         success: true,
-        result
+        result,
       };
     } catch (error) {
       // Track failures
@@ -573,21 +598,26 @@ export const robustJob = new LuaJob({
       await job.updateMetadata({
         lastFailure: new Date().toISOString(),
         lastError: error.message,
-        consecutiveFailures: failures
+        consecutiveFailures: failures,
       });
 
       // Alert after 3 consecutive failures
       if (failures >= 3) {
         const user = await job.user();
-        await user.send([{
-          type: 'text',
-          text: `⚠️ Job "${job.metadata.name}" has failed 3 times in a row. Last error: ${error.message}`
-        }]);
+        const alerted = await user.send([
+          {
+            type: 'text',
+            text: `⚠️ Job "${job.metadata.name}" has failed 3 times in a row. Last error: ${error.message}`,
+          },
+        ]);
+        if (!alerted) {
+          console.warn('Failure alert was not delivered');
+        }
       }
 
-      throw error;  // Re-throw to trigger retry
+      throw error; // Re-throw to trigger retry
     }
-  }
+  },
 });
 ```