@bcelep/capint 0.4.2 → 0.7.0

package/skills/cloudflare/references/agents-sdk/configuration.md

@@ -0,0 +1,182 @@
+# Configuration
+
+## Wrangler Setup
+
+```jsonc
+{
+  "name": "my-agents-app",
+  "durable_objects": {
+    "bindings": [
+      {"name": "MyAgent", "class_name": "MyAgent"}
+    ]
+  },
+  "migrations": [
+    {"tag": "v1", "new_sqlite_classes": ["MyAgent"]}
+  ],
+  "ai": {
+    "binding": "AI"
+  }
+}
+```
+
+## Environment Bindings
+
+**Type-safe pattern:**
+
+```typescript
+interface Env {
+  AI?: Ai;                              // Workers AI
+  MyAgent?: DurableObjectNamespace<MyAgent>;
+  ChatAgent?: DurableObjectNamespace<ChatAgent>;
+  DB?: D1Database;                      // D1 database
+  KV?: KVNamespace;                     // KV storage
+  R2?: R2Bucket;                        // R2 bucket
+  OPENAI_API_KEY?: string;              // Secrets
+  GITHUB_CLIENT_ID?: string;            // MCP OAuth credentials
+  GITHUB_CLIENT_SECRET?: string;
+  QUEUE?: Queue;                        // Queues
+}
+```
+
+**Best practice:** Define all DO bindings in Env interface for type safety.
+
+## Deployment
+
+```bash
+# Local dev
+npx wrangler dev
+
+# Deploy production
+npx wrangler deploy
+
+# Set secrets
+npx wrangler secret put OPENAI_API_KEY
+```
+
+## Agent Routing
+
+**Recommended: Use route helpers**
+
+```typescript
+import { routeAgent } from "agents";
+
+export default {
+  fetch(request: Request, env: Env) {
+    return routeAgent(request, env);
+  }
+}
+```
+
+Helper routes requests to agents automatically based on URL patterns.
+
+**Manual routing (advanced):**
+
+```typescript
+export default {
+  async fetch(request: Request, env: Env) {
+    const url = new URL(request.url);
+    
+    // Named ID (deterministic)
+    const id = env.MyAgent.idFromName("user-123");
+    
+    // Random ID (from URL param)
+    // const id = env.MyAgent.idFromString(url.searchParams.get("id"));
+    
+    const stub = env.MyAgent.get(id);
+    return stub.fetch(request);
+  }
+}
+```
+
+**Multi-agent setup:**
+
+```typescript
+import { routeAgent } from "agents";
+
+export default {
+  fetch(request: Request, env: Env) {
+    const url = new URL(request.url);
+    
+    // Route by path
+    if (url.pathname.startsWith("/chat")) {
+      return routeAgent(request, env, "ChatAgent");
+    }
+    if (url.pathname.startsWith("/task")) {
+      return routeAgent(request, env, "TaskAgent");
+    }
+    
+    return new Response("Not found", { status: 404 });
+  }
+}
+```
+
+## Email Routing
+
+**Code setup:**
+
+```typescript
+import { routeAgentEmail } from "agents";
+
+export default {
+  fetch: (req: Request, env: Env) => routeAgent(req, env),
+  email: (message: ForwardableEmailMessage, env: Env) => {
+    return routeAgentEmail(message, env);
+  }
+}
+```
+
+**Dashboard setup:**
+
+Configure email routing in Cloudflare dashboard:
+
+```
+Destination: Workers with Durable Objects
+Worker: my-agents-app
+```
+
+Then handle in agent:
+
+```typescript
+export class EmailAgent extends Agent<Env> {
+  async onEmail(email: AgentEmail) {
+    const text = await email.text();
+    // Process email
+  }
+}
+```
+
+## AI Gateway (Optional)
+
+```typescript
+// Enable caching/routing through AI Gateway
+const response = await this.env.AI.run(
+  "@cf/meta/llama-3.1-8b-instruct",
+  { prompt },
+  {
+    gateway: {
+      id: "my-gateway-id",
+      skipCache: false,
+      cacheTtl: 3600
+    }
+  }
+);
+```
+
+## MCP Configuration (Optional)
+
+For exposing tools via Model Context Protocol:
+
+```typescript
+// wrangler.jsonc - Add MCP OAuth secrets
+{
+  "vars": {
+    "MCP_SERVER_URL": "https://mcp.example.com"
+  }
+}
+
+// Set secrets via CLI
+// npx wrangler secret put GITHUB_CLIENT_ID
+// npx wrangler secret put GITHUB_CLIENT_SECRET
+```
+
+Then register in agent code (see api.md MCP section).

package/skills/cloudflare/references/agents-sdk/gotchas.md

@@ -0,0 +1,158 @@
+# Gotchas & Best Practices
+
+## Common Errors
+
+### "setState() not syncing"
+
+**Cause:** Mutating state directly or not calling `setState()` after modifications  
+**Solution:** Always use `setState()` with immutable updates:
+```ts
+// ❌ this.state.count++
+// ✅ this.setState({...this.state, count: this.state.count + 1})
+```
+
+### "Message history grows unbounded (AIChatAgent)"
+
+**Cause:** `this.messages` in `AIChatAgent` accumulates all messages indefinitely  
+**Solution:** Manually trim old messages periodically:
+```ts
+export class ChatAgent extends AIChatAgent<Env> {
+  async onChatMessage(onFinish) {
+    // Keep only last 50 messages
+    if (this.messages.length > 50) {
+      this.messages = this.messages.slice(-50);
+    }
+    
+    return this.streamText({ model: openai("gpt-4"), messages: this.messages, onFinish });
+  }
+}
+```
+
+### "SQL injection vulnerability"
+
+**Cause:** Direct string interpolation in SQL queries
+**Solution:** Use parameterized queries:
+```ts
+// ❌ this.sql`...WHERE id = '${userId}'`
+// ✅ this.sql`...WHERE id = ${userId}`
+```
+
+### "WebSocket connection timeout"
+
+**Cause:** Not calling `conn.accept()` in `onConnect`
+**Solution:** Always accept connections:
+```ts
+async onConnect(conn: Connection, ctx: ConnectionContext) { conn.accept(); conn.setState({userId: "123"}); }
+```
+
+### "Schedule limit exceeded"
+
+**Cause:** More than 1000 scheduled tasks per agent
+**Solution:** Clean up old schedules and limit creation rate:
+```ts
+async checkSchedules() { if ((await this.getSchedules()).length > 800) console.warn("Near limit!"); }
+```
+
+### "AI Gateway unavailable"
+
+**Cause:** AI service timeout or quota exceeded  
+**Solution:** Add error handling and fallbacks:
+```ts
+try { 
+  return await this.env.AI.run(model, {prompt}); 
+} catch (e) { 
+  console.error("AI error:", e);
+  return {error: "Unavailable"}; 
+}
+```
+
+### "@callable method returns undefined"
+
+**Cause:** Method doesn't return JSON-serializable value, or has non-serializable types  
+**Solution:** Ensure return values are plain objects/arrays/primitives:
+```ts
+// ❌ Returns class instance
+@callable()
+async getData() { return new Date(); }
+
+// ✅ Returns serializable object
+@callable()
+async getData() { return { timestamp: Date.now() }; }
+```
+
+### "Resumable stream not resuming"
+
+**Cause:** Stream ID must be deterministic for resumption to work  
+**Solution:** Use AIChatAgent (automatic) or ensure consistent stream IDs:
+```ts
+// AIChatAgent handles this automatically
+export class ChatAgent extends AIChatAgent<Env> {
+  // Resumption works out of the box
+}
+```
+
+### "MCP connection loss on hibernation"
+
+**Cause:** MCP server connections don't survive hibernation  
+**Solution:** Re-register servers in `onStart()` or check connection status:
+```ts
+onStart() {
+  // Re-register MCP servers after hibernation
+  await this.mcp.registerServer("github", { url: env.MCP_URL, auth: {...} });
+}
+```
+
+### "Agent not found"
+
+**Cause:** Durable Object binding missing or incorrect class name  
+**Solution:** Verify DO binding in wrangler.jsonc and class name matches
+
+## Rate Limits & Quotas
+
+| Resource/Limit | Value | Notes |
+|----------------|-------|-------|
+| CPU per request | 30s (std), 300s (max) | Set in wrangler.jsonc |
+| Memory per instance | 128MB | Shared with WebSockets |
+| Storage per agent | 10GB | SQLite storage |
+| Scheduled tasks | 1000 per agent | Monitor with `getSchedules()` |
+| WebSocket connections | Unlimited | Within memory limits |
+| SQL columns | 100 | Per table |
+| SQL row size | 2MB | Key + value |
+| WebSocket message | 32MiB | Max size |
+| DO requests/sec | ~1000 | Per unique DO instance; rate limit if needed |
+| AI Gateway (Workers AI) | Model-specific | Check dashboard for limits |
+| MCP requests | Depends on server | Implement retry/backoff |
+
+## Best Practices
+
+### State Management
+- Use immutable updates: `setState({...this.state, key: newValue})`
+- Trim unbounded arrays (messages, logs) periodically
+- Store large data in SQL, not state
+
+### SQL Usage
+- Create tables in `onStart()`, not `onRequest()`
+- Use parameterized queries: `` sql`WHERE id = ${id}` `` (NOT `` sql`WHERE id = '${id}'` ``)
+- Index frequently queried columns
+
+### Scheduling
+- Monitor schedule count: `await this.getSchedules()`
+- Cancel completed tasks to stay under 1000 limit
+- Use cron strings for recurring tasks
+
+### WebSockets
+- Always call `conn.accept()` in `onConnect()`
+- Handle client disconnects gracefully
+- Broadcast to `this.connections` efficiently
+
+### AI Integration
+- Use `AIChatAgent` for chat interfaces (auto-streaming, resumption)
+- Trim message history to avoid token limits
+- Handle AI errors with try/catch and fallbacks
+
+### Production Deployment
+- **Rate limiting:** Implement request throttling for high-traffic agents (>1000 req/s)
+- **Monitoring:** Log critical errors, track schedule count, monitor storage usage
+- **Graceful degradation:** Handle AI service outages with fallbacks
+- **Message trimming:** Enforce max history length (e.g., 100 messages) in AIChatAgent
+- **MCP reliability:** Re-register servers on hibernation, implement retry logic

package/skills/cloudflare/references/agents-sdk/patterns.md

@@ -0,0 +1,192 @@
+# Patterns & Use Cases
+
+## AI Chat w/Tools
+
+**Server (AIChatAgent):**
+
+```ts
+import { AIChatAgent } from "agents";
+import { openai } from "@ai-sdk/openai";
+import { tool } from "ai";
+import { z } from "zod";
+
+export class ChatAgent extends AIChatAgent<Env> {
+  async onChatMessage(onFinish) {
+    return this.streamText({
+      model: openai("gpt-4"),
+      messages: this.messages, // Auto-managed
+      tools: {
+        getWeather: tool({
+          description: "Get current weather",
+          parameters: z.object({ city: z.string() }),
+          execute: async ({ city }) => `Weather in ${city}: Sunny, 72°F`
+        }),
+        searchDocs: tool({
+          description: "Search documentation",
+          parameters: z.object({ query: z.string() }),
+          execute: async ({ query }) => JSON.stringify(
+            this.sql<{title, content}>`SELECT title, content FROM docs WHERE content LIKE ${'%' + query + '%'}`
+          )
+        })
+      },
+      onFinish,
+    });
+  }
+}
+```
+
+**Client (React):**
+
+```tsx
+import { useAgent } from "agents/react";
+import { useAgentChat } from "agents/ai-react";
+
+function ChatUI() {
+  const agent = useAgent({ agent: "ChatAgent" });
+  const { messages, input, handleInputChange, handleSubmit, isLoading } = useAgentChat({ agent });
+  
+  return (
+    <div>
+      {messages.map(m => <div key={m.id}>{m.role}: {m.content}</div>)}
+      <form onSubmit={handleSubmit}>
+        <input value={input} onChange={handleInputChange} disabled={isLoading} />
+        <button disabled={isLoading}>Send</button>
+      </form>
+    </div>
+  );
+}
+```
+
+## Human-in-the-Loop (Client Tools)
+
+Server defines tool, client executes:
+
+```ts
+// Server
+export class ChatAgent extends AIChatAgent<Env> {
+  async onChatMessage(onFinish) {
+    return this.streamText({
+      model: openai("gpt-4"),
+      messages: this.messages,
+      tools: {
+        confirmAction: tool({
+          description: "Ask user to confirm",
+          parameters: z.object({ action: z.string() }),
+          execute: "client", // Client-side execution
+        })
+      },
+      onFinish,
+    });
+  }
+}
+
+// Client
+const { messages } = useAgentChat({
+  agent,
+  onToolCall: async (toolCall) => {
+    if (toolCall.toolName === "confirmAction") {
+      return { confirmed: window.confirm(`Confirm: ${toolCall.args.action}?`) };
+    }
+  }
+});
+```
+
+## Task Queue & Scheduled Processing
+
+```ts
+export class TaskAgent extends Agent<Env> {
+  onStart() { 
+    this.schedule("*/5 * * * *", "processQueue", {}); // Every 5 min
+    this.schedule("0 0 * * *", "dailyCleanup", {}); // Daily
+  }
+  
+  async onRequest(req: Request) {
+    await this.queue("processVideo", { videoId: (await req.json()).videoId });
+    return Response.json({ queued: true });
+  }
+  
+  async processQueue() {
+    const tasks = await this.dequeue(10);
+    for (const task of tasks) {
+      if (task.name === "processVideo") await this.processVideo(task.data.videoId);
+    }
+  }
+  
+  async dailyCleanup() {
+    this.sql`DELETE FROM logs WHERE created_at < ${Date.now() - 86400000}`;
+  }
+}
+```
+
+## Manual WebSocket Chat
+
+Custom protocols (non-AI):
+
+```ts
+export class ChatAgent extends Agent<Env> {
+  async onConnect(conn: Connection, ctx: ConnectionContext) {
+    conn.accept();
+    conn.setState({userId: ctx.request.headers.get("X-User-ID") || "anon"});
+    conn.send(JSON.stringify({type: "history", messages: this.state.messages}));
+  }
+  
+  async onMessage(conn: Connection, msg: WSMessage) {
+    const newMsg = {userId: conn.state.userId, text: JSON.parse(msg as string).text, timestamp: Date.now()};
+    this.setState({messages: [...this.state.messages, newMsg]});
+    this.connections.forEach(c => c.send(JSON.stringify(newMsg)));
+  }
+}
+```
+
+## Email Processing w/AI
+
+```ts
+export class EmailAgent extends Agent<Env> {
+  async onEmail(email: AgentEmail) {
+    const [text, from, subject] = [await email.text(), email.from, email.headers.get("subject") || ""];
+    this.sql`INSERT INTO emails (from_addr, subject, body) VALUES (${from}, ${subject}, ${text})`;
+    
+    const { text: summary } = await generateText({
+      model: openai("gpt-4o-mini"), prompt: `Summarize: ${subject}\n\n${text}`
+    });
+    
+    this.connections.forEach(c => c.send(JSON.stringify({type: "new_email", from, summary})));
+    if (summary.includes("urgent")) await this.schedule(0, "sendAutoReply", { to: from });
+  }
+}
+```
+
+## Real-time Collaboration
+
+```ts
+export class GameAgent extends Agent<Env> {
+  initialState = { players: [], gameStarted: false };
+  
+  async onConnect(conn: Connection, ctx: ConnectionContext) {
+    conn.accept();
+    const playerId = ctx.request.headers.get("X-Player-ID") || crypto.randomUUID();
+    conn.setState({ playerId });
+    
+    const newPlayer = { id: playerId, score: 0 };
+    this.setState({...this.state, players: [...this.state.players, newPlayer]});
+    this.connections.forEach(c => c.send(JSON.stringify({type: "player_joined", player: newPlayer})));
+  }
+  
+  async onMessage(conn: Connection, msg: WSMessage) {
+    const m = JSON.parse(msg as string);
+    
+    if (m.type === "move") {
+      this.setState({
+        ...this.state,
+        players: this.state.players.map(p => p.id === conn.state.playerId ? {...p, score: p.score + m.points} : p)
+      });
+      this.connections.forEach(c => c.send(JSON.stringify({type: "player_moved", playerId: conn.state.playerId})));
+    }
+    
+    if (m.type === "start" && this.state.players.length >= 2) {
+      this.setState({...this.state, gameStarted: true});
+      this.connections.forEach(c => c.send(JSON.stringify({type: "game_started"})));
+    }
+  }
+}
+```

package/skills/cloudflare/references/ai-gateway/README.md

@@ -0,0 +1,175 @@
+# Cloudflare AI Gateway
+
+Expert guidance for implementing Cloudflare AI Gateway - a universal gateway for AI model providers with analytics, caching, rate limiting, and routing capabilities.
+
+## When to Use This Reference
+
+- Setting up AI Gateway for any AI provider (OpenAI, Anthropic, Workers AI, etc.)
+- Implementing caching, rate limiting, or request retry/fallback
+- Configuring dynamic routing with A/B testing or model fallbacks
+- Managing provider API keys securely with BYOK
+- Adding security features (guardrails, DLP)
+- Setting up observability with logging and custom metadata
+- Debugging AI Gateway requests or optimizing configurations
+
+## Quick Start
+
+**What's your setup?**
+
+- **Using Vercel AI SDK** → Pattern 1 (recommended) - see [sdk-integration.md](./sdk-integration.md)
+- **Using OpenAI SDK** → Pattern 2 - see [sdk-integration.md](./sdk-integration.md)
+- **Cloudflare Worker + Workers AI** → Pattern 3 - see [sdk-integration.md](./sdk-integration.md)
+- **Direct HTTP (any language)** → Pattern 4 - see [configuration.md](./configuration.md)
+- **Framework (LangChain, etc.)** → See [sdk-integration.md](./sdk-integration.md)
+
+## Pattern 1: Vercel AI SDK (Recommended)
+
+Most modern pattern using official `ai-gateway-provider` package with automatic fallbacks.
+
+```typescript
+import { createAiGateway } from 'ai-gateway-provider';
+import { createOpenAI } from '@ai-sdk/openai';
+import { generateText } from 'ai';
+
+const gateway = createAiGateway({
+  accountId: process.env.CF_ACCOUNT_ID,
+  gateway: process.env.CF_GATEWAY_ID,
+});
+
+const openai = createOpenAI({ 
+  apiKey: process.env.OPENAI_API_KEY 
+});
+
+// Single model
+const { text } = await generateText({
+  model: gateway(openai('gpt-4o')),
+  prompt: 'Hello'
+});
+
+// Automatic fallback array
+const { text } = await generateText({
+  model: gateway([
+    openai('gpt-4o'),              // Try first
+    anthropic('claude-sonnet-4-5'), // Fallback
+  ]),
+  prompt: 'Hello'
+});
+```
+
+**Install:** `npm install ai-gateway-provider ai @ai-sdk/openai @ai-sdk/anthropic`
+
+## Pattern 2: OpenAI SDK
+
+Drop-in replacement for OpenAI API with multi-provider support.
+
+```typescript
+import OpenAI from 'openai';
+
+const client = new OpenAI({
+  apiKey: process.env.OPENAI_API_KEY,
+  baseURL: `https://gateway.ai.cloudflare.com/v1/${accountId}/${gatewayId}/compat`,
+  defaultHeaders: {
+    'cf-aig-authorization': `Bearer ${cfToken}` // For authenticated gateways
+  }
+});
+
+// Switch providers by changing model format: {provider}/{model}
+const response = await client.chat.completions.create({
+  model: 'openai/gpt-4o', // or 'anthropic/claude-sonnet-4-5'
+  messages: [{ role: 'user', content: 'Hello!' }]
+});
+```
+
+## Pattern 3: Workers AI Binding
+
+For Cloudflare Workers using Workers AI.
+
+```typescript
+export default {
+  async fetch(request, env, ctx) {
+    const response = await env.AI.run(
+      '@cf/meta/llama-3-8b-instruct',
+      { messages: [{ role: 'user', content: 'Hello!' }] },
+      { 
+        gateway: { 
+          id: 'my-gateway',
+          metadata: { userId: '123', team: 'engineering' }
+        } 
+      }
+    );
+    
+    return Response.json(response);
+  }
+};
+```
+
+## Headers Quick Reference
+
+| Header | Purpose | Example | Notes |
+|--------|---------|---------|-------|
+| `cf-aig-authorization` | Gateway auth | `Bearer {token}` | Required for authenticated gateways |
+| `cf-aig-metadata` | Tracking | `{"userId":"x"}` | Max 5 entries, flat structure |
+| `cf-aig-cache-ttl` | Cache duration | `3600` | Seconds, min 60, max 2592000 (30 days) |
+| `cf-aig-skip-cache` | Bypass cache | `true` | - |
+| `cf-aig-cache-key` | Custom cache key | `my-key` | Must be unique per response |
+| `cf-aig-collect-log` | Skip logging | `false` | Default: true |
+| `cf-aig-cache-status` | Cache hit/miss | Response only | `HIT` or `MISS` |
+
+## In This Reference
+
+| File | Purpose |
+|------|---------|
+| [sdk-integration.md](./sdk-integration.md) | Vercel AI SDK, OpenAI SDK, Workers binding patterns |
+| [configuration.md](./configuration.md) | Dashboard setup, wrangler, API tokens |
+| [features.md](./features.md) | Caching, rate limits, guardrails, DLP, BYOK, unified billing |
+| [dynamic-routing.md](./dynamic-routing.md) | Fallbacks, A/B testing, conditional routing |
+| [troubleshooting.md](./troubleshooting.md) | Debugging, errors, observability, gotchas |
+
+## Reading Order
+
+| Task | Files |
+|------|-------|
+| First-time setup | README + [configuration.md](./configuration.md) |
+| SDK integration | README + [sdk-integration.md](./sdk-integration.md) |
+| Enable caching | README + [features.md](./features.md) |
+| Setup fallbacks | README + [dynamic-routing.md](./dynamic-routing.md) |
+| Debug errors | README + [troubleshooting.md](./troubleshooting.md) |
+
+## Architecture
+
+AI Gateway acts as a proxy between your application and AI providers:
+
+```
+Your App → AI Gateway → AI Provider (OpenAI, Anthropic, etc.)
+         ↓
+    Analytics, Caching, Rate Limiting, Logging
+```
+
+**Key URL patterns:**
+- Unified API (OpenAI-compatible): `https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/compat/chat/completions`
+- Provider-specific: `https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/{provider}/{endpoint}`
+- Dynamic routes: Use route name instead of model: `dynamic/{route-name}`
+
+## Gateway Types
+
+1. **Unauthenticated Gateway**: Open access (not recommended for production)
+2. **Authenticated Gateway**: Requires `cf-aig-authorization` header with Cloudflare API token (recommended)
+
+## Provider Authentication Options
+
+1. **Unified Billing**: Use AI Gateway billing to pay for inference (keyless mode - no provider API key needed)
+2. **BYOK (Store Keys)**: Store provider API keys in Cloudflare dashboard
+3. **Request Headers**: Include provider API key in each request
+
+## Related Skills
+
+- [Workers AI](../workers-ai/README.md) - For `env.AI.run()` details
+- [Agents SDK](../agents-sdk/README.md) - For stateful AI patterns
+- [Vectorize](../vectorize/README.md) - For RAG patterns with embeddings
+
+## Resources
+
+- [Official Docs](https://developers.cloudflare.com/ai-gateway/)
+- [API Reference](https://developers.cloudflare.com/api/resources/ai_gateway/)
+- [Provider Guides](https://developers.cloudflare.com/ai-gateway/usage/providers/)
+- [Discord Community](https://discord.cloudflare.com)