pi-cloudflare 0.1.0

package/skills/agents-sdk/references/durable-execution.md

@@ -0,0 +1,51 @@
+# Durable Execution
+
+Fetch https://developers.cloudflare.com/agents/api-reference/durable-execution/ for complete documentation.
+
+Fibers let agent work survive Durable Object eviction. Progress is checkpointed to SQLite; on recovery, you decide what to do.
+
+## `runFiber`
+
+```typescript
+export class MyAgent extends Agent<Env, State> {
+  async onRequest(request: Request) {
+    await this.runFiber("process-data", async (ctx) => {
+      const step1 = await fetchData();
+      ctx.stash({ step: 1, data: step1 });
+
+      const step2 = await transform(step1);
+      ctx.stash({ step: 2, result: step2 });
+
+      this.setState({ result: step2 });
+    });
+    return new Response("Started");
+  }
+
+  async onFiberRecovered(ctx) {
+    const checkpoint = ctx.stash;
+    if (checkpoint.step === 1) {
+      const step2 = await transform(checkpoint.data);
+      this.setState({ result: step2 });
+    }
+  }
+}
+```
+
+## Key APIs
+
+| API | Purpose |
+|-----|---------|
+| `this.runFiber(name, fn)` | Start a named fiber |
+| `ctx.stash` / `this.stash` | Read latest checkpoint |
+| `ctx.stash = data` | Write checkpoint (JSON-serializable) |
+| `onFiberRecovered(ctx)` | Called on DO restart if fiber was in-flight |
+| `keepAlive()` | Prevent hibernation while fiber runs |
+| `keepAliveWhile(fn)` | Keep alive for duration of async function |
+
+## Important
+
+- `stash` replaces the entire checkpoint — not a merge
+- The lambda is NOT restored on recovery — only the stash data is. You must re-derive what to do in `onFiberRecovered`
+- No auto-retry on throw — handle errors yourself
+- For long-running pipelines with automatic retries, use Workflows instead
+- Filter concurrent fibers by `ctx.name` in `onFiberRecovered`

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

@@ -0,0 +1,146 @@
+# Email Handling
+
+Fetch https://developers.cloudflare.com/agents/api-reference/email/ for complete documentation.
+
+## Overview
+
+Agents receive and reply to emails via Cloudflare Email Routing.
+
+## Wrangler Configuration
+
+```jsonc
+{
+  "durable_objects": {
+    "bindings": [{ "name": "EmailAgent", "class_name": "EmailAgent" }]
+  },
+  "migrations": [{ "tag": "v1", "new_sqlite_classes": ["EmailAgent"] }],
+  "send_email": [
+    { "name": "SEB", "destination_address": "reply@yourdomain.com" }
+  ]
+}
+```
+
+## Basic Email Handler
+
+```typescript
+import { Agent } from "agents";
+import { type AgentEmail } from "agents/email";
+import PostalMime from "postal-mime";
+
+export class EmailAgent extends Agent<Env, State> {
+  async onEmail(email: AgentEmail) {
+    const raw = await email.getRaw();
+    const parsed = await PostalMime.parse(raw);
+
+    console.log("From:", email.from);
+    console.log("Subject:", parsed.subject);
+
+    await this.replyToEmail(email, {
+      fromName: "My Agent",
+      subject: `Re: ${parsed.subject}`,
+      body: "Thanks for your email!"
+    });
+  }
+}
+```
+
+## Routing Emails
+
+```typescript
+import { routeAgentRequest, routeAgentEmail } from "agents";
+import { createAddressBasedEmailResolver } from "agents/email";
+
+export default {
+  async email(message, env) {
+    await routeAgentEmail(message, env, {
+      resolver: createAddressBasedEmailResolver("EmailAgent")
+    });
+  },
+
+  async fetch(request, env) {
+    return routeAgentRequest(request, env) ?? new Response("Not found", { status: 404 });
+  }
+};
+```
+
+## Resolvers
+
+### Address-Based (Inbound Mail)
+
+Routes based on recipient address:
+
+```typescript
+import { createAddressBasedEmailResolver } from "agents/email";
+
+const resolver = createAddressBasedEmailResolver("EmailAgent");
+// support@example.com → EmailAgent, instance "support"
+// NotificationAgent+user123@example.com → NotificationAgent, instance "user123"
+```
+
+### Secure Reply (Reply Flows)
+
+Verifies replies are authentic using HMAC-SHA256 signatures:
+
+```typescript
+import { createSecureReplyEmailResolver } from "agents/email";
+
+const resolver = createSecureReplyEmailResolver(env.EMAIL_SECRET, {
+  maxAge: 7 * 24 * 60 * 60, // 7 days (default: 30 days)
+  onInvalidSignature: (email, reason) => {
+    console.warn(`Invalid signature from ${email.from}: ${reason}`);
+  }
+});
+```
+
+Sign outbound emails to enable secure reply routing:
+
+```typescript
+await this.replyToEmail(email, {
+  fromName: "My Agent",
+  body: "Thanks!",
+  secret: this.env.EMAIL_SECRET  // Signs headers for secure reply routing
+});
+```
+
+### Catch-All (Single Instance)
+
+Routes all emails to one agent instance:
+
+```typescript
+import { createCatchAllEmailResolver } from "agents/email";
+
+const resolver = createCatchAllEmailResolver("EmailAgent", "default");
+```
+
+### Combining Resolvers
+
+```typescript
+async email(message, env) {
+  const secureReply = createSecureReplyEmailResolver(env.EMAIL_SECRET);
+  const addressBased = createAddressBasedEmailResolver("EmailAgent");
+
+  await routeAgentEmail(message, env, {
+    resolver: async (email, env) => {
+      // Try secure reply first
+      const result = await secureReply(email, env);
+      if (result) return result;
+      // Fall back to address-based
+      return addressBased(email, env);
+    }
+  });
+}
+```
+
+## Utilities
+
+```typescript
+import { isAutoReplyEmail } from "agents/email";
+
+async onEmail(email: AgentEmail) {
+  if (isAutoReplyEmail(email.headers)) {
+    // Skip auto-replies (vacation, out-of-office, etc.)
+    return;
+  }
+  // Process email...
+}
+```

package/skills/agents-sdk/references/human-in-the-loop.md

@@ -0,0 +1,67 @@
+# Human-in-the-Loop
+
+Fetch https://developers.cloudflare.com/agents/concepts/human-in-the-loop/ for complete documentation.
+
+Multiple patterns for adding human approval to agent actions.
+
+## Decision Guide
+
+| Pattern | Best for |
+|---------|----------|
+| Workflows `waitForApproval` | Long-running background tasks |
+| AI SDK `needsApproval` on tools | Chat tool calls requiring approval |
+| Client tools (`onToolCall`) | Tools that execute in the browser |
+| MCP `elicitInput` | Gathering structured input from MCP clients |
+
+## Workflow Approvals
+
+```typescript
+// In AgentWorkflow:
+const approved = await step.waitForEvent<{ approved: boolean }>("approval", {
+  timeout: "7d"
+});
+if (!approved.approved) throw new Error("Rejected");
+
+// From agent:
+await this.approveWorkflow(workflowId);
+await this.rejectWorkflow(workflowId);
+```
+
+## Chat Tool Approvals (`needsApproval`)
+
+```typescript
+const tools = {
+  deleteItem: tool({
+    description: "Delete an item",
+    parameters: z.object({ id: z.string() }),
+    execute: async ({ id }) => { /* delete */ },
+    needsApproval: true  // or a function: (toolCall) => boolean
+  })
+};
+```
+
+Client handles approval:
+
+```tsx
+const { addToolApprovalResponse, addToolOutput } = useAgentChat({
+  agent,
+  onToolCall: async ({ toolCall }) => {
+    if (confirm(`Allow ${toolCall.toolName}?`)) {
+      return { approve: true };
+    }
+    return { approve: false };
+  }
+});
+```
+
+To deny with a custom message:
+
+```tsx
+addToolOutput(toolCallId, "output-error", "User rejected this action");
+```
+
+## Important
+
+- `waitForApproval` may return `undefined` on timeout — handle it
+- `addToolOutput` with `output-error` does NOT auto-continue the LLM — you may need `sendMessage` after
+- For OpenAI Agents SDK, use `needsApproval` on the tool definition (same pattern)

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

@@ -0,0 +1,188 @@
+# MCP Integration
+
+Fetch https://developers.cloudflare.com/agents/api-reference/mcp-client-api/ and https://developers.cloudflare.com/agents/api-reference/mcp-agent-api/ for complete documentation.
+
+Agents include a multi-server MCP client for connecting to external MCP servers, and `McpAgent` for building MCP servers.
+
+## Add an MCP Server
+
+```typescript
+import { Agent, callable } from "agents";
+
+export class MyAgent extends Agent<Env, State> {
+  @callable()
+  async addServer(name: string, url: string) {
+    // Options-based API (recommended)
+    const result = await this.addMcpServer(name, url, {
+      callbackHost: "https://my-worker.workers.dev",
+      transport: { headers: { Authorization: "Bearer ..." } }
+    });
+
+    if (result.state === "authenticating") {
+      // OAuth required - redirect user to result.authUrl
+      return { needsAuth: true, authUrl: result.authUrl };
+    }
+
+    return { ready: true, id: result.id };
+  }
+}
+```
+
+## Use MCP Tools
+
+```typescript
+async onChatMessage() {
+  // Get AI-compatible tools from all connected MCP servers
+  const mcpTools = this.mcp.getAITools();
+  
+  const allTools = {
+    ...localTools,
+    ...mcpTools
+  };
+
+  const result = streamText({
+    model: openai("gpt-4o"),
+    messages: await convertToModelMessages(this.messages),
+    tools: allTools
+  });
+  
+  return result.toUIMessageStreamResponse();
+}
+```
+
+## List MCP Resources
+
+```typescript
+// List all registered servers
+const servers = this.mcp.listServers();
+
+// List tools from all servers
+const tools = this.mcp.listTools();
+
+// List resources
+const resources = this.mcp.listResources();
+
+// List prompts
+const prompts = this.mcp.listPrompts();
+```
+
+## Remove Server
+
+```typescript
+await this.removeMcpServer(serverId);
+```
+
+## Building an MCP Server
+
+Use `McpAgent` from the SDK to create an MCP server.
+
+**Install dependencies:**
+```bash
+npm install @modelcontextprotocol/sdk zod
+```
+
+**Wrangler config:**
+```jsonc
+{
+  "durable_objects": {
+    "bindings": [{ "name": "MyMCP", "class_name": "MyMCP" }]
+  },
+  "migrations": [{ "tag": "v1", "new_sqlite_classes": ["MyMCP"] }]
+}
+```
+
+**Server implementation:**
+```typescript
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { McpAgent } from "agents/mcp";
+import { z } from "zod";
+
+type State = { counter: number };
+
+export class MyMCP extends McpAgent<Env, State, {}> {
+  server = new McpServer({
+    name: "MyMCPServer",
+    version: "1.0.0"
+  });
+
+  initialState = { counter: 0 };
+
+  async init() {
+    // Register a resource
+    this.server.resource("counter", "mcp://resource/counter", (uri) => ({
+      contents: [{ text: String(this.state.counter), uri: uri.href }]
+    }));
+
+    // Register a tool
+    this.server.registerTool(
+      "increment",
+      {
+        description: "Increment the counter",
+        inputSchema: { amount: z.number().default(1) }
+      },
+      async ({ amount }) => {
+        this.setState({ counter: this.state.counter + amount });
+        return {
+          content: [{ text: `Counter: ${this.state.counter}`, type: "text" }]
+        };
+      }
+    );
+  }
+}
+```
+
+## Serve MCP Server
+
+```typescript
+export default {
+  fetch(request: Request, env: Env, ctx: ExecutionContext) {
+    const url = new URL(request.url);
+
+    // Streamable HTTP transport (recommended)
+    if (url.pathname.startsWith("/mcp")) {
+      return MyMCP.serve("/mcp", { binding: "MyMCP" }).fetch(request, env, ctx);
+    }
+
+    // SSE transport (legacy, deprecated)
+    if (url.pathname.startsWith("/sse")) {
+      return MyMCP.serveSSE("/sse", { binding: "MyMCP" }).fetch(request, env, ctx);
+    }
+
+    return new Response("Not found", { status: 404 });
+  }
+};
+```
+
+## Transports
+
+Fetch https://developers.cloudflare.com/agents/api-reference/mcp-transports/ for complete documentation.
+
+| Transport | Use for |
+|-----------|---------|
+| Streamable HTTP (`serve`) | External/public clients (recommended) |
+| SSE (`serveSSE`) | Legacy clients only (deprecated) |
+| RPC (`addMcpServer(name, env.Binding)`) | Same-Worker internal calls (fastest) |
+
+### RPC Transport (Same Worker)
+
+```typescript
+async onStart() {
+  await this.addMcpServer("internal-tools", this.env.MyMCPBinding, {
+    props: { userId: this.name }
+  });
+}
+```
+
+## Retry on MCP Connections
+
+```typescript
+await this.addMcpServer("tools", url, {
+  retry: { maxAttempts: 3, baseDelayMs: 500 }
+});
+```
+
+## Securing MCP Servers
+
+Fetch https://developers.cloudflare.com/agents/api-reference/securing-mcp-servers/ for complete documentation.
+
+Use `@cloudflare/workers-oauth-provider` to add OAuth in front of your MCP server. See the securing docs for proxy patterns and `redirect_uri` validation.

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

@@ -0,0 +1,44 @@
+# Observability
+
+Fetch https://developers.cloudflare.com/agents/api-reference/observability/ for complete documentation.
+
+Agents emit structured events via Node.js `diagnostics_channel`. Subscribe in development or forward via Tail Workers in production.
+
+## Subscribe to Events
+
+```typescript
+import { subscribe } from "agents/observability";
+
+subscribe("agents:rpc", (event) => {
+  console.log(`RPC call: ${event.payload.method}`);
+});
+
+subscribe("agents:state", (event) => {
+  console.log(`State change on ${event.agent}`);
+});
+```
+
+## Available Channels
+
+| Channel | Events |
+|---------|--------|
+| `agents:state` | State changes |
+| `agents:rpc` | `@callable` invocations |
+| `agents:message` | WebSocket messages |
+| `agents:schedule` | Schedule triggers |
+| `agents:lifecycle` | Agent start, connect, disconnect |
+| `agents:workflow` | Workflow progress, completion, errors |
+| `agents:mcp` | MCP server connections, tool calls |
+| `agents:email` | Email received |
+
+## Per-Agent Override
+
+```typescript
+export class MyAgent extends Agent<Env, State> {
+  observability = undefined; // disable for this agent
+}
+```
+
+## Production: Tail Workers
+
+In production, events appear as `diagnosticsChannelEvents` on the Tail Worker `event` object. Attach a Tail Worker to your agent's Worker to forward events to your observability platform.

package/skills/agents-sdk/references/queue-retries.md

@@ -0,0 +1,79 @@
+# Queue & Retries
+
+Fetch https://developers.cloudflare.com/agents/api-reference/queue-tasks/ and https://developers.cloudflare.com/agents/api-reference/retries/ for complete documentation.
+
+## Built-in Queue
+
+FIFO queue persisted in SQLite. Sequential processing, one item at a time.
+
+```typescript
+export class MyAgent extends Agent<Env, State> {
+  async onRequest(request: Request) {
+    this.queue("processItem", { id: "abc", data: "..." });
+    this.queue("processItem", { id: "def", data: "..." }, { retry: { maxAttempts: 5 } });
+    return new Response("Queued");
+  }
+
+  async processItem(payload: { id: string; data: string }, queueItem: QueueItem) {
+    await doWork(payload);
+  }
+}
+```
+
+### Queue Management
+
+```typescript
+const items = this.getQueue();
+const byCallback = this.getQueues("processItem");
+this.dequeue(itemId);
+this.dequeueAll();
+this.dequeueAllByCallback("processItem");
+```
+
+## Retries
+
+Exponential backoff with full jitter. Defaults: 3 attempts, 100ms base, 3000ms max.
+
+```typescript
+const result = await this.retry(
+  async () => {
+    const res = await fetch("https://api.example.com/data");
+    if (!res.ok) throw new Error(`HTTP ${res.status}`);
+    return res.json();
+  },
+  {
+    maxAttempts: 5,
+    baseDelayMs: 200,
+    maxDelayMs: 5000,
+    shouldRetry: (err, nextAttempt) => {
+      if (err.message.includes("429")) return true;
+      if (err.message.includes("401")) return false;
+      return nextAttempt <= 3;
+    }
+  }
+);
+```
+
+### Retry on Schedules and Queue
+
+```typescript
+await this.schedule(60, "task", payload, { retry: { maxAttempts: 3 } });
+await this.scheduleEvery(30, "poll", undefined, { retry: { maxAttempts: 2 } });
+this.queue("handler", payload, { retry: { maxAttempts: 5 } });
+```
+
+### Class-level Defaults
+
+```typescript
+export class MyAgent extends Agent<Env, State> {
+  static options = {
+    retry: { maxAttempts: 5, baseDelayMs: 200, maxDelayMs: 10000 }
+  };
+}
+```
+
+## Important
+
+- `shouldRetry` only works on `this.retry()` — not on schedule/queue (callbacks aren't serializable)
+- Queue retries block head-of-line; long delays keep the DO awake — use `schedule` for long waits instead
+- No dead-letter queue — failed items are removed after retries exhausted

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

@@ -0,0 +1,75 @@
+# Routing
+
+Fetch https://developers.cloudflare.com/agents/api-reference/routing/ for complete documentation.
+
+## Default URL Pattern
+
+`/agents/{kebab-class-name}/{instance-name}`
+
+```typescript
+import { routeAgentRequest } from "agents";
+
+export default {
+  fetch: (req, env) =>
+    routeAgentRequest(req, env) ?? new Response("Not found", { status: 404 })
+};
+```
+
+| Class | URL |
+|-------|-----|
+| `Counter` | `/agents/counter/user-123` |
+| `ChatRoom` | `/agents/chat-room/lobby` |
+| `MyAgent` | `/agents/my-agent/default` |
+
+Subpaths after the instance name (e.g. `/agents/my-agent/default/api/data`) route to `onRequest`.
+
+## Custom Routing with `getAgentByName`
+
+```typescript
+import { getAgentByName } from "agents";
+
+export default {
+  async fetch(req, env) {
+    const url = new URL(req.url);
+    if (url.pathname.startsWith("/api/")) {
+      const agent = getAgentByName(env.MyAgent, "singleton");
+      return agent.fetch(req);
+    }
+    return routeAgentRequest(req, env);
+  }
+};
+```
+
+## Options
+
+```typescript
+routeAgentRequest(req, env, {
+  cors: true,
+  prefix: "/api/agents",
+  locationHint: "enam",
+  jurisdiction: "eu",
+  props: { userId: "123" },
+  onBeforeConnect: async (req) => { /* auth check */ },
+  onBeforeRequest: async (req) => { /* auth check */ }
+});
+```
+
+`props` are delivered to `onStart(props)` on first access.
+
+## Client Side
+
+```tsx
+useAgent({
+  agent: "MyAgent",
+  name: "instance-1",
+  host: "https://my-worker.workers.dev",
+  basePath: "/api/agents",
+  path: "/custom-subpath"
+});
+```
+
+## Common Mistakes
+
+- Class name `MyAgent` becomes kebab `my-agent` in URLs — match exactly
+- "Namespace not found" error = the `class_name` in wrangler doesn't match your exported class
+- If `sendIdentityOnConnect: false`, the `ready` promise on the client may never resolve — use state sync instead