cli-jaw 0.1.0

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

@@ -0,0 +1,154 @@
+# MCP Server Integration
+
+Fetch `docs/mcp-client.md` and `docs/mcp-servers.md` from `https://github.com/cloudflare/agents/tree/main/docs` for complete documentation.
+
+Agents include a multi-server MCP client for connecting to external 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);
+
+    // SSE transport (legacy)
+    if (url.pathname.startsWith("/sse")) {
+      return MyMCP.serveSSE("/sse", { binding: "MyMCP" }).fetch(request, env, ctx);
+    }
+
+    // Streamable HTTP transport (recommended)
+    if (url.pathname.startsWith("/mcp")) {
+      return MyMCP.serve("/mcp", { binding: "MyMCP" }).fetch(request, env, ctx);
+    }
+
+    return new Response("Not found", { status: 404 });
+  }
+};
+```

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

@@ -0,0 +1,164 @@
+# State & Scheduling
+
+Fetch `docs/state.md` and `docs/scheduling.md` from `https://github.com/cloudflare/agents/tree/main/docs` 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);
+```
+
+## 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_ref/agents-sdk/references/streaming-chat.md

@@ -0,0 +1,178 @@
+# Streaming Chat with AIChatAgent
+
+Fetch `docs/resumable-streaming.md` and `docs/client-sdk.md` from `https://github.com/cloudflare/agents/tree/main/docs` for complete documentation.
+
+`AIChatAgent` 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) {
+    const result = streamText({
+      model: openai("gpt-4o"),
+      messages: await convertToModelMessages(this.messages),
+      onFinish
+    });
+    return result.toUIMessageStreamResponse();
+  }
+}
+```
+
+## With Custom System Prompt
+
+```typescript
+export class Chat extends AIChatAgent<Env> {
+  async onChatMessage(onFinish) {
+    const result = streamText({
+      model: openai("gpt-4o"),
+      system: "You are a helpful assistant specializing in...",
+      messages: await convertToModelMessages(this.messages),
+      onFinish
+    });
+    return result.toUIMessageStreamResponse();
+  }
+}
+```
+
+## 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) {
+    const result = streamText({
+      model: openai("gpt-4o"),
+      messages: await convertToModelMessages(this.messages),
+      tools,
+      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.
+
+## Status Values
+
+`useAgentChat` status:
+
+| Status | Meaning |
+|--------|---------|
+| `ready` | Idle, ready for input |
+| `streaming` | Response streaming |
+| `submitted` | Request sent, waiting |
+| `error` | Error occurred |

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

@@ -0,0 +1,132 @@
+# Workflows Integration
+
+Fetch `docs/workflows.md` from `https://github.com/cloudflare/agents/tree/main/docs` 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 }
+```