lua-cli 3.43.0 → 3.44.0

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
 

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
     }
-  }
+  },
 });
 ```