lua-cli 3.53.0 → 3.54.0

package/docs/API_REFERENCE.md

@@ -743,6 +743,29 @@ if (invokedBy && !invokedBy.supervisor) {
 
 A turn created by **another** agent accepts only `messages`/`prompt`, `threadId`, `runtimeContext`, `webhookPayload` and the reasoning `effort`.
 
+**`Lua.identity.assertion({ audience })` — prove the call comes from this agent.** It returns
+`{ token, expiresAt }`: a 60-second, single-use token that Lua signs. The token proves that the call comes from a
+live execution of this agent. Send `token` as the `X-Lua-Agent-Assertion` header on one call to the system named by
+`audience`. Only platform-allowlisted audiences are minted; today that is `'lua-api:staff'`, for an agent enrolled
+as a staff service principal bound to that agent. Mint a fresh token for every call and never reuse one. Older
+runtimes do not have it, so read it defensively:
+
+```typescript
+const assertion = await Lua.identity?.assertion({ audience: 'lua-api:staff' });
+if (!assertion) throw new Error('This runtime cannot prove the agent identity; upgrade lua-cli');
+await fetch(url, { headers: { 'X-Lua-Agent-Assertion': assertion.token /* , ... */ } });
+```
+
+It throws an `AgentIdentityError`. Check `err.code`:
+
+- `agent_identity_requires_live_execution`: thrown outside a live execution, and always in `lua test` /
+  `lua dev`.
+- `agent_identity_audience_not_allowed`: thrown for any audience that is not allowlisted.
+- `agent_identity_input_invalid`: thrown when `audience` is missing.
+- `agent_identity_unavailable`: the platform could not mint a token right now.
+
+Inside a test session it throws a `TestSessionError` with `test_session_tier_unsupported` instead.
+
 - 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`.
 

package/docs/CLI_REFERENCE.md

@@ -410,6 +410,19 @@ $ lua env delete OLD_KEY
 ✅ Deleted OLD_KEY
 ```
 
+**Setting a secret without putting it on the command line (`--stdin`):**
+
+```bash
+printf %s "$STRIPE_SECRET_KEY" | lua env production -k STRIPE_SECRET_KEY --stdin
+lua env production -k STRIPE_SECRET_KEY --stdin < stripe-key.txt
+```
+
+`-k KEY --stdin` reads the value from stdin instead of `-v`, so it never appears in shell history, `ps` output or an
+agent transcript. Exactly one trailing newline (`\n` or `\r\n`) is dropped; everything else is kept. An empty value is
+refused, and so is a terminal stdin (there is no hidden prompt; pipe or redirect the value). `--stdin` cannot be
+combined with `-v`, `--list` or `--delete`. In `sandbox` a value with an inner line break is refused (the `.env` file
+holds one `KEY=value` per line). The value is at most 64 KiB and is never printed.
+
 ---
 
 ### `lua persona`
@@ -766,6 +779,7 @@ With no arguments, prompts for a domain — **Skills** or **Agent templates**
 
 - `create`, `publish`, `view`, `versions` — manage a versioned snapshot of an agent's deployable manifest
 - `install`, `apply`, `status`, `installed`, `uninstall` — install onto one agent, or fleet-apply across many
+- `publish --views a,b` — first-party templates only: ship these views of the source agent (web-app names, in order; the first opens first) with the version. Each is frozen from its deployed version and added to the agent once, when someone hires it. Without `--views` the version ships no views.
 
 **Example:**
 

package/docs/README.md

@@ -1,6 +1,6 @@
-# lua-cli v3.53.0
+# lua-cli v3.54.0
 
-Welcome to the comprehensive API documentation for lua-cli v3.53.0. This guide covers every API, class, and function exported by the package.
+Welcome to the comprehensive API documentation for lua-cli v3.54.0. This guide covers every API, class, and function exported by the package.
 
 ## 📚 Documentation Index
 
@@ -263,7 +263,7 @@ Each API doc includes:
 
 ---
 
-**Version:** 3.53.0
+**Version:** 3.54.0
 **Last Updated:** October 2026
 
 ---

package/docs/api/LuaTool.md

@@ -11,6 +11,7 @@ import { LuaTool } from 'lua-cli/skill';
 ## Overview
 
 Tools are the building blocks of your agent's capabilities. Each tool:
+
 - Has a unique name
 - Describes what it does
 - Validates its inputs with Zod schemas
@@ -21,30 +22,37 @@ Tools are the building blocks of your agent's capabilities. Each tool:
 
 ```typescript
 interface LuaTool<TInput extends ZodType = ZodType> {
-  /** 
+  /**
    * Unique tool name (lowercase, underscores only)
    * Example: 'get_weather', 'create_order'
    */
   name: string;
-  
+
   /**
    * Human-readable description of what the tool does
    * The AI uses this to understand when to call the tool
    */
   description: string;
-  
+
+  /**
+   * Optional text the chat shows while the tool runs and when it is done,
+   * instead of the tool's name. One text, or one for each moment.
+   * {argName} is replaced with that argument's value from the call.
+   */
+  label?: string | { running: string; done: string };
+
   /**
    * Zod schema defining the input structure
    * Validates and type-checks all inputs
    */
   inputSchema: TInput;
-  
+
   /**
    * Optional Zod schema defining the output structure
    * Used for documentation and validation
    */
   outputSchema?: ZodType;
-  
+
   /**
    * The function that executes when the tool is called
    * @param input - Validated input matching inputSchema
@@ -65,19 +73,19 @@ import { z } from 'zod';
 export default class GreetingTool implements LuaTool {
   name = 'greet_user';
   description = 'Generate a personalized greeting';
-  
+
   inputSchema = z.object({
     name: z.string().describe('User name'),
-    language: z.enum(['en', 'es', 'fr']).optional().describe('Language code')
+    language: z.enum(['en', 'es', 'fr']).optional().describe('Language code'),
   });
-  
+
   async execute(input: z.infer<typeof this.inputSchema>) {
     const greetings = {
       en: `Hello, ${input.name}!`,
       es: `¡Hola, ${input.name}!`,
-      fr: `Bonjour, ${input.name}!`
+      fr: `Bonjour, ${input.name}!`,
     };
-    
+
     const lang = input.language || 'en';
     return { greeting: greetings[lang] };
   }
@@ -93,21 +101,21 @@ import { z } from 'zod';
 export default class CalculatorTool implements LuaTool {
   name = 'calculator';
   description = 'Perform mathematical calculations';
-  
+
   inputSchema = z.object({
     operation: z.enum(['add', 'subtract', 'multiply', 'divide']),
     a: z.number(),
-    b: z.number()
+    b: z.number(),
   });
-  
+
   outputSchema = z.object({
     result: z.number(),
-    operation: z.string()
+    operation: z.string(),
   });
-  
+
   async execute(input: z.infer<typeof this.inputSchema>) {
     let result: number;
-    
+
     switch (input.operation) {
       case 'add':
         result = input.a + input.b;
@@ -125,15 +133,45 @@ export default class CalculatorTool implements LuaTool {
         result = input.a / input.b;
         break;
     }
-    
+
     return {
       result,
-      operation: input.operation
+      operation: input.operation,
     };
   }
 }
 ```
 
+### With a Label
+
+While a tool runs, the chat shows the user what is happening. By default it shows the tool's name. Set `label` to show a sentence instead:
+
+```typescript
+import { LuaTool } from 'lua-cli';
+import { z } from 'zod';
+
+export class CreateTicketTool implements LuaTool {
+  name = 'create_ticket';
+  description = "Create a Zendesk ticket when the knowledge base can't help";
+  label = { running: 'Creating a ticket for {subject}', done: 'Created a ticket for {subject}' };
+
+  inputSchema = z.object({ subject: z.string() });
+
+  async execute(input: z.infer<typeof this.inputSchema>) {
+    // ...
+  }
+}
+```
+
+The chat shows "Creating a ticket for "Refund request"…" while the tool runs and "Created a ticket for "Refund request"" when it is done.
+
+- `label` is either one text for both moments (`label = 'Checked stock'`) or `{ running, done }`.
+- `{argName}` is replaced with the value of that argument from the call. Only string and number arguments are filled in.
+- Don't end the text with "…": the chat adds it while the tool runs.
+- Each text must be a string literal in the code (a const holding one works too, `${...}` template values do not) of at most 80 characters. `lua compile` reports an empty or too-long label as an error, and ignores a computed label with a warning.
+
+The same field works with `defineTool({ name, description, label, inputSchema, execute })` and with a plain tool object.
+
 ## Using Runtime APIs
 
 Tools can access Lua platform APIs:
@@ -145,30 +183,30 @@ import { z } from 'zod';
 export default class UserPreferencesTool implements LuaTool {
   name = 'save_user_preferences';
   description = 'Save user preferences for personalization';
-  
+
   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>) {
     // Get current user
     const user = await User.get();
-    
+
     // Update user data
     await user.update({
       preferences: {
         theme: input.theme,
         language: input.language,
-        notifications: input.notifications
-      }
+        notifications: input.notifications,
+      },
     });
-    
+
     return {
       success: true,
       message: 'Preferences saved successfully',
-      preferences: input
+      preferences: input,
     };
   }
 }
@@ -185,40 +223,40 @@ import { env } from 'lua-cli/skill';
 export default class WeatherTool implements LuaTool {
   name = 'get_weather';
   description = 'Get current weather for any city';
-  
+
   inputSchema = z.object({
     city: z.string().describe('City name'),
-    units: z.enum(['metric', 'imperial']).default('metric')
+    units: z.enum(['metric', 'imperial']).default('metric'),
   });
-  
+
   outputSchema = z.object({
     temperature: z.number(),
     condition: z.string(),
     humidity: z.number(),
-    city: z.string()
+    city: z.string(),
   });
-  
+
   async execute(input: z.infer<typeof this.inputSchema>) {
     const apiKey = env('WEATHER_API_KEY');
-    
+
     if (!apiKey) {
       throw new Error('WEATHER_API_KEY not configured');
     }
-    
+
     try {
       const response = await axios.get('https://api.openweathermap.org/data/2.5/weather', {
         params: {
           q: input.city,
           appid: apiKey,
-          units: input.units
-        }
+          units: input.units,
+        },
       });
-      
+
       return {
         temperature: response.data.main.temp,
         condition: response.data.weather[0].main,
         humidity: response.data.main.humidity,
-        city: input.city
+        city: input.city,
       };
     } catch (error) {
       if (axios.isAxiosError(error)) {
@@ -239,36 +277,36 @@ import { z } from 'zod';
 export default class GetProductTool implements LuaTool {
   name = 'get_product';
   description = 'Retrieve a product by ID';
-  
+
   inputSchema = z.object({
-    productId: z.string()
+    productId: z.string(),
   });
-  
+
   async execute(input: z.infer<typeof this.inputSchema>) {
     try {
       const product = await Products.getById(input.productId);
-      
+
       if (!product) {
         return {
           success: false,
           error: 'Product not found',
-          productId: input.productId
+          productId: input.productId,
         };
       }
-      
+
       return {
         success: true,
         product: {
           id: product.id,
           name: product.name,
           price: product.price,
-          stock: product.stock
-        }
+          stock: product.stock,
+        },
       };
     } catch (error) {
       return {
         success: false,
-        error: error instanceof Error ? error.message : 'Unknown error'
+        error: error instanceof Error ? error.message : 'Unknown error',
       };
     }
   }
@@ -284,66 +322,66 @@ import { z } from 'zod';
 export default class GameTool implements LuaTool {
   name = 'play_game';
   description = 'Play a number guessing game';
-  
+
   inputSchema = z.object({
     action: z.enum(['start', 'guess', 'status']),
-    guess: z.number().min(1).max(100).optional()
+    guess: z.number().min(1).max(100).optional(),
   });
-  
+
   async execute(input: z.infer<typeof this.inputSchema>) {
     // Use Data API to persist game state
     const games = await Data.get('games');
     let gameState = games.length > 0 ? games[0].data : null;
-    
+
     if (input.action === 'start') {
       // Start new game
       const secretNumber = Math.floor(Math.random() * 100) + 1;
       gameState = {
         secretNumber,
         attempts: 0,
-        started: new Date()
+        started: new Date(),
       };
-      
+
       await Data.create('games', gameState);
-      
+
       return {
         message: 'Game started! Guess a number between 1 and 100',
-        attempts: 0
+        attempts: 0,
       };
     }
-    
+
     if (input.action === 'guess') {
       if (!gameState) {
         return { error: 'No active game. Use action: "start"' };
       }
-      
+
       gameState.attempts++;
-      
+
       if (input.guess === gameState.secretNumber) {
         await Data.delete('games', gameState.id);
         return {
           message: '🎉 Correct! You won!',
-          attempts: gameState.attempts
+          attempts: gameState.attempts,
         };
       }
-      
+
       const hint = input.guess! < gameState.secretNumber ? 'higher' : 'lower';
       await Data.update('games', gameState.id, gameState);
-      
+
       return {
         message: `Try ${hint}`,
-        attempts: gameState.attempts
+        attempts: gameState.attempts,
       };
     }
-    
+
     // Status
     if (!gameState) {
       return { message: 'No active game' };
     }
-    
+
     return {
       message: 'Game in progress',
-      attempts: gameState.attempts
+      attempts: gameState.attempts,
     };
   }
 }
@@ -360,38 +398,40 @@ import { z } from 'zod';
 export default class ReminderTool implements LuaTool {
   name = 'set_reminder';
   description = 'Set a reminder to notify user later';
-  
+
   inputSchema = z.object({
     message: z.string(),
-    minutes: z.number().min(1).max(1440)
+    minutes: z.number().min(1).max(1440),
   });
-  
+
   async execute(input: z.infer<typeof this.inputSchema>) {
     // Create a job that will notify the user later
     const job = await Jobs.create({
       name: `reminder-${Date.now()}`,
       description: 'User reminder',
       metadata: {
-        message: input.message
+        message: input.message,
       },
       schedule: {
         type: 'once',
-        executeAt: new Date(Date.now() + input.minutes * 60000)
+        executeAt: new Date(Date.now() + input.minutes * 60000),
       },
       execute: async (jobInstance: JobInstance) => {
         const user = await jobInstance.user();
-        await user.send([{
-          type: 'text',
-          text: `⏰ Reminder: ${jobInstance.metadata.message}`
-        }]);
+        await user.send([
+          {
+            type: 'text',
+            text: `⏰ Reminder: ${jobInstance.metadata.message}`,
+          },
+        ]);
         return { success: true };
-      }
+      },
     });
-    
+
     return {
       success: true,
       message: `Reminder set for ${input.minutes} minutes from now`,
-      jobId: job.id
+      jobId: job.id,
     };
   }
 }
@@ -400,12 +440,14 @@ export default class ReminderTool implements LuaTool {
 ## Naming Conventions
 
 ### ✅ Good Names
+
 - `get_weather` - Action + noun, clear purpose
 - `create_order` - Verb + noun, describes action
 - `search_products` - Clear, specific
 - `calculate_tax` - Action verb, specific
 
 ### ❌ Bad Names
+
 - `weather` - Too vague, unclear if getting or setting
 - `doIt` - Meaningless
 - `tool1` - Not descriptive
@@ -414,15 +456,16 @@ export default class ReminderTool implements LuaTool {
 ## Best Practices
 
 ### 1. Single Responsibility
+
 Each tool should do one thing well:
 
 ```typescript
 // ✅ Good - Focused purpose
-class GetWeatherTool { }
-class GetForecastTool { }
+class GetWeatherTool {}
+class GetForecastTool {}
 
 // ❌ Bad - Too many responsibilities
-class WeatherAndNewsAndStocksTool { }
+class WeatherAndNewsAndStocksTool {}
 ```
 
 ### 2. Descriptive Schemas
@@ -431,13 +474,13 @@ class WeatherAndNewsAndStocksTool { }
 // ✅ Good - With descriptions
 inputSchema = z.object({
   email: z.string().email().describe('User email address'),
-  sendCopy: z.boolean().optional().describe('Send copy to user')
+  sendCopy: z.boolean().optional().describe('Send copy to user'),
 });
 
 // ❌ Bad - No context
 inputSchema = z.object({
   email: z.string(),
-  sendCopy: z.boolean()
+  sendCopy: z.boolean(),
 });
 ```
 
@@ -518,4 +561,3 @@ test();
 - [Product Tools](../../template/src/skills/tools/ProductsTool.ts)
 - [Basket Tools](../../template/src/skills/tools/BasketTool.ts)
 - [Game Tracker](../../template/src/skills/tools/GameScoreTrackerTool.ts)
-

package/docs/api/LuaWebhook.md

@@ -92,7 +92,7 @@ set `enforceSchemas: true`. Only a strict boolean `true` enforces.
 - Validation only: `execute` receives the original `event`. No coercion, defaults or key stripping are applied to `event.query`, `event.headers` or `event.body`.
 - Header names are lowercase, so keys in a `headerSchema` must be lowercase (`'x-probe'`, not `'X-Probe'`). Transport headers are present too, so avoid `z.strictObject` for headers.
 - Webhooks that also subscribe to events receive `body: { eventType, ...payload }`; make sure `bodySchema` allows `eventType`.
-- Event deliveries are checked too, and they arrive with EMPTY `query` and `headers`. A `querySchema` or `headerSchema` with required keys, or a `bodySchema` that rejects `eventType`, logs a warning on every event delivery. Only with `enforceSchemas: true` do those deliveries fail, get logged at ERROR and not retried. Keep these schemas permissive, or declare them only on webhooks that are never event-subscribed.
+- Event deliveries (CLI that includes BAC-1551, after re-push): `querySchema` and `headerSchema` are NOT applied, because `query` and `headers` are always empty there; `bodySchema` is still validated, so make sure it allows `eventType`. A body violation logs a warning (or, with `enforceSchemas: true`, is logged at ERROR and not retried). The normal HTTP path is unchanged. Bundles built with an older CLI still check the empty query/headers on event deliveries.
 - Webhooks deployed from older CLI versions keep the old, unvalidated behaviour until they are re-compiled and re-pushed.
 
 ## Request Verification

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lua-cli",
-  "version": "3.53.0",
+  "version": "3.54.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",
@@ -116,8 +116,8 @@
     "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/shared-types": "0.0.1",
     "@lua/workflow-graph": "0.0.1"
   },
   "scripts": {

package/template/README.md

@@ -56,6 +56,8 @@ export default class GreetingTool implements LuaTool {
 }
 ```
 
+Optional: add `label = { running: 'Greeting {name}', done: 'Greeted {name}' };` to choose what the chat shows while the tool runs and when it is done (by default it shows the tool's name). `{name}` is filled in from the call's arguments.
+
 ### 2. Create a skill to group your tools
 
 Create `src/skills/greeting.skill.ts`:

package/template/package.json

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

package/template-web-app/app.ts

@@ -8,6 +8,11 @@ import { z } from 'zod';
  * and the admin console). Routes: the handlers below (run in the Lua sandbox
  * with the signed-in person as `auth`; Data, env() and fetch are available).
  *
+ * GET routes must only read. Someone you share this view with view-only
+ * (`auth.accessLevel === 'view_only'`) can call every GET route, with the
+ * agent's data, and nothing else; put every change in a POST, PUT, PATCH or
+ * DELETE route.
+ *
  *   lua apps dev __APP_NAME__        pages with hot reload, routes run locally as you
  *   lua test webapp --name __APP_NAME__ --route 'GET /hello'
  *   lua push webapp --name __APP_NAME__