agents 0.16.1 → 0.17.0

package/docs/http-websockets.md

@@ -0,0 +1,668 @@
+# HTTP & WebSockets
+
+Agents handle both HTTP requests and WebSocket connections, giving you flexibility to build REST APIs, real-time applications, or hybrid architectures.
+
+## Overview
+
+Every agent can respond to:
+
+- **HTTP requests** via `onRequest()` - REST APIs, webhooks, file uploads
+- **WebSocket connections** via `onConnect()`, `onMessage()`, `onClose()` - Real-time bidirectional communication
+
+```typescript
+import { Agent } from "agents";
+
+export class MyAgent extends Agent {
+  // Handle HTTP requests
+  onRequest(request: Request): Response {
+    return new Response("Hello from HTTP!");
+  }
+
+  // Handle WebSocket connections
+  onConnect(connection: Connection, ctx: ConnectionContext) {
+    connection.send("Welcome!");
+  }
+
+  onMessage(connection: Connection, message: WSMessage) {
+    // Echo back
+    connection.send(message);
+  }
+}
+```
+
+## Lifecycle Hooks
+
+Agents have several lifecycle hooks that are called at different points:
+
+| Hook                                          | When Called                                               |
+| --------------------------------------------- | --------------------------------------------------------- |
+| `onStart(props?)`                             | Once when the agent first starts (before any connections) |
+| `onRequest(request)`                          | When an HTTP request is received (non-WebSocket)          |
+| `onConnect(connection, ctx)`                  | When a new WebSocket connection is established            |
+| `onMessage(connection, message)`              | When a WebSocket message is received                      |
+| `onClose(connection, code, reason, wasClean)` | When a WebSocket connection closes                        |
+| `onError(connection, error)`                  | When a WebSocket error occurs                             |
+| `onError(error)`                              | When a server error occurs (overloaded)                   |
+
+### Lifecycle Flow
+
+```
+Agent Created
+     ↓
+  onStart()  ←── Called once, before any connections
+     ↓
+┌─────────────────────────────────────┐
+│  For each request:                  │
+│                                     │
+│  HTTP Request ──→ onRequest()       │
+│                                     │
+│  WebSocket ──→ onConnect()          │
+│       ↓                             │
+│  Messages ──→ onMessage() (repeat)  │
+│       ↓                             │
+│  Disconnect ──→ onClose()           │
+└─────────────────────────────────────┘
+```
+
+## HTTP Requests
+
+Handle HTTP requests with `onRequest()`. This is called for any non-WebSocket request to your agent.
+
+```typescript
+export class ApiAgent extends Agent {
+  async onRequest(request: Request): Promise<Response> {
+    const url = new URL(request.url);
+
+    // Route by path
+    if (url.pathname.endsWith("/status")) {
+      return Response.json({
+        status: "ok",
+        connections: this.getConnections().length
+      });
+    }
+
+    if (url.pathname.endsWith("/data") && request.method === "POST") {
+      const data = await request.json();
+      // Process data...
+      return Response.json({ received: true });
+    }
+
+    return new Response("Not found", { status: 404 });
+  }
+}
+```
+
+### Common HTTP Patterns
+
+**REST API with CORS:**
+
+```typescript
+onRequest(request: Request): Response {
+  // Handle preflight
+  if (request.method === "OPTIONS") {
+    return new Response(null, {
+      headers: {
+        "Access-Control-Allow-Origin": "*",
+        "Access-Control-Allow-Methods": "GET, POST, OPTIONS",
+        "Access-Control-Allow-Headers": "Content-Type"
+      }
+    });
+  }
+
+  return Response.json(
+    { data: "..." },
+    { headers: { "Access-Control-Allow-Origin": "*" } }
+  );
+}
+```
+
+**File Upload:**
+
+```typescript
+async onRequest(request: Request): Promise<Response> {
+  if (request.method === "POST") {
+    const formData = await request.formData();
+    const file = formData.get("file") as File;
+
+    // Process file...
+    const content = await file.text();
+
+    return Response.json({ filename: file.name, size: file.size });
+  }
+  return new Response("Method not allowed", { status: 405 });
+}
+```
+
+## WebSocket Connections
+
+WebSockets enable real-time bidirectional communication between clients and your agent.
+
+### Connection Lifecycle
+
+```typescript
+export class ChatAgent extends Agent {
+  // Called when a client connects
+  onConnect(connection: Connection, ctx: ConnectionContext) {
+    // ctx.request contains the original HTTP request (for auth, headers, etc.)
+    const url = new URL(ctx.request.url);
+    const token = url.searchParams.get("token");
+
+    console.log(`Client ${connection.id} connected`);
+    connection.send(JSON.stringify({ type: "welcome", id: connection.id }));
+  }
+
+  // Called for each message from this connection
+  onMessage(connection: Connection, message: WSMessage) {
+    if (typeof message === "string") {
+      const data = JSON.parse(message);
+      // Handle message...
+    } else {
+      // Binary message (ArrayBuffer)
+    }
+  }
+
+  // Called when connection closes
+  onClose(
+    connection: Connection,
+    code: number,
+    reason: string,
+    wasClean: boolean
+  ) {
+    console.log(`Client ${connection.id} disconnected: ${code} ${reason}`);
+  }
+
+  // Called on WebSocket errors
+  onError(connection: Connection, error: unknown) {
+    console.error(`Error on connection ${connection.id}:`, error);
+  }
+}
+```
+
+### The Connection Object
+
+Each WebSocket connection is represented by a `Connection` object:
+
+```typescript
+interface Connection<TState = unknown> {
+  /** Unique connection identifier */
+  id: string;
+
+  /** The agent instance name this connection belongs to */
+  server: string;
+
+  /** Per-connection state (read-only, use setState to update) */
+  state: TState | null;
+
+  /** Update connection state */
+  setState(state: TState | ((prev: TState | null) => TState)): void;
+
+  /** Send a message to this connection */
+  send(message: string | ArrayBuffer): void;
+
+  /** Close this connection */
+  close(code?: number, reason?: string): void;
+}
+```
+
+### Message Types
+
+Messages can be strings or binary:
+
+```typescript
+onMessage(connection: Connection, message: WSMessage) {
+  if (typeof message === "string") {
+    // Text message - usually JSON
+    const data = JSON.parse(message);
+    this.handleTextMessage(connection, data);
+  } else {
+    // Binary message - ArrayBuffer or ArrayBufferView
+    this.handleBinaryMessage(connection, message);
+  }
+}
+```
+
+## Connection Management
+
+### Getting Connections
+
+```typescript
+// Get all connections
+const connections = this.getConnections();
+
+// Get a specific connection by ID
+const connection = this.getConnection("abc123");
+
+// Get connections with a specific tag
+const adminConnections = this.getConnections("admin");
+```
+
+### Broadcasting
+
+Send a message to all connected clients:
+
+```typescript
+// Broadcast to everyone
+this.broadcast(JSON.stringify({ type: "update", data: "..." }));
+
+// Broadcast to everyone except specific connections
+this.broadcast(
+  JSON.stringify({ type: "user-typing", userId: "123" }),
+  ["connection-id-to-exclude"] // Don't send to the originator
+);
+```
+
+### Connection Tags
+
+Tag connections for easy filtering. Override `getConnectionTags()` to assign tags:
+
+```typescript
+export class ChatAgent extends Agent {
+  // Called when a connection is established
+  getConnectionTags(connection: Connection, ctx: ConnectionContext): string[] {
+    const url = new URL(ctx.request.url);
+    const role = url.searchParams.get("role");
+
+    const tags: string[] = [];
+    if (role === "admin") tags.push("admin");
+    if (role === "moderator") tags.push("moderator");
+
+    return tags; // Up to 9 tags, max 256 chars each
+  }
+
+  // Later, broadcast only to admins
+  notifyAdmins(message: string) {
+    for (const conn of this.getConnections("admin")) {
+      conn.send(message);
+    }
+  }
+}
+```
+
+## Per-Connection State
+
+Store data specific to each connection using `connection.state` and `connection.setState()`:
+
+```typescript
+type ConnectionState = {
+  username: string;
+  joinedAt: number;
+  messageCount: number;
+};
+
+export class ChatAgent extends Agent {
+  onConnect(connection: Connection<ConnectionState>, ctx: ConnectionContext) {
+    const url = new URL(ctx.request.url);
+
+    // Initialize connection state
+    connection.setState({
+      username: url.searchParams.get("username") || "Anonymous",
+      joinedAt: Date.now(),
+      messageCount: 0
+    });
+  }
+
+  onMessage(connection: Connection<ConnectionState>, message: WSMessage) {
+    // Update message count using functional update
+    connection.setState((prev) => ({
+      ...prev!,
+      messageCount: (prev?.messageCount || 0) + 1
+    }));
+
+    // Access current state
+    const { username, messageCount } = connection.state!;
+    console.log(`${username} sent message #${messageCount}`);
+  }
+}
+```
+
+**Important:** Connection state is:
+
+- **Immutable** - Read via `connection.state`, update via `connection.setState()`
+- **Per-connection** - Each connection has its own state
+- **Persisted across hibernation** - Survives agent sleep/wake cycles
+
+## The `onStart` Hook
+
+`onStart()` is called once when the agent first starts, before any connections are established:
+
+```typescript
+export class MyAgent extends Agent {
+  private cache: Map<string, unknown> = new Map();
+
+  async onStart() {
+    // Initialize resources
+    console.log(`Agent ${this.name} starting...`);
+
+    // Load data from storage
+    const savedData = this.sql`SELECT * FROM cache`;
+    for (const row of savedData) {
+      this.cache.set(row.key, row.value);
+    }
+
+    // Restore MCP connections, check workflows, etc.
+    // (Agent does this automatically, but you can add custom logic)
+  }
+
+  onConnect(connection: Connection) {
+    // By the time connections arrive, onStart has completed
+  }
+}
+```
+
+## Protocol Message Control
+
+By default, when a WebSocket client connects, the agent sends protocol text frames (`CF_AGENT_IDENTITY`, `CF_AGENT_STATE`, `CF_AGENT_MCP_SERVERS`) to keep the client in sync. You can suppress these on a per-connection basis by overriding `shouldSendProtocolMessages`:
+
+```typescript
+export class MyAgent extends Agent {
+  shouldSendProtocolMessages(
+    connection: Connection,
+    ctx: ConnectionContext
+  ): boolean {
+    // Suppress protocol frames for binary-only clients
+    const url = new URL(ctx.request.url);
+    return url.searchParams.get("protocol") !== "false";
+  }
+}
+```
+
+When `shouldSendProtocolMessages` returns `false` for a connection:
+
+- No `CF_AGENT_IDENTITY`, `CF_AGENT_STATE`, or `CF_AGENT_MCP_SERVERS` frames are sent on connect
+- The connection is excluded from protocol broadcasts (state updates, MCP server changes)
+- Regular messages via `connection.send()` and `this.broadcast()` still work normally
+
+This is useful for IoT devices, binary-only clients, or lightweight consumers that only need raw messages.
+
+### Checking Protocol Status
+
+Use `isConnectionProtocolEnabled` to check whether a connection receives protocol messages:
+
+```typescript
+const enabled = this.isConnectionProtocolEnabled(connection);
+```
+
+This status persists across hibernation — a connection that was marked as no-protocol before hibernation remains no-protocol after waking up.
+
+## Error Handling
+
+Handle errors gracefully with `onError`:
+
+```typescript
+export class MyAgent extends Agent {
+  // WebSocket connection error
+  onError(connection: Connection, error: unknown): void {
+    console.error(`WebSocket error on ${connection.id}:`, error);
+    connection.send(
+      JSON.stringify({ type: "error", message: "Connection error" })
+    );
+  }
+
+  // Server error (overloaded signature - no connection parameter)
+  onError(error: unknown): void {
+    console.error("Server error:", error);
+    // Log to external service, etc.
+  }
+}
+```
+
+## Hibernation
+
+Agents support hibernation - they can sleep when inactive and wake when needed. This saves resources while maintaining WebSocket connections.
+
+### Enabling Hibernation
+
+Hibernation is enabled by default. To disable:
+
+```typescript
+export class AlwaysOnAgent extends Agent {
+  static options = { hibernate: false };
+}
+```
+
+### How Hibernation Works
+
+1. Agent is active, handling connections
+2. After ~10 seconds of no messages, agent hibernates (sleeps)
+3. WebSocket connections remain open (handled by Cloudflare)
+4. When a message arrives, agent wakes up
+5. `onMessage` is called as normal
+
+### What Persists Across Hibernation
+
+| Persists                   | Does Not Persist    |
+| -------------------------- | ------------------- |
+| `this.state` (agent state) | In-memory variables |
+| `connection.state`         | Timers/intervals    |
+| SQLite data (`this.sql`)   | Promises in flight  |
+| Connection metadata        | Local caches        |
+
+**Best Practice:** Store important data in `this.state` or SQLite, not in class properties:
+
+```typescript
+export class MyAgent extends Agent<Env, { counter: number }> {
+  initialState = { counter: 0 };
+
+  // ❌ Don't do this - lost on hibernation
+  private localCounter = 0;
+
+  onMessage(connection: Connection, message: WSMessage) {
+    // ✅ Do this - persists
+    this.setState({ counter: this.state.counter + 1 });
+
+    // ❌ Lost after hibernation
+    this.localCounter++;
+  }
+}
+```
+
+## Common Patterns
+
+### Authentication on Connect
+
+Validate users when they connect:
+
+```typescript
+export class SecureAgent extends Agent {
+  async onConnect(connection: Connection, ctx: ConnectionContext) {
+    const url = new URL(ctx.request.url);
+    const token = url.searchParams.get("token");
+
+    if (!token || !(await this.validateToken(token))) {
+      connection.close(4001, "Unauthorized");
+      return;
+    }
+
+    const user = await this.getUserFromToken(token);
+    connection.setState({ userId: user.id, role: user.role });
+
+    connection.send(JSON.stringify({ type: "authenticated", user }));
+  }
+
+  private async validateToken(token: string): Promise<boolean> {
+    // Validate JWT, check database, etc.
+    return true;
+  }
+}
+```
+
+### Chat Room with Broadcast
+
+```typescript
+type Message = {
+  type: "message" | "join" | "leave";
+  user: string;
+  text?: string;
+  timestamp: number;
+};
+
+export class ChatRoom extends Agent {
+  onConnect(connection: Connection, ctx: ConnectionContext) {
+    const url = new URL(ctx.request.url);
+    const username = url.searchParams.get("username") || "Anonymous";
+
+    connection.setState({ username });
+
+    // Notify others
+    this.broadcast(
+      JSON.stringify({
+        type: "join",
+        user: username,
+        timestamp: Date.now()
+      } satisfies Message),
+      [connection.id] // Don't send to the joining user
+    );
+  }
+
+  onMessage(connection: Connection, message: WSMessage) {
+    if (typeof message !== "string") return;
+
+    const { username } = connection.state as { username: string };
+
+    // Broadcast to everyone
+    this.broadcast(
+      JSON.stringify({
+        type: "message",
+        user: username,
+        text: message,
+        timestamp: Date.now()
+      } satisfies Message)
+    );
+  }
+
+  onClose(connection: Connection) {
+    const { username } = (connection.state as { username: string }) || {};
+    if (username) {
+      this.broadcast(
+        JSON.stringify({
+          type: "leave",
+          user: username,
+          timestamp: Date.now()
+        } satisfies Message)
+      );
+    }
+  }
+}
+```
+
+### Presence Tracking
+
+Track who's online using per-connection state. This pattern is clean because connection state is automatically cleaned up when users disconnect:
+
+```typescript
+type UserState = {
+  name: string;
+  joinedAt: number;
+  lastSeen: number;
+};
+
+export class PresenceAgent extends Agent {
+  onConnect(connection: Connection<UserState>, ctx: ConnectionContext) {
+    const url = new URL(ctx.request.url);
+    const name = url.searchParams.get("name") || "Anonymous";
+
+    // Store user data on the connection itself
+    connection.setState({
+      name,
+      joinedAt: Date.now(),
+      lastSeen: Date.now()
+    });
+
+    // Send current presence to new user
+    connection.send(
+      JSON.stringify({
+        type: "presence",
+        users: this.getPresence()
+      })
+    );
+
+    // Notify others that someone joined
+    this.broadcastPresence();
+  }
+
+  onClose(connection: Connection) {
+    // No manual cleanup needed - connection state is automatically gone
+    // Just broadcast updated presence to remaining users
+    this.broadcastPresence();
+  }
+
+  // Heartbeat to update lastSeen
+  onMessage(connection: Connection<UserState>, message: WSMessage) {
+    if (message === "ping") {
+      connection.setState((prev) => ({
+        ...prev!,
+        lastSeen: Date.now()
+      }));
+      connection.send("pong");
+    }
+  }
+
+  // Build presence from all connections
+  private getPresence() {
+    const users: Record<string, { name: string; lastSeen: number }> = {};
+    for (const conn of this.getConnections<UserState>()) {
+      if (conn.state) {
+        users[conn.id] = {
+          name: conn.state.name,
+          lastSeen: conn.state.lastSeen
+        };
+      }
+    }
+    return users;
+  }
+
+  private broadcastPresence() {
+    this.broadcast(
+      JSON.stringify({
+        type: "presence",
+        users: this.getPresence()
+      })
+    );
+  }
+}
+```
+
+## API Reference
+
+### Agent Lifecycle Methods
+
+| Method                       | Signature                                                       | Description                                            |
+| ---------------------------- | --------------------------------------------------------------- | ------------------------------------------------------ |
+| `onStart`                    | `(props?) => void \| Promise<void>`                             | Called once when agent starts                          |
+| `onRequest`                  | `(request: Request) => Response \| Promise<Response>`           | Handle HTTP requests                                   |
+| `onConnect`                  | `(connection, ctx) => void \| Promise<void>`                    | WebSocket connected                                    |
+| `onMessage`                  | `(connection, message) => void \| Promise<void>`                | Message received                                       |
+| `onClose`                    | `(connection, code, reason, wasClean) => void \| Promise<void>` | Connection closed                                      |
+| `onError`                    | `(connection, error) => void \| Promise<void>`                  | WebSocket error                                        |
+| `onError`                    | `(error) => void \| Promise<void>`                              | Server error (overload)                                |
+| `shouldSendProtocolMessages` | `(connection, ctx) => boolean`                                  | Control per-connection protocol frames (default: true) |
+
+### Connection Management Methods
+
+| Method                        | Signature                                 | Description                                    |
+| ----------------------------- | ----------------------------------------- | ---------------------------------------------- |
+| `getConnections`              | `(tag?: string) => Iterable<Connection>`  | Get all connections, optionally by tag         |
+| `getConnection`               | `(id: string) => Connection \| undefined` | Get connection by ID                           |
+| `getConnectionTags`           | `(connection, ctx) => string[]`           | Override to tag connections                    |
+| `broadcast`                   | `(message, without?: string[]) => void`   | Send to all connections                        |
+| `isConnectionProtocolEnabled` | `(connection) => boolean`                 | Check if connection receives protocol messages |
+
+### Connection Object
+
+| Property/Method | Type                                       | Description                      |
+| --------------- | ------------------------------------------ | -------------------------------- |
+| `id`            | `string`                                   | Unique connection identifier     |
+| `server`        | `string`                                   | Agent instance name              |
+| `state`         | `T \| null`                                | Per-connection state (read-only) |
+| `setState`      | `(state \| (prev) => state) => void`       | Update connection state          |
+| `send`          | `(message: string \| ArrayBuffer) => void` | Send message                     |
+| `close`         | `(code?, reason?) => void`                 | Close connection                 |
+
+### Agent Properties
+
+| Property     | Type                 | Description                         |
+| ------------ | -------------------- | ----------------------------------- |
+| `this.name`  | `string`             | Agent instance name                 |
+| `this.state` | `State`              | Agent state (use with `setState()`) |
+| `this.env`   | `Env`                | Environment bindings                |
+| `this.ctx`   | `DurableObjectState` | Durable Object context              |