pi-cloudflare 0.1.0

package/skills/agents-sdk/references/server-driven-messages.md

@@ -0,0 +1,63 @@
+# Server-Driven Messages (Trigger Patterns)
+
+Fetch https://developers.cloudflare.com/agents/api-reference/trigger-patterns/ for complete documentation.
+
+Patterns for server-initiated LLM turns in `AIChatAgent` — from schedules, webhooks, email, or other agents.
+
+## `saveMessages` — Trigger an LLM Turn
+
+```typescript
+await this.saveMessages((existingMessages) => [
+  ...existingMessages,
+  { role: "user", content: "Check for new notifications" }
+]);
+```
+
+`saveMessages` persists the messages AND triggers `onChatMessage`.
+
+## `persistMessages` — Save Without Triggering
+
+```typescript
+await this.persistMessages([
+  ...this.messages,
+  { role: "assistant", content: "System note: checked at " + new Date() }
+]);
+```
+
+## `waitUntilStable`
+
+**Always call before `saveMessages` from non-chat contexts** (schedules, webhooks, email):
+
+```typescript
+async checkNotifications(payload: unknown, schedule: Schedule) {
+  await this.waitUntilStable({ timeout: 30_000 });
+  await this.saveMessages((msgs) => [
+    ...msgs,
+    { role: "user", content: "Run scheduled notification check" }
+  ]);
+}
+```
+
+## `onChatResponse`
+
+Runs after each LLM turn completes. Use for chaining:
+
+```typescript
+async onChatResponse(result: ChatResponseResult) {
+  if (result.type === "finish" && needsFollowUp(result)) {
+    await this.saveMessages((msgs) => [
+      ...msgs,
+      { role: "user", content: "Continue with next step" }
+    ]);
+  }
+}
+```
+
+## Client Status
+
+```tsx
+const { isStreaming, isServerStreaming } = useAgentChat({ agent });
+```
+
+- `isStreaming` — true during any streaming (user-initiated or server-initiated)
+- `isServerStreaming` — true only during server-initiated streams

package/skills/agents-sdk/references/state-scheduling.md

@@ -0,0 +1,171 @@
+# State & Scheduling
+
+Fetch https://developers.cloudflare.com/agents/api-reference/store-and-sync-state/ and https://developers.cloudflare.com/agents/api-reference/schedule-tasks/ for complete documentation.
+
+## State Management
+
+State persists to SQLite and broadcasts to connected clients automatically.
+
+### Define Typed State
+
+```typescript
+type State = { 
+  count: number;
+  items: string[];
+};
+
+export class MyAgent extends Agent<Env, State> {
+  initialState: State = { count: 0, items: [] };
+}
+```
+
+### Read and Update
+
+```typescript
+// Read (lazy-loaded from SQLite)
+const count = this.state.count;
+
+// Write (sync, persists, broadcasts)
+this.setState({ count: this.state.count + 1 });
+```
+
+### Validation Hook
+
+`validateStateChange()` runs synchronously before state persists. Throw to reject the update.
+
+```typescript
+validateStateChange(nextState: State, source: Connection | "server") {
+  if (nextState.count < 0) {
+    throw new Error("Count cannot be negative");
+  }
+}
+```
+
+### Execution Order
+
+1. `validateStateChange(nextState, source)` - sync, gating
+2. State persisted to SQLite
+3. State broadcast to connected clients
+4. `onStateUpdate(nextState, source)` - async via `ctx.waitUntil`, non-gating
+
+### Client-Side Sync (React)
+
+```tsx
+import { useAgent } from "agents/react";
+
+function App() {
+  const [state, setLocalState] = useState<State>({ count: 0 });
+  
+  const agent = useAgent<State>({
+    agent: "MyAgent",
+    name: "instance-1",
+    onStateUpdate: (newState) => setLocalState(newState)
+  });
+
+  return <button onClick={() => agent.setState({ count: state.count + 1 })}>
+    Count: {state.count}
+  </button>;
+}
+```
+
+## SQL API
+
+Direct SQLite access for custom queries:
+
+```typescript
+// Create table
+this.sql`
+  CREATE TABLE IF NOT EXISTS items (
+    id TEXT PRIMARY KEY,
+    name TEXT,
+    created_at INTEGER DEFAULT (unixepoch())
+  )
+`;
+
+// Insert
+this.sql`INSERT INTO items (id, name) VALUES (${id}, ${name})`;
+
+// Query with types
+const items = this.sql<{ id: string; name: string }>`
+  SELECT * FROM items WHERE name LIKE ${`%${search}%`}
+`;
+```
+
+## Scheduling
+
+### Schedule Types
+
+| Mode | Syntax | Use Case |
+|------|--------|----------|
+| Delay | `this.schedule(60, ...)` | Run in 60 seconds |
+| Date | `this.schedule(new Date(...), ...)` | Run at specific time |
+| Cron | `this.schedule("0 8 * * *", ...)` | Recurring schedule |
+| Interval | `this.scheduleEvery(30, ...)` | Fixed interval (every 30s) |
+
+### Examples
+
+```typescript
+// Delay (seconds)
+await this.schedule(60, "checkStatus", { id: "abc123" });
+
+// Specific date
+await this.schedule(new Date("2025-12-25T00:00:00Z"), "sendGreeting", { to: "user" });
+
+// Cron (recurring)
+await this.schedule("0 9 * * 1-5", "weekdayReport", {});
+
+// Fixed interval (every 30 seconds, overlap prevention built-in)
+await this.scheduleEvery(30, "pollUpdates");
+await this.scheduleEvery(300, "syncData", { source: "api" });
+```
+
+### Handler
+
+```typescript
+async sendGreeting(payload: { to: string }, schedule: Schedule) {
+  console.log(`Sending greeting to ${payload.to}`);
+  // Cron schedules auto-reschedule; one-time schedules are deleted
+}
+```
+
+### Manage Schedules
+
+```typescript
+const schedules = this.getSchedules();
+const crons = this.getSchedules({ type: "cron" });
+await this.cancelSchedule(schedule.id);
+```
+
+### Retry on Schedules
+
+```typescript
+await this.schedule(60, "task", payload, { retry: { maxAttempts: 3 } });
+await this.scheduleEvery(30, "poll", undefined, { retry: { maxAttempts: 2 } });
+```
+
+## Lifecycle Callbacks
+
+```typescript
+export class MyAgent extends Agent<Env, State> {
+  async onStart() {
+    // Agent started or woke from hibernation
+  }
+
+  onConnect(conn: Connection, ctx: ConnectionContext) {
+    // WebSocket connected
+  }
+
+  onMessage(conn: Connection, message: WSMessage) {
+    // WebSocket message (non-RPC)
+  }
+
+  onStateUpdate(state: State, source: Connection | "server") {
+    // State changed (async, non-blocking)
+  }
+
+  onError(error: unknown) {
+    // Error handler
+    throw error; // Re-throw to propagate
+  }
+}
+```

package/skills/agents-sdk/references/streaming-chat.md

@@ -0,0 +1,198 @@
+# Streaming Chat with AIChatAgent
+
+Fetch https://developers.cloudflare.com/agents/api-reference/chat-agents/ for complete documentation.
+
+`AIChatAgent` from `@cloudflare/ai-chat` provides streaming chat with automatic message persistence and resumable streams.
+
+## Basic Chat Agent
+
+```typescript
+import { AIChatAgent } from "@cloudflare/ai-chat";
+import { streamText, convertToModelMessages } from "ai";
+import { openai } from "@ai-sdk/openai";
+
+export class Chat extends AIChatAgent<Env> {
+  async onChatMessage(onFinish, options) {
+    const result = streamText({
+      model: openai("gpt-4o"),
+      system: "You are a helpful assistant.",
+      messages: await convertToModelMessages(this.messages),
+      abortSignal: options?.abortSignal,
+      onFinish
+    });
+    return result.toUIMessageStreamResponse();
+  }
+}
+```
+
+**Important:** Always pass `abortSignal` and `onFinish` — they enable proper cleanup and message persistence.
+
+## With Tools
+
+```typescript
+import { tool } from "ai";
+import { z } from "zod";
+
+const tools = {
+  getWeather: tool({
+    description: "Get weather for a location",
+    parameters: z.object({ location: z.string() }),
+    execute: async ({ location }) => `Weather in ${location}: 72°F, sunny`
+  })
+};
+
+export class Chat extends AIChatAgent<Env> {
+  async onChatMessage(onFinish, options) {
+    const result = streamText({
+      model: openai("gpt-4o"),
+      messages: await convertToModelMessages(this.messages),
+      tools,
+      abortSignal: options?.abortSignal,
+      onFinish
+    });
+    return result.toUIMessageStreamResponse();
+  }
+}
+```
+
+## With Workers AI (no API keys)
+
+```typescript
+import { createWorkersAI } from "workers-ai-provider";
+
+export class Chat extends AIChatAgent<Env> {
+  async onChatMessage(onFinish, options) {
+    const workersai = createWorkersAI({ binding: this.env.AI });
+    const result = streamText({
+      model: workersai("@cf/meta/llama-4-scout-17b-16e-instruct"),
+      messages: await convertToModelMessages(this.messages),
+      abortSignal: options?.abortSignal,
+      onFinish
+    });
+    return result.toUIMessageStreamResponse();
+  }
+}
+```
+
+## Custom UI Message Stream
+
+For more control, use `createUIMessageStream`:
+
+```typescript
+import { createUIMessageStream, createUIMessageStreamResponse } from "ai";
+
+export class Chat extends AIChatAgent<Env> {
+  async onChatMessage(onFinish) {
+    const stream = createUIMessageStream({
+      execute: async ({ writer }) => {
+        const result = streamText({
+          model: openai("gpt-4o"),
+          messages: await convertToModelMessages(this.messages),
+          onFinish
+        });
+        writer.merge(result.toUIMessageStream());
+      }
+    });
+    return createUIMessageStreamResponse({ stream });
+  }
+}
+```
+
+## Resumable Streaming
+
+Streams automatically resume if client disconnects and reconnects:
+
+1. Chunks buffered to SQLite during streaming
+2. On reconnect, buffered chunks sent immediately
+3. Live streaming continues from where it left off
+
+**Enabled by default.** To disable:
+
+```tsx
+const { messages } = useAgentChat({ agent, resume: false });
+```
+
+## React Client
+
+```tsx
+import { useAgent } from "agents/react";
+import { useAgentChat } from "@cloudflare/ai-chat/react";
+
+function ChatUI() {
+  const agent = useAgent({
+    agent: "Chat",
+    name: "my-chat-session"
+  });
+
+  const { 
+    messages, 
+    input, 
+    handleInputChange, 
+    handleSubmit, 
+    status 
+  } = useAgentChat({ agent });
+
+  return (
+    <div>
+      {messages.map((m) => (
+        <div key={m.id}>
+          <strong>{m.role}:</strong> {m.content}
+        </div>
+      ))}
+      
+      <form onSubmit={handleSubmit}>
+        <input 
+          value={input} 
+          onChange={handleInputChange}
+          disabled={status === "streaming"}
+        />
+        <button type="submit">Send</button>
+      </form>
+    </div>
+  );
+}
+```
+
+## Streaming RPC Methods
+
+For non-chat streaming, use `@callable({ streaming: true })`:
+
+```typescript
+import { Agent, callable, StreamingResponse } from "agents";
+
+export class MyAgent extends Agent<Env> {
+  @callable({ streaming: true })
+  async streamData(stream: StreamingResponse, query: string) {
+    for (let i = 0; i < 10; i++) {
+      stream.send(`Result ${i}: ${query}`);
+      await sleep(100);
+    }
+    stream.close();
+  }
+}
+```
+
+Client receives streamed messages via WebSocket RPC.
+
+## Key Properties
+
+| Property | Purpose |
+|----------|---------|
+| `this.messages` | All persisted messages |
+| `maxPersistedMessages` | Limit stored messages (prune oldest) |
+| `messageConcurrency` | `"queue"` (default), `"latest"`, `"merge"`, `"drop"` |
+| `chatRecovery` | `"persist"` (default) or `"continue"` on reconnect |
+| `waitForMcpConnections` | Wait for MCP servers before first turn |
+
+## Status Values
+
+`useAgentChat` status:
+
+| Status | Meaning |
+|--------|---------|
+| `ready` | Idle, ready for input |
+| `streaming` | Response streaming |
+| `submitted` | Request sent, waiting |
+| `error` | Error occurred |
+
+Also: `isStreaming`, `isServerStreaming` for distinguishing user vs server-initiated streams.

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

@@ -0,0 +1,112 @@
+# Think (Experimental)
+
+Fetch https://developers.cloudflare.com/agents/api-reference/think/ for complete documentation.
+
+`@cloudflare/think` — a higher-level chat agent class that handles the `streamText` loop, tool execution, and message persistence for you. You provide `getModel()` and `getSystemPrompt()`; Think handles the rest.
+
+```bash
+npm install @cloudflare/think
+```
+
+## Minimal Agent
+
+```typescript
+import { Think } from "@cloudflare/think";
+import { createWorkersAI } from "workers-ai-provider";
+import { routeAgentRequest } from "agents";
+
+export class MyAgent extends Think<Env> {
+  getModel() {
+    return createWorkersAI({ binding: this.env.AI })("@cf/meta/llama-4-scout-17b-16e-instruct");
+  }
+
+  getSystemPrompt() {
+    return "You are a helpful assistant.";
+  }
+}
+
+export default {
+  fetch: (req, env) => routeAgentRequest(req, env)
+};
+```
+
+## Wrangler Config
+
+```jsonc
+{
+  "compatibility_flags": ["nodejs_compat", "experimental"],
+  "durable_objects": {
+    "bindings": [{ "name": "MyAgent", "class_name": "MyAgent" }]
+  },
+  "migrations": [{ "tag": "v1", "new_sqlite_classes": ["MyAgent"] }],
+  "ai": { "binding": "AI" }
+}
+```
+
+**Note:** Think requires the `experimental` compatibility flag.
+
+## Custom Tools
+
+```typescript
+import { tool } from "ai";
+import { z } from "zod";
+
+export class MyAgent extends Think<Env> {
+  getTools() {
+    return {
+      getWeather: tool({
+        description: "Get weather",
+        parameters: z.object({ city: z.string() }),
+        execute: async ({ city }) => `72°F in ${city}`
+      })
+    };
+  }
+}
+```
+
+## Lifecycle Hooks
+
+| Hook | When | Use for |
+|------|------|---------|
+| `configureSession()` | Agent starts | Set up memory, context providers |
+| `beforeTurn(ctx)` | Before each LLM call | Per-turn model/tools/system prompt; return `TurnConfig` |
+| `onChunk(chunk)` | Each streaming chunk | Progress tracking |
+| `onChatResponse(result)` | After LLM turn completes | Chaining, follow-up `saveMessages` |
+| `onChatError(error)` | On LLM error | Error handling |
+
+```typescript
+async beforeTurn(ctx: TurnContext): Promise<TurnConfig> {
+  if (ctx.continuation) {
+    return { model: cheaperModel };
+  }
+  return {};
+}
+```
+
+## Sub-Agents
+
+```typescript
+const child = this.subAgent(SpecialistAgent, "specialist-1");
+await child.chat("Analyze this data...", (chunk) => {
+  // stream callback
+});
+```
+
+## Client
+
+Same React hooks as `AIChatAgent`:
+
+```tsx
+const agent = useAgent({ agent: "MyAgent", name: "session-1" });
+const { messages, input, handleInputChange, handleSubmit } = useAgentChat({ agent });
+```
+
+## Think vs AIChatAgent
+
+| | Think | AIChatAgent |
+|-|-------|-------------|
+| `streamText` loop | Built-in | You write it |
+| Tool execution | Automatic | You wire it |
+| Customization | Override hooks | Full control in `onChatMessage` |
+| Built-in tools | Workspace, execute, browser | None |
+| Compatibility flag | Requires `experimental` | Standard |

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

@@ -0,0 +1,68 @@
+# Voice (Experimental)
+
+Fetch https://developers.cloudflare.com/agents/api-reference/voice/ for complete documentation.
+
+`@cloudflare/voice` — real-time speech-to-text and text-to-speech for agents. Audio streams over WebSocket.
+
+```bash
+npm install @cloudflare/voice
+```
+
+## Server
+
+```typescript
+import { Agent } from "agents";
+import { withVoice, WorkersAITTS, WorkersAINova3STT } from "@cloudflare/voice";
+
+export class VoiceAgent extends withVoice(Agent)<Env> {
+  transcriber = new WorkersAINova3STT(this);
+  tts = new WorkersAITTS(this);
+
+  async onTurn(transcript: string, context: VoiceTurnContext) {
+    const result = streamText({
+      model: createWorkersAI({ binding: this.env.AI })("@cf/meta/llama-4-scout-17b-16e-instruct"),
+      messages: [
+        { role: "system", content: "You are a voice assistant." },
+        ...context.conversationHistory,
+        { role: "user", content: transcript }
+      ]
+    });
+
+    for await (const chunk of result.textStream) {
+      if (context.signal.aborted) break;
+      context.speak(chunk);
+    }
+  }
+}
+```
+
+## Lifecycle Hooks
+
+| Hook | Purpose |
+|------|---------|
+| `onTurn(transcript, ctx)` | Handle transcribed speech (required) |
+| `beforeCallStart(conn)` | Auth/validation before call starts |
+| `onCallStart(conn)` | Call connected |
+| `onCallEnd(conn)` | Call disconnected |
+| `onInterrupt()` | User interrupted agent speech |
+
+## Client (React)
+
+```tsx
+import { useVoiceAgent } from "@cloudflare/voice/react";
+
+function VoiceUI() {
+  const { isConnected, isSpeaking, connect, disconnect } = useVoiceAgent({
+    agent: "VoiceAgent",
+    name: "session-1"
+  });
+
+  return <button onClick={isConnected ? disconnect : connect}>
+    {isConnected ? "End Call" : "Start Call"}
+  </button>;
+}
+```
+
+## STT/TTS Providers
+
+Workers AI (default), Deepgram, ElevenLabs — install the provider package and swap the `transcriber`/`tts` properties.

package/skills/agents-sdk/references/webhooks-push.md

@@ -0,0 +1,86 @@
+# Webhooks & Push Notifications
+
+## Webhooks
+
+Fetch https://developers.cloudflare.com/agents/api-reference/webhooks/ for complete documentation.
+
+Route external webhooks to agent instances via `onRequest`:
+
+```typescript
+export default {
+  async fetch(req: Request, env: Env) {
+    const url = new URL(req.url);
+    if (url.pathname.startsWith("/webhooks/")) {
+      const entityId = url.pathname.split("/")[2];
+      const agent = getAgentByName(env.MyAgent, entityId);
+      return agent.fetch(req);
+    }
+    return routeAgentRequest(req, env);
+  }
+};
+```
+
+In the agent:
+
+```typescript
+export class MyAgent extends Agent<Env, State> {
+  async onRequest(request: Request) {
+    const signature = request.headers.get("X-Signature");
+    if (!verifySignature(signature, await request.text(), this.env.WEBHOOK_SECRET)) {
+      return new Response("Unauthorized", { status: 401 });
+    }
+    const payload = JSON.parse(await request.text());
+    this.queue("processWebhook", payload);
+    return new Response("OK", { status: 202 });
+  }
+}
+```
+
+**Tips:** Respond quickly (200/202), verify signatures, deduplicate with stored event IDs, use `queue()` for async processing.
+
+## Push Notifications
+
+Fetch https://developers.cloudflare.com/agents/api-reference/push-notifications/ for complete documentation.
+
+Web Push via VAPID from agents. Store subscriptions in agent state, send via `web-push`.
+
+```bash
+npm install web-push
+```
+
+```typescript
+import webpush from "web-push";
+
+export class NotifyAgent extends Agent<Env, State> {
+  @callable()
+  async subscribe(subscription: PushSubscription) {
+    this.setState({
+      ...this.state,
+      subscriptions: [...this.state.subscriptions, subscription]
+    });
+  }
+
+  async sendReminder(payload: { message: string }, schedule: Schedule) {
+    for (const sub of this.state.subscriptions) {
+      try {
+        await webpush.sendNotification(sub, JSON.stringify({
+          title: "Reminder",
+          body: payload.message
+        }), {
+          vapidDetails: {
+            subject: "mailto:you@example.com",
+            publicKey: this.env.VAPID_PUBLIC_KEY,
+            privateKey: this.env.VAPID_PRIVATE_KEY
+          }
+        });
+      } catch (err) {
+        if (err.statusCode === 404 || err.statusCode === 410) {
+          // Remove expired subscription
+        }
+      }
+    }
+  }
+}
+```
+
+VAPID keys: generate with `npx web-push generate-vapid-keys`, store as secrets.