agents 0.16.1 → 0.17.0

package/docs/observability.md

@@ -0,0 +1,261 @@
+# Observability
+
+Agents emit structured events for every significant operation — RPC calls, state changes, schedule execution, workflow transitions, MCP connections, and more. These events are published to [diagnostics channels](https://developers.cloudflare.com/workers/runtime-apis/nodejs/diagnostics-channel/) and are silent by default (zero overhead when nobody is listening).
+
+## Event structure
+
+Every event has these fields:
+
+```ts
+{
+  type: "rpc",                        // what happened
+  agent: "MyAgent",                   // which agent class emitted it
+  name: "user-123",                   // which agent instance (Durable Object name)
+  payload: { method: "getWeather" },  // details
+  timestamp: 1758005142787            // when (ms since epoch)
+}
+```
+
+`agent` and `name` identify the source agent — `agent` is the class name and `name` is the Durable Object instance name.
+
+## Channels
+
+Events are routed to named channels based on their type:
+
+| Channel             | Event types                                                                                                                                                              | Description                                                            |
+| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------- |
+| `agents:state`      | `state:update`                                                                                                                                                           | State sync events                                                      |
+| `agents:rpc`        | `rpc`, `rpc:error`                                                                                                                                                       | RPC method calls and failures                                          |
+| `agents:message`    | `message:request`, `message:response`, `message:clear`, `message:cancel`, `message:error`, `tool:result`, `tool:approval`                                                | Chat message and tool lifecycle                                        |
+| `agents:chat`       | `chat:request:failed`, `chat:recovery:*`, `chat:stream:stalled`, `chat:context:compacted`                                                                                | Chat request, recovery, stream-stall, and context-compaction lifecycle |
+| `agents:transcript` | `chat:transcript:repaired`                                                                                                                                               | Transcript repair events                                               |
+| `agents:fiber`      | `fiber:run:*`, `fiber:recovery:*`                                                                                                                                        | Durable fiber lifecycle                                                |
+| `agents:agent_tool` | `agent_tool:recovery:*`                                                                                                                                                  | Parent/child agent-tool recovery                                       |
+| `agents:schedule`   | `schedule:create`, `schedule:execute`, `schedule:cancel`, `schedule:retry`, `schedule:error`, `schedule:duplicate_warning`, `queue:create`, `queue:retry`, `queue:error` | Scheduled and queued task lifecycle                                    |
+| `agents:lifecycle`  | `connect`, `disconnect`, `destroy`                                                                                                                                       | Agent connection and teardown                                          |
+| `agents:workflow`   | `workflow:start`, `workflow:event`, `workflow:approved`, `workflow:rejected`, `workflow:terminated`, `workflow:paused`, `workflow:resumed`, `workflow:restarted`         | Workflow state transitions                                             |
+| `agents:mcp`        | `mcp:client:preconnect`, `mcp:client:connect`, `mcp:client:authorize`, `mcp:client:discover`, `mcp:client:close`                                                         | MCP client operations                                                  |
+| `agents:email`      | `email:receive`, `email:reply`                                                                                                                                           | Email processing                                                       |
+
+## Subscribing to events
+
+### Typed subscribe helper
+
+The `subscribe()` function from `agents/observability` provides type-safe access to events on a specific channel:
+
+```ts
+import { subscribe } from "agents/observability";
+
+const unsub = subscribe("rpc", (event) => {
+  if (event.type === "rpc") {
+    console.log(`RPC call: ${event.payload.method}`);
+  }
+  if (event.type === "rpc:error") {
+    console.error(
+      `RPC failed: ${event.payload.method} — ${event.payload.error}`
+    );
+  }
+});
+
+// Clean up when done
+unsub();
+```
+
+The callback is fully typed — `event` is narrowed to only the event types that flow through that channel.
+
+The typed helper uses camelCase keys, so agent-tool recovery is `subscribe("agentTool", ...)`. Raw diagnostics channel subscribers should use the emitted channel name, `agents:agent_tool`.
+
+### Raw diagnostics_channel
+
+You can also subscribe directly using the Node.js API:
+
+```ts
+import { subscribe } from "node:diagnostics_channel";
+
+subscribe("agents:schedule", (event) => {
+  console.log(event);
+});
+```
+
+## Tail Workers (production)
+
+In production, all diagnostics channel messages are automatically forwarded to [Tail Workers](https://developers.cloudflare.com/workers/observability/tail-workers/). No subscription code is needed in the agent itself — attach a Tail Worker and access events via `event.diagnosticsChannelEvents`:
+
+```ts
+export default {
+  async tail(events) {
+    for (const event of events) {
+      for (const msg of event.diagnosticsChannelEvents) {
+        // msg.channel is "agents:rpc", "agents:workflow", etc.
+        // msg.message is the typed event payload
+        console.log(msg.timestamp, msg.channel, msg.message);
+      }
+    }
+  }
+};
+```
+
+This gives you structured, filterable observability in production with zero overhead in the agent hot path.
+
+## Custom observability
+
+You can override the default implementation by providing your own `Observability` interface:
+
+```ts
+import { Agent } from "agents";
+import type { Observability } from "agents/observability";
+
+const myObservability: Observability = {
+  emit(event) {
+    // Send to your logging service, filter events, etc.
+    if (event.type === "rpc:error") {
+      myLogger.error(event.payload.method, event.payload.error);
+    }
+  }
+};
+
+class MyAgent extends Agent {
+  override observability = myObservability;
+}
+```
+
+Set `observability` to `undefined` to disable all event emission:
+
+```ts
+class MyAgent extends Agent {
+  override observability = undefined;
+}
+```
+
+## Event reference
+
+### RPC events
+
+| Type        | Payload                  | When                            |
+| ----------- | ------------------------ | ------------------------------- |
+| `rpc`       | `{ method, streaming? }` | A `@callable` method is invoked |
+| `rpc:error` | `{ method, error }`      | A `@callable` method throws     |
+
+### State events
+
+| Type           | Payload | When                   |
+| -------------- | ------- | ---------------------- |
+| `state:update` | `{}`    | `setState()` is called |
+
+### Message and tool events (`AIChatAgent`)
+
+These events are emitted by `AIChatAgent` from `@cloudflare/ai-chat`. They track the chat message lifecycle, including client-side tool interactions.
+
+| Type               | Payload                    | When                                |
+| ------------------ | -------------------------- | ----------------------------------- |
+| `message:request`  | `{}`                       | A chat message is received          |
+| `message:response` | `{}`                       | A chat response stream completes    |
+| `message:clear`    | `{}`                       | Chat history is cleared             |
+| `message:cancel`   | `{ requestId }`            | A streaming request is cancelled    |
+| `message:error`    | `{ error }`                | A chat stream fails                 |
+| `tool:result`      | `{ toolCallId, toolName }` | A client tool result is received    |
+| `tool:approval`    | `{ toolCallId, approved }` | A tool call is approved or rejected |
+
+### Chat recovery events
+
+| Type                      | Payload                                                                  | When                                                                                                                                                                                                                                                                                                                                      |
+| ------------------------- | ------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `chat:request:failed`     | `{ requestId?, stage, messagesPersisted?, error }`                       | A Think chat request fails while parsing, persisting, running, or streaming                                                                                                                                                                                                                                                               |
+| `chat:recovery:detected`  | `{ incidentId, requestId, attempt, maxAttempts, recoveryKind }`          | An interrupted chat fiber is first observed                                                                                                                                                                                                                                                                                               |
+| `chat:recovery:attempt`   | `{ incidentId, requestId, attempt, maxAttempts, recoveryKind }`          | The framework begins a recovery attempt                                                                                                                                                                                                                                                                                                   |
+| `chat:recovery:scheduled` | `{ incidentId, requestId, attempt, maxAttempts, recoveryKind }`          | A retry or continuation callback is scheduled                                                                                                                                                                                                                                                                                             |
+| `chat:recovery:completed` | `{ incidentId, requestId, attempt, maxAttempts, recoveryKind }`          | Recovery completed successfully                                                                                                                                                                                                                                                                                                           |
+| `chat:recovery:skipped`   | `{ incidentId, requestId, attempt, maxAttempts, recoveryKind, reason? }` | Recovery was skipped because the conversation changed or was no longer recoverable                                                                                                                                                                                                                                                        |
+| `chat:recovery:failed`    | `{ incidentId, requestId, attempt, maxAttempts, recoveryKind, reason? }` | Recovery ran but failed                                                                                                                                                                                                                                                                                                                   |
+| `chat:recovery:exhausted` | `{ incidentId, requestId, attempt, maxAttempts, recoveryKind, reason }`  | Recovery exceeded its configured attempt budget                                                                                                                                                                                                                                                                                           |
+| `chat:stream:stalled`     | `{ requestId, timeoutMs }`                                               | The inactivity watchdog fired — no stream chunk arrived within `chatStreamStallTimeoutMs`. With `chatRecovery` on (the default) the turn then routes into bounded recovery (look for `chat:recovery:*`); with recovery off it terminalizes. See [Think configuration](https://github.com/cloudflare/agents/blob/main/docs/think/index.md) |
+
+`recoveryKind` is `"retry"` when recovery replays an unanswered user turn and `"continue"` when it continues a partial assistant turn.
+
+### Chat context events
+
+| Type                     | Payload                                       | When                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| ------------------------ | --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `chat:context:compacted` | `{ reason, shortened, requestId?, attempt? }` | Think compacted the session to handle a context-window overflow. `reason` is `"proactive"` (the `contextOverflow.proactive` guard fired before a step) or `"reactive"` (`contextOverflow.reactive` fired after an overflow). `shortened` is whether compaction actually reduced history — `false` means a retry would overflow again. See [Context-window overflow recovery](https://github.com/cloudflare/agents/blob/main/docs/think/index.md#context-window-overflow-recovery). |
+
+### Transcript events
+
+| Type                       | Payload                                                            | When                                                                                                                                                                                                                                                                                                                                                                         |
+| -------------------------- | ------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `chat:transcript:repaired` | `{ requestId?, removedToolCalls, normalizedInputs, toolCallIds? }` | Think repairs a persisted transcript before sending it to the provider. `removedToolCalls` counts orphaned tool calls healed (preserved as errored results, not deleted); it also fires if an incomplete tool call survives repair and is dropped by the `ignoreIncompleteToolCalls` backstop. `normalizedInputs` counts stringified/missing tool inputs that were repaired. |
+
+### Fiber events
+
+| Type                      | Payload                                                                | When                                 |
+| ------------------------- | ---------------------------------------------------------------------- | ------------------------------------ |
+| `fiber:run:started`       | `{ fiberId, fiberName, managed? }`                                     | A durable fiber starts               |
+| `fiber:run:completed`     | `{ fiberId, fiberName, managed?, elapsedMs? }`                         | A durable fiber completes            |
+| `fiber:run:failed`        | `{ fiberId, fiberName, managed?, error, elapsedMs? }`                  | A durable fiber throws               |
+| `fiber:run:interrupted`   | `{ fiberId, fiberName, managed?, recoveryReason, elapsedMs? }`         | Startup finds an interrupted fiber   |
+| `fiber:recovery:detected` | `{ fiberId, fiberName, managed?, recoveryReason, elapsedMs? }`         | Recovery sees an interrupted fiber   |
+| `fiber:recovery:attempt`  | `{ fiberId, fiberName, managed?, recoveryReason }`                     | A recovery hook starts               |
+| `fiber:recovery:handled`  | `{ fiberId, fiberName, managed?, recoveryReason, status, elapsedMs? }` | Recovery handling completes          |
+| `fiber:recovery:skipped`  | `{ fiberId, fiberName, managed?, reason, elapsedMs? }`                 | A recovery scan skips remaining work |
+| `fiber:recovery:failed`   | `{ fiberId, fiberName, managed?, error, reason?, elapsedMs? }`         | A recovery hook fails                |
+
+### Agent-tool recovery events
+
+| Type                           | Payload                                             | When                                                         |
+| ------------------------------ | --------------------------------------------------- | ------------------------------------------------------------ |
+| `agent_tool:recovery:begin`    | `{ runCount, totalTimeoutMs? }`                     | Parent recovery starts scanning stale agent-tool runs        |
+| `agent_tool:recovery:row`      | `{ runId, agentType, status, reason?, elapsedMs? }` | One stale run is reconciled                                  |
+| `agent_tool:recovery:deadline` | `{ runId, agentType, elapsedMs? }`                  | Total recovery deadline is exhausted before inspecting a row |
+| `agent_tool:recovery:complete` | `{ runCount, elapsedMs? }`                          | Parent recovery finishes scanning rows                       |
+| `agent_tool:recovery:failed`   | `{ error }`                                         | Parent recovery fails unexpectedly                           |
+
+### Schedule and queue events
+
+| Type                         | Payload                                  | When                                         |
+| ---------------------------- | ---------------------------------------- | -------------------------------------------- |
+| `schedule:create`            | `{ callback, id }`                       | A schedule is created                        |
+| `schedule:execute`           | `{ callback, id }`                       | A scheduled callback starts                  |
+| `schedule:cancel`            | `{ callback, id }`                       | A schedule is cancelled                      |
+| `schedule:retry`             | `{ callback, id, attempt, maxAttempts }` | A scheduled callback is retried              |
+| `schedule:error`             | `{ callback, id, error, attempts }`      | A scheduled callback fails after all retries |
+| `schedule:duplicate_warning` | `{ callback, count, type }`              | Duplicate schedules detected for a callback  |
+| `queue:create`               | `{ callback, id }`                       | A task is enqueued                           |
+| `queue:retry`                | `{ callback, id, attempt, maxAttempts }` | A queued callback is retried                 |
+| `queue:error`                | `{ callback, id, error, attempts }`      | A queued callback fails after all retries    |
+
+### Lifecycle events
+
+| Type         | Payload                          | When                                  |
+| ------------ | -------------------------------- | ------------------------------------- |
+| `connect`    | `{ connectionId }`               | A WebSocket connection is established |
+| `disconnect` | `{ connectionId, code, reason }` | A WebSocket connection is closed      |
+| `destroy`    | `{}`                             | The agent is destroyed                |
+
+### Workflow events
+
+| Type                  | Payload                         | When                           |
+| --------------------- | ------------------------------- | ------------------------------ |
+| `workflow:start`      | `{ workflowId, workflowName? }` | A workflow instance is started |
+| `workflow:event`      | `{ workflowId, eventType? }`    | An event is sent to a workflow |
+| `workflow:approved`   | `{ workflowId, reason? }`       | A workflow is approved         |
+| `workflow:rejected`   | `{ workflowId, reason? }`       | A workflow is rejected         |
+| `workflow:terminated` | `{ workflowId, workflowName? }` | A workflow is terminated       |
+| `workflow:paused`     | `{ workflowId, workflowName? }` | A workflow is paused           |
+| `workflow:resumed`    | `{ workflowId, workflowName? }` | A workflow is resumed          |
+| `workflow:restarted`  | `{ workflowId, workflowName? }` | A workflow is restarted        |
+
+### MCP events
+
+| Type                    | Payload                                      | When                                                                               |
+| ----------------------- | -------------------------------------------- | ---------------------------------------------------------------------------------- |
+| `mcp:client:preconnect` | `{ serverId }`                               | Before connecting to an MCP server                                                 |
+| `mcp:client:connect`    | `{ url, transport, state, error? }`          | An MCP connection attempt completes or fails                                       |
+| `mcp:client:authorize`  | `{ serverId, authUrl, clientId? }`           | An MCP OAuth flow begins                                                           |
+| `mcp:client:discover`   | `{ url?, state?, error?, capability? }`      | MCP capability discovery succeeds or fails                                         |
+| `mcp:client:close`      | `{ url, transport?, state, error?, phase? }` | An MCP connection is closed (`phase` is `"terminate-session"` or `"client-close"`) |
+
+### Email events
+
+| Type            | Payload                  | When                  |
+| --------------- | ------------------------ | --------------------- |
+| `email:receive` | `{ from, to, subject? }` | An email is received  |
+| `email:reply`   | `{ from, to, subject? }` | A reply email is sent |

package/docs/push-notifications.md

@@ -0,0 +1,367 @@
+# Push Notifications
+
+Send browser push notifications from your agent — even when the user has closed the tab. By combining the agent's persistent state (for storing push subscriptions), scheduling (for timed delivery), and the [Web Push API](https://developer.mozilla.org/en-US/docs/Web/API/Push_API), you can reach users who are completely offline.
+
+## How It Works
+
+```
+Browser                              Agent (Durable Object)
+───────                              ──────────────────────
+1. Register service worker
+2. Subscribe to push (VAPID key)
+3. Send subscription to agent ──────► Store in this.state
+4. Create reminder ─────────────────► this.schedule(delay, "sendReminder", payload)
+
+   ... user closes tab ...
+
+5.                                    Alarm fires → sendReminder()
+                                      web-push sends encrypted payload
+                                              │
+6. Service worker receives push ◄─────────────┘
+7. showNotification()
+```
+
+The agent stores push subscriptions durably in its state and uses `this.schedule()` to fire notifications at the right time. When the alarm triggers, the agent calls the push service endpoint using the [`web-push`](https://www.npmjs.com/package/web-push) library. The browser's service worker receives the push event and displays a native notification.
+
+## Prerequisites
+
+### Generate VAPID Keys
+
+Web Push requires a VAPID (Voluntary Application Server Identification) key pair. Generate one:
+
+```bash
+npx web-push generate-vapid-keys
+```
+
+Store the keys in a `.env` file for local development:
+
+```
+VAPID_PUBLIC_KEY=BGxK...
+VAPID_PRIVATE_KEY=abc1...
+VAPID_SUBJECT=mailto:you@example.com
+```
+
+For production, use `wrangler secret put`:
+
+```bash
+wrangler secret put VAPID_PUBLIC_KEY
+wrangler secret put VAPID_PRIVATE_KEY
+wrangler secret put VAPID_SUBJECT
+```
+
+## Create the Agent
+
+The agent has three responsibilities: store push subscriptions, schedule reminders, and send notifications when alarms fire.
+
+```typescript
+import { Agent, callable, routeAgentRequest } from "agents";
+import webpush from "web-push";
+
+type Subscription = {
+  endpoint: string;
+  expirationTime: number | null;
+  keys: {
+    p256dh: string;
+    auth: string;
+  };
+};
+
+type Reminder = {
+  id: string;
+  message: string;
+  scheduledAt: number;
+  sent: boolean;
+};
+
+type ReminderAgentState = {
+  subscriptions: Subscription[];
+  reminders: Reminder[];
+};
+
+export class ReminderAgent extends Agent<Env, ReminderAgentState> {
+  initialState: ReminderAgentState = {
+    subscriptions: [],
+    reminders: []
+  };
+
+  @callable()
+  getVapidPublicKey(): string {
+    return this.env.VAPID_PUBLIC_KEY;
+  }
+
+  @callable()
+  async subscribe(subscription: Subscription): Promise<{ ok: boolean }> {
+    const exists = this.state.subscriptions.some(
+      (s) => s.endpoint === subscription.endpoint
+    );
+    if (!exists) {
+      this.setState({
+        ...this.state,
+        subscriptions: [...this.state.subscriptions, subscription]
+      });
+    }
+    return { ok: true };
+  }
+
+  @callable()
+  async unsubscribe(endpoint: string): Promise<{ ok: boolean }> {
+    this.setState({
+      ...this.state,
+      subscriptions: this.state.subscriptions.filter(
+        (s) => s.endpoint !== endpoint
+      )
+    });
+    return { ok: true };
+  }
+
+  @callable()
+  async createReminder(
+    message: string,
+    delaySeconds: number
+  ): Promise<Reminder> {
+    const id = crypto.randomUUID();
+    const scheduledAt = Date.now() + delaySeconds * 1000;
+    const reminder: Reminder = { id, message, scheduledAt, sent: false };
+
+    this.setState({
+      ...this.state,
+      reminders: [...this.state.reminders, reminder]
+    });
+
+    await this.schedule(delaySeconds, "sendReminder", { id, message });
+
+    return reminder;
+  }
+```
+
+When the scheduled alarm fires, send the push notification to all stored subscriptions:
+
+```typescript
+  async sendReminder(payload: { id: string; message: string }) {
+    webpush.setVapidDetails(
+      this.env.VAPID_SUBJECT,
+      this.env.VAPID_PUBLIC_KEY,
+      this.env.VAPID_PRIVATE_KEY
+    );
+
+    const deadEndpoints: string[] = [];
+
+    await Promise.all(
+      this.state.subscriptions.map(async (sub) => {
+        try {
+          await webpush.sendNotification(
+            sub,
+            JSON.stringify({
+              title: "Reminder",
+              body: payload.message,
+              tag: `reminder-${payload.id}`
+            })
+          );
+        } catch (err: unknown) {
+          const statusCode =
+            err instanceof webpush.WebPushError ? err.statusCode : 0;
+          if (statusCode === 404 || statusCode === 410) {
+            deadEndpoints.push(sub.endpoint);
+          }
+        }
+      })
+    );
+
+    // Clean up expired or revoked subscriptions
+    if (deadEndpoints.length > 0) {
+      this.setState({
+        ...this.state,
+        subscriptions: this.state.subscriptions.filter(
+          (s) => !deadEndpoints.includes(s.endpoint)
+        )
+      });
+    }
+
+    // Mark reminder as sent
+    this.setState({
+      ...this.state,
+      reminders: this.state.reminders.map((r) =>
+        r.id === payload.id ? { ...r, sent: true } : r
+      )
+    });
+
+    // Notify any connected clients in real time
+    this.broadcast(
+      JSON.stringify({
+        type: "reminder_sent",
+        id: payload.id,
+        timestamp: Date.now()
+      })
+    );
+  }
+}
+```
+
+The `sendReminder` callback handles three things: delivering the push notification via the `web-push` library, cleaning up dead subscriptions (the push service returns 404 or 410 when a subscription is no longer valid), and broadcasting to any connected clients so the UI updates in real time.
+
+## Set Up the Service Worker
+
+The service worker runs in the browser and receives push events even when no tabs are open. Place this file at `public/sw.js` so it is served from the root of your domain:
+
+```javascript
+self.addEventListener("push", (event) => {
+  if (!event.data) return;
+
+  const data = event.data.json();
+
+  event.waitUntil(
+    self.registration.showNotification(data.title || "Notification", {
+      body: data.body || "",
+      icon: data.icon || "/favicon.ico",
+      tag: data.tag,
+      data: data.data
+    })
+  );
+});
+
+self.addEventListener("notificationclick", (event) => {
+  event.notification.close();
+
+  event.waitUntil(
+    self.clients.matchAll({ type: "window" }).then((windowClients) => {
+      for (const client of windowClients) {
+        if (client.url.includes(self.location.origin) && "focus" in client) {
+          return client.focus();
+        }
+      }
+      return self.clients.openWindow("/");
+    })
+  );
+});
+```
+
+The `push` event handler parses the JSON payload and displays a native notification. The `notificationclick` handler focuses an existing tab or opens a new one when the user taps the notification.
+
+## Build the Client
+
+The client needs to: register the service worker, request notification permission, subscribe to push using the VAPID public key, and send the subscription to the agent.
+
+### Register the Service Worker
+
+```typescript
+useEffect(() => {
+  if (!("serviceWorker" in navigator) || !("PushManager" in window)) {
+    return; // Push not supported
+  }
+
+  navigator.serviceWorker.register("/sw.js");
+}, []);
+```
+
+### Subscribe to Push
+
+Fetch the VAPID public key from the agent, then subscribe through the Push API:
+
+```typescript
+function base64urlToUint8Array(base64url: string): Uint8Array {
+  const padded = base64url + "=".repeat((4 - (base64url.length % 4)) % 4);
+  const binary = atob(padded.replace(/-/g, "+").replace(/_/g, "/"));
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
+  return bytes;
+}
+
+async function subscribeToPush(agent) {
+  const permission = await Notification.requestPermission();
+  if (permission !== "granted") return;
+
+  const vapidPublicKey = await agent.call("getVapidPublicKey");
+  const reg = await navigator.serviceWorker.ready;
+  const subscription = await reg.pushManager.subscribe({
+    userVisibleOnly: true,
+    applicationServerKey: base64urlToUint8Array(vapidPublicKey).buffer
+  });
+
+  const subJson = subscription.toJSON();
+  await agent.call("subscribe", [
+    {
+      endpoint: subJson.endpoint,
+      expirationTime: subJson.expirationTime ?? null,
+      keys: subJson.keys
+    }
+  ]);
+}
+```
+
+### Create Reminders
+
+With the subscription stored, creating a reminder is a single RPC call. The agent handles scheduling and delivery:
+
+```typescript
+await agent.call("createReminder", ["Check the oven", 300]);
+```
+
+The agent schedules an alarm for 300 seconds (5 minutes). When it fires, the push notification arrives — even if the user closed the tab minutes ago.
+
+## Configuration
+
+### wrangler.jsonc
+
+```jsonc
+{
+  "name": "push-notifications",
+  "compatibility_date": "2026-01-28",
+  "compatibility_flags": ["nodejs_compat"],
+  "main": "src/server.ts",
+  "durable_objects": {
+    "bindings": [{ "name": "ReminderAgent", "class_name": "ReminderAgent" }]
+  },
+  "migrations": [{ "tag": "v1", "new_sqlite_classes": ["ReminderAgent"] }],
+  "assets": {
+    "not_found_handling": "single-page-application"
+  }
+}
+```
+
+The `nodejs_compat` compatibility flag is required for the `web-push` library.
+
+### Dependencies
+
+```bash
+npm install agents web-push
+```
+
+## Production Considerations
+
+### Subscription Expiry
+
+Push subscriptions can expire or be revoked by the user. Always handle 404 and 410 responses from the push service by removing the dead subscription from state, as shown in the `sendReminder` example above.
+
+### Per-User vs Shared Agents
+
+For most applications, use one agent per user (using the user ID as the agent name). This isolates each user's subscriptions and reminders. For broadcast-style notifications (same message to many users), a shared agent can store all subscriptions, but be aware of the state size as the subscription list grows.
+
+### Combining Push with WebSocket Broadcast
+
+Use `this.broadcast()` for clients that are currently connected (instant, no push service roundtrip) and Web Push for clients that are offline. The `sendReminder` example above does both — connected clients get a real-time WebSocket message, and offline clients get a push notification.
+
+### Multiple Devices
+
+A single user may subscribe from multiple browsers or devices. The agent stores each subscription separately, and `sendReminder` iterates over all of them. Each device receives its own push notification.
+
+### Retry on Failure
+
+If the push service returns a 5xx error (temporary failure), you can retry using `this.schedule()` with a short delay:
+
+```typescript
+try {
+  await webpush.sendNotification(sub, payload);
+} catch (err: unknown) {
+  const statusCode = err instanceof webpush.WebPushError ? err.statusCode : 0;
+  if (statusCode >= 500) {
+    await this.schedule(60, "retrySendNotification", {
+      endpoint: sub.endpoint,
+      payload
+    });
+  }
+}
+```
+
+## Full Example
+
+See the complete working example at [`examples/push-notifications/`](https://github.com/cloudflare/agents/tree/main/examples/push-notifications) — includes the agent, service worker, and a React client with subscription management, reminder creation, and real-time state sync.