lua-cli 3.42.0-beta.1 → 3.42.0-beta.3

package/docs/api/Data.md

@@ -11,6 +11,7 @@ import { Data } from 'lua-cli';
 ## Overview
 
 The Data API is perfect for:
+
 - Custom data collections (movies, recipes, documents)
 - Vector/semantic search
 - User-specific data storage
@@ -24,6 +25,7 @@ The Data API is perfect for:
 Retrieves entries from a collection with optional filtering and pagination.
 
 **Parameters:**
+
 - `collectionName` (string) - Name of the collection
 - `filter` (object, optional) - MongoDB-style filter criteria
 - `page` (number, optional) - Page number (default: 1)
@@ -48,6 +50,7 @@ Retrieves entries from a collection with optional filtering and pagination.
 ```
 
 **Example:**
+
 ```typescript
 // Get all (first page)
 const result = await Data.get('movies');
@@ -69,6 +72,7 @@ const sciFi = await Data.get('movies', { genre: 'Sci-Fi' });
 Performs semantic search on a collection using AI embeddings.
 
 **Parameters:**
+
 - `collectionName` (string) - Collection to search
 - `query` (string) - Search query (uses AI embeddings)
 - `limit` (number, optional) - Max results (default: 10)
@@ -79,6 +83,7 @@ Performs semantic search on a collection using AI embeddings.
 Each result includes a `score` property indicating similarity (0-1).
 
 **Example:**
+
 ```typescript
 const results = await Data.search('movies', 'sci-fi action thriller', 5, 0.7);
 
@@ -93,6 +98,7 @@ for (const movie of results) {
 Creates a new entry in a collection.
 
 **Parameters:**
+
 - `collectionName` (string) - Collection name
 - `data` (object) - Data to store
 - `searchText` (string, optional) - Text to use for vector search indexing
@@ -100,13 +106,18 @@ Creates a new entry in a collection.
 **Returns:** `Promise<DataEntryInstance>`
 
 **Example:**
+
 ```typescript
-const movie = await Data.create('movies', {
-  title: 'Inception',
-  year: 2010,
-  director: 'Christopher Nolan',
-  genre: ['Sci-Fi', 'Thriller']
-}, 'Inception 2010 sci-fi thriller Christopher Nolan dream heist');
+const movie = await Data.create(
+  'movies',
+  {
+    title: 'Inception',
+    year: 2010,
+    director: 'Christopher Nolan',
+    genre: ['Sci-Fi', 'Thriller'],
+  },
+  'Inception 2010 sci-fi thriller Christopher Nolan dream heist'
+);
 
 console.log('Created:', movie.id);
 ```
@@ -116,6 +127,7 @@ console.log('Created:', movie.id);
 Updates an existing entry.
 
 **Parameters:**
+
 - `collectionName` (string) - Collection name
 - `entryId` (string) - Entry ID to update
 - `data` (object) - Updated data
@@ -124,30 +136,140 @@ Updates an existing entry.
 **Returns:** `Promise<UpdateCustomDataResponse>`
 
 **Example:**
+
 ```typescript
-const result = await Data.update(
-  'movies',
-  'entry_123',
-  { rating: 9.5, views: 1000 },
-  'Inception highly rated popular'
-);
+const result = await Data.update('movies', 'entry_123', { rating: 9.5, views: 1000 }, 'Inception highly rated popular');
 
 if (result.status === 'success') {
   console.log(result.message); // "Custom data entry updated"
 }
 ```
 
+### `Data.patch(collectionName, entryId, mutation, options?)`
+
+Atomically sets and removes top-level fields in **one** write. Unlike `Data.update` (which reads the entry,
+merges your fields and writes the whole `data` back, so concurrent updates can overwrite each other), `patch`
+only touches the fields you name.
+
+**Parameters:**
+
+- `collectionName` (string) - Collection name
+- `entryId` (string) - Entry ID
+- `mutation` (object) - `{ set?: Record<string, any>; unset?: string[]; searchText?: string | null }`
+  (`searchText: null` clears the entry's search text and vector)
+- `options` (object, optional) - `{ ifVersion?: number }` for compare-and-swap (below)
+
+**Returns:** `Promise<UpdateCustomDataResponse>` - `{ status, message, version }`, where `version` is the entry's
+new version
+
+```typescript
+await Data.patch('tickets', ticketId, { set: { status: 'closed' }, unset: ['assignee'] });
+```
+
+#### Compare-and-swap with `ifVersion`
+
+Every entry carries a `version` number that **every** write (`create`, `update`, `patch`, `increment`)
+bumps. Read it as `entry.version` on the entries `Data.get` returns, or `entry._version` on the
+`DataEntryInstance` that `Data.getEntry` / `Data.create` return (underscored so it never hides a `version`
+field of your own data). Entries not written since versioning was introduced report `0`.
+
+Pass the version you read as `ifVersion` and the patch applies **only if nobody wrote the entry in between**.
+Otherwise nothing is written and the call rejects with an error whose `code` is `'data_version_conflict'`
+(`status` 409); `error.currentVersion` carries the version to re-read from and `error.expectedVersion` the
+stale one you sent. This is the same in `lua test`, in deployed agents and in voice agents.
+
+`ifVersion` must be a non-negative integer. If the `ifVersion` key is present with any other value,
+including `undefined`, the call throws a `TypeError` and sends nothing. It is never quietly dropped, which
+would turn the compare-and-swap into an unconditional write. Leave the key out entirely for an unconditional
+patch, so build options with a conditional spread: `{ ...(v !== undefined ? { ifVersion: v } : {}) }`.
+
+```typescript
+// Claim a seat exactly once, even if two conversations race for it.
+async function claimSeat(seatId: string, userId: string): Promise<boolean> {
+  for (let attempt = 0; attempt < 3; attempt++) {
+    const seat = await Data.getEntry('seats', seatId);
+    if (seat.data.heldBy) return false;
+    try {
+      await Data.patch('seats', seatId, { set: { heldBy: userId } }, { ifVersion: seat._version });
+      return true;
+    } catch (error: any) {
+      if (error?.code !== 'data_version_conflict') throw error;
+      // Someone else wrote the seat first: loop and re-read.
+    }
+  }
+  return false;
+}
+```
+
+Compare `error.code` against the string `'data_version_conflict'` rather than using `instanceof`.
+
+**Notes:**
+
+- A patch with `ifVersion` is sent once and is not retried, because a retry of an attempt that landed would
+  find its own version bump and report a false conflict. So a network error leaves the outcome unknown,
+  just as with `increment`. After a network error, re-read the entry: if your change is there, your write
+  landed.
+- Versions start at `1` when an entry is created, including by an `increment` upsert. If an entry is deleted
+  and an entry with the **same ID** is created again, its version restarts, and an `ifVersion` read from the
+  deleted entry can match the new one. Do not reuse the IDs of deleted entries for state you guard with
+  `ifVersion`.
+
+### `Data.increment(collectionName, entryId, field, by?, options?)`
+
+Atomically adds `by` to a top-level numeric field and resolves the field's **new value**. Simultaneous
+increments never lose a count (each is a single database operation), which a `get` + `update` cannot
+guarantee.
+
+**Parameters:**
+
+- `collectionName` (string) - Collection name
+- `entryId` (string) - Entry ID (the ID to create under when upserting)
+- `field` (string) - Top-level field name (no dots, no leading `$`)
+- `by` (number, optional) - Amount to add; default `1`. Negative and fractional amounts are allowed
+- `options` (object, optional) - `{ upsert?: boolean }`. With `upsert: true` a missing entry is created as
+  `{ [field]: by }` instead of failing
+
+**Returns:** `Promise<number>` - the field's value after the increment
+
+**Errors:** 404 when the entry does not exist and `upsert` is not set; 400 when the field (or the entry's
+`data`) is not numeric. A missing field starts at `0`.
+
+```typescript
+const views = await Data.increment('stats', 'homepage', 'views'); // 1, 2, 3, ...
+await Data.increment('inventory', sku, 'available', -1); // decrement
+
+// A daily counter: one long-lived entry, one FIELD per day. The entry is created once (see the note
+// below); each new day's field simply starts at 0, so no conversation ever has to create anything.
+await Data.increment('stats', 'calls', `day-${today}`); // `today` like '2026-10-01'
+```
+
+**Notes:**
+
+- Upsert race: `upsert` is **not** safe for an entry that many conversations may create at the same moment.
+  Two first-time upserts of the same new ID that run concurrently can each create an entry. Later
+  increments then land on only one of them, and the count in the other is lost. So do not upsert a fresh
+  ID per day or per event under load (for example
+  ``Data.increment('daily', `calls-${today}`, 'count', 1, { upsert: true })``). Create the entry once
+  from a path that does not run concurrently, such as a setup job or
+  `Data.increment('stats', 'calls', 'total', 0, { upsert: true })` before go-live. After that,
+  increment it, or add new fields to it, as above.
+- The SDK sends the request once and does not retry it: an increment is not idempotent, so after a network
+  error the count may or may not have been applied. Do not blindly retry an increment that failed with a
+  network error if an exact count matters.
+
 ### `Data.delete(collectionName, entryId)`
 
 Deletes an entry from a collection.
 
 **Parameters:**
+
 - `collectionName` (string) - Collection name
 - `entryId` (string) - Entry ID to delete
 
 **Returns:** `Promise<DeleteCustomDataResponse>`
 
 **Example:**
+
 ```typescript
 const result = await Data.delete('movies', 'entry_123');
 
@@ -165,13 +287,14 @@ Data entries have convenient methods:
 Updates this entry.
 
 **Example:**
+
 ```typescript
 const movies = await Data.get('movies');
 const movie = movies[0];
 
 await movie.update({
   rating: 9.0,
-  views: movie.views + 1
+  views: movie.views + 1,
 });
 ```
 
@@ -180,9 +303,10 @@ await movie.update({
 Deletes this entry.
 
 **Example:**
+
 ```typescript
 const movies = await Data.get('movies');
-const oldMovie = movies.find(m => m.year < 1950);
+const oldMovie = movies.find((m) => m.year < 1950);
 
 if (oldMovie) {
   await oldMovie.delete();
@@ -194,6 +318,7 @@ if (oldMovie) {
 Saves modifications to this entry.
 
 **Example:**
+
 ```typescript
 const movies = await Data.get('movies');
 const movie = movies[0];
@@ -236,7 +361,7 @@ import { z } from 'zod';
 export default class MovieDatabaseTool implements LuaTool {
   name = 'manage_movies';
   description = 'Manage a movie database';
-  
+
   inputSchema = z.object({
     action: z.enum(['add', 'search', 'update', 'delete']),
     title: z.string().optional(),
@@ -245,78 +370,82 @@ export default class MovieDatabaseTool implements LuaTool {
     genre: z.array(z.string()).optional(),
     rating: z.number().min(0).max(10).optional(),
     movieId: z.string().optional(),
-    query: z.string().optional()
+    query: z.string().optional(),
   });
-  
+
   async execute(input: z.infer<typeof this.inputSchema>) {
     switch (input.action) {
       case 'add':
         if (!input.title || !input.year) {
           return { success: false, error: 'Title and year required' };
         }
-        
+
         const searchText = `${input.title} ${input.year} ${input.director || ''} ${input.genre?.join(' ') || ''}`;
-        
-        const movie = await Data.create('movies', {
-          title: input.title,
-          year: input.year,
-          director: input.director,
-          genre: input.genre || [],
-          rating: input.rating || 0,
-          createdAt: new Date().toISOString()
-        }, searchText);
-        
+
+        const movie = await Data.create(
+          'movies',
+          {
+            title: input.title,
+            year: input.year,
+            director: input.director,
+            genre: input.genre || [],
+            rating: input.rating || 0,
+            createdAt: new Date().toISOString(),
+          },
+          searchText
+        );
+
         return {
           success: true,
           message: `Added "${input.title}"`,
-          movieId: movie.id
+          movieId: movie.id,
         };
-        
+
       case 'search':
         if (!input.query) {
           return { success: false, error: 'Query required' };
         }
-        
+
         const results = await Data.search('movies', input.query, 10);
-        
+
         return {
           success: true,
           count: results.data.length,
-          movies: results.data.map(r => ({
+          movies: results.data.map((r) => ({
             id: r.id,
             title: r.data.title,
             year: r.data.year,
             director: r.data.director,
-            relevance: r.score
-          }))
+            relevance: r.score,
+          })),
         };
-        
+
       case 'update':
         if (!input.movieId) {
           return { success: false, error: 'Movie ID required' };
         }
-        
+
         const updates: any = {};
         if (input.rating !== undefined) updates.rating = input.rating;
         if (input.director) updates.director = input.director;
-        
+
         const updateResult = await Data.update('movies', input.movieId, updates);
-        
+
         return {
           success: updateResult.status === 'success',
-          message: updateResult.message
+          message: updateResult.message,
         };
-        
+
       case 'delete':
         if (!input.movieId) {
           return { success: false, error: 'Movie ID required' };
         }
-        
+
         const deleteResult = await Data.delete('movies', input.movieId);
-        
+
         return {
           success: deleteResult.status === 'success',
-          message: deleteResult.message
+          message: deleteResult.message,
         };
     }
   }
@@ -332,33 +461,33 @@ import { z } from 'zod';
 export default class KnowledgeBaseTool implements LuaTool {
   name = 'search_knowledge_base';
   description = 'Search company knowledge base for information';
-  
+
   inputSchema = z.object({
-    question: z.string().describe('User question')
+    question: z.string().describe('User question'),
   });
-  
+
   async execute(input: z.infer<typeof this.inputSchema>) {
     // Semantic search finds relevant articles
     const results = await Data.search('knowledge-base', input.question, 3);
-    
+
     if (results.data.length === 0) {
       return {
         success: true,
         found: false,
-        message: 'No relevant articles found'
+        message: 'No relevant articles found',
       };
     }
-    
+
     // Return top results
     return {
       success: true,
       found: true,
-      articles: results.data.map(r => ({
+      articles: results.data.map((r) => ({
         title: r.data.title,
         content: r.data.content,
         relevance: Math.round(r.score * 100),
-        url: r.data.url
-      }))
+        url: r.data.url,
+      })),
     };
   }
 }
@@ -373,27 +502,27 @@ import { z } from 'zod';
 export default class RecipeTool implements LuaTool {
   name = 'find_recipe';
   description = 'Find recipes based on ingredients or cuisine';
-  
+
   inputSchema = z.object({
-    searchTerm: z.string().describe('Ingredients, cuisine, or dish name')
+    searchTerm: z.string().describe('Ingredients, cuisine, or dish name'),
   });
-  
+
   async execute(input: z.infer<typeof this.inputSchema>) {
     // Search recipes
     const results = await Data.search('recipes', input.searchTerm, 5);
-    
+
     return {
       success: true,
       count: results.data.length,
-      recipes: results.data.map(r => ({
+      recipes: results.data.map((r) => ({
         name: r.data.name,
         cuisine: r.data.cuisine,
         ingredients: r.data.ingredients,
         instructions: r.data.instructions,
         prepTime: r.data.prepTime,
         difficulty: r.data.difficulty,
-        matchScore: Math.round(r.score * 100)
-      }))
+        matchScore: Math.round(r.score * 100),
+      })),
     };
   }
 }
@@ -413,6 +542,7 @@ await Data.search('movies', 'Star Wars type movies');
 ```
 
 **Tips:**
+
 - Use descriptive search text when creating entries
 - Search queries can be natural language
 - Results include similarity scores (0-1)
@@ -421,6 +551,7 @@ await Data.search('movies', 'Star Wars type movies');
 ## Best Practices
 
 ### ✅ DO
+
 - Use descriptive collection names (`user-notes`, not `notes`)
 - Provide searchText for better semantic search
 - Include all relevant keywords in searchText
@@ -428,6 +559,7 @@ await Data.search('movies', 'Star Wars type movies');
 - Use meaningful property names
 
 ### ❌ DON'T
+
 - Don't store large binary data (use URLs instead)
 - Don't use Data API for relational data (use Products/Orders)
 - Don't skip searchText if you plan to search
@@ -443,4 +575,3 @@ await Data.search('movies', 'Star Wars type movies');
 
 - [Custom Data Tool Example](../../template/src/skills/tools/CustomDataTool.ts)
 - [Vector Search Guide](../guides/VectorSearch.md)
-

package/docs/api/Jobs.md

@@ -30,6 +30,8 @@ Creates a new scheduled job.
 
 **Returns:** `Promise<JobInstance>`
 
+Dynamic jobs are stored as `<name> - <epoch ms>`, the same under `lua test` and deployed.
+
 **Example:**
 ```typescript
 const job = await Jobs.create({