@caddis/cli 0.1.0 → 0.2.0

package/bundles/antigravity-plugin-extras/skills/building-ai-agent-on-cloudflare/references/state-patterns.md

@@ -0,0 +1,360 @@
+# State Management Patterns
+
+Strategies for managing state in Cloudflare Agents.
+
+## How State Works
+
+State is automatically persisted to the `cf_agents_state` SQL table. The `this.state` getter lazily loads from storage, while `this.setState()` serializes and persists changes. State survives Durable Object evictions.
+
+```typescript
+class MyAgent extends Agent<Env, { count: number }> {
+  initialState = { count: 0 };
+
+  increment() {
+    this.setState({ count: this.state.count + 1 });
+  }
+
+  onStateUpdate(state: State, source: string) {
+    console.log("State updated by:", source);
+  }
+}
+```
+
+## State vs SQL: When to Use Which
+
+### Use `this.state` + `setState()` When:
+
+- Data is small (< 1MB recommended)
+- Needs real-time sync to all connected clients
+- Simple key-value or object structure
+- Frequently read, occasionally updated
+
+```typescript
+interface State {
+  currentUser: { id: string; name: string };
+  preferences: Record<string, string>;
+  recentMessages: Message[];  // Keep limited, e.g., last 50
+  isTyping: boolean;
+}
+```
+
+### Use `this.sql` When:
+
+- Large datasets (many records)
+- Complex queries (JOINs, aggregations, filtering)
+- Historical data / audit logs
+- Data that doesn't need real-time sync
+
+```typescript
+// Good for SQL
+// - Full message history
+// - User documents
+// - Analytics events
+// - Search indexes
+```
+
+## Hybrid Pattern
+
+Combine both for optimal performance:
+
+```typescript
+interface State {
+  recentMessages: Message[];
+  onlineUsers: string[];
+  currentDocument: Document | null;
+}
+
+export class HybridAgent extends Agent<Env, State> {
+  initialState: State = {
+    recentMessages: [],
+    onlineUsers: [],
+    currentDocument: null,
+  };
+
+  async onStart() {
+    await this.sql`
+      CREATE TABLE IF NOT EXISTS messages (
+        id TEXT PRIMARY KEY,
+        user_id TEXT NOT NULL,
+        content TEXT NOT NULL,
+        created_at DATETIME DEFAULT CURRENT_TIMESTAMP
+      )
+    `;
+
+    const recent = await this.sql`
+      SELECT * FROM messages
+      ORDER BY created_at DESC
+      LIMIT 50
+    `;
+
+    this.setState({
+      ...this.state,
+      recentMessages: recent.reverse(),
+    });
+  }
+
+  async addMessage(message: Message) {
+    await this.sql`
+      INSERT INTO messages (id, user_id, content)
+      VALUES (${message.id}, ${message.userId}, ${message.content})
+    `;
+
+    const recentMessages = [...this.state.recentMessages, message].slice(-50);
+    this.setState({ ...this.state, recentMessages });
+  }
+}
+```
+
+---
+
+## Queue System
+
+The SDK includes a built-in queue for background task processing. Tasks are stored in SQLite and processed in FIFO order.
+
+### Queue Methods
+
+| Method | Purpose |
+|--------|---------|
+| `queue(callback, payload)` | Add task, returns task ID |
+| `dequeue(id)` | Remove specific task |
+| `dequeueAll()` | Clear entire queue |
+| `dequeueAllByCallback(name)` | Remove tasks by callback name |
+| `getQueue(id)` | Get single task |
+| `getQueues(key, value)` | Find tasks by payload field |
+
+### Queue Example
+
+```typescript
+export class TaskAgent extends Agent<Env, State> {
+  async onMessage(connection: Connection, message: string) {
+    const data = JSON.parse(message);
+
+    if (data.type === "process_later") {
+      const taskId = await this.queue("processItem", {
+        itemId: data.itemId,
+        priority: data.priority,
+      });
+
+      connection.send(JSON.stringify({ queued: true, taskId }));
+    }
+  }
+
+  // Callback receives payload and QueueItem metadata
+  async processItem(payload: { itemId: string }, item: QueueItem) {
+    console.log(`Processing ${payload.itemId}, queued at ${item.createdAt}`);
+    // Successfully executed tasks are auto-removed
+  }
+}
+```
+
+**Queue characteristics:**
+- Sequential processing (no parallelization)
+- Persists across agent restarts
+- No built-in retry mechanism
+- Payloads must be JSON-serializable
+
+---
+
+## Context Management
+
+Custom methods automatically have full agent context. Use `getCurrentAgent()` to access context from external functions.
+
+```typescript
+import { getCurrentAgent } from "agents";
+
+// External utility function
+async function logActivity(action: string) {
+  const { agent } = getCurrentAgent<MyAgent>();
+  await agent.sql`
+    INSERT INTO activity_log (action, timestamp)
+    VALUES (${action}, ${Date.now()})
+  `;
+}
+
+export class MyAgent extends Agent<Env, State> {
+  async performAction() {
+    // Context automatically available
+    await logActivity("action_performed");
+  }
+}
+```
+
+`getCurrentAgent<T>()` returns:
+- `agent` - The current agent instance
+- `connection` - Connection object (if applicable)
+- `request` - Request object (if applicable)
+
+---
+
+## State Synchronization
+
+### Optimistic Updates
+
+Update UI immediately, then persist:
+
+```typescript
+async onMessage(connection: Connection, message: string) {
+  const data = JSON.parse(message);
+
+  if (data.type === "update_preference") {
+    this.setState({
+      ...this.state,
+      preferences: {
+        ...this.state.preferences,
+        [data.key]: data.value,
+      },
+    });
+
+    await this.sql`
+      INSERT OR REPLACE INTO preferences (key, value)
+      VALUES (${data.key}, ${data.value})
+    `;
+  }
+}
+```
+
+### Conflict Resolution
+
+Handle concurrent updates with versioning:
+
+```typescript
+interface State {
+  document: {
+    content: string;
+    version: number;
+    lastModifiedBy: string;
+  };
+}
+
+async updateDocument(userId: string, newContent: string, expectedVersion: number) {
+  if (this.state.document.version !== expectedVersion) {
+    throw new Error("Conflict: document was modified by another user");
+  }
+
+  this.setState({
+    ...this.state,
+    document: {
+      content: newContent,
+      version: expectedVersion + 1,
+      lastModifiedBy: userId,
+    },
+  });
+}
+```
+
+### Per-Connection State
+
+Track ephemeral state for each connected client:
+
+```typescript
+export class MultiUserAgent extends Agent<Env, State> {
+  private connectionState = new Map<string, {
+    userId: string;
+    cursor: { x: number; y: number };
+    lastActivity: number;
+  }>();
+
+  async onConnect(connection: Connection) {
+    this.connectionState.set(connection.id, {
+      userId: "",
+      cursor: { x: 0, y: 0 },
+      lastActivity: Date.now(),
+    });
+  }
+
+  async onClose(connection: Connection) {
+    this.connectionState.delete(connection.id);
+  }
+}
+```
+
+---
+
+## State Migration
+
+When state schema changes:
+
+```typescript
+interface StateV2 {
+  messages: Array<{ id: string; content: string; timestamp: string }>;
+  version: 2;
+}
+
+export class MigratingAgent extends Agent<Env, StateV2> {
+  initialState: StateV2 = {
+    messages: [],
+    version: 2,
+  };
+
+  async onStart() {
+    const rawState = this.state as any;
+
+    if (!rawState.version || rawState.version < 2) {
+      const migratedMessages = (rawState.messages || []).map(
+        (content: string, i: number) => ({
+          id: `migrated-${i}`,
+          content,
+          timestamp: new Date().toISOString(),
+        })
+      );
+
+      this.setState({
+        messages: migratedMessages,
+        version: 2,
+      });
+    }
+  }
+}
+```
+
+---
+
+## State Size Management
+
+Keep state lean for performance:
+
+```typescript
+export class LeanStateAgent extends Agent<Env, State> {
+  private readonly MAX_RECENT_MESSAGES = 100;
+
+  async addMessage(message: Message) {
+    await this.sql`INSERT INTO messages (id, content) VALUES (${message.id}, ${message.content})`;
+
+    let recentMessages = [...this.state.recentMessages, message];
+    if (recentMessages.length > this.MAX_RECENT_MESSAGES) {
+      recentMessages = recentMessages.slice(-this.MAX_RECENT_MESSAGES);
+    }
+
+    this.setState({
+      ...this.state,
+      recentMessages,
+      stats: {
+        ...this.state.stats,
+        totalMessages: this.state.stats.totalMessages + 1,
+        lastActivity: new Date().toISOString(),
+      },
+    });
+  }
+}
+```
+
+---
+
+## Debugging State
+
+```typescript
+async onMessage(connection: Connection, message: string) {
+  const data = JSON.parse(message);
+
+  if (data.type === "debug_state") {
+    connection.send(JSON.stringify({
+      type: "debug_response",
+      state: this.state,
+      stateSize: JSON.stringify(this.state).length,
+      sqlTables: await this.sql`
+        SELECT name FROM sqlite_master WHERE type='table'
+      `,
+    }));
+  }
+}
+```

package/bundles/antigravity-plugin-extras/skills/building-ai-agent-on-cloudflare/references/troubleshooting.md

@@ -0,0 +1,362 @@
+# Agent Troubleshooting
+
+Common issues and solutions for Cloudflare Agents.
+
+## Connection Issues
+
+### "WebSocket connection failed"
+
+**Symptoms:** Client cannot connect to agent.
+
+**Causes & Solutions:**
+
+1. **Worker not deployed**
+   ```bash
+   wrangler deployments list
+   wrangler deploy  # If not deployed
+   ```
+
+2. **Wrong URL path**
+   ```javascript
+   // Ensure your routing handles the agent path
+   // Client:
+   new WebSocket("wss://my-worker.workers.dev/agent/user123");
+
+   // Worker must route to agent:
+   if (url.pathname.startsWith("/agent/")) {
+     const id = url.pathname.split("/")[2];
+     return env.AGENT.get(env.AGENT.idFromName(id)).fetch(request);
+   }
+   ```
+
+3. **CORS issues (browser clients)**
+   Agents handle WebSocket upgrades automatically, but ensure your entry worker doesn't block the request.
+
+### "Connection closed unexpectedly"
+
+1. **Agent threw an error**
+   ```bash
+   wrangler tail  # Check for exceptions
+   ```
+
+2. **Message handler crashed**
+   ```typescript
+   async onMessage(connection: Connection, message: string) {
+     try {
+       // Your logic
+     } catch (error) {
+       console.error("Message handling error:", error);
+       connection.send(JSON.stringify({ type: "error", message: error.message }));
+     }
+   }
+   ```
+
+3. **Hibernation woke agent with stale connection**
+   Ensure you handle reconnection gracefully in client code.
+
+## State Issues
+
+### "State not persisting"
+
+**Causes:**
+
+1. **Didn't call `setState()`**
+   ```typescript
+   // Wrong - direct mutation doesn't persist
+   this.state.messages.push(newMessage);
+
+   // Correct - use setState
+   this.setState({
+     ...this.state,
+     messages: [...this.state.messages, newMessage],
+   });
+   ```
+
+2. **Agent crashed before state saved**
+   `setState()` is durable, but if agent crashes during processing before `setState()`, changes are lost.
+
+3. **Wrong agent instance**
+   Each unique ID gets a separate agent. Ensure clients connect to the same ID.
+
+### "State out of sync between clients"
+
+`setState()` automatically syncs to all connected clients via `onStateUpdate()`. If sync isn't working:
+
+1. **Check `onStateUpdate` is implemented**
+   ```typescript
+   onStateUpdate(state: State, source: string) {
+     // This fires when state changes from any source
+     console.log("State updated:", state, "from:", source);
+   }
+   ```
+
+2. **Client not listening for state updates**
+   ```typescript
+   // React hook handles this automatically
+   const { state } = useAgent({ agent: "my-agent", name: id });
+
+   // Manual WebSocket - listen for state messages
+   ws.onmessage = (event) => {
+     const data = JSON.parse(event.data);
+     if (data.type === "state_update") {
+       updateLocalState(data.state);
+     }
+   };
+   ```
+
+### "State too large" / Performance issues
+
+State is serialized as JSON. Keep it small:
+
+```typescript
+// Bad - storing everything in state
+interface State {
+  allMessages: Message[];  // Could be thousands
+  allDocuments: Document[];
+}
+
+// Good - state for hot data, SQL for cold
+interface State {
+  recentMessages: Message[];  // Last 50 only
+  currentDocument: Document | null;
+}
+
+// Store full history in SQL
+await this.sql`INSERT INTO messages ...`;
+```
+
+## SQL Issues
+
+### "no such table"
+
+Table not created. Create in `onStart()`:
+
+```typescript
+async onStart() {
+  await this.sql`
+    CREATE TABLE IF NOT EXISTS messages (
+      id TEXT PRIMARY KEY,
+      content TEXT NOT NULL,
+      created_at DATETIME DEFAULT CURRENT_TIMESTAMP
+    )
+  `;
+}
+```
+
+### "SQL logic error"
+
+Check your query syntax. Use tagged templates correctly:
+
+```typescript
+// Wrong - string interpolation (SQL injection risk!)
+await this.sql`SELECT * FROM users WHERE id = '${userId}'`;
+
+// Correct - parameterized query
+await this.sql`SELECT * FROM users WHERE id = ${userId}`;
+```
+
+### SQL query returns empty
+
+1. **Wrong table name**
+2. **Data in different agent instance** (each agent ID has isolated storage)
+3. **Query conditions don't match**
+
+Debug:
+```typescript
+const tables = await this.sql`
+  SELECT name FROM sqlite_master WHERE type='table'
+`;
+console.log("Tables:", tables);
+
+const count = await this.sql`SELECT COUNT(*) as count FROM messages`;
+console.log("Message count:", count);
+```
+
+## Scheduled Task Issues
+
+### "Task never fires"
+
+1. **Method name mismatch**
+   ```typescript
+   // Schedule references method that must exist
+   await this.schedule(60, "sendReminder", { ... });
+
+   // Method must be defined on the class
+   async sendReminder(data: any) {
+     // This method MUST exist
+   }
+   ```
+
+2. **Cron syntax error**
+   ```typescript
+   // Invalid cron
+   await this.schedule("every 5 minutes", "task", {});  // Wrong
+
+   // Valid cron
+   await this.schedule("*/5 * * * *", "task", {});  // Every 5 minutes
+   ```
+
+3. **Task was cancelled**
+   ```typescript
+   const schedules = await this.getSchedules();
+   console.log("Active schedules:", schedules);
+   ```
+
+### "Task fires multiple times"
+
+If you schedule in `onStart()` without checking:
+
+```typescript
+async onStart() {
+  // Bad - schedules new task every time agent wakes
+  await this.schedule("0 9 * * *", "dailyTask", {});
+
+  // Good - check first
+  const schedules = await this.getSchedules();
+  const hasDaily = schedules.some(s => s.callback === "dailyTask");
+  if (!hasDaily) {
+    await this.schedule("0 9 * * *", "dailyTask", {});
+  }
+}
+```
+
+## Deployment Issues
+
+### "Class MyAgent is not exported"
+
+```typescript
+// src/index.ts - Must export the class
+export { MyAgent } from "./agent";
+
+// Or if defined in same file
+export class MyAgent extends Agent { ... }
+```
+
+### "Durable Object not found"
+
+Check `wrangler.toml`:
+
+```toml
+[durable_objects]
+bindings = [{ name = "AGENT", class_name = "MyAgent" }]
+
+[[migrations]]
+tag = "v1"
+new_classes = ["MyAgent"]
+```
+
+### "Migration required"
+
+When adding new Durable Object classes:
+
+```toml
+[[migrations]]
+tag = "v2"  # Increment from previous
+new_classes = ["NewAgentClass"]
+
+# Or for renames
+# renamed_classes = [{ from = "OldName", to = "NewName" }]
+```
+
+## AI Integration Issues
+
+### "AI binding not found"
+
+Add to `wrangler.toml`:
+
+```toml
+[ai]
+binding = "AI"
+```
+
+### "Model not found" / "Rate limited"
+
+```typescript
+// Check model name is correct
+const response = await this.env.AI.run(
+  "@cf/meta/llama-3-8b-instruct",  // Exact model name
+  { messages: [...] }
+);
+
+// Handle rate limits
+try {
+  const response = await this.env.AI.run(...);
+} catch (error) {
+  if (error.message.includes("rate limit")) {
+    // Retry with backoff or use queue
+  }
+}
+```
+
+### "Streaming not working"
+
+```typescript
+// Enable streaming
+const stream = await this.env.AI.run("@cf/meta/llama-3-8b-instruct", {
+  messages: [...],
+  stream: true,  // Must be true
+});
+
+// Iterate over stream
+for await (const chunk of stream) {
+  connection.send(JSON.stringify({ type: "chunk", content: chunk.response }));
+}
+```
+
+## Debugging Tips
+
+### Enable Verbose Logging
+
+```typescript
+export class MyAgent extends Agent<Env, State> {
+  async onStart() {
+    console.log("Agent starting, state:", JSON.stringify(this.state));
+  }
+
+  async onConnect(connection: Connection) {
+    console.log("Client connected:", connection.id);
+  }
+
+  async onMessage(connection: Connection, message: string) {
+    console.log("Received message:", message);
+    // ... handle
+    console.log("State after:", JSON.stringify(this.state));
+  }
+
+  async onClose(connection: Connection) {
+    console.log("Client disconnected:", connection.id);
+  }
+}
+```
+
+View logs:
+```bash
+wrangler tail --format pretty
+```
+
+### Test Locally First
+
+```bash
+npm start
+# Connect with test client or use browser console:
+# new WebSocket("ws://localhost:8787/agent/test")
+```
+
+### Inspect State
+
+Add a debug endpoint:
+
+```typescript
+async onRequest(request: Request) {
+  const url = new URL(request.url);
+
+  if (url.pathname === "/debug") {
+    return Response.json({
+      state: this.state,
+      schedules: await this.getSchedules(),
+    });
+  }
+
+  return new Response("Not found", { status: 404 });
+}
+```