agents 0.16.2 → 0.17.1

package/docs/chat-sdk.md

@@ -0,0 +1,181 @@
+# Chat SDK state
+
+Use `agents/chat-sdk` when you run the [Chat SDK](https://chat-sdk.dev/) inside an Agent and want the Chat SDK `StateAdapter` to use Agents sub-agents for durable state.
+
+The adapter stores Chat SDK subscriptions, locks, queues, dedupe keys, thread state, channel state, callback metadata, transcript lists, and thread history in Durable Object SQLite. Each state shard is a `ChatSdkStateAgent` sub-agent under your ingress Agent.
+
+## Install
+
+Install both packages in the Worker that hosts your messenger ingress:
+
+```bash
+npm install agents chat
+```
+
+`agents/chat-sdk` itself does not provide a messenger adapter. Use it with any Chat SDK adapter, such as Telegram, Slack, Discord, Teams, or Google Chat.
+
+## Basic setup
+
+Create a parent Agent that owns your Chat SDK runtime. Pass `createChatSdkState()` as the Chat SDK `state` option.
+
+```typescript
+import { Agent } from "agents";
+import { Chat } from "chat";
+import { createChatSdkState } from "agents/chat-sdk";
+import { createTelegramAdapter } from "@chat-adapter/telegram";
+
+export { ChatSdkStateAgent } from "agents/chat-sdk";
+
+export class MessengerAgent extends Agent<Env> {
+  private chat!: Chat;
+
+  onStart() {
+    const telegram = createTelegramAdapter({
+      botToken: this.env.TELEGRAM_BOT_TOKEN,
+      mode: "webhook",
+      secretToken: this.env.TELEGRAM_WEBHOOK_SECRET_TOKEN,
+      userName: "my_bot"
+    });
+
+    this.chat = new Chat({
+      adapters: { telegram },
+      userName: "my_bot",
+      state: createChatSdkState(),
+      concurrency: { strategy: "burst", debounceMs: 600 }
+    });
+  }
+}
+```
+
+Add the parent Agent to your Durable Object migration:
+
+```jsonc
+{
+  "durable_objects": {
+    "bindings": [{ "name": "MessengerAgent", "class_name": "MessengerAgent" }]
+  },
+  "migrations": [
+    {
+      "tag": "v1",
+      "new_sqlite_classes": ["MessengerAgent"]
+    }
+  ]
+}
+```
+
+Export `ChatSdkStateAgent` from your Worker entry point so sub-agent routing can resolve it. When `createChatSdkState()` is called inside an Agent lifecycle method, it uses the current Agent as the parent and creates state shards with `this.subAgent()`.
+
+## State sharding
+
+By default, Chat SDK state is sharded by the first two colon-separated segments of a thread-like key.
+
+For example, `telegram:-100123:456` and `telegram:-100123:789` share the same state shard, `telegram:-100123`.
+
+The default key sharder recognizes these Chat SDK key prefixes:
+
+- `thread-state:`
+- `channel-state:`
+- `msg-history:`
+- `transcripts:user:`
+
+Unknown keys use the adapter's default shard name, `default`.
+
+## Custom sharding
+
+Use `shardKey` to control how thread IDs map to state sub-agent names:
+
+```typescript
+const state = createChatSdkState({
+  shardKey(threadId) {
+    return threadId.split(":").slice(0, 2).join(":");
+  }
+});
+```
+
+Use `keyShard` when an adapter stores non-thread-shaped keys that should still route to a provider-specific shard:
+
+```typescript
+const state = createChatSdkState({
+  keyShard(key) {
+    if (!key.startsWith("dedupe:telegram:")) {
+      return undefined;
+    }
+
+    const chatId = key.slice("dedupe:telegram:".length).split(":")[0];
+    return chatId ? `telegram:${chatId}` : undefined;
+  }
+});
+```
+
+Returning `undefined` falls back to the built-in key sharder and then to the default shard.
+
+## API
+
+### `createChatSdkState(options)`
+
+Creates a Chat SDK `StateAdapter` backed by a `ChatSdkStateAgent` sub-agent.
+
+```typescript
+import { createChatSdkState } from "agents/chat-sdk";
+
+export { ChatSdkStateAgent } from "agents/chat-sdk";
+
+const state = createChatSdkState({
+  // parent: this // optional, defaults to the current Agent from `getCurrentAgent()`
+});
+```
+
+Options:
+
+- `agent`: Optional custom subclass of `ChatSdkStateAgent`. Defaults to `ChatSdkStateAgent`.
+- `parent`: Optional parent Agent that will call `subAgent()` to create state shards. Defaults to the current Agent from `getCurrentAgent()` when called inside an Agent lifecycle method or request handler.
+- `name`: Default shard name for keys that cannot be mapped. Defaults to `default`.
+- `shardKey(threadId)`: Maps Chat SDK thread IDs and lock keys to a shard name.
+- `keyShard(key)`: Maps generic Chat SDK cache/list keys to a shard name.
+
+### `ChatSdkStateAgent`
+
+The sub-agent class that stores state in SQLite. Export it from your Worker entry point so the runtime can create it.
+
+```typescript
+export { ChatSdkStateAgent } from "agents/chat-sdk";
+```
+
+### `ChatSdkStateAdapter`
+
+The concrete `StateAdapter` implementation returned by `createChatSdkState()`. Most applications do not need to instantiate it directly.
+
+## What is stored
+
+The adapter implements the full Chat SDK `StateAdapter` interface:
+
+- Subscriptions for `thread.subscribe()` and `thread.unsubscribe()`.
+- Locks for per-thread or per-channel concurrency.
+- Pending message queues for `queue`, `debounce`, and `burst` concurrency strategies.
+- Generic key-value cache entries with optional TTL.
+- Append-only lists with max-length trimming and list-level TTL refresh.
+
+Chat SDK features built on these primitives include:
+
+- Message deduplication.
+- Thread and channel state.
+- Persistent thread history for adapters that opt in to `persistThreadHistory`.
+- Callback URL token storage.
+- Modal context storage.
+- Cross-platform transcripts.
+
+## Cleanup behavior
+
+TTL reads are strict: expired locks, cache values, queue entries, and list entries are ignored or deleted before they are returned.
+
+Physical cleanup is lazy. `ChatSdkStateAgent` schedules one cleanup callback for the earliest known expiry and reschedules after cleanup runs. This keeps idle shards quiet while preventing expired rows from accumulating indefinitely.
+
+## Example
+
+See `examples/chat-sdk-messenger` for a complete Telegram bot that uses:
+
+- `createChatSdkState()` for Chat SDK state.
+- `ThinkMessengerStateAgent`, a Think-specific wrapper around
+  `ChatSdkStateAgent`, as a sub-agent.
+- Chat SDK burst/debounce concurrency.
+- Think-backed AI replies running in managed fibers.

package/docs/client-sdk.md

@@ -0,0 +1,520 @@
+# Client SDK
+
+Connect to agents from any JavaScript runtime — browsers, Node.js, Deno, Bun, or edge functions — using WebSockets or HTTP. The SDK provides real-time state synchronization, RPC method calls, and streaming responses.
+
+## Overview
+
+The client SDK offers two ways to connect with a websocket connection, and one way to make HTTP requests.
+
+| Client        | Use Case                                                    |
+| ------------- | ----------------------------------------------------------- |
+| `useAgent`    | React hook with automatic reconnection and state management |
+| `AgentClient` | Vanilla JavaScript/TypeScript class for any environment     |
+| `agentFetch`  | HTTP requests when WebSocket isn't needed                   |
+
+All clients provide:
+
+- **Bidirectional state sync** - Push and receive state updates in real-time
+- **RPC calls** - Call agent methods with typed arguments and return values
+- **Streaming** - Handle chunked responses for AI completions
+- **Auto-reconnection** - Built on [PartySocket](https://docs.partykit.io/reference/partysocket-api/) for reliable connections
+
+## Quick Start
+
+### React
+
+```tsx
+import { useAgent } from "agents/react";
+
+function Chat() {
+  const agent = useAgent({
+    agent: "ChatAgent",
+    name: "room-123"
+  });
+
+  const sendMessage = async () => {
+    const response = await agent.call("sendMessage", ["Hello!"]);
+    console.log("Response:", response);
+  };
+
+  return (
+    <div>
+      <p>Messages: {agent.state?.messageCount ?? 0}</p>
+      <button onClick={sendMessage}>Send</button>
+    </div>
+  );
+}
+```
+
+### Vanilla JavaScript
+
+```typescript
+import { AgentClient } from "agents/client";
+
+const client = new AgentClient({
+  agent: "ChatAgent",
+  name: "room-123",
+  host: "your-worker.your-subdomain.workers.dev"
+});
+
+await client.ready;
+
+// Read state directly
+console.log("Current state:", client.state);
+
+// Call a method
+const response = await client.call("sendMessage", ["Hello!"]);
+```
+
+## Connecting to Agents
+
+### Agent Naming
+
+The `agent` parameter is your agent class name. It's automatically converted from camelCase to kebab-case for the URL:
+
+```typescript
+// These are equivalent:
+useAgent({ agent: "ChatAgent" }); // → /agents/chat-agent/...
+useAgent({ agent: "MyCustomAgent" }); // → /agents/my-custom-agent/...
+useAgent({ agent: "LOUD_AGENT" }); // → /agents/loud-agent/...
+```
+
+### Instance Names
+
+The `name` parameter identifies a specific agent instance. If omitted, defaults to `"default"`:
+
+```typescript
+// Connect to a specific chat room
+useAgent({ agent: "ChatAgent", name: "room-123" });
+
+// Connect to a user's personal agent
+useAgent({ agent: "UserAgent", name: userId });
+
+// Uses "default" instance
+useAgent({ agent: "ChatAgent" });
+```
+
+### Connection Options
+
+Both `useAgent` and `AgentClient` accept PartySocket options:
+
+```typescript
+useAgent({
+  agent: "ChatAgent",
+  name: "room-123",
+
+  // Connection settings
+  host: "my-worker.workers.dev", // Custom host (defaults to current origin)
+  path: "/custom/path", // Custom path prefix
+
+  // Query parameters (sent on connection)
+  query: {
+    token: "abc123",
+    version: "2"
+  },
+
+  // Event handlers
+  onOpen: () => console.log("Connected"),
+  onClose: () => console.log("Disconnected"),
+  onError: (error) => console.error("Error:", error)
+});
+```
+
+### Async Query Parameters
+
+For authentication tokens or other async data, pass a function that returns a Promise:
+
+```typescript
+useAgent({
+  agent: "ChatAgent",
+  name: "room-123",
+
+  // Async query - called before connecting
+  query: async () => {
+    const token = await getAuthToken();
+    return { token };
+  },
+
+  // Dependencies that trigger re-fetching the query
+  queryDeps: [userId],
+
+  // Cache TTL for the query result (default: 5 minutes)
+  cacheTtl: 60 * 1000 // 1 minute
+});
+```
+
+The query function is cached and only re-called when:
+
+- `queryDeps` change
+- `cacheTtl` expires
+- The component remounts
+
+## State Synchronization
+
+Agents can maintain state that syncs bidirectionally with all connected clients. Both `useAgent` and `AgentClient` expose a `state` property that tracks the current agent state.
+
+### Reading State
+
+```tsx
+const agent = useAgent({
+  agent: "GameAgent",
+  name: "game-123"
+});
+
+// Read state directly — reactive in React (re-renders on change)
+return <div>Score: {agent.state?.score}</div>;
+```
+
+`agent.state` starts as `undefined` and is populated when the server sends state on connect (from the agent's `initialState`). Use optional chaining for safe access.
+
+### Pushing State Updates
+
+```typescript
+// Update the agent's state from the client
+agent.setState({ score: 100, level: 5 });
+
+// Spread existing state for partial updates
+agent.setState({ ...agent.state, score: agent.state.score + 10 });
+```
+
+When you call `setState()`:
+
+1. The state is sent to the agent over WebSocket
+2. The agent's `onStateChanged()` method is called
+3. The agent broadcasts the new state to all connected clients
+4. `agent.state` updates on the next render (React) or immediately (`AgentClient`)
+
+### Listening for State Changes
+
+For side effects when state changes, use the `onStateUpdate` callback:
+
+```typescript
+const agent = useAgent({
+  agent: "GameAgent",
+  name: "game-123",
+  onStateUpdate: (state, source) => {
+    // source: "server" (agent pushed) or "client" (you pushed)
+    console.log(`State updated from ${source}:`, state);
+  }
+});
+```
+
+> For most use cases, reading `agent.state` directly is simpler than tracking state manually with `onStateUpdate`. Use `onStateUpdate` when you need to trigger side effects on state changes.
+
+### State Flow
+
+```
+┌─────────┐                      ┌─────────┐
+│ Client  │ ── setState() ────▶  │  Agent  │
+│         │                      │         │
+│ .state  │ ◀── state update ── │         │
+└─────────┘      (broadcast)     └─────────┘
+```
+
+## Calling Agent Methods (RPC)
+
+Call methods on your agent that are decorated with `@callable()`.
+
+> **Note:** The `@callable()` decorator is only required for methods called from external runtimes (browsers, other services). When calling from within the same Worker, you can use standard [Durable Object RPC](https://developers.cloudflare.com/durable-objects/best-practices/create-durable-object-stubs-and-send-requests/#invoke-rpc-methods) directly on the stub without the decorator.
+
+### Using call()
+
+```typescript
+// Basic call
+const result = await agent.call("getUser", [userId]);
+
+// Call with multiple arguments
+const result = await agent.call("createPost", [title, content, tags]);
+
+// Call with no arguments
+const result = await agent.call("getStats");
+```
+
+### Using the Stub Proxy
+
+The `stub` property provides a cleaner syntax for method calls:
+
+```typescript
+// Instead of:
+const user = await agent.call("getUser", ["user-123"]);
+
+// You can write:
+const user = await agent.stub.getUser("user-123");
+
+// Multiple arguments work naturally:
+const post = await agent.stub.createPost(title, content, tags);
+```
+
+### TypeScript Integration
+
+For full type safety, pass your Agent class as a type parameter:
+
+```typescript
+import type { MyAgent } from "./agents/my-agent";
+
+const agent = useAgent<MyAgent, MyAgentState>({
+  agent: "MyAgent",
+  name: "instance-1"
+});
+
+// Now stub methods are fully typed!
+const result = await agent.stub.processData({ input: "test" });
+//    ^? Awaited<ReturnType<MyAgent["processData"]>>
+```
+
+### Streaming Responses
+
+For methods that return `StreamingResponse`, handle chunks as they arrive:
+
+```typescript
+// Agent-side:
+@callable()
+async generateText(prompt: string) {
+  return new StreamingResponse(async (stream) => {
+    for await (const chunk of llm.stream(prompt)) {
+      await stream.write(chunk);
+    }
+  });
+}
+
+// Client-side:
+await agent.call("generateText", [prompt], {
+  onChunk: (chunk) => {
+    // Called for each chunk
+    appendToOutput(chunk);
+  },
+  onDone: (finalResult) => {
+    // Called when stream completes
+    console.log("Complete:", finalResult);
+  },
+  onError: (error) => {
+    // Called if streaming fails
+    console.error("Stream error:", error);
+  }
+});
+```
+
+## HTTP Requests with agentFetch
+
+For one-off requests without maintaining a WebSocket connection:
+
+```typescript
+import { agentFetch } from "agents/client";
+
+// GET request
+const response = await agentFetch({
+  agent: "DataAgent",
+  name: "instance-1",
+  host: "my-worker.workers.dev"
+});
+
+const data = await response.json();
+
+// POST request with body
+const response = await agentFetch(
+  {
+    agent: "DataAgent",
+    name: "instance-1",
+    host: "my-worker.workers.dev"
+  },
+  {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ action: "process" })
+  }
+);
+```
+
+**When to use `agentFetch` vs WebSocket:**
+
+| Use `agentFetch`                | Use `useAgent`/`AgentClient` |
+| ------------------------------- | ---------------------------- |
+| One-time requests               | Real-time updates needed     |
+| Server-to-server calls          | Bidirectional communication  |
+| Simple REST-style API           | State synchronization        |
+| No persistent connection needed | Multiple RPC calls           |
+
+## React Hook Reference
+
+### UseAgentOptions
+
+```typescript
+type UseAgentOptions<State> = {
+  // Required
+  agent: string; // Agent class name
+
+  // Optional
+  name?: string; // Instance name (default: "default")
+  host?: string; // Custom host
+  path?: string; // Custom path prefix
+
+  // Query parameters
+  query?:
+    | Record<string, string | null>
+    | (() => Promise<Record<string, string | null>>);
+  queryDeps?: unknown[]; // Dependencies for async query
+  cacheTtl?: number; // Query cache TTL in ms (default: 5 min)
+
+  // Callbacks
+  onStateUpdate?: (state: State, source: "server" | "client") => void;
+  onMcpUpdate?: (mcpServers: MCPServersState) => void;
+  onOpen?: () => void;
+  onClose?: () => void;
+  onError?: (error: Event) => void;
+  onMessage?: (message: MessageEvent) => void;
+};
+```
+
+### Return Value
+
+```typescript
+const agent = useAgent(options);
+
+agent.state;           // State | undefined - Current agent state (reactive)
+agent.agent;           // string - Kebab-case agent name
+agent.name;            // string - Instance name
+agent.setState(state); // void - Push state to agent
+agent.call(method, args?, streamOptions?); // Promise<T> - Call agent method
+agent.stub;            // Proxy - Typed method calls
+agent.send(data);      // void - Send raw WebSocket message
+agent.close();         // void - Close connection
+agent.reconnect();     // void - Force reconnection
+```
+
+## Vanilla JS Reference
+
+### AgentClientOptions
+
+```typescript
+type AgentClientOptions<State> = {
+  // Required
+  agent: string; // Agent class name
+  host: string; // Worker host
+
+  // Optional
+  name?: string; // Instance name (default: "default")
+  path?: string; // Custom path prefix
+  query?: Record<string, string>;
+
+  // Callbacks
+  onStateUpdate?: (state: State, source: "server" | "client") => void;
+};
+```
+
+### AgentClient Methods
+
+```typescript
+const client = new AgentClient(options);
+
+client.state;           // State | undefined - Current agent state
+client.agent;           // string - Kebab-case agent name
+client.name;            // string - Instance name
+client.setState(state); // void - Push state to agent
+client.call(method, args?, streamOptions?); // Promise<T> - Call agent method
+client.send(data);      // void - Send raw WebSocket message
+client.close();         // void - Close connection
+client.reconnect();     // void - Force reconnection
+
+// Event listeners (inherited from PartySocket)
+client.addEventListener("open", () => {});
+client.addEventListener("close", () => {});
+client.addEventListener("error", () => {});
+client.addEventListener("message", () => {});
+```
+
+## MCP Server Integration
+
+If your agent uses MCP (Model Context Protocol) servers, you can receive updates about their state:
+
+```typescript
+const agent = useAgent({
+  agent: "AssistantAgent",
+  name: "session-123",
+  onMcpUpdate: (mcpServers) => {
+    // mcpServers is a record of server states
+    for (const [serverId, server] of Object.entries(mcpServers)) {
+      console.log(`${serverId}: ${server.connectionState}`);
+      console.log(`Tools: ${server.tools?.map((t) => t.name).join(", ")}`);
+    }
+  }
+});
+```
+
+## Error Handling
+
+### Connection Errors
+
+```typescript
+const agent = useAgent({
+  agent: "MyAgent",
+  onError: (error) => {
+    console.error("WebSocket error:", error);
+  },
+  onClose: () => {
+    console.log("Connection closed, will auto-reconnect...");
+  }
+});
+```
+
+### RPC Errors
+
+```typescript
+try {
+  const result = await agent.call("riskyMethod", [data]);
+} catch (error) {
+  // Error thrown by the agent method
+  console.error("RPC failed:", error.message);
+}
+```
+
+### Streaming Errors
+
+```typescript
+await agent.call("streamingMethod", [data], {
+  onChunk: (chunk) => handleChunk(chunk),
+  onError: (errorMessage) => {
+    // Stream-specific error handling
+    console.error("Stream error:", errorMessage);
+  }
+});
+```
+
+## Best Practices
+
+### 1. Use Typed Stubs
+
+```typescript
+// Prefer this:
+const user = await agent.stub.getUser(id);
+
+// Over this:
+const user = await agent.call("getUser", [id]);
+```
+
+### 2. Reconnection is Automatic
+
+The client auto-reconnects and the agent automatically sends the current state on each connection. `agent.state` is updated automatically — no manual re-sync needed.
+
+### 3. Optimize Query Caching
+
+```typescript
+// For auth tokens that expire hourly:
+useAgent({
+  query: async () => ({ token: await getToken() }),
+  cacheTtl: 55 * 60 * 1000, // Refresh 5 min before expiry
+  queryDeps: [userId] // Refresh if user changes
+});
+```
+
+### 4. Clean Up Connections
+
+In vanilla JS, close connections when done:
+
+```typescript
+const client = new AgentClient({ agent: "MyAgent", host: "..." });
+
+// When done:
+client.close();
+```
+
+React's `useAgent` handles cleanup automatically on unmount.