pi-cloudflare 0.1.0

package/skills/agents-sdk/references/workflows.md

@@ -0,0 +1,132 @@
+# Workflows Integration
+
+Fetch https://developers.cloudflare.com/agents/api-reference/run-workflows/ for complete documentation.
+
+## Overview
+
+Agents handle real-time communication; Workflows handle durable execution. Together they enable:
+
+- Long-running background tasks with automatic retries
+- Human-in-the-loop approval flows
+- Multi-step pipelines that survive failures
+
+| Use Case | Recommendation |
+|----------|----------------|
+| Chat/messaging | Agent only |
+| Quick API calls (<30s) | Agent only |
+| Background processing (<30s) | Agent `queue()` |
+| Long-running tasks (>30s) | Agent + Workflow |
+| Human approval flows | Agent + Workflow |
+
+## AgentWorkflow Base Class
+
+```typescript
+import { AgentWorkflow } from "agents/workflows";
+import type { AgentWorkflowEvent, AgentWorkflowStep } from "agents/workflows";
+
+type TaskParams = { taskId: string; data: string };
+
+export class ProcessingWorkflow extends AgentWorkflow<MyAgent, TaskParams> {
+  async run(event: AgentWorkflowEvent<TaskParams>, step: AgentWorkflowStep) {
+    const params = event.payload;
+
+    // Durable step - retries on failure
+    const result = await step.do("process", async () => {
+      return processData(params.data);
+    });
+
+    // Non-durable: progress reporting
+    await this.reportProgress({ step: "process", percent: 0.5 });
+
+    // Non-durable: broadcast to connected clients
+    this.broadcastToClients({ type: "update", taskId: params.taskId });
+
+    // Durable: merge state via step
+    await step.mergeAgentState({ lastProcessed: params.taskId });
+
+    // Durable: report completion
+    await step.reportComplete(result);
+
+    return result;
+  }
+}
+```
+
+## Wrangler Configuration
+
+```jsonc
+{
+  "workflows": [
+    { "name": "processing-workflow", "binding": "PROCESSING_WORKFLOW", "class_name": "ProcessingWorkflow" }
+  ],
+  "durable_objects": {
+    "bindings": [{ "name": "MyAgent", "class_name": "MyAgent" }]
+  },
+  "migrations": [{ "tag": "v1", "new_sqlite_classes": ["MyAgent"] }]
+}
+```
+
+## Agent Methods for Workflows
+
+```typescript
+// Start a workflow
+const instance = await this.runWorkflow("ProcessingWorkflow", { taskId: "123", data: "..." });
+
+// Send event to waiting workflow
+await this.sendWorkflowEvent("ProcessingWorkflow", workflowId, { type: "approve" });
+
+// Query workflows
+const workflow = await this.getWorkflow(workflowId);
+const workflows = await this.getWorkflows({ status: "running" });
+
+// Control workflows
+await this.approveWorkflow(workflowId);
+await this.rejectWorkflow(workflowId);
+await this.terminateWorkflow(workflowId);
+await this.pauseWorkflow(workflowId);
+await this.resumeWorkflow(workflowId);
+
+// Delete workflows
+await this.deleteWorkflow(workflowId);
+await this.deleteWorkflows({ status: "complete", before: new Date(...) });
+```
+
+## Lifecycle Callbacks
+
+```typescript
+export class MyAgent extends Agent<Env, State> {
+  async onWorkflowProgress(workflowName: string, workflowId: string, progress: unknown) {
+    // Workflow reported progress via this.reportProgress()
+    this.broadcast({ type: "progress", workflowId, progress });
+  }
+
+  async onWorkflowComplete(workflowName: string, workflowId: string, result?: unknown) {
+    // Workflow finished successfully
+  }
+
+  async onWorkflowError(workflowName: string, workflowId: string, error: Error) {
+    // Workflow failed
+  }
+
+  async onWorkflowEvent(workflowName: string, workflowId: string, event: unknown) {
+    // Workflow received an event via sendWorkflowEvent()
+  }
+}
+```
+
+## Human-in-the-Loop
+
+```typescript
+// In workflow: wait for approval
+const approved = await step.waitForEvent<{ approved: boolean }>("approval", {
+  timeout: "7d"
+});
+
+if (!approved.approved) {
+  throw new Error("Rejected");
+}
+
+// From agent: approve or reject
+await this.approveWorkflow(workflowId);  // Sends { approved: true }
+await this.rejectWorkflow(workflowId);   // Sends { approved: false }
+```

package/skills/cloudflare/SKILL.md

@@ -0,0 +1,248 @@
+---
+name: cloudflare
+description: Comprehensive Cloudflare platform skill covering Workers, Pages, storage (KV, D1, R2), AI (Workers AI, Vectorize, Agents SDK), feature flags (Flagship), networking (Tunnel, Spectrum), security (WAF, DDoS), and infrastructure-as-code (Terraform, Pulumi). Use for any Cloudflare development task. Biases towards retrieval from Cloudflare docs over pre-trained knowledge.
+references:
+  - workers
+  - pages
+  - d1
+  - durable-objects
+  - workers-ai
+---
+
+# Cloudflare Platform Skill
+
+Consolidated skill for building on the Cloudflare platform. Use decision trees below to find the right product, then load detailed references.
+
+Your knowledge of Cloudflare APIs, types, limits, and pricing may be outdated. **Prefer retrieval over pre-training** — the references in this skill are starting points, not source of truth.
+
+## Retrieval Sources
+
+Fetch the **latest** information before citing specific numbers, API signatures, or configuration options. Do not rely on baked-in knowledge or these reference files alone.
+
+| Source | How to retrieve | Use for |
+|--------|----------------|---------|
+| Cloudflare docs | Cloudflare MCP `docs` tool or `https://developers.cloudflare.com/` | Limits, pricing, API reference, compatibility dates/flags |
+| Workers types | `npm pack @cloudflare/workers-types` or check `node_modules` | Type signatures, binding shapes, handler types |
+| Wrangler config schema | `node_modules/wrangler/config-schema.json` | Config fields, binding shapes, allowed values |
+| Product changelogs | `https://developers.cloudflare.com/changelog/` | Recent changes to limits, features, deprecations |
+
+When a reference file and the docs disagree, **trust the docs**. This is especially important for: numeric limits, pricing tiers, type signatures, and configuration options.
+
+## Quick Decision Trees
+
+### "I need feature flags"
+
+```
+Need feature flags?
+└─ Feature toggles, targeting rules, percentage rollouts → flagship/
+   ├─ Evaluate in Workers → Flagship binding (env.FLAGS)
+   ├─ Evaluate in Node.js / browser → OpenFeature SDK (@cloudflare/flagship)
+   └─ Manage flags via API → Flagship REST API
+```
+
+### "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/
+├─ Lightweight edge logic (modify HTTP) → snippets/
+├─ Process Worker execution events (logs/observability) → tail-workers/
+└─ Optimize latency to backend infrastructure → smart-placement/
+```
+
+### "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/
+├─ Versioned file trees (repos, build outputs, checkpoints) → artifacts/
+├─ 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/
+├─ Managed Apache Iceberg catalog on R2 → r2-data-catalog/
+├─ Serverless SQL analytics over Iceberg tables → r2-sql/
+└─ Persistent cache (long-term retention) → cache-reserve/
+```
+
+### "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/
+├─ Optimize latency to backend (not user) → smart-placement/
+└─ 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 analytics/metrics data"
+
+```
+Need analytics?
+├─ Query across all Cloudflare products (HTTP, Workers, DNS, etc.) → graphql-api/
+├─ Custom high-cardinality metrics from Workers → analytics-engine/
+├─ Client-side (RUM) performance data → web-analytics/
+├─ Workers Logs and real-time debugging → observability/
+├─ SQL over Iceberg data lake (logs, events) → r2-sql/ (+ pipelines/, r2-data-catalog/)
+└─ Raw logs (Logpush to external tools) → Cloudflare docs
+```
+
+### "I need infrastructure-as-code"
+
+```
+Need IaC? → pulumi/ (Pulumi), terraform/ (Terraform), or api/ (REST API)
+```
+
+## Product Index
+
+### Feature Flags
+| Product | Reference |
+|---------|-----------|
+| Flagship | `references/flagship/` |
+
+### Compute & Runtime
+| Product | Reference |
+|---------|-----------|
+| Workers | `references/workers/` |
+| Pages | `references/pages/` |
+| Pages Functions | `references/pages-functions/` |
+| Durable Objects | `references/durable-objects/` |
+| Workflows | `references/workflows/` |
+| Containers | `references/containers/` |
+| Workers for Platforms | `references/workers-for-platforms/` |
+| Cron Triggers | `references/cron-triggers/` |
+| Tail Workers | `references/tail-workers/` |
+| Snippets | `references/snippets/` |
+| Smart Placement | `references/smart-placement/` |
+
+### Storage & Data
+| Product | Reference |
+|---------|-----------|
+| KV | `references/kv/` |
+| D1 | `references/d1/` |
+| R2 | `references/r2/` |
+| Artifacts | `references/artifacts/` |
+| Queues | `references/queues/` |
+| Hyperdrive | `references/hyperdrive/` |
+| DO Storage | `references/do-storage/` |
+| Secrets Store | `references/secrets-store/` |
+| Pipelines | `references/pipelines/` |
+| R2 Data Catalog | `references/r2-data-catalog/` |
+| R2 SQL | `references/r2-sql/` |
+
+### AI & Machine Learning
+| Product | Reference |
+|---------|-----------|
+| Workers AI | `references/workers-ai/` |
+| Vectorize | `references/vectorize/` |
+| Agents SDK | `references/agents-sdk/` |
+| AI Gateway | `references/ai-gateway/` |
+| AI Search | `references/ai-search/` |
+
+### Networking & Connectivity
+| Product | Reference |
+|---------|-----------|
+| Tunnel | `references/tunnel/` |
+| Spectrum | `references/spectrum/` |
+| TURN | `references/turn/` |
+| Network Interconnect | `references/network-interconnect/` |
+| Argo Smart Routing | `references/argo-smart-routing/` |
+| Workers VPC | `references/workers-vpc/` |
+
+### Security
+| Product | Reference |
+|---------|-----------|
+| WAF | `references/waf/` |
+| DDoS Protection | `references/ddos/` |
+| Bot Management | `references/bot-management/` |
+| API Shield | `references/api-shield/` |
+| Turnstile | `references/turnstile/` |
+
+### Media & Content
+| Product | Reference |
+|---------|-----------|
+| Images | `references/images/` |
+| Stream | `references/stream/` |
+| Browser Rendering | `references/browser-rendering/` |
+| Zaraz | `references/zaraz/` |
+
+### Real-Time Communication
+| Product | Reference |
+|---------|-----------|
+| RealtimeKit | `references/realtimekit/` |
+| Realtime SFU | `references/realtime-sfu/` |
+
+### Developer Tools
+| Product | Reference |
+|---------|-----------|
+| Wrangler | `references/wrangler/` |
+| Miniflare | `references/miniflare/` |
+| C3 | `references/c3/` |
+| Observability | `references/observability/` |
+| GraphQL Analytics API | `references/graphql-api/` |
+| Analytics Engine | `references/analytics-engine/` |
+| Web Analytics | `references/web-analytics/` |
+| Sandbox | `references/sandbox/` |
+| Workerd | `references/workerd/` |
+| Workers Playground | `references/workers-playground/` |
+
+### Infrastructure as Code
+| Product | Reference |
+|---------|-----------|
+| Pulumi | `references/pulumi/` |
+| Terraform | `references/terraform/` |
+| API | `references/api/` |
+
+### Other Services
+| Product | Reference |
+|---------|-----------|
+| Email Routing | `references/email-routing/` |
+| Email Workers | `references/email-workers/` |
+| Static Assets | `references/static-assets/` |
+| Bindings | `references/bindings/` |
+| Cache Reserve | `references/cache-reserve/` |

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

@@ -0,0 +1,89 @@
+# 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
+
+## What Type of Agent?
+
+| Use Case | Class | Key Features |
+|----------|-------|--------------|
+| AI chat interface | `AIChatAgent` | Auto-streaming, tools, message history, resumable |
+| MCP tool provider | `Agent` + MCP | Expose tools to AI systems |
+| Custom logic/routing | `Agent` | Full control, WebSockets, email, SQL |
+| Real-time collaboration | `Agent` | WebSocket state, broadcasts |
+| Email processing | `Agent` | `onEmail()` handler |
+
+## Quick Start
+
+**AI Chat Agent:**
+```typescript
+import { AIChatAgent } from "@cloudflare/ai-chat";
+import { openai } from "@ai-sdk/openai";
+
+export class ChatAgent extends AIChatAgent<Env> {
+  async onChatMessage(onFinish) {
+    return this.streamText({
+      model: openai("gpt-4"),
+      messages: this.messages,
+      onFinish,
+    });
+  }
+}
+```
+
+**Base Agent:**
+```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 });
+  }
+}
+```
+
+## Reading Order
+
+| Task | Files to Read |
+|------|---------------|
+| Quick start | README only |
+| Build chat agent | README → api.md (AIChatAgent) → patterns.md |
+| Setup project | README → configuration.md |
+| Add React frontend | README → api.md (Client Hooks) → patterns.md |
+| Build MCP server | api.md (MCP) → patterns.md |
+| Background tasks | api.md (Scheduling, Task Queue) → patterns.md |
+| Debug issues | gotchas.md |
+
+## Package Entry Points
+
+| Import | Purpose |
+|--------|---------|
+| `agents` | Server-side Agent classes, lifecycle |
+| `agents/react` | `useAgent()` hook for WebSocket connections |
+| `agents/ai-react` | `useAgentChat()` hook for AI chat UIs |
+
+## In This Reference
+- [configuration.md](./configuration.md) - SDK setup, wrangler config, routing
+- [api.md](./api.md) - Agent classes, lifecycle, client hooks
+- [patterns.md](./patterns.md) - Common workflows, best practices
+- [gotchas.md](./gotchas.md) - Common issues, limits
+
+## See Also
+- durable-objects - Agent infrastructure
+- d1 - External database integration
+- workers-ai - AI model integration
+- vectorize - Vector search for RAG patterns

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

@@ -0,0 +1,190 @@
+# API Reference
+
+## Agent Classes
+
+### AIChatAgent
+
+For AI chat with auto-streaming, message history, tools, resumable streaming.
+
+```ts
+import { AIChatAgent } from "@cloudflare/ai-chat";
+import { openai } from "@ai-sdk/openai";
+
+export class ChatAgent extends AIChatAgent<Env> {
+  async onChatMessage(onFinish) {
+    return this.streamText({
+      model: openai("gpt-4"),
+      messages: this.messages, // Auto-managed message history
+      tools: {
+        getWeather: {
+          description: "Get weather",
+          parameters: z.object({ city: z.string() }),
+          execute: async ({ city }) => `Sunny, 72°F in ${city}`
+        }
+      },
+      onFinish, // Persist response to this.messages
+    });
+  }
+}
+```
+
+### Agent (Base Class)
+
+Full control for custom logic, WebSockets, email, and SQL.
+
+```ts
+import { Agent } from "agents";
+
+export class MyAgent extends Agent<Env, State> {
+  // Lifecycle methods below
+}
+```
+
+**Type params:** `Agent<Env, State, ConnState>` - Env bindings, agent state, connection state
+
+## Lifecycle Hooks
+
+```ts
+onStart() { // Init/restart
+  this.sql`CREATE TABLE IF NOT EXISTS users (id TEXT, name TEXT)`;
+}
+
+async onRequest(req: Request) { // HTTP
+  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});
+}
+
+async onConnect(conn: Connection<ConnState>, ctx: ConnectionContext) { // WebSocket
+  conn.accept();
+  conn.setState({userId: ctx.request.headers.get("X-User-ID")});
+  conn.send(JSON.stringify({type: "connected", state: this.state}));
+}
+
+async onMessage(conn: Connection<ConnState>, msg: WSMessage) { // WS messages
+  const m = JSON.parse(msg as string);
+  this.setState({messages: [...this.state.messages, m]});
+  this.connections.forEach(c => c.send(JSON.stringify(m)));
+}
+
+async onEmail(email: AgentEmail) { // Email routing
+  this.sql`INSERT INTO emails (from_addr,subject,body) VALUES (${email.from},${email.headers.get("subject")},${await email.text()})`;
+}
+```
+
+## State, SQL, Scheduling
+
+```ts
+// State
+this.setState({count: 42}); // Auto-syncs
+this.setState({...this.state, count: this.state.count + 1});
+
+// SQL (parameterized queries prevent injection)
+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 WHERE id = ${userId}`;
+
+// Scheduling
+await this.schedule(new Date("2026-12-25"), "sendGreeting", {msg:"Hi"}); // Date
+await this.schedule(60, "checkStatus", {}); // Delay (sec)
+await this.schedule("0 0 * * *", "dailyCleanup", {}); // Cron
+await this.cancelSchedule(scheduleId);
+```
+
+## RPC Methods (@callable)
+
+```ts
+import { Agent, callable } from "agents";
+
+export class MyAgent extends Agent<Env> {
+  @callable()
+  async processTask(input: {text: string}): Promise<{result: string}> {
+    return { result: await this.env.AI.run("@cf/meta/llama-3.1-8b-instruct", {prompt: input.text}) };
+  }
+}
+// Client: const result = await agent.processTask({ text: "Hello" });
+// Must return JSON-serializable values
+```
+
+## Connections & AI
+
+```ts
+// Connections (type: Agent<Env, State, ConnState>)
+this.connections.forEach(c => c.send(JSON.stringify(msg))); // Broadcast
+conn.setState({userId:"123"}); conn.close(1000, "Goodbye");
+
+// Workers AI
+const r = await this.env.AI.run("@cf/meta/llama-3.1-8b-instruct", {prompt});
+
+// Manual streaming (prefer AIChatAgent)
+const stream = await client.chat.completions.create({model: "gpt-4", messages, stream: true});
+for await (const chunk of stream) conn.send(JSON.stringify({chunk: chunk.choices[0].delta.content}));
+```
+
+**Type-safe state:** `Agent<Env, State, ConnState>` - third param types `conn.state`
+
+## MCP Integration
+
+Model Context Protocol for exposing tools:
+
+```ts
+// Register & use MCP server
+await this.mcp.registerServer("github", {
+  url: env.MCP_SERVER_URL,
+  auth: { type: "oauth", clientId: env.GITHUB_CLIENT_ID, clientSecret: env.GITHUB_CLIENT_SECRET }
+});
+const tools = await this.mcp.getAITools(["github"]);
+return this.streamText({ model: openai("gpt-4"), messages: this.messages, tools, onFinish });
+```
+
+## Task Queue
+
+```ts
+await this.queue("processVideo", { videoId: "abc123" }); // Add task
+const tasks = await this.dequeue(10); // Process up to 10
+```
+
+## Context & Cleanup
+
+```ts
+const agent = getCurrentAgent<MyAgent>(); // Get current instance
+async destroy() { /* cleanup before agent destroyed */ }
+```
+
+## AI Integration
+
+```ts
+// Workers AI
+const r = await this.env.AI.run("@cf/meta/llama-3.1-8b-instruct", {prompt});
+
+// Manual streaming (prefer AIChatAgent for auto-streaming)
+const stream = await client.chat.completions.create({model: "gpt-4", messages, stream: true});
+for await (const chunk of stream) {
+  if (chunk.choices[0]?.delta?.content) conn.send(JSON.stringify({chunk: chunk.choices[0].delta.content}));
+}
+```
+
+## Client Hooks (React)
+
+```ts
+// useAgent() - WebSocket connection + RPC
+import { useAgent } from "agents/react";
+const agent = useAgent({ agent: "MyAgent", name: "user-123" }); // name for idFromName
+const result = await agent.processTask({ text: "Hello" }); // Call @callable methods
+// agent.readyState: 0=CONNECTING, 1=OPEN, 2=CLOSING, 3=CLOSED
+
+// useAgentChat() - AI chat UI
+import { useAgentChat } from "@cloudflare/ai-chat/react";
+const agent = useAgent({ agent: "ChatAgent" });
+const { messages, input, handleInputChange, handleSubmit, isLoading, stop, clearHistory } = 
+  useAgentChat({ 
+    agent, 
+    maxSteps: 5,        // Max tool iterations
+    resume: true,       // Auto-resume on disconnect
+    onToolCall: async (toolCall) => {
+      // Client tools (human-in-the-loop)
+      if (toolCall.toolName === "confirm") return { ok: window.confirm("Proceed?") };
+    }
+  });
+// status: "ready" | "submitted" | "streaming" | "error"
+```