feat(agents): WebSockets speaks the Agent protocol for plain hosts; Cap'n Web transport as a socket class

.changeset/capnweb-transport.md

@@ -0,0 +1,22 @@
+---
+"agents": minor
+---
+
+Add a Cap'n Web connection transport to the WebSockets capability.
+
+A connection can opt into a second wire (`?__agents_transport=capnweb`):
+the same frames travel over a single Cap'n Web RPC session whose root
+carries exactly one method — the message pipe. The capability's
+handlers are transport-agnostic: both kinds of connection dispatch the
+same `onConnect`/`onMessage`/`onClose`, appear in `getConnections()`,
+and propagate `connection.close(code, reason)` to the client.
+
+Because `Agent` rides the capability, `useAgent({ transport: "capnweb" })`
+works against any Agent with the hook surface unchanged — identity,
+state sync, `call`/`stub` RPC frames, and chat all flow over the pipe,
+with reconnection and terminal-close semantics matching the PartySocket
+path. The pipe client is internal to the hook — there is no new public
+client surface.
+
+Cap'n Web transport connections are non-hibernating: the Durable Object
+stays pinned in memory while one is open.

.changeset/websockets-capability.md

@@ -0,0 +1,47 @@
+---
+"agents": minor
+---
+
+Move WebSockets out of Lifecycle into the opt-in `WebSockets`
+capability, with callables served from an `RpcTarget`.
+
+Lifecycle no longer models WebSockets — many hosts never use sockets.
+Hosts that want connections install the capability, which owns the
+subsystem end to end:
+
+```ts
+new WebSockets({
+  handlers: { onConnect, onMessage, onClose },
+  callables: new RoomCallables()
+});
+```
+
+The capability claims WebSocket upgrades, accepts hibernating sockets,
+dispatches handlers inside the host invocation boundary, reciprocates
+close handshakes, closes owned connections on host destruction, and
+answers `getConnections()`/`getConnection()`. Without it installed,
+upgrades are declined.
+
+`callables` exposes an `RpcTarget`'s prototype methods to remote
+callers over a Cap'n Web session (`?__agents_rpc=capnweb`), with native
+`ReadableStream` streaming. `Agent` adds no new surface for this: its
+`@callable()`-decorated methods are its interface, served on every wire
+— natively over the legacy JSON RPC protocol and, through the
+decorator-derived target, over the Cap'n Web endpoint. There is no
+separate browser client either: `useAgent().stub`/`call` reach the
+same interface, and a plain host's endpoint is one
+`newWebSocketRpcSession(new WebSocket(callablesRpcUrl(url)))` away.
+
+`Agent` installs the capability itself, so its `onConnect`/`onMessage`/
+`onClose`/`onError`/`getConnectionTags` overrides and connection APIs
+behave exactly as before (same wire, same hibernation attachment
+format). The Lifecycle host contract drops the WebSocket hooks and
+Lifecycle's `getConnections`/`getConnection`/`broadcast` are removed.
+
+Lifecycle keeps only generic platform pass-throughs —
+`onWebSocketUpgrade` plus `onWebSocketMessage`/`Close`/`Error` for
+capability-owned hibernation wakes — and `LifecycleServices` gains a
+narrow `sockets` surface (accept/get) and a connection/request scope on
+`runInHostContext`. The capability interaction contract (three
+channels: hooks, services, composition-root apertures) is now
+documented on `DurableObjectCapability`.

docs/agents/lifecycle.md

@@ -65,9 +65,10 @@ export default {
 The default URL shape is `/agents/:binding/:name`. Direct
 `env.MY_OBJECT.getByName(name).fetch(request)` calls work as well.
 
-`Agent` already constructs this lifecycle. Existing Agent classes continue to
-override `onStart`, `onRequest`, `onConnect`, `onMessage`, `onClose`, and
-`onError` normally.
+`Agent` already constructs this lifecycle (and installs the `WebSockets`
+capability for its connections). Existing Agent classes continue to override
+`onStart`, `onRequest`, `onConnect`, `onMessage`, `onClose`, and `onError`
+normally.
 
 ## Request call path
 
@@ -267,33 +268,54 @@ Host context values follow the invocation:
 
 - `onStart` and `onAlarm`: object;
 - `onRequest`: object and request;
-- `onConnect`: object, connection, and upgrade request;
-- `onMessage`, `onClose`, and `onError`: object and connection.
+- `WebSockets` capability handlers `onConnect`: object, connection, and
+  upgrade request;
+- `WebSockets` capability handlers `onMessage`, `onClose`, and `onError`:
+  object and connection.
 
 `getConnectionTags(connection, { request })` remains argument-driven because it
 already receives both values explicitly. The root `agents` package continues
 to export `getCurrentAgent()` for the `Agent` class as a compatibility alias.
 
-## WebSockets always hibernate
+## WebSockets are an opt-in capability
 
-The lifecycle always uses Cloudflare's WebSocket Hibernation API. Idle clients
-remain connected while the Durable Object can leave memory. When a message
-wakes the object, its constructor and lifecycle startup run again before
-`onMessage`.
-
-State needed after a wake must be stored durably or through connection state:
+Lifecycle itself does not model WebSockets. Hosts that want connections
+install the `WebSockets` capability, which owns the subsystem end to end —
+it claims upgrades, accepts hibernating sockets, dispatches handlers inside
+the host invocation boundary, and answers `getConnections()`:
 
 ```ts
-onConnect(connection: Connection): void {
-  connection.setState({ authenticated: true });
-}
+import { WebSockets } from "agents/websockets";
 
-onMessage(connection: Connection<{ authenticated: boolean }>): void {
-  console.log(connection.state?.authenticated);
+export class MyObject extends DurableObject<Env> {
+  readonly webSockets = new WebSockets({
+    handlers: {
+      onConnect: (connection) => {
+        connection.setState({ authenticated: true });
+      },
+      onMessage: (connection, message) => {
+        connection.send(`echo:${message}`);
+      }
+    }
+  });
+  readonly lifecycle = Lifecycle.install(this).use(this.webSockets);
 }
 ```
 
-There is no non-hibernating mode.
+Without the capability installed, WebSocket upgrades are declined.
+
+The capability can also serve remote methods: pass an `RpcTarget` as
+`callables` and its prototype methods become the complete remote interface,
+served over a Cap'n Web session (`?__agents_rpc=capnweb`). An `Agent` adds
+no new surface for this — its `@callable()`-decorated methods are its
+interface, served on every wire: natively over the legacy JSON RPC protocol
+and, through the decorator-derived target, over the Cap'n Web endpoint.
+
+Connections use Cloudflare's WebSocket Hibernation API. Idle clients remain
+connected while the Durable Object can leave memory; when a message wakes the
+object, its constructor and lifecycle startup run again before `onMessage`.
+State needed after a wake must be stored durably or through
+`connection.setState()`. There is no non-hibernating mode.
 
 ## Native RPC
 

examples/next/lifecycle/README.md

@@ -8,7 +8,18 @@ base class.
 export class DoAgent extends DurableObject<Env> {
   private readonly activity = new ActivityCapability(this.ctx.storage);
   private wake: { id: string; startedAt: string } | undefined;
-  readonly lifecycle = Lifecycle.install(this).use(this.activity);
+
+  // WebSockets are opt-in: connections live in the WebSockets capability.
+  private readonly webSockets = new WebSockets({
+    handlers: {
+      onConnect: (connection) => connection.send("connected"),
+      onMessage: (connection, message) => connection.send(`echo:${message}`)
+    }
+  });
+
+  readonly lifecycle = Lifecycle.install(this)
+    .use(this.activity)
+    .use(this.webSockets);
 
   onStart() {
     // Runs once whenever this Durable Object enters memory, including after a
@@ -55,10 +66,12 @@ curl http://localhost:8787/agents/do-agent/demo
 curl http://localhost:8787/agents/do-agent/demo/stats
 ```
 
-Connect a WebSocket to `ws://localhost:8787/agents/do-agent/demo`. The object
-sends a connection snapshot and echoes each message. The socket uses Cloudflare's
-WebSocket Hibernation API, so it remains connected while the Durable Object can
-leave memory.
+Connect a WebSocket to `ws://localhost:8787/agents/do-agent/demo`. The
+`WebSockets` capability claims the upgrade, sends a connection snapshot, and
+echoes each message. The socket uses Cloudflare's WebSocket Hibernation API, so
+it remains connected while the Durable Object can leave memory. Lifecycle itself
+does not model WebSockets — without the capability installed, upgrades are
+declined.
 
 Each normal HTTP request schedules an alarm five seconds later. The capability
 records the alarm before the object's `onAlarm` callback runs.

examples/next/lifecycle/src/index.ts

@@ -1,12 +1,11 @@
-import { DurableObject } from "cloudflare:workers";
+import { DurableObject, RpcTarget } from "cloudflare:workers";
 import { routeAgentRequest } from "agents";
 import {
   Lifecycle,
   type CapabilityRequestContext,
-  type Connection,
-  type DurableObjectCapability,
-  type WSMessage
+  type DurableObjectCapability
 } from "agents/lifecycle";
+import { WebSockets } from "agents/websockets";
 
 type Activity = {
   requests: number;
@@ -58,11 +57,51 @@ class ActivityCapability implements DurableObjectCapability {
   }
 }
 
+/**
+ * Remote methods served over the Cap'n Web callables endpoint
+ * (`?__agents_rpc=capnweb`). The target's prototype methods are the
+ * complete remote interface.
+ */
+class ActivityCallables extends RpcTarget {
+  constructor(private readonly host: DoAgent) {
+    super();
+  }
+
+  activity(): Promise<Activity> {
+    return this.host.getActivity();
+  }
+}
+
 /** A plain Durable Object composed with the Agents lifecycle. */
 export class DoAgent extends DurableObject<Env> {
   private readonly activity = new ActivityCapability(this.ctx.storage);
   private wake: Wake | undefined;
-  readonly lifecycle = Lifecycle.install(this).use(this.activity);
+
+  // WebSockets are opt-in: Lifecycle itself does not model connections.
+  // The capability owns upgrades, hibernating sockets, handler
+  // dispatch, and the Cap'n Web callables endpoint.
+  private readonly webSockets = new WebSockets({
+    callables: new ActivityCallables(this),
+    handlers: {
+      onConnect: (connection) => {
+        connection.send(
+          JSON.stringify({
+            type: "connected",
+            name: this.lifecycle.name,
+            wake: this.wake,
+            activity: this.activity.getActivity()
+          })
+        );
+      },
+      onMessage: (connection, message) => {
+        connection.send(`echo:${String(message)}`);
+      }
+    }
+  });
+
+  readonly lifecycle = Lifecycle.install(this)
+    .use(this.activity)
+    .use(this.webSockets);
 
   onStart(): void {
     this.wake = {
@@ -86,21 +125,6 @@ export class DoAgent extends DurableObject<Env> {
     console.log("alarm", this.lifecycle.name, this.activity.getActivity());
   }
 
-  onConnect(connection: Connection): void {
-    connection.send(
-      JSON.stringify({
-        type: "connected",
-        name: this.lifecycle.name,
-        wake: this.wake,
-        activity: this.activity.getActivity()
-      })
-    );
-  }
-
-  onMessage(connection: Connection, message: WSMessage): void {
-    connection.send(`echo:${String(message)}`);
-  }
-
   async getActivity(): Promise<Activity> {
     await this.lifecycle.start();
     return this.activity.getActivity();

packages/agents/package.json

@@ -24,6 +24,7 @@
     "@babel/plugin-proposal-decorators": "^8.0.2",
     "@cfworker/json-schema": "^4.1.1",
     "@rolldown/plugin-babel": "^0.2.3",
+    "capnweb": "^0.12.0",
     "cron-schedule": "^6.0.0",
     "esbuild": "^0.28.1",
     "mimetext": "^3.0.28",
@@ -167,6 +168,11 @@
       "import": "./dist/react.js",
       "require": "./dist/react.js"
     },
+    "./websockets": {
+      "types": "./dist/websockets/index.d.ts",
+      "import": "./dist/websockets/index.js",
+      "require": "./dist/websockets/index.js"
+    },
     "./schedule": {
       "types": "./dist/schedule.d.ts",
       "import": "./dist/schedule.js",

packages/agents/scripts/build.ts

@@ -23,6 +23,7 @@ const entries = [
   "src/observability/ai/index.ts",
   "src/schedules/index.ts",
   "src/schedules/parser.ts",
+  "src/websockets/index.ts",
   "src/codemode/ai.ts",
   "src/experimental/memory/session/index.ts",
   "src/experimental/memory/utils/index.ts",