lua-cli 3.42.0 → 3.44.0

package/docs/api/User.md

@@ -11,6 +11,7 @@ import { User } from 'lua-cli';
 ## Overview
 
 The User API allows you to:
+
 - Retrieve user profile data
 - Update user information
 - Send messages to users
@@ -24,11 +25,13 @@ The User API allows you to:
 Retrieves user data by userId, email, or phone.
 
 **Signature:**
+
 ```typescript
 async get(identifier?: string | UserLookupOptions): Promise<UserDataInstance | null>
 ```
 
 **Parameters:**
+
 - `identifier` (optional) - One of:
   - No parameter: Returns current user's data (in tools with conversation context)
   - `string`: User ID to retrieve
@@ -65,6 +68,7 @@ console.log(specificUser.email);
 ```
 
 **Use Cases:**
+
 - Fetch data for specific users in admin tools
 - Access user information in webhooks/jobs
 - Multi-user data operations
@@ -75,6 +79,7 @@ console.log(specificUser.email);
 Look up a user by email or phone number. This is particularly useful in webhooks where you don't have the user ID but know the user's contact information.
 
 **Signature:**
+
 ```typescript
 async get(options: { email?: string; phone?: string }): Promise<UserDataInstance | null>
 ```
@@ -104,6 +109,7 @@ if (!user) {
 ```
 
 **Use Cases:**
+
 - Webhooks that receive user email/phone from external systems
 - Admin tools where operators search by contact info
 - Integration with third-party systems that don't have Lua user IDs
@@ -113,6 +119,7 @@ if (!user) {
 Gets the conversation history for the current user.
 
 **Signature:**
+
 ```typescript
 async getChatHistory(): Promise<ChatHistoryMessage[]>
 ```
@@ -120,6 +127,7 @@ async getChatHistory(): Promise<ChatHistoryMessage[]>
 **Returns:** Array of chat messages
 
 **Example:**
+
 ```typescript
 const history = await User.getChatHistory();
 
@@ -155,17 +163,20 @@ user.data.email = 'new@email.com';
 Starting in v3.1.0, the user object includes a read-only `_luaProfile` property that provides secure access to core user identity data.
 
 **Properties:**
+
 - `userId` - The unique user identifier
 - `fullName` - User's full name
 - `mobileNumbers` - Array of mobile numbers
 - `emailAddresses` - Array of email addresses
 
 **Important:**
+
 - `_luaProfile` is **read-only** - attempts to modify it are silently ignored
 - Uses the `_lua` prefix to avoid conflicts with custom `user.profile` fields
 - `user.userId` is deprecated in favor of `user._luaProfile.userId`
 
 **Example:**
+
 ```typescript
 const user = await User.get();
 
@@ -189,11 +200,13 @@ user._luaProfile.userId = 'new-id'; // Silently ignored
 Updates user data.
 
 **Parameters:**
+
 - `data` (object) - Data to update
 
 **Returns:** Promise<object> - Updated user data
 
 **Example:**
+
 ```typescript
 const user = await User.get();
 
@@ -201,11 +214,11 @@ await user.update({
   preferences: {
     theme: 'dark',
     language: 'en',
-    notifications: true
+    notifications: true,
   },
   metadata: {
-    lastActive: new Date().toISOString()
-  }
+    lastActive: new Date().toISOString(),
+  },
 });
 ```
 
@@ -213,33 +226,41 @@ await user.update({
 
 Sends messages to the user.
 
+**Where it lands:** `user.send()` targets the user's last-interaction channel (WhatsApp, Teams, SMS and so on). For a user who only chats on webchat, it writes the message to the user's base conversation thread (the `${userId}-${agentId}` root thread) and pushes it live to the webchat widget. It does **not** target a specific workspace conversation; there is no conversation or thread option.
+
 **Parameters:**
+
 - `messages` (ChatMessage[]) - Array of messages to send
 
-**Returns:** Promise<boolean> - `true` only when the platform confirmed delivery, `false` otherwise (including an unconfirmed result). It never throws, so check the result instead of using try/catch.
+**Returns:** Promise<boolean> - `true` only when the platform confirmed delivery, `false` otherwise (including an unconfirmed result). It never throws, so a bare `try/catch` never fires: check the result instead (in a job, log it or retry on `false`). For a message that must be seen with certainty, use `User.Inbox.push`, which is receipted.
 
 **Example:**
+
 ```typescript
 const user = await User.get();
 
 // Send text message
-await user.send([{
-  type: 'text',
-  text: 'Hello! Your order has shipped.'
-}]);
+await user.send([
+  {
+    type: 'text',
+    text: 'Hello! Your order has shipped.',
+  },
+]);
 
 // Send image
-await user.send([{
-  type: 'image',
-  imageUrl: 'https://example.com/product.jpg',
-  altText: 'Product image'
-}]);
+await user.send([
+  {
+    type: 'image',
+    imageUrl: 'https://example.com/product.jpg',
+    altText: 'Product image',
+  },
+]);
 
 // Send multiple messages
 await user.send([
   { type: 'text', text: 'Your order summary:' },
   { type: 'text', text: '- Item 1: $10' },
-  { type: 'text', text: 'Total: $10' }
+  { type: 'text', text: 'Total: $10' },
 ]);
 ```
 
@@ -250,6 +271,7 @@ Clears all user data.
 **Returns:** `Promise<{ success: boolean }>` - `{ success: true }` once the data is cleared. Throws if the clear fails.
 
 **Example:**
+
 ```typescript
 const user = await User.get();
 await user.clear();
@@ -262,6 +284,7 @@ Saves current user data state.
 **Returns:** Promise<boolean>
 
 **Example:**
+
 ```typescript
 const user = await User.get();
 user.data.lastLogin = new Date().toISOString();
@@ -275,12 +298,13 @@ Gets chat history for this user.
 **Returns:** Promise<ChatHistoryMessage[]>
 
 **Example:**
+
 ```typescript
 const user = await User.get();
 const history = await user.getChatHistory();
 
 // Analyze conversation
-const userMessages = history.filter(m => m.role === 'user');
+const userMessages = history.filter((m) => m.role === 'user');
 console.log(`User sent ${userMessages.length} messages`);
 ```
 
@@ -295,32 +319,32 @@ import { z } from 'zod';
 export default class UpdatePreferencesTool implements LuaTool {
   name = 'update_preferences';
   description = 'Update user preferences';
-  
+
   inputSchema = z.object({
     theme: z.enum(['light', 'dark']).optional(),
     language: z.string().optional(),
-    notifications: z.boolean().optional()
+    notifications: z.boolean().optional(),
   });
-  
+
   async execute(input: z.infer<typeof this.inputSchema>) {
     const user = await User.get();
-    
+
     // Get current preferences
     const currentPrefs = user.data.preferences || {};
-    
+
     // Merge with new preferences
     const newPrefs = {
       ...currentPrefs,
-      ...input
+      ...input,
     };
-    
+
     // Update
     await user.update({ preferences: newPrefs });
-    
+
     return {
       success: true,
       message: 'Preferences updated',
-      preferences: newPrefs
+      preferences: newPrefs,
     };
   }
 }
@@ -335,36 +359,38 @@ import { z } from 'zod';
 export default class NotifyUserTool implements LuaTool {
   name = 'notify_user';
   description = 'Send a notification to the user';
-  
+
   inputSchema = z.object({
     title: z.string(),
     message: z.string(),
-    urgent: z.boolean().optional()
+    urgent: z.boolean().optional(),
   });
-  
+
   async execute(input: z.infer<typeof this.inputSchema>) {
     const user = await User.get();
-    
+
     const prefix = input.urgent ? '🚨 URGENT: ' : '📬 ';
     const fullMessage = `${prefix}${input.title}\n\n${input.message}`;
-    
-    await user.send([{
-      type: 'text',
-      text: fullMessage
-    }]);
-    
+
+    await user.send([
+      {
+        type: 'text',
+        text: fullMessage,
+      },
+    ]);
+
     // Log the notification
     await user.update({
       lastNotification: {
         title: input.title,
         sentAt: new Date().toISOString(),
-        urgent: input.urgent || false
-      }
+        urgent: input.urgent || false,
+      },
     });
-    
+
     return {
       success: true,
-      message: 'Notification sent'
+      message: 'Notification sent',
     };
   }
 }
@@ -379,35 +405,31 @@ import { z } from 'zod';
 export default class ChatAnalyticsTool implements LuaTool {
   name = 'analyze_conversation';
   description = 'Analyze the conversation history';
-  
+
   inputSchema = z.object({});
-  
+
   async execute(input: z.infer<typeof this.inputSchema>) {
     const history = await User.getChatHistory();
-    
+
     const stats = {
       totalMessages: history.length,
-      userMessages: history.filter(m => m.role === 'user').length,
-      assistantMessages: history.filter(m => m.role === 'assistant').length,
+      userMessages: history.filter((m) => m.role === 'user').length,
+      assistantMessages: history.filter((m) => m.role === 'assistant').length,
       averageLength: 0,
-      topics: [] as string[]
+      topics: [] as string[],
     };
-    
+
     // Calculate average message length
-    const lengths = history.map(m => 
-      m.content.reduce((sum, c) => sum + (c.text?.length || 0), 0)
-    );
-    stats.averageLength = Math.round(
-      lengths.reduce((a, b) => a + b, 0) / lengths.length
-    );
-    
+    const lengths = history.map((m) => m.content.reduce((sum, c) => sum + (c.text?.length || 0), 0));
+    stats.averageLength = Math.round(lengths.reduce((a, b) => a + b, 0) / lengths.length);
+
     return {
       success: true,
       analytics: stats,
-      recentMessages: history.slice(-5).map(m => ({
+      recentMessages: history.slice(-5).map((m) => ({
         role: m.role,
-        preview: m.content[0]?.text?.substring(0, 50) + '...'
-      }))
+        preview: m.content[0]?.text?.substring(0, 50) + '...',
+      })),
     };
   }
 }
@@ -416,6 +438,7 @@ export default class ChatAnalyticsTool implements LuaTool {
 ## Message Types
 
 ### Text Message
+
 ```typescript
 {
   type: 'text',
@@ -424,6 +447,7 @@ export default class ChatAnalyticsTool implements LuaTool {
 ```
 
 ### Image Message
+
 ```typescript
 {
   type: 'image',
@@ -433,6 +457,7 @@ export default class ChatAnalyticsTool implements LuaTool {
 ```
 
 ### File Message
+
 ```typescript
 {
   type: 'file',
@@ -445,12 +470,14 @@ export default class ChatAnalyticsTool implements LuaTool {
 ## Best Practices
 
 ### ✅ DO
+
 - Always handle missing user data gracefully
 - Use `user.update()` instead of modifying and saving separately
 - Check if data exists before accessing nested properties
 - Send clear, actionable messages to users
 
 ### ❌ DON'T
+
 - Don't assume user data structure
 - Don't modify user data without validation
 - Don't send empty or malformed messages
@@ -479,7 +506,7 @@ const user = await User.get();
 await user.update({
   name: 'John Doe',
   email: 'john@example.com',
-  preferences: { theme: 'dark' }
+  preferences: { theme: 'dark' },
 });
 
 // ❌ Multiple separate updates (slower)
@@ -492,16 +519,20 @@ await user.update({ preferences: { theme: 'dark' } });
 
 ```typescript
 // ✅ Clear, formatted message
-await user.send([{
-  type: 'text',
-  text: `Order Confirmation\n\nOrder ID: ${orderId}\nTotal: $${total}\n\nThank you for your order!`
-}]);
+await user.send([
+  {
+    type: 'text',
+    text: `Order Confirmation\n\nOrder ID: ${orderId}\nTotal: $${total}\n\nThank you for your order!`,
+  },
+]);
 
 // ❌ Unformatted dump
-await user.send([{
-  type: 'text',
-  text: JSON.stringify(orderData)
-}]);
+await user.send([
+  {
+    type: 'text',
+    text: JSON.stringify(orderData),
+  },
+]);
 ```
 
 ## Webhook Example: User Lookup by Phone
@@ -514,30 +545,30 @@ import { LuaWebhook, User } from 'lua-cli';
 export default new LuaWebhook({
   name: 'update-routing-preference',
   description: 'Update user routing preference by phone number',
-  
+
   execute: async (event) => {
     const { phone, routingEnabled } = event.body;
-    
+
     if (!phone) {
       return { error: 'Phone number is required' };
     }
-    
+
     // Look up user by phone
     const user = await User.get({ phone });
     if (!user) {
       return { error: 'User not found' };
     }
-    
+
     // Update routing preference
     user.routingEnabled = routingEnabled;
     await user.save();
-    
-    return { 
-      success: true, 
+
+    return {
+      success: true,
       userId: user._luaProfile.userId,
-      routingEnabled 
+      routingEnabled,
     };
-  }
+  },
 });
 ```
 
@@ -564,4 +595,3 @@ interface UserLookupOptions {
 
 - [User Data Tool Example](../../template/src/skills/tools/UserDataTool.ts)
 - [Notification Patterns](../guides/NotificationPatterns.md)
-

package/docs/workflows/workspaces-and-long-steps.md

@@ -8,7 +8,7 @@ _Source of truth: workflows-spec 05 §5.17 (D19-r1/r2). This page is the develop
 
 `workspace` on `createWorkflow` declares the checkout: `{ kind:'git', repo, ref, credentialsRef, sizeGb?, verify? }` or `{ kind:'empty' }`. Steps mount it with `workspace: { mount: 'rw'|'ro', isolation?: 'worktree' }` and read `ctx.workspace = { root, mount, branch, headSha, isolation, baseSha?, arm?, backend? }` — `root` is the absolute directory of the checkout (`/workspace`); `baseSha` is the commit the run's base ref resolved to at provision (`headSha` is where this step's checkout is), `arm` the worktree arm id under `isolation:'worktree'`, `backend` the volume backend — the three are present when the pod hands the run's stamps to the step and absent otherwise (an `empty` workspace, a shared mount). The pre-3.33 name `path` is served by the Job pod as a deprecated alias for one minor (it warns once per step) and then removed; new code reads `root`.
 
-`ttlHours` is how long a released or held volume is kept before it expires: 72 h by default, 24 h for a completed `keepArtefacts` volume. The platform has a **168 h** ceiling on it, a platform setting that applies once the platform enables it: a larger value is then refused at `lua push` with `workspace-ttl-exceeds-cap` (a non-positive or non-numeric one with `workspace-ttl-invalid`) and held volumes are clamped to 168 h. Until then `lua compile` does not check it, so do not rely on a long hold.
+`ttlHours` is how long a released or held volume is kept before it expires: 72 h by default, 24 h for a completed `keepArtefacts` volume. The platform has a **168 h** ceiling on it, a platform setting that applies once the platform enables it: a larger value is then refused at `lua push` — and likewise at compose and dynamic-definition validation — with `workspace-ttl-exceeds-cap` (a non-positive or non-numeric one with `workspace-ttl-invalid`) and held volumes are clamped to 168 h. Until then `lua compile` does not check it, so do not rely on a long hold.
 
 `credentialsRef` is a connection id **or a key you declare under `connections: [{ key, integrationType }]`** — declare a key; it resolves against the owner agent's own connections on any agent at run time (see [Git credentials](./git-credentials.md)), so the definition never freezes a production id.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lua-cli",
-  "version": "3.42.0",
+  "version": "3.44.0",
   "description": "Build, test, and deploy AI agents with custom tools, webhooks, and scheduled jobs. Features LuaAgent unified configuration, streaming chat, and batch deployment.",
   "readmeFilename": "README.md",
   "main": "dist/api-exports.js",
@@ -114,11 +114,11 @@
     "stripe": "^19.2.0",
     "ts-node": "^10.9.2",
     "tsup": "^8.5.1",
+    "@lua/sandbox-runtime": "0.0.1",
     "@lua/shared-sandbox": "0.0.1",
-    "@lua/shared-types": "0.0.1",
     "@lua/shared-source-sync": "0.0.1",
-    "@lua/workflow-graph": "0.0.1",
-    "@lua/sandbox-runtime": "0.0.1"
+    "@lua/shared-types": "0.0.1",
+    "@lua/workflow-graph": "0.0.1"
   },
   "scripts": {
     "clean": "rm -rf dist temp",

package/template/examples/postprocessors/modifyResponse.ts

@@ -1,16 +1,17 @@
-import { PostProcessor, UserDataInstance } from 'lua-cli';
+import { PostProcessor, UserDataInstance, PostProcessorMessage, messageText } from 'lua-cli';
 
 const modifyResponsePostProcessor = new PostProcessor({
   name: 'modify-response',
   description: 'Modifies the response to the user',
-  execute: async (user: UserDataInstance, message: string, response: string, channel: string) => {
+  execute: async (user: UserDataInstance, message: PostProcessorMessage, response: string, channel: string) => {
+    // `message` is a string or the message's parts; messageText() gives its text either way.
     console.log('Modify response post processor', user, message, response, channel);
     console.log('User data', await user.data);
     console.log('Message', message);
     console.log('Response', response);
     console.log('Channel', channel);
     if (response.includes('test')) {
-      return { modifiedResponse: message.toUpperCase() };
+      return { modifiedResponse: messageText(message).toUpperCase() };
     }
     return { modifiedResponse: response };
   },

package/template/package.json

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