lua-cli 2.5.7 → 3.0.0-alpha.1

package/template/src/jobs/HealthCheckJob.ts

@@ -0,0 +1,87 @@
+/**
+ * Health Check Job Example
+ * 
+ * This job runs every 5 minutes to check system health and alert on issues.
+ * Demonstrates: Interval scheduling, monitoring, and alerting.
+ */
+
+import { LuaJob, Data, Products } from "lua-cli";
+
+const healthCheckJob = new LuaJob({
+  name: "health-check",
+  version: "1.0.0",
+  description: "System health monitoring",
+  context: "Runs every 5 minutes to check API health, database connectivity, and service availability. " +
+           "Logs health metrics and can trigger alerts if issues are detected.",
+
+  // Interval schedule: Every 5 minutes
+  schedule: {
+    type: 'interval',
+    seconds: 300  // 5 minutes = 300 seconds
+  },
+
+  // Quick timeout for health checks
+  timeout: 30,
+
+  execute: async () => {
+    console.log('❤️ Running health check...');
+    const checks: any = {};
+
+    // Check 1: Database connectivity
+    try {
+      const testQuery = await Data.get('health-checks', {}, 1, 1);
+      checks.database = {
+        status: 'healthy',
+        responseTime: Date.now()
+      };
+    } catch (error) {
+      checks.database = {
+        status: 'unhealthy',
+        error: String(error)
+      };
+    }
+
+    // Check 2: Products API
+    try {
+      const startTime = Date.now();
+      await Products.get(1, 1);
+      const responseTime = Date.now() - startTime;
+      
+      checks.productsApi = {
+        status: 'healthy',
+        responseTime: `${responseTime}ms`
+      };
+    } catch (error) {
+      checks.productsApi = {
+        status: 'unhealthy',
+        error: String(error)
+      };
+    }
+
+    // Determine overall health
+    const allHealthy = Object.values(checks).every((check: any) => check.status === 'healthy');
+    const overallStatus = allHealthy ? 'healthy' : 'degraded';
+
+    // Log health check result
+    await Data.create('health-checks', {
+      status: overallStatus,
+      checks,
+      timestamp: new Date().toISOString()
+    });
+
+    // Alert if unhealthy (in production, send to monitoring service)
+    if (!allHealthy) {
+      console.warn('⚠️ System health degraded:', checks);
+      // TODO: Send alert to monitoring service
+    }
+
+    return {
+      status: overallStatus,
+      checks,
+      timestamp: new Date().toISOString()
+    };
+  }
+});
+
+export default healthCheckJob;
+

package/template/src/postprocessors/ResponseFormatter.ts

@@ -0,0 +1,151 @@
+/**
+ * Response Formatter PostProcessor
+ * 
+ * PostProcessors run AFTER the AI agent generates a response.
+ * They can:
+ * - Format or beautify responses
+ * - Add branding or signatures
+ * - Translate responses
+ * - Add disclaimers
+ * - Filter sensitive information
+ * - Adapt tone or style
+ * 
+ * The execute function receives:
+ * - user: UserDataInstance (current user info)
+ * - message: string (the user's original message)
+ * - response: string (the agent's generated response)
+ * - channel: string (where the response will be sent)
+ * 
+ * Returns: The formatted response that will be sent to the user
+ */
+
+import { PostProcessor } from "lua-cli";
+
+const responseFormatter = new PostProcessor({
+  name: "response-formatter",
+  version: "1.0.0",
+  description: "Formats and enhances agent responses before sending to users",
+  context: "This postprocessor adds branding, formats responses for different channels, and ensures consistency.",
+  
+  execute: async (user, message, response, channel) => {
+    console.log(`[ResponseFormatter] Formatting response for user ${user.id} via ${channel}`);
+    
+    let formattedResponse = response;
+    
+    // Example 1: Add personalized greeting for first-time users
+    if (user.metadata?.isFirstMessage) {
+      formattedResponse = `👋 Welcome, ${user.name || 'there'}! ${formattedResponse}`;
+    }
+    
+    // Example 2: Format based on channel
+    switch (channel.toLowerCase()) {
+      case 'sms':
+        // SMS: Keep it short, remove emojis, add link to full response
+        formattedResponse = formattedResponse
+          .replace(/[^\w\s.,!?-]/g, '') // Remove special chars
+          .substring(0, 160); // SMS limit
+        if (response.length > 160) {
+          formattedResponse += '... (continued at app.example.com)';
+        }
+        break;
+        
+      case 'email':
+        // Email: Add proper formatting and signature
+        formattedResponse = `
+<html>
+<body style="font-family: Arial, sans-serif; line-height: 1.6;">
+  <p>Hi ${user.name || 'there'},</p>
+  <p>${formattedResponse.replace(/\n/g, '<br>')}</p>
+  <br>
+  <p>Best regards,<br>
+  <strong>Zara</strong><br>
+  <em>Your E-commerce Assistant</em></p>
+  <hr>
+  <p style="font-size: 0.8em; color: #666;">
+    This is an automated response. Reply to this email if you need further assistance.
+  </p>
+</body>
+</html>`;
+        break;
+        
+      case 'slack':
+      case 'discord':
+        // Chat platforms: Add markdown formatting
+        formattedResponse = formattedResponse
+          .replace(/\*\*(.*?)\*\*/g, '*$1*') // Bold
+          .replace(/__(.*?)__/g, '_$1_'); // Italic
+        break;
+        
+      default:
+        // Default: Clean formatting
+        break;
+    }
+    
+    // Example 3: Add product links automatically
+    // Detect when products are mentioned and add quick links
+    const productMentionPattern = /(?:product|item|sku)[\s:]+(\w+)/gi;
+    const matches = formattedResponse.matchAll(productMentionPattern);
+    
+    for (const match of matches) {
+      const productId = match[1];
+      // You could look up actual product URLs here
+      formattedResponse = formattedResponse.replace(
+        match[0],
+        `${match[0]} [View](https://example.com/products/${productId})`
+      );
+    }
+    
+    // Example 4: Add helpful footer based on context
+    const hasOrderMention = /order|purchase|buy/i.test(message);
+    const hasBasketMention = /basket|cart|checkout/i.test(message);
+    
+    if (hasOrderMention) {
+      formattedResponse += '\n\n💡 Tip: You can track your orders anytime by asking "show my orders"';
+    } else if (hasBasketMention) {
+      formattedResponse += '\n\n🛒 Need help? Just ask me to "show my basket" or "checkout"';
+    }
+    
+    // Example 5: Filter sensitive information
+    // Remove any accidentally exposed sensitive data
+    formattedResponse = formattedResponse
+      .replace(/\b\d{16}\b/g, '****-****-****-****') // Credit card numbers
+      .replace(/\b\d{3}-\d{2}-\d{4}\b/g, '***-**-****') // SSN
+      .replace(/password[:\s]+\S+/gi, 'password: [REDACTED]'); // Passwords
+    
+    // Example 6: Add emoji based on sentiment (simple version)
+    if (/thank|great|awesome|love|perfect/i.test(message)) {
+      formattedResponse = `😊 ${formattedResponse}`;
+    } else if (/problem|issue|error|wrong|broken/i.test(message)) {
+      formattedResponse = `🔧 ${formattedResponse}`;
+    } else if (/help|how|what|where/i.test(message)) {
+      formattedResponse = `💡 ${formattedResponse}`;
+    }
+    
+    // Example 7: Add timestamp for long responses
+    if (formattedResponse.length > 500) {
+      const timestamp = new Date().toLocaleTimeString();
+      formattedResponse += `\n\n_Response generated at ${timestamp}_`;
+    }
+    
+    // Example 8: Add disclaimer for legal/financial advice
+    const needsDisclaimer = /legal|law|lawsuit|sue|invest|stock|crypto|tax/i.test(message);
+    if (needsDisclaimer) {
+      formattedResponse += '\n\n⚠️ _Disclaimer: This information is for general guidance only and should not be considered professional legal or financial advice. Please consult with a qualified professional for your specific situation._';
+    }
+    
+    // Example 9: Ensure proper length
+    const MAX_LENGTH = 4000; // Most platforms have limits
+    if (formattedResponse.length > MAX_LENGTH) {
+      formattedResponse = formattedResponse.substring(0, MAX_LENGTH - 50) + 
+        '...\n\n_Response truncated. Please ask for more specific information._';
+    }
+    
+    console.log(`[ResponseFormatter] Original length: ${response.length} chars`);
+    console.log(`[ResponseFormatter] Formatted length: ${formattedResponse.length} chars`);
+    
+    return formattedResponse;
+  }
+});
+
+export default responseFormatter;
+

package/template/src/preprocessors/MessageFilter.ts

@@ -0,0 +1,91 @@
+/**
+ * Message Filter PreProcessor
+ * 
+ * PreProcessors run BEFORE messages reach the AI agent.
+ * They can:
+ * - Filter out spam or inappropriate content
+ * - Translate messages
+ * - Add context to messages
+ * - Modify user input
+ * - Block certain types of requests
+ * 
+ * The execute function receives:
+ * - user: UserDataInstance (current user info)
+ * - message: string (the user's message)
+ * - channel: string (where the message came from)
+ * 
+ * Returns: The potentially modified message that will be sent to the agent
+ */
+
+import { PreProcessor } from "lua-cli";
+
+const messageFilter = new PreProcessor({
+  name: "message-filter",
+  version: "1.0.0",
+  description: "Filters and preprocesses user messages before they reach the agent",
+  context: "This preprocessor removes spam, blocks inappropriate content, and adds helpful context to user messages.",
+  
+  execute: async (user, message, channel) => {
+    console.log(`[MessageFilter] Processing message from user ${user.id} via ${channel}`);
+    
+    // Example 1: Block spam patterns
+    const spamPatterns = [
+      /buy now/i,
+      /click here/i,
+      /free money/i,
+      /\b(viagra|cialis)\b/i
+    ];
+    
+    for (const pattern of spamPatterns) {
+      if (pattern.test(message)) {
+        console.log('[MessageFilter] Spam detected, blocking message');
+        return "[This message was blocked by spam filter]";
+      }
+    }
+    
+    // Example 2: Remove excessive punctuation
+    let filteredMessage = message.replace(/([!?.]){3,}/g, '$1$1'); // Reduce !!!!! to !!
+    
+    // Example 3: Normalize whitespace
+    filteredMessage = filteredMessage.trim().replace(/\s+/g, ' ');
+    
+    // Example 4: Add user context for the agent
+    // This helps the agent understand who they're talking to
+    if (user.name && !filteredMessage.toLowerCase().includes('my name')) {
+      // Agent will have context about user's name without being intrusive
+      filteredMessage = `[User: ${user.name}] ${filteredMessage}`;
+    }
+    
+    // Example 5: Detect and flag urgent messages
+    const urgentKeywords = ['urgent', 'emergency', 'asap', 'immediately', 'help'];
+    const isUrgent = urgentKeywords.some(keyword => 
+      filteredMessage.toLowerCase().includes(keyword)
+    );
+    
+    if (isUrgent) {
+      filteredMessage = `[URGENT] ${filteredMessage}`;
+      console.log('[MessageFilter] Urgent message flagged');
+    }
+    
+    // Example 6: Add channel context
+    // This helps the agent adapt its response based on the channel
+    if (channel && channel !== 'default') {
+      filteredMessage = `[Via ${channel}] ${filteredMessage}`;
+    }
+    
+    // Example 7: Language detection hint (optional)
+    // You could integrate with a language detection library here
+    const hasNonEnglish = /[^\u0000-\u007F]/.test(message);
+    if (hasNonEnglish) {
+      filteredMessage = `[Contains non-ASCII characters] ${filteredMessage}`;
+    }
+    
+    console.log(`[MessageFilter] Original: "${message}"`);
+    console.log(`[MessageFilter] Filtered: "${filteredMessage}"`);
+    
+    return filteredMessage;
+  }
+});
+
+export default messageFilter;
+

package/template/src/tools/GameScoreTrackerTool.ts

@@ -0,0 +1,356 @@
+/**
+ * Game Score Tracker Tool - Complex Dynamic Job Example
+ * 
+ * This tool demonstrates:
+ * 1. Creating a game tracking record
+ * 2. Creating an interval job that starts at game time
+ * 3. Job fetches score updates periodically
+ * 4. Job checks if game is over
+ * 5. Job deactivates itself when game ends
+ * 
+ * Use case: Live sports score tracking, esports matches, auction monitoring
+ */
+
+import { LuaTool, Jobs, Data } from "lua-cli";
+import { z } from "zod";
+
+export class TrackGameScoresTool implements LuaTool {
+  name = "track_game_scores";
+  description = "Track live scores for a game with automatic updates";
+  
+  inputSchema = z.object({
+    gameId: z.string(),
+    gameName: z.string(),
+    startTime: z.string(), // ISO 8601 timestamp
+    updateIntervalSeconds: z.number().min(30).max(600).default(60), // 30s to 10min
+    apiEndpoint: z.string().optional() // Optional external API
+  });
+
+  async execute(input: {
+    gameId: string;
+    gameName: string;
+    startTime: string;
+    updateIntervalSeconds: number;
+    apiEndpoint?: string;
+  }) {
+    console.log(`🎮 Setting up score tracking for: ${input.gameName}`);
+
+    // Step 1: Create game record in database
+    const gameRecord = {
+      gameId: input.gameId,
+      gameName: input.gameName,
+      startTime: input.startTime,
+      status: 'scheduled',
+      currentScore: { home: 0, away: 0 },
+      lastUpdate: new Date().toISOString(),
+      createdAt: new Date().toISOString()
+    };
+
+    const game = await Data.create('games', gameRecord, 
+      `${input.gameName} ${input.gameId}`
+    );
+
+    console.log(`✅ Game record created: ${game.id}`);
+
+    // Step 2: Calculate when the job should start
+    const gameStartTime = new Date(input.startTime);
+    const now = new Date();
+
+    // If game hasn't started yet, schedule job to start at game time
+    // If game already started, start immediately
+    const jobStartTime = gameStartTime > now ? gameStartTime : now;
+
+    console.log(`⏰ Job will start at: ${jobStartTime.toLocaleString()}`);
+    console.log(`🔄 Updates every ${input.updateIntervalSeconds} seconds`);
+
+    // Step 3: Capture variables for the job closure
+    const gameId = input.gameId;
+    const gameName = input.gameName;
+    const intervalSeconds = input.updateIntervalSeconds;
+    const apiEndpoint = input.apiEndpoint || 'https://api.example.com/scores';
+    const gameRecordId = game.id;
+
+    // Step 4: Create an interval job that monitors the game
+    // This job will run every X seconds and stop itself when game ends
+    const job = await Jobs.create({
+      name: `track-game-${gameId}`,
+      description: `Live score tracking for ${gameName}`,
+      
+      // Important: Use interval schedule
+      schedule: {
+        type: 'interval',
+        seconds: intervalSeconds
+      },
+      
+      timeout: 30,  // Each update should complete in 30 seconds
+      
+      retry: {
+        maxAttempts: 2,  // Retry failed updates
+        backoffSeconds: 10
+      },
+      
+      // The job logic - runs every interval until game ends
+      execute: async () => {
+        console.log('🎮 Fetching score update for game ' + gameId + '...');
+        
+        try {
+          // Fetch current game data from our database
+          const gameData = await Data.getEntry('games', gameRecordId);
+          
+          // Check if game is already over
+          if (gameData.data.status === 'finished') {
+            console.log('🏁 Game ' + gameId + ' is already finished. Stopping job.');
+            
+            // IMPORTANT: Job stops itself!
+            await Jobs.deactivate(job.jobId);
+            
+            return {
+              action: 'job-stopped',
+              reason: 'game-finished',
+              gameId: gameId,
+              finalScore: gameData.data.currentScore
+            };
+          }
+          
+          // Fetch latest scores from external API
+          let scoreUpdate;
+          try {
+            const response = await fetch(apiEndpoint + '/' + gameId);
+            
+            if (!response.ok) {
+              throw new Error('API returned ' + response.status);
+            }
+            
+            scoreUpdate = await response.json();
+          } catch (apiError) {
+            // If external API fails, generate mock data for demo
+            console.warn('External API failed, using mock data:', apiError);
+            
+            // Simulate score progression
+            const currentScore = gameData.data.currentScore;
+            scoreUpdate = {
+              home: currentScore.home + Math.floor(Math.random() * 2),
+              away: currentScore.away + Math.floor(Math.random() * 2),
+              quarter: Math.min(4, Math.floor(Date.now() / 1000 / 60 / 15) % 5),
+              timeRemaining: '12:34',
+              isFinished: Math.random() > 0.9  // 10% chance game ends
+            };
+          }
+          
+          // Update game record with new scores
+          const updatedGame = await Data.update('games', gameRecordId, {
+            ...gameData.data,
+            currentScore: {
+              home: scoreUpdate.home,
+              away: scoreUpdate.away
+            },
+            quarter: scoreUpdate.quarter,
+            timeRemaining: scoreUpdate.timeRemaining,
+            status: scoreUpdate.isFinished ? 'finished' : 'in-progress',
+            lastUpdate: new Date().toISOString()
+          });
+          
+          console.log('📊 Score update: ' + scoreUpdate.home + ' - ' + scoreUpdate.away);
+          
+          // Check if game just ended
+          if (scoreUpdate.isFinished) {
+            console.log('🏁 Game ' + gameId + ' has finished!');
+            console.log('Final score: ' + scoreUpdate.home + ' - ' + scoreUpdate.away);
+            
+            // Store final game result
+            await Data.create('game-results', {
+              gameId: gameId,
+              gameName: gameName,
+              finalScore: {
+                home: scoreUpdate.home,
+                away: scoreUpdate.away
+              },
+              finishedAt: new Date().toISOString()
+            });
+            
+            // IMPORTANT: Job stops itself when game ends!
+            await Jobs.deactivate(job.jobId);
+            
+            console.log('⏹️  Score tracking job stopped for game ' + gameId);
+            
+            return {
+              action: 'game-ended-job-stopped',
+              gameId: gameId,
+              finalScore: {
+                home: scoreUpdate.home,
+                away: scoreUpdate.away
+              }
+            };
+          }
+          
+          // Game still in progress
+          return {
+            action: 'score-updated',
+            gameId: gameId,
+            currentScore: {
+              home: scoreUpdate.home,
+              away: scoreUpdate.away
+            },
+            quarter: scoreUpdate.quarter,
+            timeRemaining: scoreUpdate.timeRemaining
+          };
+          
+        } catch (error: any) {
+          console.error('❌ Error updating score for game ' + gameId + ':', error);
+          
+          // Don't stop job on errors - just log and continue
+          return {
+            action: 'error',
+            gameId: gameId,
+            error: error.message
+          };
+        }
+      }
+    });
+
+    console.log(`✅ Score tracking job created: ${job.jobId}`);
+    console.log(`📊 Job will update scores every ${input.updateIntervalSeconds} seconds`);
+    console.log(`⏹️  Job will automatically stop when game ends`);
+
+    return {
+      success: true,
+      game: {
+        id: game.id,
+        gameId: input.gameId,
+        name: input.gameName,
+        startTime: input.startTime,
+        status: 'scheduled'
+      },
+      scoreTracker: {
+        jobId: job.jobId,
+        jobName: job.name,
+        updateInterval: input.updateIntervalSeconds,
+        startsAt: jobStartTime.toISOString(),
+        message: 'Job will automatically stop when game ends'
+      }
+    };
+  }
+}
+
+/**
+ * Get Game Scores Tool
+ * 
+ * Retrieves current scores for a game or all active games
+ */
+export class GetGameScoresTool implements LuaTool {
+  name = "get_game_scores";
+  description = "Get current scores for tracked games";
+  
+  inputSchema = z.object({
+    gameId: z.string().optional()
+  });
+
+  async execute(input: { gameId?: string }) {
+    if (input.gameId) {
+      // Get specific game
+      const games = await Data.get('games', {}, 1, 100);
+      const game = games.data?.find((g: any) => g.data.gameId === input.gameId);
+      
+      if (!game) {
+        return {
+          found: false,
+          gameId: input.gameId,
+          message: 'Game not found'
+        };
+      }
+
+      return {
+        found: true,
+        game: {
+          gameId: game.data.gameId,
+          name: game.data.gameName,
+          status: game.data.status,
+          currentScore: game.data.currentScore,
+          quarter: game.data.quarter,
+          timeRemaining: game.data.timeRemaining,
+          lastUpdate: game.data.lastUpdate
+        }
+      };
+    }
+
+    // Get all active games
+    const allGames = await Data.get('games', {}, 1, 50);
+    
+    const activeGames = (allGames.data || [])
+      .filter((g: any) => g.data.status === 'in-progress' || g.data.status === 'scheduled')
+      .map((g: any) => ({
+        gameId: g.data.gameId,
+        name: g.data.gameName,
+        status: g.data.status,
+        currentScore: g.data.currentScore,
+        lastUpdate: g.data.lastUpdate
+      }));
+
+    return {
+      activeGamesCount: activeGames.length,
+      games: activeGames
+    };
+  }
+}
+
+/**
+ * Stop Game Tracking Tool
+ * 
+ * Manually stops score tracking for a game
+ */
+export class StopGameTrackingTool implements LuaTool {
+  name = "stop_game_tracking";
+  description = "Manually stop score tracking for a game";
+  
+  inputSchema = z.object({
+    gameId: z.string()
+  });
+
+  async execute(input: { gameId: string }) {
+    console.log(`⏹️  Stopping score tracking for game ${input.gameId}...`);
+
+    // Find the tracking job
+    const allJobs = await Jobs.getAll();
+    
+    if (!allJobs.success || !allJobs.data) {
+      throw new Error('Failed to fetch jobs');
+    }
+
+    const trackingJob = allJobs.data.jobs.find((j: any) => 
+      j.name === `track-game-${input.gameId}`
+    );
+
+    if (!trackingJob) {
+      return {
+        success: false,
+        gameId: input.gameId,
+        message: 'No tracking job found for this game'
+      };
+    }
+
+    // Deactivate the job
+    const result = await Jobs.deactivate(trackingJob.id);
+
+    // Update game status
+    const games = await Data.get('games', {}, 1, 100);
+    const game = games.data?.find((g: any) => g.data.gameId === input.gameId);
+    
+    if (game) {
+      await Data.update('games', game.id, {
+        ...game.data,
+        status: 'stopped',
+        stoppedAt: new Date().toISOString()
+      });
+    }
+
+    console.log(`✅ Score tracking stopped for game ${input.gameId}`);
+
+    return {
+      success: true,
+      gameId: input.gameId,
+      jobId: trackingJob.id,
+      message: 'Score tracking stopped successfully'
+    };
+  }
+}
+