lua-cli 3.0.0-alpha.1 → 3.0.0-alpha.5

package/template/DYNAMIC_JOB_CREATION.md

@@ -1,371 +0,0 @@
-# Dynamic Job Creation from Tools
-
-**Question:** Why doesn't the SmartBasketTool actually create a job?
-
-**Answer:** There are **two approaches** for scheduling future tasks from tools. The example shows both!
-
----
-
-## 🎯 Two Approaches Explained
-
-### **Approach 1: Data-Based Scheduling** ✅ (Currently Implemented)
-
-**How it works:**
-1. Tool stores reminder data in custom data collection
-2. A recurring job checks for due reminders
-3. When time comes, job processes the reminder
-
-**Pros:**
-- ✅ Simple to implement
-- ✅ No dynamic job creation needed
-- ✅ Works now (no backend changes required)
-- ✅ Easy to manage (single recurring job)
-
-**Cons:**
-- ⚠️ Requires a recurring job to run frequently
-- ⚠️ Less precise timing (depends on job interval)
-- ⚠️ More database queries
-
-**Code:**
-```typescript
-// In the tool:
-await Data.create('basket-reminders', {
-  basketId: basket.id,
-  scheduledFor: checkTime.toISOString(),
-  status: 'pending'
-});
-
-// Separate recurring job (every 15 minutes):
-const reminders = await Data.get('basket-reminders', {});
-for (const reminder of reminders) {
-  if (new Date(reminder.scheduledFor) <= now) {
-    // Process reminder
-  }
-}
-```
-
----
-
-### **Approach 2: Dynamic Job Creation** 🚀 (Advanced - Commented Out)
-
-**How it works:**
-1. Tool creates a one-time job via API
-2. Backend scheduler runs the job at exact time
-3. Job executes once and auto-deactivates
-
-**Pros:**
-- ✅ Precise timing (exact execution time)
-- ✅ No polling/recurring job needed
-- ✅ Each task is isolated
-- ✅ Auto-cleanup after execution
-
-**Cons:**
-- ⚠️ Requires backend API support (create jobs endpoint)
-- ⚠️ More complex implementation
-- ⚠️ More jobs in system (one per basket)
-
-**Code (when backend supports it):**
-```typescript
-// Create job dynamically
-const jobPayload = {
-  name: `check-basket-${basket.id}`,
-  schedule: {
-    type: 'once',
-    executeAt: checkTime.toISOString()
-  },
-  executeFunction: `
-    async () => {
-      const basket = await Baskets.getById('${basket.id}');
-      if (basket.status === 'active') {
-        // Send reminder
-      }
-    }
-  `
-};
-
-await fetch('/developer/jobs/{agentId}', {
-  method: 'POST',
-  body: JSON.stringify(jobPayload)
-});
-```
-
----
-
-## 📊 Comparison
-
-| Feature | Approach 1 (Data-Based) | Approach 2 (Dynamic Jobs) |
-|---------|------------------------|---------------------------|
-| **Complexity** | ⭐ Simple | ⭐⭐⭐ Complex |
-| **Timing Precision** | ~15 minutes | Exact |
-| **Backend Support** | ✅ Available now | ⏳ Coming soon |
-| **Jobs Created** | 1 recurring | 1 per basket |
-| **Database Queries** | High | Low |
-| **Best For** | Most use cases | High-precision timing |
-
----
-
-## 🎯 When to Use Each Approach
-
-### Use Approach 1 (Data-Based) When:
-- ✅ Timing doesn't need to be exact (±15 minutes is fine)
-- ✅ You have many similar scheduled tasks
-- ✅ You want simpler code
-- ✅ Backend doesn't support dynamic job creation yet
-
-**Examples:**
-- Abandoned cart reminders (3 hours ± 15 min is fine)
-- Follow-up emails (24 hours ± 15 min is fine)
-- Subscription renewals (checking daily is fine)
-
-### Use Approach 2 (Dynamic Jobs) When:
-- ✅ Timing must be exact
-- ✅ Each task is unique
-- ✅ You want isolated execution
-- ✅ Backend supports job creation API
-
-**Examples:**
-- Scheduled content publishing (must be exact time)
-- Billing cycles (must be precise)
-- Auction endings (exact second matters)
-- Appointment reminders (exact timing important)
-
----
-
-## 🔧 Implementation Details
-
-### Approach 1: Complete Flow
-
-**Step 1 - Tool stores reminder:**
-```typescript
-// SmartBasketTool.ts
-await Data.create('basket-reminders', {
-  basketId: basket.id,
-  scheduledFor: new Date(Date.now() + 3 * 60 * 60 * 1000).toISOString(),
-  status: 'pending'
-});
-```
-
-**Step 2 - Recurring job processes reminders:**
-```typescript
-// AbandonedBasketProcessorJob.ts
-const job = new LuaJob({
-  name: "process-basket-reminders",
-  schedule: {
-    type: 'interval',
-    seconds: 900  // Every 15 minutes
-  },
-  execute: async () => {
-    const reminders = await Data.get('basket-reminders', {});
-    const now = new Date();
-    
-    for (const reminder of reminders) {
-      if (new Date(reminder.scheduledFor) <= now && reminder.status === 'pending') {
-        // Check basket and send reminder if abandoned
-        const basket = await Baskets.getById(reminder.basketId);
-        
-        if (basket.status === 'active') {
-          // Send reminder
-          console.log(`📧 Sending reminder for basket ${basket.id}`);
-        }
-        
-        // Mark as processed
-        await Data.update('basket-reminders', reminder.id, { status: 'completed' });
-      }
-    }
-  }
-});
-```
-
----
-
-### Approach 2: Complete Flow (When Available)
-
-**Step 1 - Tool creates job via API:**
-```typescript
-// SmartBasketTool.ts
-const jobPayload = {
-  name: `check-basket-${basket.id}`,
-  description: `Check basket ${basket.id}`,
-  schedule: {
-    type: 'once',
-    executeAt: new Date(Date.now() + 3 * 60 * 60 * 1000).toISOString()
-  },
-  executeFunction: `
-    async () => {
-      const basket = await Baskets.getById('${basket.id}');
-      if (basket.status === 'active') {
-        await Data.create('abandoned-baskets', { basketId: '${basket.id}' });
-        // Send reminder
-      }
-      return { checked: true };
-    }
-  `
-};
-
-// Create job
-const response = await fetch(`/developer/jobs/{agentId}`, {
-  method: 'POST',
-  headers: { 'Authorization': `Bearer ${apiKey}` },
-  body: JSON.stringify(jobPayload)
-});
-
-const job = await response.json();
-
-// Push version to activate it
-await fetch(`/developer/jobs/{agentId}/${job.id}/version`, {
-  method: 'POST',
-  body: JSON.stringify({ ...jobPayload, version: '1.0.0', jobId: job.id })
-});
-```
-
-**Step 2 - Backend scheduler:**
-- Job is created and scheduled
-- At exactly 3 hours later, job executes
-- Job runs once and auto-deactivates
-- Result is logged in execution history
-
----
-
-## 🚀 Current Implementation (Approach 1)
-
-The `SmartBasketTool` currently uses **Approach 1** because:
-
-1. ✅ **Works immediately** - No backend changes needed
-2. ✅ **Simple** - Easy to understand and maintain
-3. ✅ **Sufficient** - 15-minute precision is fine for cart reminders
-4. ✅ **Scalable** - One job handles all baskets
-
-**Files involved:**
-- `src/tools/SmartBasketTool.ts` - Creates basket + stores reminder
-- `src/jobs/AbandonedBasketProcessorJob.ts` - Processes reminders every 15 min
-
-**To enable:**
-```typescript
-// In src/index.ts
-import { CreateSmartBasketTool } from "./tools/SmartBasketTool";
-import abandonedBasketProcessorJob from "./jobs/AbandonedBasketProcessorJob";
-
-const basketSkill = new LuaSkill({
-  tools: [new CreateSmartBasketTool()]
-});
-```
-
----
-
-## 🔮 Future: Approach 2 (When Backend Ready)
-
-When the backend implements dynamic job creation API, you can:
-
-1. **Uncomment Approach 2** in `SmartBasketTool.ts`
-2. **Remove the data-based reminder** code
-3. **Remove the recurring processor job** (no longer needed)
-
-**Benefits:**
-- Jobs execute at **exact** 3-hour mark
-- No recurring job needed
-- Each basket gets its own isolated job
-- Automatic cleanup after execution
-
----
-
-## 💡 Hybrid Approach (Best of Both Worlds)
-
-You can also combine both approaches:
-
-```typescript
-async execute(input: { currency: string }) {
-  const basket = await Baskets.create({ currency: input.currency });
-  
-  // Approach 1: Quick fallback (works now)
-  await Data.create('basket-reminders', {
-    basketId: basket.id,
-    scheduledFor: checkTime.toISOString()
-  });
-  
-  // Approach 2: Try dynamic job (if backend supports it)
-  try {
-    const jobResponse = await createDynamicJob(basket.id, checkTime);
-    if (jobResponse.ok) {
-      // Dynamic job created - mark data reminder as redundant
-      await Data.update('basket-reminders', reminder.id, {
-        status: 'delegated-to-job'
-      });
-    }
-  } catch (error) {
-    // Fall back to approach 1 (already stored)
-    console.log('Using data-based reminder (dynamic jobs not available)');
-  }
-  
-  return { success: true, basket };
-}
-```
-
----
-
-## 📋 Summary
-
-### Current State ✅
-- ✅ **SmartBasketTool** stores reminders in data
-- ✅ **AbandonedBasketProcessorJob** processes them every 15 minutes
-- ✅ **Works perfectly** for abandoned cart recovery
-- ✅ **No backend changes needed**
-
-### Why No Real Job Created?
-Because **Approach 1 is simpler and sufficient** for most use cases!
-
-### When Will Approach 2 Work?
-When backend implements:
-- `POST /developer/jobs/{agentId}` - Create job endpoint
-- `POST /developer/jobs/{agentId}/{jobId}/version` - Push job version
-
-Then you can uncomment the code in lines 65-134 of `SmartBasketTool.ts`!
-
----
-
-## 🎓 Teaching Point
-
-This example teaches an important pattern:
-
-> **"Not every future task needs a separate job!"**
-
-Sometimes storing data and processing it with a recurring job is:
-- Simpler
-- More efficient
-- Easier to manage
-- Perfectly adequate
-
-**Use dynamic job creation when you truly need precision timing.**
-
----
-
-## 🚀 Try It Out
-
-```bash
-# 1. Enable the example
-# Uncomment in src/index.ts:
-# - CreateSmartBasketTool
-# - AbandonedBasketProcessorJob
-
-# 2. Compile
-lua compile
-
-# 3. Test the tool
-lua test skill
-# Select: create_smart_basket
-# See: Basket created + reminder stored
-
-# 4. Test the processor job
-lua test job  
-# Select: process-basket-reminders
-# See: Reminders checked and processed
-
-# 5. Deploy both
-lua push skill
-lua push job
-lua jobs production  # Activate processor job
-```
-
----
-
-**The system is designed to work today, with an upgrade path to dynamic jobs in the future!** 🎯
-