lua-cli 3.39.4 → 3.41.0

package/docs/API_REFERENCE.md

@@ -9,6 +9,7 @@ Complete reference for all lua-cli runtime APIs available in your tools, webhook
 When your code runs in the Lua platform (either in sandbox or production), you have access to powerful APIs for managing users, products, data, and more. These APIs are injected as globals into the VM execution environment.
 
 **Import APIs in your code:**
+
 ```typescript
 import { User, Products, Data, Jobs, AI } from 'lua-cli';
 ```
@@ -18,6 +19,7 @@ import { User, Products, Data, Jobs, AI } from 'lua-cli';
 ## Table of Contents
 
 ### Core Primitives
+
 - [LuaAgent](#luaagent) - Agent configuration
 - [LuaSkill](#luaskill) - Tool collections
 - [LuaTool](#luatool) - Individual tools
@@ -27,6 +29,7 @@ import { User, Products, Data, Jobs, AI } from 'lua-cli';
 - [PostProcessor](#postprocessor) - Response postprocessing
 
 ### Runtime APIs
+
 - [User API](#user-api) - User data management
 - [Products API](#products-api) - Product catalog
 - [Data API](#data-api) - Custom data storage
@@ -39,6 +42,7 @@ import { User, Products, Data, Jobs, AI } from 'lua-cli';
 - [Channels API](#channels-api) - Outbound channel sends
 
 ### Utilities
+
 - [env()](#env) - Environment variables
 - [Lua Runtime](#lua-runtime) - Request context
 
@@ -80,6 +84,7 @@ import {
 ### Common Patterns
 
 **Create a Tool:**
+
 ```typescript
 import { LuaTool } from 'lua-cli/skill';
 import { z } from 'zod';
@@ -96,6 +101,7 @@ export default class MyTool implements LuaTool {
 ```
 
 **Access User Data:**
+
 ```typescript
 import { User } from 'lua-cli';
 
@@ -105,6 +111,7 @@ await user.send([{ type: 'text', text: 'Hello!' }]);
 ```
 
 **Use Custom Storage:**
+
 ```typescript
 import { Data } from 'lua-cli';
 
@@ -124,6 +131,7 @@ Unified agent configuration that combines skills, webhooks, jobs, and processors
 **Documentation:** [docs/api/LuaAgent.md](./api/LuaAgent.md)
 
 **Quick Example:**
+
 ```typescript
 import { LuaAgent, LuaSkill } from 'lua-cli';
 
@@ -134,7 +142,7 @@ export const agent = new LuaAgent({
   webhooks: [webhook1],
   jobs: [job1],
   preProcessors: [preProcessor1],
-  postProcessors: [postProcessor1]
+  postProcessors: [postProcessor1],
 });
 ```
 
@@ -147,6 +155,7 @@ Group related tools together with shared context.
 **Documentation:** [docs/api/LuaSkill.md](./api/LuaSkill.md)
 
 **Quick Example:**
+
 ```typescript
 import { LuaSkill } from 'lua-cli';
 
@@ -154,7 +163,7 @@ export default new LuaSkill({
   name: 'weather-skill',
   description: 'Weather information tools',
   context: 'Use these tools to get weather data',
-  tools: [tool1, tool2]
+  tools: [tool1, tool2],
 });
 ```
 
@@ -167,6 +176,7 @@ Individual function your agent can call.
 **Documentation:** [docs/api/LuaTool.md](./api/LuaTool.md)
 
 **Quick Example:**
+
 ```typescript
 import { LuaTool } from 'lua-cli/skill';
 import { z } from 'zod';
@@ -176,7 +186,7 @@ export default class GetWeatherTool implements LuaTool {
   description = 'Get current weather';
 
   inputSchema = z.object({
-    city: z.string()
+    city: z.string(),
   });
 
   async execute(input) {
@@ -194,6 +204,7 @@ HTTP endpoint for external integrations.
 **Documentation:** [docs/api/LuaWebhook.md](./api/LuaWebhook.md)
 
 **Quick Example:**
+
 ```typescript
 import { LuaWebhook } from 'lua-cli';
 import { z } from 'zod';
@@ -204,12 +215,12 @@ export default new LuaWebhook({
 
   bodySchema: z.object({
     orderId: z.string(),
-    amount: z.number()
+    amount: z.number(),
   }),
 
   execute: async ({ body, headers, query }) => {
     return { status: 200, body: { received: true } };
-  }
+  },
 });
 ```
 
@@ -222,6 +233,7 @@ Scheduled task that runs automatically.
 **Documentation:** [docs/api/LuaJob.md](./api/LuaJob.md)
 
 **Quick Example:**
+
 ```typescript
 import { LuaJob } from 'lua-cli';
 
@@ -231,12 +243,12 @@ export default new LuaJob({
 
   schedule: {
     type: 'cron',
-    pattern: '0 0 * * *'  // Midnight daily
+    pattern: '0 0 * * *', // Midnight daily
   },
 
   execute: async (job) => {
     return { success: true, deleted: 42 };
-  }
+  },
 });
 ```
 
@@ -249,6 +261,7 @@ Filter or modify messages before they reach your agent.
 **Documentation:** [docs/api/PreProcessor.md](./api/PreProcessor.md)
 
 **Quick Example:**
+
 ```typescript
 import { PreProcessor } from 'lua-cli';
 
@@ -261,7 +274,7 @@ export default new PreProcessor({
       return { action: 'BLOCK' };
     }
     return { action: 'PROCEED' };
-  }
+  },
 });
 ```
 
@@ -274,6 +287,7 @@ Transform or format agent responses.
 **Documentation:** [docs/api/PostProcessor.md](./api/PostProcessor.md)
 
 **Quick Example:**
+
 ```typescript
 import { PostProcessor } from 'lua-cli';
 
@@ -283,7 +297,7 @@ export default new PostProcessor({
 
   execute: async (response) => {
     return response.toUpperCase() + ' 🎉';
-  }
+  },
 });
 ```
 
@@ -298,12 +312,14 @@ Access and manage user data.
 **Documentation:** [docs/api/User.md](./api/User.md)
 
 **Methods:**
+
 - `User.get()` - Get current user
 - `user.update(data)` - Update user data
 - `user.send(messages)` - Send messages to user
 - `user.getChatHistory()` - Get conversation history
 
 **Example:**
+
 ```typescript
 import { User } from 'lua-cli';
 
@@ -314,7 +330,7 @@ await user.update({ preferences: 'dark-mode' });
 
 await user.send([
   { type: 'text', text: 'Hello!' },
-  { type: 'image', url: 'https://example.com/image.jpg' }
+  { type: 'image', url: 'https://example.com/image.jpg' },
 ]);
 
 const history = await user.getChatHistory();
@@ -329,6 +345,7 @@ Manage product catalog.
 **Documentation:** [docs/api/Products.md](./api/Products.md)
 
 **Methods:**
+
 - `Products.get(filter?)` - List products
 - `Products.getById(id)` - Get single product
 - `Products.search(query, filter?)` - Search products
@@ -337,6 +354,7 @@ Manage product catalog.
 - `product.delete()` - Delete product
 
 **Example:**
+
 ```typescript
 import { Products } from 'lua-cli';
 
@@ -346,7 +364,7 @@ const products = await Products.get();
 // Search products
 const results = await Products.search('laptop', {
   category: 'electronics',
-  inStock: true
+  inStock: true,
 });
 
 // Create product
@@ -354,7 +372,7 @@ const product = await Products.create({
   name: 'MacBook Pro',
   price: 2499,
   category: 'electronics',
-  stock: 10
+  stock: 10,
 });
 
 // Update
@@ -373,6 +391,7 @@ Custom data storage with vector search.
 **Documentation:** [docs/api/Data.md](./api/Data.md)
 
 **Methods:**
+
 - `Data.get(collection, filter?)` - List entries
 - `Data.getEntry(collection, id)` - Get single entry
 - `Data.search(collection, query)` - Vector search
@@ -381,6 +400,7 @@ Custom data storage with vector search.
 - `entry.delete()` - Delete entry
 
 **Example:**
+
 ```typescript
 import { Data } from 'lua-cli';
 
@@ -388,7 +408,7 @@ import { Data } from 'lua-cli';
 await Data.create('notes', {
   title: 'Meeting Notes',
   content: 'Discussed Q1 roadmap...',
-  tags: ['meeting', 'planning']
+  tags: ['meeting', 'planning'],
 });
 
 // List
@@ -414,6 +434,7 @@ Shopping cart management.
 **Documentation:** [docs/api/Baskets.md](./api/Baskets.md)
 
 **Methods:**
+
 - `Baskets.get()` - List baskets
 - `Baskets.create()` - Create basket
 - `Baskets.getById(id)` - Get basket
@@ -423,6 +444,7 @@ Shopping cart management.
 - `basket.placeOrder()` - Convert to order
 
 **Example:**
+
 ```typescript
 import { Baskets } from 'lua-cli';
 
@@ -433,7 +455,7 @@ const basket = await Baskets.create();
 await basket.addItem({
   productId: 'prod-123',
   quantity: 2,
-  price: 29.99
+  price: 29.99,
 });
 
 // Place order
@@ -449,6 +471,7 @@ Order management and fulfillment.
 **Documentation:** [docs/api/Orders.md](./api/Orders.md)
 
 **Methods:**
+
 - `Orders.get(filter?)` - List orders
 - `Orders.getById(id)` - Get order
 - `Orders.create(data)` - Create order
@@ -456,6 +479,7 @@ Order management and fulfillment.
 - `order.updateData(data)` - Update order data
 
 **Example:**
+
 ```typescript
 import { Orders } from 'lua-cli';
 
@@ -479,6 +503,7 @@ Create jobs dynamically from tools.
 **Documentation:** [docs/api/Jobs.md](./api/Jobs.md)
 
 **Methods:**
+
 - `Jobs.create(config)` - Create job
 - `Jobs.getJob(jobId)` - Get job
 - `Jobs.getAll()` - List all jobs
@@ -486,6 +511,7 @@ Create jobs dynamically from tools.
 - `job.delete()` - Delete job
 
 **Example:**
+
 ```typescript
 import { Jobs } from 'lua-cli';
 
@@ -495,16 +521,18 @@ const job = await Jobs.create({
   metadata: { message: 'Meeting in 1 hour' },
   schedule: {
     type: 'once',
-    executeAt: new Date(Date.now() + 3600000)
+    executeAt: new Date(Date.now() + 3600000),
   },
   execute: async (job) => {
     const user = await job.user();
-    await user.send([{
-      type: 'text',
-      text: job.metadata.message
-    }]);
+    await user.send([
+      {
+        type: 'text',
+        text: job.metadata.message,
+      },
+    ]);
     return { success: true };
-  }
+  },
 });
 ```
 
@@ -517,15 +545,17 @@ Generate AI text responses.
 **Documentation:** [docs/api/AI.md](./api/AI.md)
 
 **Methods:**
+
 - `AI.generate(prompt, options?)` - Generate text
 
 **Example:**
+
 ```typescript
 import { AI } from 'lua-cli';
 
 const response = await AI.generate('Summarize this text: ...', {
   maxTokens: 100,
-  temperature: 0.7
+  temperature: 0.7,
 });
 
 console.log(response.text);
@@ -540,11 +570,13 @@ Send WhatsApp template messages.
 **Documentation:** [docs/api/Templates.md](./api/Templates.md)
 
 **Methods:**
+
 - `Templates.whatsapp.list()` - List templates
 - `Templates.whatsapp.get(name)` - Get template
 - `Templates.whatsapp.send(config)` - Send template
 
 **Example:**
+
 ```typescript
 import { Templates } from 'lua-cli';
 
@@ -555,8 +587,8 @@ await Templates.whatsapp.send({
   to: '+1234567890',
   parameters: {
     order_id: '12345',
-    amount: '$99.99'
-  }
+    amount: '$99.99',
+  },
 });
 ```
 
@@ -569,16 +601,18 @@ Upload and download files.
 **Documentation:** [docs/api/CDN.md](./api/CDN.md)
 
 **Methods:**
+
 - `CDN.upload(file, options)` - Upload file
 - `CDN.get(fileId)` - Get file URL
 
 **Example:**
+
 ```typescript
 import { CDN } from 'lua-cli';
 
 const result = await CDN.upload(fileBuffer, {
   filename: 'report.pdf',
-  contentType: 'application/pdf'
+  contentType: 'application/pdf',
 });
 
 const url = await CDN.get(result.fileId);
@@ -595,11 +629,13 @@ A successful send with a memory write failure returns `{ delivered: true, persis
 this is HTTP 200 and is never thrown as an error.
 
 **Methods:**
+
 - `Channels.send(input)` - Send a text message on any channel
 - `Channels.whatsapp.sendTemplate(input)` - Send a WhatsApp Business template
 - `Channels.email.send(input)` - Send an email
 
 **Examples:**
+
 ```typescript
 import { Channels } from 'lua-cli';
 
@@ -638,6 +674,7 @@ if (!result.persisted) {
 Access environment variables.
 
 **Usage:**
+
 ```typescript
 import { env } from 'lua-cli';
 
@@ -646,6 +683,7 @@ const baseUrl = env('BASE_URL') || 'https://api.example.com';
 ```
 
 **Setting Environment Variables:**
+
 ```bash
 # Via CLI
 lua env set OPENAI_API_KEY sk-...
@@ -661,6 +699,7 @@ OPENAI_API_KEY=sk-...
 Access request context information.
 
 **Usage:**
+
 ```typescript
 import { Lua } from 'lua-cli';
 
@@ -675,8 +714,31 @@ if (Lua.request.webhook) {
 ```
 
 **Properties:**
+
 - `Lua.request.channel` - Channel type (`'whatsapp'`, `'web'`, `'api'`)
 - `Lua.request.webhook` - Webhook info (if running in webhook)
+- `Lua.request.invokedBy` - Present only when **another agent** created this turn through `Agents.invoke`:
+  `{ agentId, supervisor, scopes, delegatedUserId? }`. Verified by the platform, never caller-supplied.
+  - `supervisor` is true only when an org admin granted the caller `supervision:act` on this agent. Observe, preview and release grants do not set it.
+  - `scopes` lists the caller's supervision scopes on this agent. It is `[]` on version-preview turns.
+  - `delegatedUserId` is set when the caller passed `input.userId`.
+  - The field is absent on user, channel, job, webhook and self-invoked turns, and offline in `lua test`.
+
+**Gating writes on agent invocation.** Treat a turn with `invokedBy` as agent-initiated. A mutating tool should
+refuse it unless `invokedBy.supervisor === true` and the change is in the tool's supervisor allowlist. A
+`delegatedUserId` never grants owner rights. Read it defensively, since older runtimes do not set it:
+
+```typescript
+const invokedBy = (Lua.request as any).invokedBy;
+if (invokedBy && !invokedBy.supervisor) {
+  return { refused: 'agent-invocation-not-authorised' };
+}
+```
+
+A turn created by **another** agent accepts only `messages`/`prompt`, `threadId`, `runtimeContext`, `webhookPayload` and the reasoning `effort`.
+
+- The platform drops every other field: the persona (`systemPrompt`), `model`, tool scoping, version preview, workflow role and billing identities.
+- It also resets a platform channel (`workflow`/`task`/`trigger`) to `agent-invocation`.
 
 ---
 
@@ -686,14 +748,14 @@ if (Lua.request.webhook) {
 
 These are returned by API calls and provide instance methods:
 
-| Instance | Methods | Description |
-|----------|---------|-------------|
-| `UserDataInstance` | `update()`, `send()`, `save()` | User with data access |
-| `ProductInstance` | `update()`, `delete()`, `save()` | Product with CRUD |
-| `BasketInstance` | `addItem()`, `removeItem()`, `placeOrder()` | Shopping cart |
-| `OrderInstance` | `updateStatus()`, `updateData()` | Order management |
-| `DataEntryInstance` | `update()`, `delete()`, `save()` | Custom data entry |
-| `JobInstance` | `user()`, `delete()` | Job with metadata |
+| Instance            | Methods                                     | Description           |
+| ------------------- | ------------------------------------------- | --------------------- |
+| `UserDataInstance`  | `update()`, `send()`, `save()`              | User with data access |
+| `ProductInstance`   | `update()`, `delete()`, `save()`            | Product with CRUD     |
+| `BasketInstance`    | `addItem()`, `removeItem()`, `placeOrder()` | Shopping cart         |
+| `OrderInstance`     | `updateStatus()`, `updateData()`            | Order management      |
+| `DataEntryInstance` | `update()`, `delete()`, `save()`            | Custom data entry     |
+| `JobInstance`       | `user()`, `delete()`                        | Job with metadata     |
 
 ### Enums
 
@@ -703,7 +765,7 @@ enum BasketStatus {
   ACTIVE = 'ACTIVE',
   CHECKED_OUT = 'CHECKED_OUT',
   ABANDONED = 'ABANDONED',
-  EXPIRED = 'EXPIRED'
+  EXPIRED = 'EXPIRED',
 }
 
 // Order status
@@ -711,7 +773,7 @@ enum OrderStatus {
   PENDING = 'PENDING',
   CONFIRMED = 'CONFIRMED',
   FULFILLED = 'FULFILLED',
-  CANCELLED = 'CANCELLED'
+  CANCELLED = 'CANCELLED',
 }
 ```
 
@@ -719,38 +781,42 @@ enum OrderStatus {
 
 ## Complete API Index
 
-| API | Purpose | Key Methods |
-|-----|---------|-------------|
-| [User](./api/User.md) | User data | `get()`, `update()`, `send()` |
-| [Products](./api/Products.md) | Product catalog | `get()`, `search()`, `create()` |
-| [Data](./api/Data.md) | Custom storage | `get()`, `search()`, `create()` |
-| [Baskets](./api/Baskets.md) | Shopping carts | `create()`, `addItem()`, `placeOrder()` |
-| [Orders](./api/Orders.md) | Order management | `get()`, `updateStatus()` |
-| [Jobs](./api/Jobs.md) | Dynamic jobs | `create()`, `getAll()` |
-| [AI](./api/AI.md) | AI generation | `generate()` |
-| [Templates](./api/Templates.md) | WhatsApp templates | `list()`, `send()` |
-| [CDN](./api/CDN.md) | File storage | `upload()`, `get()` |
+| API                             | Purpose            | Key Methods                             |
+| ------------------------------- | ------------------ | --------------------------------------- |
+| [User](./api/User.md)           | User data          | `get()`, `update()`, `send()`           |
+| [Products](./api/Products.md)   | Product catalog    | `get()`, `search()`, `create()`         |
+| [Data](./api/Data.md)           | Custom storage     | `get()`, `search()`, `create()`         |
+| [Baskets](./api/Baskets.md)     | Shopping carts     | `create()`, `addItem()`, `placeOrder()` |
+| [Orders](./api/Orders.md)       | Order management   | `get()`, `updateStatus()`               |
+| [Jobs](./api/Jobs.md)           | Dynamic jobs       | `create()`, `getAll()`                  |
+| [AI](./api/AI.md)               | AI generation      | `generate()`                            |
+| [Templates](./api/Templates.md) | WhatsApp templates | `list()`, `send()`                      |
+| [CDN](./api/CDN.md)             | File storage       | `upload()`, `get()`                     |
 
 ---
 
 ## Usage by Category
 
 ### Building an Agent
+
 1. [LuaAgent](./api/LuaAgent.md) - Configure agent
 2. [LuaSkill](./api/LuaSkill.md) - Organize tools
 3. [LuaTool](./api/LuaTool.md) - Create tools
 
 ### E-commerce
+
 1. [Products API](./api/Products.md) - Manage catalog
 2. [Baskets API](./api/Baskets.md) - Shopping carts
 3. [Orders API](./api/Orders.md) - Process orders
 
 ### Automation
+
 1. [LuaJob](./api/LuaJob.md) - Scheduled tasks
 2. [Jobs API](./api/Jobs.md) - Dynamic jobs
 3. [LuaWebhook](./api/LuaWebhook.md) - HTTP triggers
 
 ### Data Management
+
 1. [User API](./api/User.md) - User data
 2. [Data API](./api/Data.md) - Custom storage
 3. [CDN API](./api/CDN.md) - File storage
@@ -762,6 +828,7 @@ enum OrderStatus {
 ### Error Handling
 
 Always wrap API calls in try-catch:
+
 ```typescript
 try {
   const user = await User.get();
@@ -775,6 +842,7 @@ try {
 ### Type Safety
 
 Use TypeScript types for better IDE support:
+
 ```typescript
 import { UserDataInstance, ProductInstance } from 'lua-cli';
 
@@ -785,6 +853,7 @@ const product: ProductInstance = await Products.getById('prod-123');
 ### Environment Variables
 
 Never hardcode secrets:
+
 ```typescript
 // ❌ Bad
 const apiKey = 'sk-1234567890';
@@ -797,6 +866,7 @@ const apiKey = env('OPENAI_API_KEY');
 ### Async/Await
 
 All API calls are async:
+
 ```typescript
 // ❌ Bad (missing await)
 const user = User.get();