monitoring

demo-tools.ts

@@ -1,96 +0,0 @@
-#!/usr/bin/env bun
-
-console.log("Starting demo script...");
-
-import { OpenAIService } from "./src/openai-service";
-
-console.log("OpenAI service imported successfully");
-
-const openAIService = new OpenAIService();
-
-console.log("OpenAI service initialized");
-
-// Demo function calling scenarios
-async function demoFunctionCalling() {
-  console.log("🚀 DuckAI Function Calling Demo\n");
-
-  // Scenario 1: Time function with tool_choice required
-  console.log("📅 Scenario 1: Getting current time (tool_choice: required)");
-  try {
-    const timeRequest = {
-      model: "gpt-4o-mini",
-      messages: [{ role: "user", content: "What time is it?" }],
-      tools: [
-        {
-          type: "function",
-          function: {
-            name: "get_current_time",
-            description: "Get the current time",
-          },
-        },
-      ],
-      tool_choice: "required" as const,
-    };
-
-    const timeResponse = await openAIService.createChatCompletion(timeRequest);
-    console.log("Response:", JSON.stringify(timeResponse, null, 2));
-
-    // Execute the tool call if present
-    if (timeResponse.choices[0].message.tool_calls) {
-      const toolCall = timeResponse.choices[0].message.tool_calls[0];
-      const result = await openAIService.executeToolCall(toolCall);
-      console.log("Tool execution result:", result);
-    }
-  } catch (error) {
-    console.error("Error:", error);
-  }
-
-  console.log("\n" + "=".repeat(60) + "\n");
-
-  // Scenario 2: Calculator function
-  console.log("🧮 Scenario 2: Mathematical calculation");
-  try {
-    const calcRequest = {
-      model: "gpt-4o-mini",
-      messages: [{ role: "user", content: "Calculate 25 * 4 + 10" }],
-      tools: [
-        {
-          type: "function",
-          function: {
-            name: "calculate",
-            description: "Perform mathematical calculations",
-            parameters: {
-              type: "object",
-              properties: {
-                expression: {
-                  type: "string",
-                  description: "Mathematical expression to evaluate",
-                },
-              },
-              required: ["expression"],
-            },
-          },
-        },
-      ],
-      tool_choice: "required" as const,
-    };
-
-    const calcResponse = await openAIService.createChatCompletion(calcRequest);
-    console.log("Response:", JSON.stringify(calcResponse, null, 2));
-
-    // Execute the tool call if present
-    if (calcResponse.choices[0].message.tool_calls) {
-      const toolCall = calcResponse.choices[0].message.tool_calls[0];
-      const result = await openAIService.executeToolCall(toolCall);
-      console.log("Tool execution result:", result);
-    }
-  } catch (error) {
-    console.error("Error:", error);
-  }
-
-  console.log("\n✅ Demo completed!");
-}
-
-// Run the demo
-console.log("About to run demo...");
-demoFunctionCalling().catch(console.error);

src/duckai.ts

@@ -1,5 +1,6 @@
 import UserAgent from "user-agents";
 import { JSDOM } from "jsdom";
+import { RateLimitStore } from "./rate-limit-store";
 import type {
   ChatCompletionMessage,
   VQDResponse,
@@ -8,7 +9,187 @@ import type {
 
 const userAgent = new UserAgent();
 
+// Rate limiting tracking
+interface RateLimitInfo {
+  requestCount: number;
+  windowStart: number;
+  lastRequestTime: number;
+  isLimited: boolean;
+  retryAfter?: number;
+}
+
 export class DuckAI {
+  private rateLimitInfo: RateLimitInfo = {
+    requestCount: 0,
+    windowStart: Date.now(),
+    lastRequestTime: 0,
+    isLimited: false,
+  };
+  private rateLimitStore: RateLimitStore;
+
+  // Conservative rate limiting - adjust based on observed limits
+  private readonly MAX_REQUESTS_PER_MINUTE = 20;
+  private readonly WINDOW_SIZE_MS = 60 * 1000; // 1 minute
+  private readonly MIN_REQUEST_INTERVAL_MS = 1000; // 1 second between requests
+
+  constructor() {
+    this.rateLimitStore = new RateLimitStore();
+    this.loadRateLimitFromStore();
+  }
+
+  /**
+   * Load rate limit data from shared store
+   */
+  private loadRateLimitFromStore(): void {
+    const stored = this.rateLimitStore.read();
+    if (stored) {
+      this.rateLimitInfo = {
+        requestCount: stored.requestCount,
+        windowStart: stored.windowStart,
+        lastRequestTime: stored.lastRequestTime,
+        isLimited: stored.isLimited,
+        retryAfter: stored.retryAfter,
+      };
+    }
+  }
+
+  /**
+   * Save rate limit data to shared store
+   */
+  private saveRateLimitToStore(): void {
+    this.rateLimitStore.write({
+      requestCount: this.rateLimitInfo.requestCount,
+      windowStart: this.rateLimitInfo.windowStart,
+      lastRequestTime: this.rateLimitInfo.lastRequestTime,
+      isLimited: this.rateLimitInfo.isLimited,
+      retryAfter: this.rateLimitInfo.retryAfter,
+    });
+  }
+
+  /**
+   * Get current rate limit status
+   */
+  getRateLimitStatus(): {
+    requestsInCurrentWindow: number;
+    maxRequestsPerMinute: number;
+    timeUntilWindowReset: number;
+    isCurrentlyLimited: boolean;
+    recommendedWaitTime: number;
+  } {
+    // Load latest data from store first
+    this.loadRateLimitFromStore();
+
+    const now = Date.now();
+    const windowElapsed = now - this.rateLimitInfo.windowStart;
+
+    // Reset window if it's been more than a minute
+    if (windowElapsed >= this.WINDOW_SIZE_MS) {
+      this.rateLimitInfo.requestCount = 0;
+      this.rateLimitInfo.windowStart = now;
+      this.saveRateLimitToStore();
+    }
+
+    const timeUntilReset = Math.max(0, this.WINDOW_SIZE_MS - windowElapsed);
+    const timeSinceLastRequest = now - this.rateLimitInfo.lastRequestTime;
+    const recommendedWait = Math.max(
+      0,
+      this.MIN_REQUEST_INTERVAL_MS - timeSinceLastRequest
+    );
+
+    return {
+      requestsInCurrentWindow: this.rateLimitInfo.requestCount,
+      maxRequestsPerMinute: this.MAX_REQUESTS_PER_MINUTE,
+      timeUntilWindowReset: timeUntilReset,
+      isCurrentlyLimited: this.rateLimitInfo.isLimited,
+      recommendedWaitTime: recommendedWait,
+    };
+  }
+
+  /**
+   * Check if we should wait before making a request
+   */
+  private shouldWaitBeforeRequest(): { shouldWait: boolean; waitTime: number } {
+    // Load latest data from store first
+    this.loadRateLimitFromStore();
+
+    const now = Date.now();
+    const windowElapsed = now - this.rateLimitInfo.windowStart;
+
+    // Reset window if needed
+    if (windowElapsed >= this.WINDOW_SIZE_MS) {
+      this.rateLimitInfo.requestCount = 0;
+      this.rateLimitInfo.windowStart = now;
+      this.rateLimitInfo.isLimited = false;
+      this.saveRateLimitToStore();
+    }
+
+    // Check if we're hitting the rate limit
+    if (this.rateLimitInfo.requestCount >= this.MAX_REQUESTS_PER_MINUTE) {
+      const timeUntilReset = this.WINDOW_SIZE_MS - windowElapsed;
+      return { shouldWait: true, waitTime: timeUntilReset };
+    }
+
+    // Check minimum interval between requests
+    const timeSinceLastRequest = now - this.rateLimitInfo.lastRequestTime;
+    if (timeSinceLastRequest < this.MIN_REQUEST_INTERVAL_MS) {
+      const waitTime = this.MIN_REQUEST_INTERVAL_MS - timeSinceLastRequest;
+      return { shouldWait: true, waitTime };
+    }
+
+    return { shouldWait: false, waitTime: 0 };
+  }
+
+  /**
+   * Update rate limit tracking after a request
+   */
+  private updateRateLimitTracking(response: Response) {
+    const now = Date.now();
+    this.rateLimitInfo.requestCount++;
+    this.rateLimitInfo.lastRequestTime = now;
+
+    // Check for rate limit headers (DuckDuckGo might not send these, but we'll check)
+    const rateLimitRemaining = response.headers.get("x-ratelimit-remaining");
+    const rateLimitReset = response.headers.get("x-ratelimit-reset");
+    const retryAfter = response.headers.get("retry-after");
+
+    if (response.status === 429) {
+      this.rateLimitInfo.isLimited = true;
+      if (retryAfter) {
+        this.rateLimitInfo.retryAfter = parseInt(retryAfter) * 1000; // Convert to ms
+      }
+      console.warn("Rate limited by DuckAI API:", {
+        status: response.status,
+        retryAfter: retryAfter,
+        rateLimitRemaining,
+        rateLimitReset,
+      });
+    }
+
+    // Log rate limit info if headers are present
+    if (rateLimitRemaining || rateLimitReset) {
+      console.log("DuckAI Rate Limit Info:", {
+        remaining: rateLimitRemaining,
+        reset: rateLimitReset,
+        currentCount: this.rateLimitInfo.requestCount,
+      });
+    }
+
+    // Save updated rate limit info to store
+    this.saveRateLimitToStore();
+  }
+
+  /**
+   * Wait if necessary before making a request
+   */
+  private async waitIfNeeded(): Promise<void> {
+    const { shouldWait, waitTime } = this.shouldWaitBeforeRequest();
+
+    if (shouldWait) {
+      console.log(`Rate limiting: waiting ${waitTime}ms before next request`);
+      await new Promise((resolve) => setTimeout(resolve, waitTime));
+    }
+  }
+
   private async getVQD(): Promise<VQDResponse> {
     const response = await fetch("https://duckduckgo.com/duckchat/v1/status", {
       headers: {
@@ -70,6 +251,9 @@ export class DuckAI {
   }
 
   async chat(request: DuckAIRequest): Promise<string> {
+    // Wait if rate limiting is needed
+    await this.waitIfNeeded();
+
     const vqd = await this.getVQD();
 
     const { window } = new JSDOM(
@@ -84,6 +268,12 @@ export class DuckAI {
 
     const clientHashes = await this.hashClientHashes(hash.client_hashes);
 
+    // Update rate limit tracking BEFORE making the request
+    const now = Date.now();
+    this.rateLimitInfo.requestCount++;
+    this.rateLimitInfo.lastRequestTime = now;
+    this.saveRateLimitToStore();
+
     const response = await fetch("https://duckduckgo.com/duckchat/v1/chat", {
       headers: {
         accept: "text/event-stream",
@@ -114,6 +304,21 @@ export class DuckAI {
       credentials: "include",
     });
 
+    // Handle rate limiting
+    if (response.status === 429) {
+      const retryAfter = response.headers.get("retry-after");
+      const waitTime = retryAfter ? parseInt(retryAfter) * 1000 : 60000; // Default 1 minute
+      throw new Error(
+        `Rate limited. Retry after ${waitTime}ms. Status: ${response.status}`
+      );
+    }
+
+    if (!response.ok) {
+      throw new Error(
+        `DuckAI API error: ${response.status} ${response.statusText}`
+      );
+    }
+
     const text = await response.text();
 
     // Check for errors
@@ -154,6 +359,9 @@ export class DuckAI {
   }
 
   async chatStream(request: DuckAIRequest): Promise<ReadableStream<string>> {
+    // Wait if rate limiting is needed
+    await this.waitIfNeeded();
+
     const vqd = await this.getVQD();
 
     const { window } = new JSDOM(
@@ -168,6 +376,12 @@ export class DuckAI {
 
     const clientHashes = await this.hashClientHashes(hash.client_hashes);
 
+    // Update rate limit tracking BEFORE making the request
+    const now = Date.now();
+    this.rateLimitInfo.requestCount++;
+    this.rateLimitInfo.lastRequestTime = now;
+    this.saveRateLimitToStore();
+
     const response = await fetch("https://duckduckgo.com/duckchat/v1/chat", {
       headers: {
         accept: "text/event-stream",
@@ -198,6 +412,21 @@ export class DuckAI {
       credentials: "include",
     });
 
+    // Handle rate limiting
+    if (response.status === 429) {
+      const retryAfter = response.headers.get("retry-after");
+      const waitTime = retryAfter ? parseInt(retryAfter) * 1000 : 60000; // Default 1 minute
+      throw new Error(
+        `Rate limited. Retry after ${waitTime}ms. Status: ${response.status}`
+      );
+    }
+
+    if (!response.ok) {
+      throw new Error(
+        `DuckAI API error: ${response.status} ${response.statusText}`
+      );
+    }
+
     if (!response.body) {
       throw new Error("No response body");
     }

src/openai-service.ts

@@ -625,4 +625,11 @@ export class OpenAIService {
       this.availableFunctions
     );
   }
+
+  /**
+   * Get current rate limit status from DuckAI
+   */
+  getRateLimitStatus() {
+    return this.duckAI.getRateLimitStatus();
+  }
 }

src/rate-limit-store.ts

@@ -0,0 +1,108 @@
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "fs";
+import { join } from "path";
+import { tmpdir } from "os";
+
+interface RateLimitData {
+  requestCount: number;
+  windowStart: number;
+  lastRequestTime: number;
+  isLimited: boolean;
+  retryAfter?: number;
+  processId: string;
+  lastUpdated: number;
+}
+
+export class RateLimitStore {
+  private readonly storeDir: string;
+  private readonly storeFile: string;
+  private readonly processId: string;
+
+  constructor() {
+    this.storeDir = join(tmpdir(), "duckai");
+    this.storeFile = join(this.storeDir, "rate-limit.json");
+    this.processId = `${process.pid}-${Date.now()}`;
+
+    // Ensure directory exists
+    if (!existsSync(this.storeDir)) {
+      mkdirSync(this.storeDir, { recursive: true });
+    }
+  }
+
+  /**
+   * Read rate limit data from shared store
+   */
+  read(): RateLimitData | null {
+    try {
+      if (!existsSync(this.storeFile)) {
+        return null;
+      }
+
+      const data = readFileSync(this.storeFile, "utf8");
+
+      // Handle empty file
+      if (!data.trim()) {
+        return null;
+      }
+
+      const parsed: RateLimitData = JSON.parse(data);
+
+      // Check if data is stale (older than 5 minutes)
+      const now = Date.now();
+      if (now - parsed.lastUpdated > 5 * 60 * 1000) {
+        return null;
+      }
+
+      return parsed;
+    } catch (error) {
+      // Don't log warnings for expected cases like empty files
+      return null;
+    }
+  }
+
+  /**
+   * Write rate limit data to shared store
+   */
+  write(data: Omit<RateLimitData, "processId" | "lastUpdated">): void {
+    try {
+      const storeData: RateLimitData = {
+        ...data,
+        processId: this.processId,
+        lastUpdated: Date.now(),
+      };
+
+      writeFileSync(this.storeFile, JSON.stringify(storeData, null, 2));
+    } catch (error) {
+      console.warn("Failed to write rate limit store:", error);
+    }
+  }
+
+  /**
+   * Update rate limit data atomically
+   */
+  update(updater: (current: RateLimitData | null) => RateLimitData): void {
+    const current = this.read();
+    const updated = updater(current);
+    this.write(updated);
+  }
+
+  /**
+   * Clear the store
+   */
+  clear(): void {
+    try {
+      if (existsSync(this.storeFile)) {
+        const fs = require("fs");
+        fs.unlinkSync(this.storeFile);
+      }
+    } catch (error) {
+      console.warn("Failed to clear rate limit store:", error);
+    }
+  }
+
+  /**
+   * Get store file path for debugging
+   */
+  getStorePath(): string {
+    return this.storeFile;
+  }
+}

src/shared-rate-limit-monitor.ts

@@ -0,0 +1,303 @@
+import { RateLimitStore } from "./rate-limit-store";
+
+/**
+ * Shared Rate Limit Monitor
+ *
+ * This monitor reads rate limit data from a shared store,
+ * allowing it to display real-time rate limit information
+ * across all DuckAI processes.
+ */
+export class SharedRateLimitMonitor {
+  private rateLimitStore: RateLimitStore;
+  private monitoringInterval?: NodeJS.Timeout;
+
+  // Rate limit constants (should match DuckAI class)
+  private readonly MAX_REQUESTS_PER_MINUTE = 20;
+  private readonly WINDOW_SIZE_MS = 60 * 1000; // 1 minute
+  private readonly MIN_REQUEST_INTERVAL_MS = 1000; // 1 second
+
+  constructor() {
+    this.rateLimitStore = new RateLimitStore();
+  }
+
+  /**
+   * Get current rate limit status from shared store
+   */
+  getCurrentStatus() {
+    const stored = this.rateLimitStore.read();
+
+    if (!stored) {
+      // No data available, return default state
+      return {
+        requestsInCurrentWindow: 0,
+        maxRequestsPerMinute: this.MAX_REQUESTS_PER_MINUTE,
+        timeUntilWindowReset: this.WINDOW_SIZE_MS,
+        isCurrentlyLimited: false,
+        recommendedWaitTime: 0,
+        utilizationPercentage: 0,
+        timeUntilWindowResetMinutes: 1,
+        recommendedWaitTimeSeconds: 0,
+        dataSource: "default" as const,
+        lastUpdated: null,
+      };
+    }
+
+    const now = Date.now();
+    const windowElapsed = now - stored.windowStart;
+
+    // Calculate if window should be reset
+    let requestsInWindow = stored.requestCount;
+    let timeUntilReset = this.WINDOW_SIZE_MS - windowElapsed;
+
+    if (windowElapsed >= this.WINDOW_SIZE_MS) {
+      requestsInWindow = 0;
+      timeUntilReset = this.WINDOW_SIZE_MS;
+    }
+
+    // Calculate recommended wait time
+    const timeSinceLastRequest = now - stored.lastRequestTime;
+    const recommendedWait = Math.max(
+      0,
+      this.MIN_REQUEST_INTERVAL_MS - timeSinceLastRequest
+    );
+
+    const utilizationPercentage =
+      (requestsInWindow / this.MAX_REQUESTS_PER_MINUTE) * 100;
+
+    return {
+      requestsInCurrentWindow: requestsInWindow,
+      maxRequestsPerMinute: this.MAX_REQUESTS_PER_MINUTE,
+      timeUntilWindowReset: Math.max(0, timeUntilReset),
+      isCurrentlyLimited: stored.isLimited,
+      recommendedWaitTime: recommendedWait,
+      utilizationPercentage,
+      timeUntilWindowResetMinutes: Math.ceil(
+        Math.max(0, timeUntilReset) / 60000
+      ),
+      recommendedWaitTimeSeconds: Math.ceil(recommendedWait / 1000),
+      dataSource: "shared" as const,
+      lastUpdated: new Date(stored.lastUpdated).toISOString(),
+      processId: stored.processId,
+    };
+  }
+
+  /**
+   * Print current rate limit status to console
+   */
+  printStatus() {
+    const status = this.getCurrentStatus();
+
+    console.log("\n🔍 DuckAI Rate Limit Status (Shared):");
+    console.log("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━");
+    console.log(
+      `📊 Requests in current window: ${status.requestsInCurrentWindow}/${status.maxRequestsPerMinute}`
+    );
+    console.log(`📈 Utilization: ${status.utilizationPercentage.toFixed(1)}%`);
+    console.log(
+      `⏰ Window resets in: ${status.timeUntilWindowResetMinutes} minutes`
+    );
+    console.log(
+      `🚦 Currently limited: ${status.isCurrentlyLimited ? "❌ Yes" : "✅ No"}`
+    );
+
+    if (status.recommendedWaitTimeSeconds > 0) {
+      console.log(
+        `⏳ Recommended wait: ${status.recommendedWaitTimeSeconds} seconds`
+      );
+    }
+
+    // Data source info
+    if (status.dataSource === "shared" && status.lastUpdated) {
+      const updateTime = new Date(status.lastUpdated).toLocaleTimeString();
+      console.log(`📡 Data from: Process ${status.processId} at ${updateTime}`);
+    } else {
+      console.log(`📡 Data source: ${status.dataSource} (no active processes)`);
+    }
+
+    // Visual progress bar
+    const barLength = 20;
+    const filledLength = Math.round(
+      (status.utilizationPercentage / 100) * barLength
+    );
+    const bar = "█".repeat(filledLength) + "░".repeat(barLength - filledLength);
+    console.log(
+      `📊 Usage: [${bar}] ${status.utilizationPercentage.toFixed(1)}%`
+    );
+    console.log("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n");
+  }
+
+  /**
+   * Start continuous monitoring (prints status every interval)
+   */
+  startMonitoring(intervalSeconds: number = 30) {
+    console.log(
+      `🔄 Starting shared rate limit monitoring (every ${intervalSeconds}s)...`
+    );
+    console.log(`📁 Store location: ${this.rateLimitStore.getStorePath()}`);
+    this.printStatus();
+
+    this.monitoringInterval = setInterval(() => {
+      this.printStatus();
+    }, intervalSeconds * 1000);
+  }
+
+  /**
+   * Stop continuous monitoring
+   */
+  stopMonitoring() {
+    if (this.monitoringInterval) {
+      clearInterval(this.monitoringInterval);
+      this.monitoringInterval = undefined;
+      console.log("⏹️  Shared rate limit monitoring stopped.");
+    }
+  }
+
+  /**
+   * Get recommendations for optimal usage
+   */
+  getRecommendations() {
+    const status = this.getCurrentStatus();
+    const recommendations: string[] = [];
+
+    if (status.dataSource === "default") {
+      recommendations.push(
+        "ℹ️  No active DuckAI processes detected. Start making API calls to see real data."
+      );
+    }
+
+    if (status.utilizationPercentage > 80) {
+      recommendations.push(
+        "⚠️  High utilization detected. Consider implementing request queuing."
+      );
+    }
+
+    if (status.recommendedWaitTimeSeconds > 0) {
+      recommendations.push(
+        `⏳ Wait ${status.recommendedWaitTimeSeconds}s before next request.`
+      );
+    }
+
+    if (status.isCurrentlyLimited) {
+      recommendations.push(
+        "🚫 Currently rate limited. Wait for window reset or implement exponential backoff."
+      );
+    }
+
+    if (status.utilizationPercentage < 50 && status.dataSource === "shared") {
+      recommendations.push(
+        "✅ Good utilization level. You can safely increase request frequency."
+      );
+    }
+
+    recommendations.push(
+      "💡 Consider implementing request batching for better efficiency."
+    );
+    recommendations.push("🔄 Use exponential backoff for retry logic.");
+    recommendations.push("📊 Monitor rate limits continuously in production.");
+
+    return recommendations;
+  }
+
+  /**
+   * Print recommendations
+   */
+  printRecommendations() {
+    const recommendations = this.getRecommendations();
+
+    console.log("\n💡 Rate Limit Recommendations:");
+    console.log("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━");
+    recommendations.forEach((rec) => console.log(rec));
+    console.log("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n");
+  }
+
+  /**
+   * Clear the shared rate limit store
+   */
+  clearStore() {
+    this.rateLimitStore.clear();
+    console.log("🗑️  Shared rate limit store cleared.");
+  }
+
+  /**
+   * Get store information
+   */
+  getStoreInfo() {
+    const stored = this.rateLimitStore.read();
+    return {
+      storePath: this.rateLimitStore.getStorePath(),
+      hasData: !!stored,
+      data: stored,
+    };
+  }
+}
+
+// CLI usage for shared monitoring
+if (require.main === module) {
+  const monitor = new SharedRateLimitMonitor();
+
+  // Parse command line arguments
+  const args = process.argv.slice(2);
+  const command = args[0];
+
+  switch (command) {
+    case "status":
+      monitor.printStatus();
+      monitor.printRecommendations();
+      break;
+
+    case "monitor":
+      const interval = parseInt(args[1]) || 30;
+      monitor.startMonitoring(interval);
+
+      // Stop monitoring on Ctrl+C
+      process.on("SIGINT", () => {
+        monitor.stopMonitoring();
+        process.exit(0);
+      });
+      break;
+
+    case "clear":
+      monitor.clearStore();
+      break;
+
+    case "info":
+      const info = monitor.getStoreInfo();
+      console.log("📁 Store Information:");
+      console.log(`   Path: ${info.storePath}`);
+      console.log(`   Has Data: ${info.hasData}`);
+      if (info.data) {
+        console.log(
+          `   Last Updated: ${new Date(info.data.lastUpdated).toLocaleString()}`
+        );
+        console.log(`   Process ID: ${info.data.processId}`);
+        console.log(`   Requests: ${info.data.requestCount}`);
+      }
+      break;
+
+    default:
+      console.log("🔍 DuckAI Shared Rate Limit Monitor");
+      console.log("");
+      console.log("This monitor reads rate limit data from a shared store,");
+      console.log("showing real-time information across all DuckAI processes.");
+      console.log("");
+      console.log("Usage:");
+      console.log(
+        "  bun run src/shared-rate-limit-monitor.ts status                    # Show current status"
+      );
+      console.log(
+        "  bun run src/shared-rate-limit-monitor.ts monitor [interval]       # Start monitoring (default: 30s)"
+      );
+      console.log(
+        "  bun run src/shared-rate-limit-monitor.ts clear                     # Clear stored data"
+      );
+      console.log(
+        "  bun run src/shared-rate-limit-monitor.ts info                      # Show store info"
+      );
+      console.log("");
+      console.log("Examples:");
+      console.log("  bun run src/shared-rate-limit-monitor.ts status");
+      console.log("  bun run src/shared-rate-limit-monitor.ts monitor 10");
+      console.log("  bun run src/shared-rate-limit-monitor.ts clear");
+      break;
+  }
+}

src/shared-rate-limit-tester.ts

@@ -0,0 +1,232 @@
+import { DuckAI } from "./duckai";
+
+/**
+ * Shared Rate Limit Tester
+ *
+ * This utility tests rate limits using the DuckAI class which writes to the shared store,
+ * allowing cross-process monitoring to work correctly.
+ */
+export class SharedRateLimitTester {
+  private duckAI: DuckAI;
+
+  constructor() {
+    this.duckAI = new DuckAI();
+  }
+
+  /**
+   * Get current rate limit status
+   */
+  getCurrentStatus() {
+    const status = this.duckAI.getRateLimitStatus();
+    return {
+      ...status,
+      utilizationPercentage:
+        (status.requestsInCurrentWindow / status.maxRequestsPerMinute) * 100,
+      timeUntilWindowResetMinutes: Math.ceil(
+        status.timeUntilWindowReset / 60000
+      ),
+      recommendedWaitTimeSeconds: Math.ceil(status.recommendedWaitTime / 1000),
+    };
+  }
+
+  /**
+   * Print current rate limit status to console
+   */
+  printStatus() {
+    const status = this.getCurrentStatus();
+
+    console.log("\n🔍 DuckAI Rate Limit Status (Shared Tester):");
+    console.log("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━");
+    console.log(
+      `📊 Requests in current window: ${status.requestsInCurrentWindow}/${status.maxRequestsPerMinute}`
+    );
+    console.log(`📈 Utilization: ${status.utilizationPercentage.toFixed(1)}%`);
+    console.log(
+      `⏰ Window resets in: ${status.timeUntilWindowResetMinutes} minutes`
+    );
+    console.log(
+      `🚦 Currently limited: ${status.isCurrentlyLimited ? "❌ Yes" : "✅ No"}`
+    );
+
+    if (status.recommendedWaitTimeSeconds > 0) {
+      console.log(
+        `⏳ Recommended wait: ${status.recommendedWaitTimeSeconds} seconds`
+      );
+    }
+
+    // Visual progress bar
+    const barLength = 20;
+    const filledLength = Math.round(
+      (status.utilizationPercentage / 100) * barLength
+    );
+    const bar = "█".repeat(filledLength) + "░".repeat(barLength - filledLength);
+    console.log(
+      `📊 Usage: [${bar}] ${status.utilizationPercentage.toFixed(1)}%`
+    );
+    console.log("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n");
+  }
+
+  /**
+   * Test rate limits by making a series of requests using DuckAI (writes to shared store)
+   */
+  async testRateLimits(
+    numberOfRequests: number = 5,
+    delayBetweenRequests: number = 1000
+  ) {
+    console.log(
+      `🧪 Testing rate limits with ${numberOfRequests} requests (${delayBetweenRequests}ms delay)...`
+    );
+    console.log(
+      "📡 Using DuckAI class - data will be shared across processes!"
+    );
+
+    for (let i = 1; i <= numberOfRequests; i++) {
+      console.log(`\n📤 Making request ${i}/${numberOfRequests}...`);
+
+      try {
+        const startTime = Date.now();
+
+        const response = await this.duckAI.chat({
+          model: "gpt-4o-mini",
+          messages: [{ role: "user", content: `Shared test request ${i}` }],
+        });
+
+        const endTime = Date.now();
+        const responseTime = endTime - startTime;
+
+        console.log(`✅ Request ${i} successful (${responseTime}ms)`);
+        this.printStatus();
+
+        if (i < numberOfRequests) {
+          console.log(
+            `⏳ Waiting ${delayBetweenRequests}ms before next request...`
+          );
+          await new Promise((resolve) =>
+            setTimeout(resolve, delayBetweenRequests)
+          );
+        }
+      } catch (error) {
+        const errorMessage =
+          error instanceof Error ? error.message : String(error);
+        console.log(`❌ Request ${i} failed:`, errorMessage);
+        this.printStatus();
+
+        // If rate limited, wait longer
+        if (errorMessage.includes("Rate limited")) {
+          const waitTime =
+            this.getCurrentStatus().recommendedWaitTimeSeconds * 1000;
+          console.log(`⏳ Rate limited! Waiting ${waitTime}ms...`);
+          await new Promise((resolve) => setTimeout(resolve, waitTime));
+        }
+      }
+    }
+
+    console.log("\n🏁 Shared rate limit test completed!");
+    console.log(
+      "📡 Data has been written to shared store for cross-process monitoring!"
+    );
+  }
+
+  /**
+   * Get recommendations for optimal usage
+   */
+  getRecommendations() {
+    const status = this.getCurrentStatus();
+    const recommendations: string[] = [];
+
+    if (status.utilizationPercentage > 80) {
+      recommendations.push(
+        "⚠️  High utilization detected. Consider implementing request queuing."
+      );
+    }
+
+    if (status.recommendedWaitTimeSeconds > 0) {
+      recommendations.push(
+        `⏳ Wait ${status.recommendedWaitTimeSeconds}s before next request.`
+      );
+    }
+
+    if (status.isCurrentlyLimited) {
+      recommendations.push(
+        "🚫 Currently rate limited. Wait for window reset or implement exponential backoff."
+      );
+    }
+
+    if (status.utilizationPercentage < 50) {
+      recommendations.push(
+        "✅ Good utilization level. You can safely increase request frequency."
+      );
+    }
+
+    recommendations.push(
+      "💡 Consider implementing request batching for better efficiency."
+    );
+    recommendations.push("🔄 Use exponential backoff for retry logic.");
+    recommendations.push("📊 Monitor rate limits continuously in production.");
+    recommendations.push(
+      "📡 Use shared monitoring for cross-process visibility."
+    );
+
+    return recommendations;
+  }
+
+  /**
+   * Print recommendations
+   */
+  printRecommendations() {
+    const recommendations = this.getRecommendations();
+
+    console.log("\n💡 Rate Limit Recommendations:");
+    console.log("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━");
+    recommendations.forEach((rec) => console.log(rec));
+    console.log("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n");
+  }
+}
+
+// CLI usage
+if (require.main === module) {
+  const tester = new SharedRateLimitTester();
+
+  // Parse command line arguments
+  const args = process.argv.slice(2);
+  const command = args[0];
+
+  switch (command) {
+    case "status":
+      tester.printStatus();
+      tester.printRecommendations();
+      break;
+
+    case "test":
+      const requests = parseInt(args[1]) || 5;
+      const delay = parseInt(args[2]) || 1000;
+      tester.testRateLimits(requests, delay).then(() => {
+        tester.printRecommendations();
+        process.exit(0);
+      });
+      break;
+
+    default:
+      console.log("🔍 DuckAI Shared Rate Limit Tester");
+      console.log("📡 Uses DuckAI class - data is shared across processes!");
+      console.log("");
+      console.log("Usage:");
+      console.log(
+        "  bun run src/shared-rate-limit-tester.ts status                    # Show current status"
+      );
+      console.log(
+        "  bun run src/shared-rate-limit-tester.ts test [requests] [delay]  # Test rate limits (shared)"
+      );
+      console.log("");
+      console.log("Examples:");
+      console.log("  bun run src/shared-rate-limit-tester.ts status");
+      console.log("  bun run src/shared-rate-limit-tester.ts test 10 2000");
+      console.log("");
+      console.log("💡 For cross-process monitoring, run this in one terminal:");
+      console.log("  bun run src/shared-rate-limit-tester.ts test 20 3000");
+      console.log("");
+      console.log("And this in another terminal:");
+      console.log("  bun run src/shared-rate-limit-monitor.ts monitor 2");
+      break;
+  }
+}

tests/rate-limit-monitor.test.ts

@@ -0,0 +1,256 @@
+import { describe, it, expect, beforeEach } from "bun:test";
+import { RateLimitMonitor } from "../src/rate-limit-monitor";
+import { OpenAIService } from "../src/openai-service";
+
+describe("Rate Limit Monitor", () => {
+  let monitor: RateLimitMonitor;
+  let openAIService: OpenAIService;
+
+  beforeEach(() => {
+    monitor = new RateLimitMonitor();
+    openAIService = new OpenAIService();
+  });
+
+  describe("getCurrentStatus", () => {
+    it("should return rate limit status with additional calculated fields", () => {
+      const status = monitor.getCurrentStatus();
+
+      expect(status).toHaveProperty("requestsInCurrentWindow");
+      expect(status).toHaveProperty("maxRequestsPerMinute");
+      expect(status).toHaveProperty("timeUntilWindowReset");
+      expect(status).toHaveProperty("isCurrentlyLimited");
+      expect(status).toHaveProperty("recommendedWaitTime");
+      expect(status).toHaveProperty("utilizationPercentage");
+      expect(status).toHaveProperty("timeUntilWindowResetMinutes");
+      expect(status).toHaveProperty("recommendedWaitTimeSeconds");
+
+      expect(typeof status.utilizationPercentage).toBe("number");
+      expect(status.utilizationPercentage).toBeGreaterThanOrEqual(0);
+      expect(status.utilizationPercentage).toBeLessThanOrEqual(100);
+    });
+
+    it("should calculate utilization percentage correctly", () => {
+      const status = monitor.getCurrentStatus();
+      const expectedUtilization =
+        (status.requestsInCurrentWindow / status.maxRequestsPerMinute) * 100;
+
+      expect(status.utilizationPercentage).toBe(expectedUtilization);
+    });
+  });
+
+  describe("getRecommendations", () => {
+    it("should return an array of recommendations", () => {
+      const recommendations = monitor.getRecommendations();
+
+      expect(Array.isArray(recommendations)).toBe(true);
+      expect(recommendations.length).toBeGreaterThan(0);
+
+      // Should always include basic recommendations
+      expect(recommendations.some((rec) => rec.includes("batching"))).toBe(
+        true
+      );
+      expect(
+        recommendations.some((rec) => rec.includes("exponential backoff"))
+      ).toBe(true);
+      expect(recommendations.some((rec) => rec.includes("Monitor"))).toBe(true);
+    });
+
+    it("should provide specific recommendations based on status", () => {
+      const recommendations = monitor.getRecommendations();
+
+      // All recommendations should be strings
+      recommendations.forEach((rec) => {
+        expect(typeof rec).toBe("string");
+        expect(rec.length).toBeGreaterThan(0);
+      });
+    });
+  });
+
+  describe("OpenAI Service Rate Limit Integration", () => {
+    it("should expose rate limit status through OpenAI service", () => {
+      const status = openAIService.getRateLimitStatus();
+
+      expect(status).toHaveProperty("requestsInCurrentWindow");
+      expect(status).toHaveProperty("maxRequestsPerMinute");
+      expect(status).toHaveProperty("timeUntilWindowReset");
+      expect(status).toHaveProperty("isCurrentlyLimited");
+      expect(status).toHaveProperty("recommendedWaitTime");
+
+      expect(typeof status.requestsInCurrentWindow).toBe("number");
+      expect(typeof status.maxRequestsPerMinute).toBe("number");
+      expect(typeof status.timeUntilWindowReset).toBe("number");
+      expect(typeof status.isCurrentlyLimited).toBe("boolean");
+      expect(typeof status.recommendedWaitTime).toBe("number");
+    });
+
+    it("should track requests correctly", async () => {
+      const initialStatus = openAIService.getRateLimitStatus();
+      const initialCount = initialStatus.requestsInCurrentWindow;
+
+      // Mock the DuckAI response to avoid actual API calls
+      const originalChat = openAIService["duckAI"].chat;
+      openAIService["duckAI"].chat = async () => "Mock response";
+
+      try {
+        await openAIService.createChatCompletion({
+          model: "gpt-4o-mini",
+          messages: [{ role: "user", content: "Test" }],
+        });
+
+        const afterStatus = openAIService.getRateLimitStatus();
+        expect(afterStatus.requestsInCurrentWindow).toBe(initialCount + 1);
+      } catch (error) {
+        // If it fails due to rate limiting, that's also a valid test result
+        expect(error).toBeInstanceOf(Error);
+      } finally {
+        // Restore original method
+        openAIService["duckAI"].chat = originalChat;
+      }
+    });
+  });
+
+  describe("Rate Limit Window Management", () => {
+    it("should reset window after time period", () => {
+      const status1 = openAIService.getRateLimitStatus();
+
+      // Simulate time passing by directly accessing the DuckAI instance
+      const duckAI = openAIService["duckAI"];
+
+      // Force a window reset by manipulating the internal state
+      if (duckAI["rateLimitInfo"]) {
+        duckAI["rateLimitInfo"].windowStart = Date.now() - 61000; // 61 seconds ago
+      }
+
+      const status2 = openAIService.getRateLimitStatus();
+
+      // After window reset, request count should be reset
+      expect(status2.requestsInCurrentWindow).toBeLessThanOrEqual(
+        status1.requestsInCurrentWindow
+      );
+    });
+
+    it("should calculate time until reset correctly", () => {
+      const status = openAIService.getRateLimitStatus();
+
+      expect(status.timeUntilWindowReset).toBeGreaterThanOrEqual(0);
+      expect(status.timeUntilWindowReset).toBeLessThanOrEqual(60000); // Should be within 1 minute
+    });
+  });
+
+  describe("Rate Limit Enforcement", () => {
+    it("should recommend waiting when requests are too frequent", () => {
+      const duckAI = openAIService["duckAI"];
+
+      // Simulate recent request
+      if (duckAI["rateLimitInfo"]) {
+        duckAI["rateLimitInfo"].lastRequestTime = Date.now() - 500; // 500ms ago
+      }
+
+      const status = openAIService.getRateLimitStatus();
+
+      // Should recommend waiting since last request was recent
+      expect(status.recommendedWaitTime).toBeGreaterThan(0);
+    });
+
+    it("should detect when rate limit is exceeded", () => {
+      const duckAI = openAIService["duckAI"];
+
+      // Simulate hitting rate limit by directly manipulating the rate limit info
+      if (duckAI["rateLimitInfo"]) {
+        const rateLimitInfo = duckAI["rateLimitInfo"];
+        rateLimitInfo.requestCount = 25; // Exceed the limit of 20
+        rateLimitInfo.windowStart = Date.now(); // Ensure current window
+        rateLimitInfo.isLimited = true; // Mark as limited
+      }
+
+      // Get status directly from the modified state
+      const status = openAIService.getRateLimitStatus();
+
+      // Should detect that we're over the limit
+      expect(status.requestsInCurrentWindow).toBeGreaterThan(20);
+      expect(status.isCurrentlyLimited).toBe(true);
+    });
+  });
+
+  describe("Error Handling", () => {
+    it("should handle rate limit errors gracefully", async () => {
+      // Mock the DuckAI to throw rate limit error
+      const originalChat = openAIService["duckAI"].chat;
+      openAIService["duckAI"].chat = async () => {
+        const error = new Error(
+          "Rate limited. Retry after 60000ms. Status: 429"
+        );
+        throw error;
+      };
+
+      try {
+        await openAIService.createChatCompletion({
+          model: "gpt-4o-mini",
+          messages: [{ role: "user", content: "Test" }],
+        });
+
+        // Should not reach here
+        expect(true).toBe(false);
+      } catch (error) {
+        expect(error).toBeInstanceOf(Error);
+        expect(error.message).toContain("Rate limited");
+      } finally {
+        // Restore original method
+        openAIService["duckAI"].chat = originalChat;
+      }
+    });
+  });
+
+  describe("Monitoring Functions", () => {
+    it("should start and stop monitoring without errors", () => {
+      // Test that monitoring can be started and stopped
+      expect(() => {
+        monitor.startMonitoring(1); // 1 second interval for testing
+        monitor.stopMonitoring();
+      }).not.toThrow();
+    });
+
+    it("should handle multiple stop calls gracefully", () => {
+      expect(() => {
+        monitor.stopMonitoring();
+        monitor.stopMonitoring(); // Should not throw
+      }).not.toThrow();
+    });
+  });
+
+  describe("Utility Functions", () => {
+    it("should print status without errors", () => {
+      // Mock console.log to capture output
+      const originalLog = console.log;
+      const logs: string[] = [];
+      console.log = (...args) => logs.push(args.join(" "));
+
+      try {
+        monitor.printStatus();
+
+        // Should have printed something
+        expect(logs.length).toBeGreaterThan(0);
+        expect(logs.some((log) => log.includes("Rate Limit Status"))).toBe(
+          true
+        );
+      } finally {
+        console.log = originalLog;
+      }
+    });
+
+    it("should print recommendations without errors", () => {
+      const originalLog = console.log;
+      const logs: string[] = [];
+      console.log = (...args) => logs.push(args.join(" "));
+
+      try {
+        monitor.printRecommendations();
+
+        expect(logs.length).toBeGreaterThan(0);
+        expect(logs.some((log) => log.includes("Recommendations"))).toBe(true);
+      } finally {
+        console.log = originalLog;
+      }
+    });
+  });
+});