lua-cli 3.42.0 → 3.44.0

package/docs/api/PostProcessor.md

@@ -11,6 +11,7 @@ import { PostProcessor } from 'lua-cli';
 ## Overview
 
 PostProcessors enable:
+
 - Format and style agent responses
 - Add branding and signatures
 - Translate responses to user's language
@@ -27,7 +28,12 @@ class PostProcessor {
   constructor(config: PostProcessorConfig);
   getName(): string;
   getDescription(): string;
-  execute(user: UserDataInstance, message: string, response: string, channel: string): Promise<PostProcessorResponse>;
+  execute(
+    user: UserDataInstance,
+    message: PostProcessorMessage,
+    response: string,
+    channel: string
+  ): Promise<PostProcessorResponse>;
 }
 ```
 
@@ -47,20 +53,42 @@ interface PostProcessorConfig {
    */
   execute: (
     user: UserDataInstance,
-    message: string,      // Original user message
-    response: string,     // Agent's response
-    channel: string       // Channel (whatsapp, web, etc.)
+    message: PostProcessorMessage, // The user's message: a string OR its parts — use messageText(message)
+    response: string, // Agent's response
+    channel: string // Channel (whatsapp, web, etc.)
   ) => Promise<PostProcessorResponse>;
 }
 ```
 
+## The `message` argument
+
+`message` is the user's message exactly as Lua received it: either a plain `string`, or an array of
+message parts (`[{ type: 'text', text }, { type: 'image', ... }]`). Messages sent from Lua Desktop and most
+channels arrive as parts, so never call string methods on `message` directly. Use `messageText`:
+
+```typescript
+import { PostProcessor, messageText } from 'lua-cli';
+
+export default new PostProcessor({
+  name: 'mention-question',
+  description: 'Reminds the user what they asked',
+  execute: async (user, message, response) => {
+    const asked = messageText(message); // '' when the message has no text (e.g. an image only)
+    return { modifiedResponse: asked ? `${response}\n\n(You asked: ${asked})` : response };
+  },
+});
+```
+
+A postprocessor that throws doesn't block the reply: Lua sends the unmodified response and records the error
+in the agent's logs.
+
 ## Response Type
 
 PostProcessors must return:
 
 ```typescript
 interface PostProcessorResponse {
-  modifiedResponse: string;  // The formatted response text
+  modifiedResponse: string; // The formatted response text
 }
 ```
 
@@ -79,15 +107,15 @@ export const brandingFooter = new PostProcessor({
     const footer = '\n\n---\n💼 Powered by Acme Corp\n🌐 www.acme.com | 📧 support@acme.com';
 
     return {
-      modifiedResponse: response + footer
+      modifiedResponse: response + footer,
     };
-  }
+  },
 });
 ```
 
 ### Markdown Formatter
 
-```typescript
+````typescript
 import { PostProcessor } from 'lua-cli';
 
 export const markdownFormatter = new PostProcessor({
@@ -116,13 +144,13 @@ export const markdownFormatter = new PostProcessor({
     formatted = formatted.replace(/\n/g, '<br>');
 
     return { modifiedResponse: formatted };
-  }
+  },
 });
-```
+````
 
 ### WhatsApp Formatter
 
-```typescript
+````typescript
 import { PostProcessor } from 'lua-cli';
 
 export const whatsappFormatter = new PostProcessor({
@@ -157,9 +185,9 @@ export const whatsappFormatter = new PostProcessor({
     }
 
     return { modifiedResponse: formatted };
-  }
+  },
 });
-```
+````
 
 ### Response Translator
 
@@ -188,7 +216,7 @@ export const responseTranslator = new PostProcessor({
       pt: 'Portuguese',
       ja: 'Japanese',
       ko: 'Korean',
-      zh: 'Chinese'
+      zh: 'Chinese',
     };
 
     const targetLanguage = languageNames[userLanguage] || userLanguage;
@@ -199,7 +227,7 @@ export const responseTranslator = new PostProcessor({
     );
 
     return { modifiedResponse: translatedResponse };
-  }
+  },
 });
 ```
 
@@ -218,7 +246,7 @@ export const linkInjector = new PostProcessor({
       pricing: 'View pricing: https://example.com/pricing',
       support: 'Get support: https://example.com/support',
       documentation: 'Read docs: https://example.com/docs',
-      account: 'Manage account: https://example.com/account'
+      account: 'Manage account: https://example.com/account',
     };
 
     let modified = response;
@@ -237,7 +265,7 @@ export const linkInjector = new PostProcessor({
     }
 
     return { modifiedResponse: modified };
-  }
+  },
 });
 ```
 
@@ -268,7 +296,7 @@ export const sentimentAnalyzer = new PostProcessor({
         sentiment: result.sentiment,
         score: result.score,
         channel,
-        timestamp: new Date().toISOString()
+        timestamp: new Date().toISOString(),
       });
 
       // Add positive emoji for positive sentiments
@@ -280,7 +308,7 @@ export const sentimentAnalyzer = new PostProcessor({
     }
 
     return { modifiedResponse: response };
-  }
+  },
 });
 ```
 
@@ -295,23 +323,30 @@ export const legalDisclaimer = new PostProcessor({
 
   execute: async (user, message, response, channel) => {
     const financialKeywords = [
-      'invest', 'stock', 'trading', 'financial', 'money',
-      'portfolio', 'crypto', 'bitcoin', 'tax', 'retirement'
+      'invest',
+      'stock',
+      'trading',
+      'financial',
+      'money',
+      'portfolio',
+      'crypto',
+      'bitcoin',
+      'tax',
+      'retirement',
     ];
 
     const lowerResponse = response.toLowerCase();
-    const containsFinancialContent = financialKeywords.some(
-      keyword => lowerResponse.includes(keyword)
-    );
+    const containsFinancialContent = financialKeywords.some((keyword) => lowerResponse.includes(keyword));
 
     if (containsFinancialContent) {
-      const disclaimer = '\n\n⚠️ Disclaimer: This information is for educational purposes only and should not be considered financial advice. Please consult with a licensed financial advisor before making investment decisions.';
+      const disclaimer =
+        '\n\n⚠️ Disclaimer: This information is for educational purposes only and should not be considered financial advice. Please consult with a licensed financial advisor before making investment decisions.';
 
       return { modifiedResponse: response + disclaimer };
     }
 
     return { modifiedResponse: response };
-  }
+  },
 });
 ```
 
@@ -331,15 +366,14 @@ export const responseSummarizer = new PostProcessor({
     }
 
     // Generate summary
-    const summary = await AI.generate(
-      'Create a 1-sentence summary (TL;DR) of this response.',
-      [{ type: 'text', text: response }]
-    );
+    const summary = await AI.generate('Create a 1-sentence summary (TL;DR) of this response.', [
+      { type: 'text', text: response },
+    ]);
 
     const modified = `**TL;DR:** ${summary}\n\n---\n\n${response}`;
 
     return { modifiedResponse: modified };
-  }
+  },
 });
 ```
 
@@ -371,7 +405,7 @@ export const ctaInjector = new PostProcessor({
     }
 
     return { modifiedResponse: response + cta };
-  }
+  },
 });
 ```
 
@@ -398,7 +432,7 @@ export const profanityFilter = new PostProcessor({
     }
 
     return { modifiedResponse: filtered };
-  }
+  },
 });
 ```
 
@@ -419,12 +453,12 @@ export const responseLogger = new PostProcessor({
       agentResponse: response,
       responseLength: response.length,
       channel,
-      timestamp: new Date().toISOString()
+      timestamp: new Date().toISOString(),
     });
 
     // Return response unchanged
     return { modifiedResponse: response };
-  }
+  },
 });
 ```
 
@@ -456,7 +490,7 @@ export const channelFormatter = new PostProcessor({
       default:
         return { modifiedResponse: response };
     }
-  }
+  },
 });
 ```
 
@@ -505,13 +539,13 @@ export const safePostProcessor = new PostProcessor({
         error: error.message,
         userId: user.id,
         originalResponse: response,
-        timestamp: new Date().toISOString()
+        timestamp: new Date().toISOString(),
       });
 
       // Return original response on error
       return { modifiedResponse: response };
     }
-  }
+  },
 });
 ```
 
@@ -529,10 +563,7 @@ return { modifiedResponse: response };
 ### String Manipulation
 
 ```typescript
-const modified = response
-  .replace(/old/g, 'new')
-  .trim()
-  .toUpperCase();
+const modified = response.replace(/old/g, 'new').trim().toUpperCase();
 
 return { modifiedResponse: modified };
 ```