cli-jaw 0.1.0

package/skills_ref/agents-sdk/SKILL.md

@@ -0,0 +1,155 @@
+---
+name: agents-sdk
+description: Build AI agents on Cloudflare Workers using the Agents SDK. Load when creating stateful agents, durable workflows, real-time WebSocket apps, scheduled tasks, MCP servers, or chat applications. Covers Agent class, state management, callable RPC, Workflows integration, and React hooks.
+---
+
+# Cloudflare Agents SDK
+
+**STOP.** Your knowledge of the Agents SDK may be outdated. Prefer retrieval over pre-training for any Agents SDK task.
+
+## Documentation
+
+Fetch current docs from `https://github.com/cloudflare/agents/tree/main/docs` before implementing.
+
+| Topic | Doc | Use for |
+|-------|-----|---------|
+| Getting started | `docs/getting-started.md` | First agent, project setup |
+| State | `docs/state.md` | `setState`, `validateStateChange`, persistence |
+| Routing | `docs/routing.md` | URL patterns, `routeAgentRequest`, `basePath` |
+| Callable methods | `docs/callable-methods.md` | `@callable`, RPC, streaming, timeouts |
+| Scheduling | `docs/scheduling.md` | `schedule()`, `scheduleEvery()`, cron |
+| Workflows | `docs/workflows.md` | `AgentWorkflow`, durable multi-step tasks |
+| HTTP/WebSockets | `docs/http-websockets.md` | Lifecycle hooks, hibernation |
+| Email | `docs/email.md` | Email routing, secure reply resolver |
+| MCP client | `docs/mcp-client.md` | Connecting to MCP servers |
+| MCP server | `docs/mcp-servers.md` | Building MCP servers with `McpAgent` |
+| Client SDK | `docs/client-sdk.md` | `useAgent`, `useAgentChat`, React hooks |
+| Human-in-the-loop | `docs/human-in-the-loop.md` | Approval flows, pausing workflows |
+| Resumable streaming | `docs/resumable-streaming.md` | Stream recovery on disconnect |
+
+Cloudflare docs: https://developers.cloudflare.com/agents/
+
+## Capabilities
+
+The Agents SDK provides:
+
+- **Persistent state** - SQLite-backed, auto-synced to clients
+- **Callable RPC** - `@callable()` methods invoked over WebSocket
+- **Scheduling** - One-time, recurring (`scheduleEvery`), and cron tasks
+- **Workflows** - Durable multi-step background processing via `AgentWorkflow`
+- **MCP integration** - Connect to MCP servers or build your own with `McpAgent`
+- **Email handling** - Receive and reply to emails with secure routing
+- **Streaming chat** - `AIChatAgent` with resumable streams
+- **React hooks** - `useAgent`, `useAgentChat` for client apps
+
+## FIRST: Verify Installation
+
+```bash
+npm ls agents  # Should show agents package
+```
+
+If not installed:
+```bash
+npm install agents
+```
+
+## Wrangler Configuration
+
+```jsonc
+{
+  "durable_objects": {
+    "bindings": [{ "name": "MyAgent", "class_name": "MyAgent" }]
+  },
+  "migrations": [{ "tag": "v1", "new_sqlite_classes": ["MyAgent"] }]
+}
+```
+
+## Agent Class
+
+```typescript
+import { Agent, routeAgentRequest, callable } from "agents";
+
+type State = { count: number };
+
+export class Counter extends Agent<Env, State> {
+  initialState = { count: 0 };
+
+  // Validation hook - runs before state persists (sync, throwing rejects the update)
+  validateStateChange(nextState: State, source: Connection | "server") {
+    if (nextState.count < 0) throw new Error("Count cannot be negative");
+  }
+
+  // Notification hook - runs after state persists (async, non-blocking)
+  onStateUpdate(state: State, source: Connection | "server") {
+    console.log("State updated:", state);
+  }
+
+  @callable()
+  increment() {
+    this.setState({ count: this.state.count + 1 });
+    return this.state.count;
+  }
+}
+
+export default {
+  fetch: (req, env) => routeAgentRequest(req, env) ?? new Response("Not found", { status: 404 })
+};
+```
+
+## Routing
+
+Requests route to `/agents/{agent-name}/{instance-name}`:
+
+| Class | URL |
+|-------|-----|
+| `Counter` | `/agents/counter/user-123` |
+| `ChatRoom` | `/agents/chat-room/lobby` |
+
+Client: `useAgent({ agent: "Counter", name: "user-123" })`
+
+## Core APIs
+
+| Task | API |
+|------|-----|
+| Read state | `this.state.count` |
+| Write state | `this.setState({ count: 1 })` |
+| SQL query | `` this.sql`SELECT * FROM users WHERE id = ${id}` `` |
+| Schedule (delay) | `await this.schedule(60, "task", payload)` |
+| Schedule (cron) | `await this.schedule("0 * * * *", "task", payload)` |
+| Schedule (interval) | `await this.scheduleEvery(30, "poll")` |
+| RPC method | `@callable() myMethod() { ... }` |
+| Streaming RPC | `@callable({ streaming: true }) stream(res) { ... }` |
+| Start workflow | `await this.runWorkflow("ProcessingWorkflow", params)` |
+
+## React Client
+
+```tsx
+import { useAgent } from "agents/react";
+
+function App() {
+  const [state, setLocalState] = useState({ count: 0 });
+
+  const agent = useAgent({
+    agent: "Counter",
+    name: "my-instance",
+    onStateUpdate: (newState) => setLocalState(newState),
+    onIdentity: (name, agentType) => console.log(`Connected to ${name}`)
+  });
+
+  return (
+    <button onClick={() => agent.setState({ count: state.count + 1 })}>
+      Count: {state.count}
+    </button>
+  );
+}
+```
+
+## References
+
+- **[references/workflows.md](references/workflows.md)** - Durable Workflows integration
+- **[references/callable.md](references/callable.md)** - RPC methods, streaming, timeouts
+- **[references/state-scheduling.md](references/state-scheduling.md)** - State persistence, scheduling
+- **[references/streaming-chat.md](references/streaming-chat.md)** - AIChatAgent, resumable streams
+- **[references/mcp.md](references/mcp.md)** - MCP server integration
+- **[references/email.md](references/email.md)** - Email routing and handling
+- **[references/codemode.md](references/codemode.md)** - Code Mode (experimental)

package/skills_ref/agents-sdk/references/callable.md

@@ -0,0 +1,92 @@
+# Callable Methods
+
+Fetch `docs/callable-methods.md` from `https://github.com/cloudflare/agents/tree/main/docs` for complete documentation.
+
+## Overview
+
+`@callable()` exposes agent methods to clients via WebSocket RPC.
+
+```typescript
+import { Agent, callable } from "agents";
+
+export class MyAgent extends Agent<Env, State> {
+  @callable()
+  async greet(name: string): Promise<string> {
+    return `Hello, ${name}!`;
+  }
+
+  @callable()
+  async processData(data: unknown): Promise<Result> {
+    // Long-running work
+    return result;
+  }
+}
+```
+
+## Client Usage
+
+```typescript
+// Basic call
+const greeting = await agent.call("greet", ["World"]);
+
+// With timeout
+const result = await agent.call("processData", [data], {
+  timeout: 5000  // 5 second timeout
+});
+```
+
+## Streaming Responses
+
+```typescript
+import { Agent, callable, StreamingResponse } from "agents";
+
+export class MyAgent extends Agent<Env, State> {
+  @callable({ streaming: true })
+  async streamResults(stream: StreamingResponse, query: string) {
+    for await (const item of fetchResults(query)) {
+      stream.send(JSON.stringify(item));
+    }
+    stream.close();
+  }
+
+  @callable({ streaming: true })
+  async streamWithError(stream: StreamingResponse) {
+    try {
+      // ... work
+    } catch (error) {
+      stream.error(error.message);  // Signal error to client
+      return;
+    }
+    stream.close();
+  }
+}
+```
+
+Client with streaming:
+
+```typescript
+await agent.call("streamResults", ["search term"], {
+  stream: {
+    onChunk: (data) => console.log("Chunk:", data),
+    onDone: () => console.log("Complete"),
+    onError: (error) => console.error("Error:", error)
+  }
+});
+```
+
+## Introspection
+
+```typescript
+// Get list of callable methods on an agent
+const methods = await agent.call("getCallableMethods", []);
+// Returns: ["greet", "processData", "streamResults", ...]
+```
+
+## When to Use
+
+| Scenario | Use |
+|----------|-----|
+| Browser/mobile calling agent | `@callable()` |
+| External service calling agent | `@callable()` |
+| Worker calling agent (same codebase) | DO RPC directly |
+| Agent calling another agent | `getAgentByName()` + DO RPC |

package/skills_ref/agents-sdk/references/codemode.md

@@ -0,0 +1,207 @@
+# Code Mode (Experimental)
+
+Code Mode generates executable JavaScript instead of making individual tool calls. This significantly reduces token usage and enables complex multi-tool workflows.
+
+## Why Code Mode?
+
+Traditional tool calling:
+- One tool call per LLM request
+- Multiple round-trips for chained operations
+- High token usage for complex workflows
+
+Code Mode:
+- LLM generates code that orchestrates multiple tools
+- Single execution for complex workflows
+- Self-debugging and error recovery
+- Ideal for MCP server orchestration
+
+## Setup
+
+### 1. Wrangler Config
+
+```jsonc
+{
+  "name": "my-agent-worker",
+  "compatibility_flags": ["experimental", "enable_ctx_exports"],
+  "durable_objects": {
+    // "class_name" must match your Agent class name exactly
+    "bindings": [{ "name": "MyAgent", "class_name": "MyAgent" }]
+  },
+  "migrations": [
+    // Required: list all Agent classes for SQLite storage
+    { "tag": "v1", "new_sqlite_classes": ["MyAgent"] }
+  ],
+  "services": [
+    {
+      "binding": "globalOutbound",
+      // "service" must match "name" above
+      "service": "my-agent-worker",
+      "entrypoint": "globalOutbound"
+    },
+    {
+      "binding": "CodeModeProxy",
+      "service": "my-agent-worker",
+      "entrypoint": "CodeModeProxy"
+    }
+  ],
+  "worker_loaders": [{ "binding": "LOADER" }]
+}
+```
+
+### 2. Export Required Classes
+
+```typescript
+// Export the proxy for tool execution (required for codemode)
+export { CodeModeProxy } from "@cloudflare/codemode/ai";
+
+// Define outbound fetch handler for security filtering
+export const globalOutbound = {
+  fetch: async (input: string | URL | RequestInfo, init?: RequestInit) => {
+    const url = new URL(
+      typeof input === "string"
+        ? input
+        : typeof input === "object" && "url" in input
+          ? input.url
+          : input.toString()
+    );
+    // Block certain domains if needed
+    if (url.hostname === "blocked.example.com") {
+      return new Response("Not allowed", { status: 403 });
+    }
+    return fetch(input, init);
+  }
+};
+```
+
+### 3. Install Dependencies
+
+```bash
+npm install @cloudflare/codemode ai @ai-sdk/openai zod
+```
+
+### 4. Use Code Mode in Agent
+
+```typescript
+import { Agent } from "agents";
+import { experimental_codemode as codemode } from "@cloudflare/codemode/ai";
+import { streamText, tool, convertToModelMessages } from "ai";
+import { openai } from "@ai-sdk/openai";
+import { env } from "cloudflare:workers";
+import { z } from "zod";
+
+const tools = {
+  getWeather: tool({
+    description: "Get weather for a location",
+    parameters: z.object({ location: z.string() }),
+    execute: async ({ location }) => `Weather: ${location} 72°F`
+  }),
+  sendEmail: tool({
+    description: "Send an email",
+    parameters: z.object({ to: z.string(), subject: z.string(), body: z.string() }),
+    execute: async ({ to, subject, body }) => `Email sent to ${to}`
+  })
+};
+
+export class MyAgent extends Agent<Env, State> {
+  tools = {};
+
+  // Method called by codemode proxy
+  callTool(functionName: string, args: unknown[]) {
+    return this.tools[functionName]?.execute?.(args, {
+      abortSignal: new AbortController().signal,
+      toolCallId: "codemode",
+      messages: []
+    });
+  }
+
+  async onChatMessage() {
+    this.tools = { ...tools, ...this.mcp.getAITools() };
+
+    const { prompt, tools: wrappedTools } = await codemode({
+      prompt: "You are a helpful assistant...",
+      tools: this.tools,
+      globalOutbound: env.globalOutbound,
+      loader: env.LOADER,
+      proxy: this.ctx.exports.CodeModeProxy({
+        props: {
+          binding: "MyAgent",  // Class name
+          name: this.name,     // Instance name
+          callback: "callTool" // Method to call
+        }
+      })
+    });
+
+    const result = streamText({
+      system: prompt,
+      model: openai("gpt-4o"),
+      messages: await convertToModelMessages(this.state.messages),
+      tools: wrappedTools  // Use wrapped tools, not original
+    });
+
+    // ... handle stream
+  }
+}
+```
+
+## Generated Code Example
+
+When user asks "Check the weather in NYC and email me the forecast", codemode generates:
+
+```javascript
+async function executeTask() {
+  const weather = await codemode.getWeather({ location: "NYC" });
+  
+  await codemode.sendEmail({
+    to: "user@example.com",
+    subject: "NYC Weather Forecast",
+    body: `Current weather: ${weather}`
+  });
+  
+  return { success: true, weather };
+}
+```
+
+## MCP Server Orchestration
+
+Code Mode excels at orchestrating multiple MCP servers:
+
+```javascript
+async function executeTask() {
+  // Query file system MCP
+  const files = await codemode.listFiles({ path: "/projects" });
+  
+  // Query database MCP
+  const status = await codemode.queryDatabase({
+    query: "SELECT * FROM projects WHERE name = ?",
+    params: [files[0].name]
+  });
+  
+  // Conditional logic based on results
+  if (status.length === 0) {
+    await codemode.createTask({
+      title: `Review: ${files[0].name}`,
+      priority: "high"
+    });
+  }
+  
+  return { files, status };
+}
+```
+
+## When to Use
+
+| Scenario | Use Code Mode? |
+|----------|---------------|
+| Single tool call | No |
+| Chained tool calls | Yes |
+| Conditional logic across tools | Yes |
+| MCP multi-server workflows | Yes |
+| Token budget constrained | Yes |
+| Simple Q&A chat | No |
+
+## Limitations
+
+- Experimental - API may change
+- Requires Cloudflare Workers
+- JavaScript execution only (Python planned)
+- Requires additional wrangler config

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

@@ -0,0 +1,146 @@
+# Email Handling
+
+Fetch `docs/email.md` from `https://github.com/cloudflare/agents/tree/main/docs` 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...
+}
+```