@namch/agent-assistant 1.0.0

package/skills/cloudflare-expert/SKILL.md

@@ -0,0 +1,227 @@
+---
+name: cloudflare-expert
+description: Comprehensive Cloudflare platform skill covering Workers, Pages, storage (KV, D1, R2), AI (Workers AI, Vectorize, Agents SDK), networking (Tunnel, Spectrum), security (WAF, DDoS), and infrastructure-as-code (Terraform, Pulumi). Use PROACTIVELY for any Cloudflare development task.
+---
+
+# Cloudflare Platform Skill
+
+Consolidated skill for building on the Cloudflare platform. Use decision trees below to find the right product, then load detailed references.
+
+## How to Use This Skill
+
+### Reference File Structure
+
+Each product in `./references/<product>/` contains a `README.md` as the entry point, which may be structured in one of two ways:
+
+**Multi-file format (5 files):**
+| File | Purpose | When to Read |
+|------|---------|--------------|
+| `README.md` | Overview, when to use, getting started | **Always read first** |
+| `api.md` | Runtime API, types, method signatures | Writing code |
+| `configuration.md` | wrangler.toml, bindings, setup | Configuring a project |
+| `patterns.md` | Common patterns, best practices | Implementation guidance |
+| `gotchas.md` | Pitfalls, limitations, edge cases | Debugging, avoiding mistakes |
+
+**Single-file format:** All information consolidated in `README.md`.
+
+### Reading Order
+
+1. Start with `README.md`
+2. Then read additional files relevant to your task (if multi-file format):
+   - Building feature → `api.md` + `patterns.md`
+   - Setting up project → `configuration.md`
+   - Troubleshooting → `gotchas.md`
+
+### Example Paths
+
+```
+./references/workflows/README.md         # Start here for Workflows
+./references/workflows/api.md            # Workflow class, step methods
+./references/durable-objects/gotchas.md  # DO limitations
+./references/workers-ai/README.md        # Single-file - all Workers AI docs
+```
+
+## Quick Decision Trees
+
+### "I need to run code"
+
+```
+Need to run code?
+├─ Serverless functions at the edge → workers/
+├─ Full-stack web app with Git deploys → pages/
+├─ Stateful coordination/real-time → durable-objects/
+├─ Long-running multi-step jobs → workflows/
+├─ Run containers → containers/
+├─ Multi-tenant (customers deploy code) → workers-for-platforms/
+└─ Scheduled tasks (cron) → cron-triggers/
+```
+
+### "I need to store data"
+
+```
+Need storage?
+├─ Key-value (config, sessions, cache) → kv/
+├─ Relational SQL → d1/ (SQLite) or hyperdrive/ (existing Postgres/MySQL)
+├─ Object/file storage (S3-compatible) → r2/
+├─ Message queue (async processing) → queues/
+├─ Vector embeddings (AI/semantic search) → vectorize/
+├─ Strongly-consistent per-entity state → durable-objects/ (DO storage)
+├─ Secrets management → secrets-store/
+└─ Streaming ETL to R2 → pipelines/
+```
+
+### "I need AI/ML"
+
+```
+Need AI?
+├─ Run inference (LLMs, embeddings, images) → workers-ai/
+├─ Vector database for RAG/search → vectorize/
+├─ Build stateful AI agents → agents-sdk/
+├─ Gateway for any AI provider (caching, routing) → ai-gateway/
+└─ AI-powered search widget → ai-search/
+```
+
+### "I need networking/connectivity"
+
+```
+Need networking?
+├─ Expose local service to internet → tunnel/
+├─ TCP/UDP proxy (non-HTTP) → spectrum/
+├─ WebRTC TURN server → turn/
+├─ Private network connectivity → network-interconnect/
+├─ Optimize routing → argo-smart-routing/
+└─ Real-time video/audio → realtimekit/ or realtime-sfu/
+```
+
+### "I need security"
+
+```
+Need security?
+├─ Web Application Firewall → waf/
+├─ DDoS protection → ddos/
+├─ Bot detection/management → bot-management/
+├─ API protection → api-shield/
+├─ CAPTCHA alternative → turnstile/
+└─ Credential leak detection → waf/ (managed ruleset)
+```
+
+### "I need media/content"
+
+```
+Need media?
+├─ Image optimization/transformation → images/
+├─ Video streaming/encoding → stream/
+├─ Browser automation/screenshots → browser-rendering/
+└─ Third-party script management → zaraz/
+```
+
+### "I need infrastructure-as-code"
+
+```
+Need IaC?
+├─ Pulumi → pulumi/
+├─ Terraform → terraform/
+└─ Direct API → api/
+```
+
+## Product Index
+
+### Compute & Runtime
+| Product | Entry File |
+|---------|------------|
+| Workers | `./references/workers/README.md` |
+| Pages | `./references/pages/README.md` |
+| Pages Functions | `./references/pages-functions/README.md` |
+| Durable Objects | `./references/durable-objects/README.md` |
+| Workflows | `./references/workflows/README.md` |
+| Containers | `./references/containers/README.md` |
+| Workers for Platforms | `./references/workers-for-platforms/README.md` |
+| Cron Triggers | `./references/cron-triggers/README.md` |
+| Tail Workers | `./references/tail-workers/README.md` |
+| Snippets | `./references/snippets/README.md` |
+| Smart Placement | `./references/smart-placement/README.md` |
+
+### Storage & Data
+| Product | Entry File |
+|---------|------------|
+| KV | `./references/kv/README.md` |
+| D1 | `./references/d1/README.md` |
+| R2 | `./references/r2/README.md` |
+| Queues | `./references/queues/README.md` |
+| Hyperdrive | `./references/hyperdrive/README.md` |
+| DO Storage | `./references/do-storage/README.md` |
+| Secrets Store | `./references/secrets-store/README.md` |
+| Pipelines | `./references/pipelines/README.md` |
+| R2 Data Catalog | `./references/r2-data-catalog/README.md` |
+| R2 SQL | `./references/r2-sql/README.md` |
+
+### AI & Machine Learning
+| Product | Entry File |
+|---------|------------|
+| Workers AI | `./references/workers-ai/README.md` |
+| Vectorize | `./references/vectorize/README.md` |
+| Agents SDK | `./references/agents-sdk/README.md` |
+| AI Gateway | `./references/ai-gateway/README.md` |
+| AI Search | `./references/ai-search/README.md` |
+
+### Networking & Connectivity
+| Product | Entry File |
+|---------|------------|
+| Tunnel | `./references/tunnel/README.md` |
+| Spectrum | `./references/spectrum/README.md` |
+| TURN | `./references/turn/README.md` |
+| Network Interconnect | `./references/network-interconnect/README.md` |
+| Argo Smart Routing | `./references/argo-smart-routing/README.md` |
+| Workers VPC | `./references/workers-vpc/README.md` |
+
+### Security
+| Product | Entry File |
+|---------|------------|
+| WAF | `./references/waf/README.md` |
+| DDoS Protection | `./references/ddos/README.md` |
+| Bot Management | `./references/bot-management/README.md` |
+| API Shield | `./references/api-shield/README.md` |
+| Turnstile | `./references/turnstile/README.md` |
+
+### Media & Content
+| Product | Entry File |
+|---------|------------|
+| Images | `./references/images/README.md` |
+| Stream | `./references/stream/README.md` |
+| Browser Rendering | `./references/browser-rendering/README.md` |
+| Zaraz | `./references/zaraz/README.md` |
+
+### Real-Time Communication
+| Product | Entry File |
+|---------|------------|
+| RealtimeKit | `./references/realtimekit/README.md` |
+| Realtime SFU | `./references/realtime-sfu/README.md` |
+
+### Developer Tools
+| Product | Entry File |
+|---------|------------|
+| Wrangler | `./references/wrangler/README.md` |
+| Miniflare | `./references/miniflare/README.md` |
+| C3 | `./references/c3/README.md` |
+| Observability | `./references/observability/README.md` |
+| Analytics Engine | `./references/analytics-engine/README.md` |
+| Web Analytics | `./references/web-analytics/README.md` |
+| Sandbox | `./references/sandbox/README.md` |
+| Workerd | `./references/workerd/README.md` |
+| Workers Playground | `./references/workers-playground/README.md` |
+
+### Infrastructure as Code
+| Product | Entry File |
+|---------|------------|
+| Pulumi | `./references/pulumi/README.md` |
+| Terraform | `./references/terraform/README.md` |
+| API | `./references/api/README.md` |
+
+### Other Services
+| Product | Entry File |
+|---------|------------|
+| Email Routing | `./references/email-routing/README.md` |
+| Email Workers | `./references/email-workers/README.md` |
+| Static Assets | `./references/static-assets/README.md` |
+| Bindings | `./references/bindings/README.md` |
+| Cache Reserve | `./references/cache-reserve/README.md` |

package/skills/cloudflare-expert/references/agents-sdk/README.md

@@ -0,0 +1,35 @@
+# Cloudflare Agents SDK
+
+Cloudflare Agents SDK enables building AI-powered agents on Durable Objects with state, WebSockets, SQL, scheduling, and AI integration.
+
+## Core Value
+Build stateful, globally distributed AI agents with persistent memory, real-time connections, scheduled tasks, and async workflows.
+
+## When to Use
+- Persistent state + memory required
+- Real-time WebSocket connections
+- Long-running workflows (minutes/hours)
+- Chat interfaces with AI models
+- Scheduled/recurring tasks with state
+- DB queries with agent state
+
+## Quick Start
+```typescript
+import { Agent } from "agents";
+
+export class MyAgent extends Agent<Env> {
+  onStart() {
+    this.sql`CREATE TABLE IF NOT EXISTS users (id TEXT PRIMARY KEY)`;
+  }
+  
+  async onRequest(request: Request) {
+    return Response.json({ state: this.state });
+  }
+}
+```
+
+## See Also
+- durable-objects - Agent infrastructure
+- d1 - External database integration
+- workers-ai - AI model integration
+- vectorize - Vector search for RAG patterns

package/skills/cloudflare-expert/references/agents-sdk/api.md

@@ -0,0 +1,100 @@
+# API Reference
+
+## Lifecycle
+
+**onStart()** - Init/hibernation restart:
+```ts
+onStart() {
+  this.sql`CREATE TABLE IF NOT EXISTS users (id TEXT PRIMARY KEY, name TEXT)`;
+  if (!this.state.initialized) this.setState({initialized: true, messages: []});
+}
+```
+
+**onRequest(req)** - HTTP:
+```ts
+async onRequest(req: Request) {
+  const {pathname} = new URL(req.url);
+  if (pathname === "/users") return Response.json(this.sql<{id,name}>`SELECT * FROM users`);
+  return new Response("Not found", {status: 404});
+}
+```
+
+**onConnect(conn, ctx)** - WebSocket:
+```ts
+async onConnect(conn: Connection, ctx: ConnectionContext) {
+  conn.accept();
+  conn.setState({userId: ctx.request.headers.get("X-User-ID")});
+  conn.send(JSON.stringify({type: "connected", state: this.state}));
+}
+```
+
+**onMessage(conn, msg)** - WS messages:
+```ts
+async onMessage(conn: Connection, msg: WSMessage) {
+  const m = JSON.parse(msg as string);
+  if (m.type === "chat") {
+    this.setState({messages: [...this.state.messages, m]});
+    this.connections.forEach(c => c.send(JSON.stringify(m)));
+  }
+}
+```
+
+**onEmail(email)** - Email routing:
+```ts
+async onEmail(email: AgentEmail) {
+  const text = await email.text();
+  this.sql`INSERT INTO emails (from_addr,subject,body) VALUES (${email.from},${email.headers.get("subject")},${text})`;
+}
+```
+
+## State
+
+```ts
+this.setState({count: 42, users: []}); // Auto-syncs
+this.setState({...this.state, count: this.state.count + 1});
+const s = this.state;
+```
+
+## SQL
+
+```ts
+this.sql`CREATE TABLE IF NOT EXISTS users (id TEXT PRIMARY KEY, name TEXT)`;
+this.sql`INSERT INTO users (id,name) VALUES (${userId},${name})`;
+const users = this.sql<{id,name}>`SELECT * FROM users`;
+const user = this.sql<{name}>`SELECT name FROM users WHERE id = ${userId}`; // Prevents injection
+```
+
+## Scheduling
+
+```ts
+await this.schedule(new Date("2026-12-25T00:00:00Z"), "sendGreeting", {msg:"Hi"}); // Time
+await this.schedule(60, "checkStatus", {}); // Delay (sec)
+await this.schedule("0 0 * * *", "dailyCleanup", {}); // Cron
+await this.schedule("*/5 * * * *", "syncData", {}); // Every 5min
+const schedules = await this.getSchedules();
+await this.cancelSchedule(scheduleId);
+```
+
+## Connections
+
+```ts
+this.connections.forEach(c => c.send(JSON.stringify(msg))); // Broadcast
+conn.send(JSON.stringify({type:"update",data})); // Specific
+conn.close(1000, "Goodbye");
+conn.setState({userId:"123",role:"admin"});
+const uid = conn.state.userId;
+```
+
+## AI
+
+```ts
+const r = await this.env.AI.run("@cf/meta/llama-3.1-8b-instruct", {prompt});
+
+const stream = await client.chat.completions.create({
+  model: "gpt-4", messages: [{role:"user",content:prompt}], stream: true
+});
+for await (const chunk of stream) {
+  const content = chunk.choices[0]?.delta?.content;
+  if (content) conn.send(JSON.stringify({type:"chunk",content}));
+}
+```

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

@@ -0,0 +1,99 @@
+# Configuration
+
+## Wrangler Setup
+
+```toml
+name = "my-agents-app"
+
+[[durable_objects.bindings]]
+name = "MyAgent"
+class_name = "MyAgent"
+
+[[migrations]]
+tag = "v1"
+new_sqlite_classes = ["MyAgent"]
+
+[ai]
+binding = "AI"
+```
+
+```jsonc
+{
+  "durable_objects": {
+    "bindings": [
+      {"name": "MyAgent", "class_name": "MyAgent"}
+    ]
+  },
+  "migrations": [
+    {"tag": "v1", "new_sqlite_classes": ["MyAgent"]}
+  ],
+  "ai": {
+    "binding": "AI"
+  }
+}
+```
+
+## Environment Bindings
+
+```typescript
+interface Env {
+  AI?: Ai;                              // Workers AI
+  MyAgent?: DurableObjectNamespace<MyAgent>;
+  DB?: D1Database;                      // D1 database
+  KV?: KVNamespace;                     // KV storage
+  R2?: R2Bucket;                        // R2 bucket
+  OPENAI_API_KEY?: string;              // Secrets
+  QUEUE?: Queue;                        // Queues
+}
+```
+
+## Deployment
+
+```bash
+# Local dev
+npx wrangler dev
+
+# Deploy production
+npx wrangler deploy
+
+# Set secrets
+npx wrangler secret put OPENAI_API_KEY
+```
+
+## Agent Routing
+
+```typescript
+export default {
+  async fetch(request: Request, env: Env) {
+    const id = env.MyAgent.idFromName("user-123");
+    const stub = env.MyAgent.get(id);
+    return stub.fetch(request);
+  }
+}
+```
+
+## Email Routing
+
+Configure email routing in dashboard to deliver emails to agent:
+
+```
+Destination: Workers with Durable Objects
+Worker: my-agents-app
+```
+
+## 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
+    }
+  }
+);
+```

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

@@ -0,0 +1,59 @@
+# Gotchas & Best Practices
+
+## State
+DO: `setState()` (auto-syncs), serializable, limit size | DON'T: Mutate directly, large objects (SQL), functions/circular
+```ts
+// ❌ this.state.count++ | ✅ this.setState({...this.state, count: this.state.count + 1})
+```
+
+## SQL
+DO: Parameterized, create in `onStart()`, types | DON'T: Direct interpolation, assume exists
+```ts
+// ❌ this.sql`...WHERE id = '${userId}'` | ✅ this.sql`...WHERE id = ${userId}`
+```
+
+## WebSocket
+DO: `conn.accept()`, errors, cleanup | DON'T: Forget accept (timeout), assume persist, sensitive in state
+```ts
+async onConnect(conn: Connection, ctx: ConnectionContext) { conn.accept(); conn.setState({userId: "123"}); }
+```
+
+## Scheduling
+1000 tasks/agent, 1min min, persist. Clean old, descriptive names, handle failures
+```ts
+async checkSchedules() { if ((await this.getSchedules()).length > 800) console.warn("Near limit!"); }
+```
+
+## AI
+Optimize: AI Gateway cache, rate limit, stream | Error: try/catch, fallback, quota/timeout
+```ts
+try { return await this.env.AI.run(model, {prompt}); } catch (e) { return {error: "Unavailable"}; }
+```
+
+## Perf
+State: Batch `setState()`, low-freq, SQL for large | Conns: Limit broadcast, selective, backpressure
+
+## Debug
+`npx wrangler dev` (local), `npx wrangler tail` (remote)
+Issues: "Agent not found" (DO binding), State not sync (`setState()`), Timeout (`conn.accept()`), SQL (create in `onStart()`)
+
+## Security
+DO: Validate, sanitize, auth WS, env secrets | DON'T: Trust headers, expose sensitive, unauth
+```ts
+async onConnect(conn: Connection, ctx: ConnectionContext) {
+  const token = ctx.request.headers.get("Authorization");
+  if (!await this.validateToken(token)) { conn.close(4001, "Unauthorized"); return; }
+  conn.accept();
+}
+```
+
+## Limits
+CPU: 30s/req, Mem: 128MB/inst, Storage: SQL shares DO quota, Conns: no limit (watch mem), Schedules: 1000/agent
+
+## Migration
+`new_sqlite_classes`, test staging, no downgrade w/SQL, careful state
+```toml
+[[migrations]]
+tag = "v1"
+new_sqlite_classes = ["MyAgent"]
+```

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

@@ -0,0 +1,89 @@
+# Patterns & Use Cases
+
+## Chat
+
+```ts
+export class ChatAgent extends Agent<Env, ChatState> {
+  initialState = {messages: [], participants: []};
+  async onConnect(conn: Connection, ctx: ConnectionContext) {
+    conn.accept();
+    const userId = ctx.request.headers.get("X-User-ID");
+    conn.setState({userId});
+    this.setState({...this.state, participants: [...this.state.participants, userId]});
+    conn.send(JSON.stringify({type: "history", messages: this.state.messages}));
+  }
+  async onMessage(conn: Connection, msg: WSMessage) {
+    const m = JSON.parse(msg as string);
+    if (m.type === "chat")
+      this.setState({...this.state, messages: [...this.state.messages, {userId: conn.state.userId, text: m.text, timestamp: Date.now()}]});
+  }
+}
+```
+
+## AI w/Tools
+
+```ts
+import {tool} from "ai"; import {z} from "zod";
+const weatherTool = tool({description: "Get weather", inputSchema: z.object({city: z.string()}), execute: async ({city}) => `Weather: ${city} Sunny 72°F`});
+export class AIAgent extends Agent<Env> {
+  tools = {getWeather: weatherTool};
+  async onMessage(conn: Connection, msg: WSMessage) {
+    const m = JSON.parse(msg as string);
+    conn.send(JSON.stringify({response: await this.env.AI.run("@cf/meta/llama-3.1-8b-instruct", {prompt: m.prompt, tools: this.tools})}));
+  }
+}
+```
+
+## Streaming
+
+```ts
+import {OpenAI} from "openai";
+export class StreamingAgent extends Agent<Env> {
+  async onMessage(conn: Connection, msg: WSMessage) {
+    const m = JSON.parse(msg as string);
+    const stream = await new OpenAI({apiKey: this.env.OPENAI_API_KEY}).chat.completions.create({model: "gpt-4", messages: [{role: "user", content: m.prompt}], stream: true});
+    for await (const chunk of stream) { const c = chunk.choices[0]?.delta?.content || ""; if (c) conn.send(JSON.stringify({type: "chunk", content: c})); }
+    conn.send(JSON.stringify({type: "done"}));
+  }
+}
+```
+
+## Cron/Scheduled
+
+```ts
+export class TaskAgent extends Agent<Env> {
+  onStart() { this.schedule("0 0 * * *", "dailyCleanup", {}); this.schedule("0 * * * *", "syncData", {}); }
+  async dailyCleanup() { this.sql`DELETE FROM logs WHERE created_at < ${Date.now() - 86400000}`; }
+  async syncData() { const data = await (await fetch(this.env.API_URL)).json(); this.sql`INSERT INTO cache (data,updated_at) VALUES (${JSON.stringify(data)},${Date.now()})`; }
+}
+```
+
+## Email+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,received_at) VALUES (${from},${subject},${text},${Date.now()})`;
+    const r = await this.env.AI.run("@cf/meta/llama-3.1-8b-instruct", {prompt: `Summarize: ${text}`});
+    this.setState({...this.state, lastEmail: {from, subject, summary: r}});
+    this.connections.forEach(c => c.send(JSON.stringify({type: "new_email", from, subject})));
+  }
+}
+```
+
+## Game
+
+```ts
+export class GameAgent extends Agent<Env, GameState> {
+  initialState = {players: [], score: 0, round: 1};
+  async onConnect(conn: Connection, ctx: ConnectionContext) {
+    conn.accept(); const playerId = ctx.request.headers.get("X-Player-ID"); conn.setState({playerId});
+    this.setState({...this.state, players: [...this.state.players, {id: playerId, score: 0}]});
+  }
+  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)});
+  }
+}
+```