cli-jaw 0.1.6 → 0.1.8

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

@@ -1,154 +0,0 @@
-# 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

@@ -1,164 +0,0 @@
-# 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

@@ -1,178 +0,0 @@
-# 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

@@ -1,132 +0,0 @@
-# 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 }
-```