lua-cli 3.55.0 → 3.56.0

package/docs/README.md

@@ -1,6 +1,6 @@
-# lua-cli v3.55.0
+# lua-cli v3.56.0
 
-Welcome to the comprehensive API documentation for lua-cli v3.55.0. This guide covers every API, class, and function exported by the package.
+Welcome to the comprehensive API documentation for lua-cli v3.56.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.55.0
+**Version:** 3.56.0
 **Last Updated:** October 2026
 
 ---

package/docs/api/PreProcessor.md

@@ -11,6 +11,7 @@ import { PreProcessor } from 'lua-cli';
 ## Overview
 
 PreProcessors enable:
+
 - Filter and block inappropriate content
 - Modify messages before agent processing
 - Add context and enrichment to messages
@@ -60,11 +61,7 @@ interface PreProcessorConfig {
   /**
    * Function that processes messages before sending to agent.
    */
-  execute: (
-    user: UserDataInstance,
-    messages: ChatMessage[],
-    channel: string
-  ) => Promise<PreProcessorResult>;
+  execute: (user: UserDataInstance, messages: ChatMessage[], channel: string) => Promise<PreProcessorResult>;
 }
 ```
 
@@ -90,10 +87,22 @@ Continue to the next preprocessor or agent:
 {
   action: 'proceed',
   modifiedMessage?: ChatMessage[],  // Optional modified messages
-  metadata?: Record<string, any>    // Optional metadata
+  metadata?: { turnContext?: string; [key: string]: any }  // Optional metadata
 }
 ```
 
+#### Turn context
+
+Set `metadata.turnContext` to give the model a short note for this turn only, such as state read from your own data:
+
+```typescript
+return { action: 'proceed', metadata: { turnContext: 'Checklist in progress: section 12 of 48.' } };
+```
+
+The platform adds it after the conversation, labelled as system-provided context the user did not write. It is never stored, never in chat history and never shown to the user. Notes from several preprocessors are joined in run order and capped at 2,000 characters in total; anything that is not a string is ignored.
+
+The model is told the note is data, not instructions, because it may quote text users wrote. Do not use it to steer the agent's behaviour; put rules in the persona or a skill.
+
 ## Message Types
 
 ```typescript
@@ -113,7 +122,7 @@ import { PreProcessor } from 'lua-cli';
 export const contentFilter = new PreProcessor({
   name: 'content-filter',
   description: 'Filters inappropriate content',
-  priority: 10,  // Run early
+  priority: 10, // Run early
 
   execute: async (user, messages, channel) => {
     const blockedWords = ['spam', 'scam', 'phishing'];
@@ -130,8 +139,8 @@ export const contentFilter = new PreProcessor({
               response: 'Your message contains inappropriate content and cannot be processed.',
               metadata: {
                 reason: 'blocked_word',
-                word
-              }
+                word,
+              },
             };
           }
         }
@@ -139,7 +148,7 @@ export const contentFilter = new PreProcessor({
     }
 
     return { action: 'proceed' };
-  }
+  },
 });
 ```
 
@@ -151,7 +160,7 @@ import { PreProcessor } from 'lua-cli';
 export const userVerification = new PreProcessor({
   name: 'user-verification',
   description: 'Verifies user has completed onboarding',
-  priority: 5,  // Run very early
+  priority: 5, // Run very early
 
   execute: async (user, messages, channel) => {
     const userData = await user.get();
@@ -162,8 +171,8 @@ export const userVerification = new PreProcessor({
         action: 'block',
         response: 'Please complete your profile setup before using the assistant. Type "/start" to begin.',
         metadata: {
-          reason: 'onboarding_incomplete'
-        }
+          reason: 'onboarding_incomplete',
+        },
       };
     }
 
@@ -173,13 +182,13 @@ export const userVerification = new PreProcessor({
         action: 'block',
         response: 'Your account has been suspended. Please contact support.',
         metadata: {
-          reason: 'account_suspended'
-        }
+          reason: 'account_suspended',
+        },
       };
     }
 
     return { action: 'proceed' };
-  }
+  },
 });
 ```
 
@@ -199,7 +208,7 @@ export const messageEnrichment = new PreProcessor({
     // Add context message with user info
     const contextMessage = {
       type: 'text' as const,
-      text: `[User Context: Name: ${userData.data?.name || 'Unknown'}, Plan: ${userData.data?.plan || 'free'}, Location: ${userData.data?.location || 'Unknown'}]`
+      text: `[User Context: Name: ${userData.data?.name || 'Unknown'}, Plan: ${userData.data?.plan || 'free'}, Location: ${userData.data?.location || 'Unknown'}]`,
     };
 
     // Prepend context to messages
@@ -210,10 +219,10 @@ export const messageEnrichment = new PreProcessor({
       modifiedMessage: enrichedMessages,
       metadata: {
         enriched: true,
-        userPlan: userData.data?.plan
-      }
+        userPlan: userData.data?.plan,
+      },
     };
-  }
+  },
 });
 ```
 
@@ -230,27 +239,26 @@ export const rateLimiter = new PreProcessor({
   execute: async (user, messages, channel) => {
     const userId = user.id;
     const now = Date.now();
-    const windowMs = 60 * 1000;  // 1 minute
+    const windowMs = 60 * 1000; // 1 minute
     const maxMessages = 10;
 
     // Get user's recent messages
     const rateLimitKey = `rate_limit_${userId}`;
     const records = await Data.get('rate_limits');
-    let userRecord = records.find(r => r.data.key === rateLimitKey);
+    let userRecord = records.find((r) => r.data.key === rateLimitKey);
 
     if (!userRecord) {
       // Create new record
       await Data.create('rate_limits', {
         key: rateLimitKey,
         messages: [now],
-        windowStart: now
+        windowStart: now,
       });
       return { action: 'proceed' };
     }
 
     // Filter messages within window
-    const recentMessages = userRecord.data.messages
-      .filter((timestamp: number) => now - timestamp < windowMs);
+    const recentMessages = userRecord.data.messages.filter((timestamp: number) => now - timestamp < windowMs);
 
     // Check if limit exceeded
     if (recentMessages.length >= maxMessages) {
@@ -259,19 +267,19 @@ export const rateLimiter = new PreProcessor({
         response: 'You are sending messages too quickly. Please wait a moment and try again.',
         metadata: {
           reason: 'rate_limit_exceeded',
-          retryAfter: windowMs - (now - recentMessages[0])
-        }
+          retryAfter: windowMs - (now - recentMessages[0]),
+        },
       };
     }
 
     // Update record
     await Data.update('rate_limits', userRecord.id, {
       ...userRecord.data,
-      messages: [...recentMessages, now]
+      messages: [...recentMessages, now],
     });
 
     return { action: 'proceed' };
-  }
+  },
 });
 ```
 
@@ -284,17 +292,17 @@ export const spamDetector = new PreProcessor({
   name: 'spam-detector',
   description: 'AI-powered spam detection',
   priority: 20,
-  async: true,  // Can run in background
+  async: true, // Can run in background
 
   execute: async (user, messages, channel) => {
     // Only check text messages
-    const textMessages = messages.filter(m => m.type === 'text');
+    const textMessages = messages.filter((m) => m.type === 'text');
 
     if (textMessages.length === 0) {
       return { action: 'proceed' };
     }
 
-    const messageText = textMessages.map(m => m.text).join(' ');
+    const messageText = textMessages.map((m) => m.text).join(' ');
 
     // Use AI to detect spam
     const analysis = await AI.generate(
@@ -312,8 +320,8 @@ export const spamDetector = new PreProcessor({
           metadata: {
             reason: 'spam_detected',
             confidence: result.confidence,
-            analysis: result.reason
-          }
+            analysis: result.reason,
+          },
         };
       }
     } catch (error) {
@@ -322,7 +330,7 @@ export const spamDetector = new PreProcessor({
     }
 
     return { action: 'proceed' };
-  }
+  },
 });
 ```
 
@@ -349,7 +357,7 @@ export const businessHoursChecker = new PreProcessor({
       // Add notice to message
       const noticeMessage = {
         type: 'text' as const,
-        text: '[Note: You are contacting us outside business hours. Our team will respond when we return (Monday-Friday, 9 AM - 5 PM).]'
+        text: '[Note: You are contacting us outside business hours. Our team will respond when we return (Monday-Friday, 9 AM - 5 PM).]',
       };
 
       return {
@@ -357,13 +365,13 @@ export const businessHoursChecker = new PreProcessor({
         modifiedMessage: [noticeMessage, ...messages],
         metadata: {
           outsideBusinessHours: true,
-          timestamp: now.toISOString()
-        }
+          timestamp: now.toISOString(),
+        },
       };
     }
 
     return { action: 'proceed' };
-  }
+  },
 });
 ```
 
@@ -379,7 +387,7 @@ export const languageTranslator = new PreProcessor({
   async: true,
 
   execute: async (user, messages, channel) => {
-    const textMessages = messages.filter(m => m.type === 'text');
+    const textMessages = messages.filter((m) => m.type === 'text');
 
     if (textMessages.length === 0) {
       return { action: 'proceed' };
@@ -403,7 +411,7 @@ export const languageTranslator = new PreProcessor({
       );
 
       // Replace with translated text
-      const translatedMessages = messages.map(msg => {
+      const translatedMessages = messages.map((msg) => {
         if (msg.type === 'text') {
           return { type: 'text' as const, text: translation };
         }
@@ -415,13 +423,13 @@ export const languageTranslator = new PreProcessor({
         modifiedMessage: translatedMessages,
         metadata: {
           originalLanguage: language,
-          translated: true
-        }
+          translated: true,
+        },
       };
     }
 
     return { action: 'proceed' };
-  }
+  },
 });
 ```
 
@@ -448,7 +456,7 @@ export const priorityRouter = new PreProcessor({
             // Mark as high priority
             const priorityMessage = {
               type: 'text' as const,
-              text: `[HIGH PRIORITY] ${message.text}`
+              text: `[HIGH PRIORITY] ${message.text}`,
             };
 
             return {
@@ -457,8 +465,8 @@ export const priorityRouter = new PreProcessor({
               metadata: {
                 priority: 'high',
                 keyword,
-                flagged: true
-              }
+                flagged: true,
+              },
             };
           }
         }
@@ -468,10 +476,10 @@ export const priorityRouter = new PreProcessor({
     return {
       action: 'proceed',
       metadata: {
-        priority: 'normal'
-      }
+        priority: 'normal',
+      },
     };
-  }
+  },
 });
 ```
 
@@ -493,11 +501,13 @@ new PreProcessor({ priority: 50, ... });
 ## Async vs Sync
 
 ### Synchronous (default)
+
 - Blocks message processing until complete
 - Best for fast operations (< 100ms)
 - Use for filtering, validation, simple transforms
 
 ### Asynchronous
+
 - Runs in background, doesn't block
 - Best for slow operations (API calls, AI)
 - Set `async: true` in config
@@ -568,13 +578,13 @@ export const safePreProcessor = new PreProcessor({
       await Data.create('preprocessor_errors', {
         error: error.message,
         userId: user.id,
-        timestamp: new Date().toISOString()
+        timestamp: new Date().toISOString(),
       });
 
       // Proceed anyway (fail open)
       return { action: 'proceed' };
     }
-  }
+  },
 });
 ```
 
@@ -586,7 +596,7 @@ export const safePreProcessor = new PreProcessor({
 if (shouldBlock) {
   return {
     action: 'block',
-    response: 'Message blocked'
+    response: 'Message blocked',
   };
 }
 return { action: 'proceed' };
@@ -595,7 +605,7 @@ return { action: 'proceed' };
 ### Message Modification
 
 ```typescript
-const modifiedMessages = messages.map(msg => {
+const modifiedMessages = messages.map((msg) => {
   if (msg.type === 'text') {
     return { type: 'text', text: msg.text.toUpperCase() };
   }
@@ -604,7 +614,7 @@ const modifiedMessages = messages.map(msg => {
 
 return {
   action: 'proceed',
-  modifiedMessage: modifiedMessages
+  modifiedMessage: modifiedMessages,
 };
 ```
 
@@ -614,7 +624,7 @@ return {
 const contextMsg = { type: 'text' as const, text: '[Context info]' };
 return {
   action: 'proceed',
-  modifiedMessage: [contextMsg, ...messages]
+  modifiedMessage: [contextMsg, ...messages],
 };
 ```
 

package/docs/api/Threads.md

@@ -120,3 +120,17 @@ await Workflows.start('refund', input, { originThreadId: threadId, callback: tru
 ```
 
 This works only for the run's own user. A user-less, agent-level run cannot target a home thread yet.
+
+## Threads.resetContext
+
+```typescript
+// In a tool, after a checklist section is recorded:
+await Threads.resetContext(); // { status: 'reset' } or { status: 'skipped', reason }
+```
+
+Starts the agent's context afresh from the current turn. From the next turn on, the agent reads this turn and what follows, not the earlier messages or the observation log built from them. The person still sees the whole conversation, and nothing is deleted.
+
+- **Where.** Only from a tool or processor of a 1:1 chat turn. A job, webhook, trigger, room turn or workflow step gets `skipped: not_chat_turn`.
+- **When it applies.** The agent's `contextReset` feature must be on, and the agent must use observational memory (the default). The same feature also resets once a day: the first turn after 04:00 in the person's timezone drops everything from earlier days.
+- **Never throws.** A reset is advisory. It answers `skipped` with a reason when the feature is off (`disabled`), memory is off (`memory_off`), nothing older is left (`nothing_to_reset`), memory was busy (`busy`; the next reset will apply), or offline in `lua test` / `lua dev` (`unavailable`).
+- **Give the agent what it still needs.** After a reset the agent no longer sees earlier turns. Put where the person is in a task in your own data and add it to each turn, for example in a preprocessor.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lua-cli",
-  "version": "3.55.0",
+  "version": "3.56.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",

package/template/package.json

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