agents 0.20.1 → 0.22.0

package/docs/mcp-transports.md

@@ -2,13 +2,18 @@
 
 This guide explains the different transport options for connecting to MCP servers with the Agents SDK.
 
-For a primer on MCP servers and how they are implemented in the Agents SDK with `McpAgent`, see [Creating MCP Servers](./mcp-servers.md).
+For a primer on MCP servers, see [Creating MCP Servers](./mcp-servers.md).
 
 ## Streamable HTTP Transport (Recommended)
 
-The **Streamable HTTP** transport is the recommended way to connect to MCP servers.
+The Agents SDK has two server paths:
 
-### How it works
+- Current SDK v2 servers use `createMcpHandler`, a per-request stateless Worker handler with no Durable Object or WebSocket bridge.
+- Retained SDK v1 servers use the deprecated, feature-frozen `McpAgent`, which provides sessionful transports through a Durable Object and internal WebSocket bridge.
+
+The current stateless handler also accepts stateless 2025-era Streamable HTTP requests by default. It does not expose standalone legacy SSE.
+
+### Legacy `McpAgent` architecture
 
 When a client connects to your MCP server:
 
@@ -44,13 +49,13 @@ The `serve()` method returns a Worker with a `fetch` handler that:
 
 ### Connection from clients
 
-Clients connect using the `streamable-http` transport:
+The Agents MCP client uses `"auto"` by default. It tries Streamable HTTP first and falls back to legacy SSE only when the endpoint reports that Streamable HTTP is unsupported:
 
 ```typescript
 await agent.addMcpServer("my-server", "https://your-worker.workers.dev/mcp");
 ```
 
-## Auto Transport
+## Legacy `McpAgent` Server Auto Transport
 
 The **auto** transport serves both Streamable HTTP and legacy SSE on the same endpoint. Capable clients use Streamable HTTP automatically, while older SSE-only clients continue to work.
 
@@ -60,7 +65,7 @@ export default MyMCP.serve("/mcp", { transport: "auto" });
 
 The handler distinguishes between the two protocols based on the request shape — no configuration or content negotiation is required from clients. This is useful when migrating from SSE to Streamable HTTP without breaking existing clients.
 
-## SSE Transport (Deprecated)
+## Legacy `McpAgent` SSE Transport (Deprecated)
 
 We also support the legacy **SSE (Server-Sent Events)** transport, but it is deprecated in favor of Streamable HTTP.
 
@@ -294,12 +299,13 @@ export class MyMCP extends McpAgent<Env, State> {
 
 ## Choosing a transport
 
-| Transport           | Use when                                 | Pros                                     | Cons                            |
-| ------------------- | ---------------------------------------- | ---------------------------------------- | ------------------------------- |
-| **Streamable HTTP** | External MCP servers, production apps    | Standard protocol, secure, supports auth | Slight network overhead         |
-| **Auto**            | Migrating from SSE, mixed client support | Serves both protocols on one endpoint    | Reserves `{path}/message` route |
-| **RPC**             | Internal agents                          | Fastest, simplest setup                  | No auth, Service Bindings only  |
-| **SSE**             | Legacy compatibility                     | Backwards compatible                     | Deprecated, use Streamable HTTP |
+| Transport                         | Use when                                            | Pros                                       | Cons                                   |
+| --------------------------------- | --------------------------------------------------- | ------------------------------------------ | -------------------------------------- |
+| **Streamable HTTP**               | New servers and external MCP connections            | Current standard transport; supports OAuth | Slight network overhead                |
+| **Client `auto`**                 | The remote server's HTTP transport is not known     | Tries Streamable HTTP, then legacy SSE     | May make a fallback connection attempt |
+| **Legacy `McpAgent` server auto** | An existing server must accept both HTTP transports | Serves both protocols on one endpoint      | Uses the deprecated server path        |
+| **RPC**                           | Internal agents                                     | Fastest, simplest setup                    | No auth, Service Bindings only         |
+| **SSE**                           | Legacy compatibility                                | Backwards compatible                       | Deprecated, use Streamable HTTP        |
 
 ## Examples
 

package/docs/migration-to-ai-sdk-v5.md

@@ -2,7 +2,7 @@
 
 This guide covers the changes needed when upgrading from AI SDK v4 to v5 with `@cloudflare/ai-chat`.
 
-> If you are on AI SDK v5 and upgrading to v6, see the [v6 migration guide](./migration-to-ai-sdk-v6.md) instead.
+> The current `agents` and `@cloudflare/ai-chat` packages support AI SDK v6 and v7, not v5. If an application is still on v4, apply the intermediate changes on this page and then continue through the [v6 migration guide](./migration-to-ai-sdk-v6.md). Do not install AI SDK v5 alongside the current Cloudflare packages.
 
 ## Message format: `content` to `parts`
 
@@ -71,7 +71,7 @@ chunk.type === "text-delta" && chunk.delta;
 
 ## Migration checklist
 
-1. Update dependencies: `npm update agents ai`
+1. Apply this intermediate checklist without installing v5, then continue through the [v6 migration guide](./migration-to-ai-sdk-v6.md) and install the supported package majors shown there
 2. Replace `import type { Message }` with `import type { UIMessage }`
 3. Replace `"ai/react"` imports with `"@ai-sdk/react"`
 4. Rename `parameters` to `inputSchema` in tool definitions

package/docs/migration-to-ai-sdk-v6.md

@@ -4,10 +4,14 @@ This guide covers the changes needed when upgrading from AI SDK v5 to v6 with `@
 
 ## Installation
 
+Pin the v6-compatible majors so this migration does not also install AI SDK v7:
+
 ```bash
-npm install ai@latest @ai-sdk/react@latest @ai-sdk/openai@latest
+npm install ai@^6 @ai-sdk/react@^3 @ai-sdk/openai@^3
 ```
 
+The current `agents` and `@cloudflare/ai-chat` releases support both AI SDK v6 and v7. This guide covers v6 only.
+
 ## Breaking changes
 
 ### 1. `convertToModelMessages()` is now async

package/docs/observability.md

@@ -158,17 +158,17 @@ These events are emitted by `AIChatAgent` from `@cloudflare/ai-chat`. They track
 
 ### 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) |
+| 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`. The turn then routes into bounded recovery; look for `chat:recovery:*`. 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.
 
@@ -292,9 +292,9 @@ metadata fields for applications with a different identity model. Payload
 storage is off by default. Set `storeMessages` and/or `storeTools` on the Think
 agent to opt in; these are wrapper settings, not span attributes.
 
-### AI SDK v6
+### AI SDK v6 and v7
 
-Wrap the SDK namespace:
+Wrap the SDK namespace and call the wrapped functions:
 
 ```ts
 import * as ai from "ai";
@@ -303,14 +303,17 @@ import { wrapAISDK } from "agents/observability/ai";
 const { generateText, streamText } = wrapAISDK(ai);
 ```
 
-`wrapAISDK` instruments `generateText`, `streamText`, `generateObject`, and
-`streamObject`. Span names use `{operation} {target}` and fall back to the bare
-operation past 64 UTF-8 bytes; the full target remains on its semantic
-attribute. A model object is wrapped with the SDK's `wrapLanguageModel` helper,
-so provider work is a `chat {model}` child of the operation span. Tool
-execution is wrapped as `execute_tool {tool}`. AI SDK v6 approval lifecycle
-segments appear as bounded `tool_approval {tool}` children of an
-`execute_tool {tool}` span, correlated by `gen_ai.tool.call.id` and carrying
+`wrapAISDK` supports AI SDK v6 and v7. It instruments `generateText`,
+`streamText`, `generateObject`, and `streamObject`. You do not need to register a
+telemetry integration for Agents tracing on AI SDK v7.
+
+Span names use `{operation} {target}` and fall back to the bare operation past
+64 UTF-8 bytes; the full target remains on its semantic attribute. A model
+object is wrapped with the SDK's `wrapLanguageModel` helper, so provider work is
+a `chat {model}` child of the `invoke_agent {agent}` operation span. Tool
+execution is wrapped as `execute_tool {tool}`. Approval lifecycle segments
+appear as bounded `tool_approval {tool}` children of an `execute_tool {tool}`
+span, correlated by `gen_ai.tool.call.id` and carrying
 `cloudflare.agents.tool.approval.state` (`requested`, `approved`, or `denied`).
 They never remain open while waiting for a human across invocations. Stream
 spans close on completion, cancellation, an in-band error, or early consumer
@@ -329,46 +332,10 @@ const traced = wrapAISDK(ai, {
 });
 ```
 
-### AI SDK v7
-
-AI SDK v7 ships a first-class telemetry lifecycle. Register the adapter once and
-every `generateText`, `streamText`, `generateObject`, and `streamObject` call is
-instrumented:
-
-```ts
-import { registerTelemetry } from "ai";
-import { createAISDKTelemetry } from "agents/observability/ai";
-
-registerTelemetry(
-  createAISDKTelemetry({ storeMessages: true, storeTools: true })
-);
-```
-
-Or scope it to a single call through `experimental_telemetry`:
-
-```ts
-import { createAISDKTelemetry } from "agents/observability/ai";
-
-await generateText({
-  model,
-  prompt: "...",
-  experimental_telemetry: {
-    integrations: [createAISDKTelemetry()]
-  }
-});
-```
-
-The v7 adapter uses `cloudflare.agents.call.id` to correlate operation, model,
-and tool spans. Its execution hooks keep provider work under the `chat` span and
-nested work performed by a tool under the `execute_tool` span. It handles both
-`onEnd` and `onAbort` terminal paths. `wrapAISDK` and `createAISDKTelemetry`
-project into the same span schema, so the two SDK versions are dashboard-
-compatible.
-
 When a gateway-backed provider exposes its AI Gateway log ID through response
 headers, provider metadata, or the Workers AI binding, the corresponding
 `chat` span includes `cloudflare.ai_gateway.log.id`. The attribute is omitted
-when no actual response exposes an ID; the adapter does not infer one or make an
+when no actual response exposes an ID; the wrapper does not infer one or make an
 extra request.
 
 ### Identity
@@ -445,13 +412,13 @@ await generateText({
 | `gen_ai.usage.cache_creation.input_tokens`, `gen_ai.usage.cache_read.input_tokens` | Provider cache usage when reported                                                           |
 | `gen_ai.usage.reasoning.output_tokens`                                             | Reasoning output usage when reported                                                         |
 | `gen_ai.tool.name`, `gen_ai.tool.type`, `gen_ai.tool.call.id`                      | Tool identity; call ID also correlates approval lifecycle segments                           |
-| `cloudflare.agents.tool.approval.state`                                            | AI SDK v6 approval lifecycle segment: `requested`, `approved`, or `denied`                   |
+| `cloudflare.agents.tool.approval.state`                                            | Approval lifecycle segment: `requested`, `approved`, or `denied`                             |
 | `gen_ai.input.messages`, `gen_ai.output.messages`                                  | Opt-in OTel-schema model messages on `chat`, including tool parts and output finish reasons  |
 | `gen_ai.tool.call.arguments`, `gen_ai.tool.call.result`                            | Opt-in tool arguments/results on `execute_tool`                                              |
 | `user.id`                                                                          | Explicit v6 metadata key `user.id`                                                           |
 | `error.type`                                                                       | Low-cardinality error class; raw error messages are never recorded                           |
 
-The adapter also emits a small vendor namespace where no standard equivalent
+The wrapper also emits a small vendor namespace where no standard equivalent
 exists:
 
 | Attribute                                                                               | Meaning                                                                 |
@@ -459,12 +426,10 @@ exists:
 | `cloudflare.ai_gateway.log.id`                                                          | AI Gateway log reference on `chat`, when exposed by the actual response |
 | `cloudflare.agents.integration.name`                                                    | Instrumentation source (`ai-sdk`)                                       |
 | `cloudflare.agents.operation.name`                                                      | Original SDK operation (`streamText`, `doStream`, `tool.execute`, etc.) |
-| `cloudflare.agents.call.id`                                                             | AI SDK v7 callback correlation ID                                       |
 | `cloudflare.agents.response.finish_reason`                                              | One finish reason as a scalar                                           |
 | `cloudflare.agents.tool.count`                                                          | Precomputed tool-call count for dashboards                              |
 | `cloudflare.agents.usage.total_tokens`                                                  | Provider total, or input plus output when both are known                |
 | `cloudflare.agents.runtime_context.{key}`                                               | Explicitly included scalar runtime context                              |
-| `cloudflare.agents.tool_context.{tool}.{key}`                                           | Explicitly included scalar context on the executed tool span            |
 | `cloudflare.agents.metadata.{key}`                                                      | Other scalar v6 telemetry metadata                                      |
 | `cloudflare.agents.turn.{request_id,trigger,admission,channel,continuation,generation}` | Think turn context, from v6 metadata or v7 runtime context              |
 | `cloudflare.agents.canceled`                                                            | Recognized cancellation, not a failure                                  |
@@ -472,16 +437,16 @@ exists:
 
 `gen_ai.response.finish_reasons` and `gen_ai.request.stop_sequences` are arrays
 in OTel. Workers' custom `Span.setAttribute` currently accepts only a string,
-number, or boolean, so the adapter omits those attributes rather than placing
+number, or boolean, so the wrapper omits those attributes rather than placing
 JSON text under an array-typed key. Similarly, span status is state rather than
-an attribute: failures emit `error.type`, but the adapter does not invent an
+an attribute: failures emit `error.type`, but the wrapper does not invent an
 `otel.status_code` attribute when Workers exposes no custom-span status setter.
 
 ### Context and safety
 
 Payload storage is explicit and off by default. `storeMessages` writes only
 `gen_ai.input.messages` / `gen_ai.output.messages` on `chat`; when the message
-attribute exceeds its budget, the adapter repeatedly drops the oldest
+attribute exceeds its budget, the wrapper repeatedly drops the oldest
 unprotected message (index 2), preserving the first two messages and newest
 tail. `storeTools` writes only `gen_ai.tool.call.arguments` /
 `gen_ai.tool.call.result` on `execute_tool`. The flags themselves are never
@@ -489,7 +454,7 @@ written to telemetry metadata or spans.
 
 System instructions that the AI SDK presents to the model as a system-role chat
 message remain in `gen_ai.input.messages`, which OTel explicitly permits for
-instructions that are part of chat history. The adapter does not separately
+instructions that are part of chat history. The wrapper does not separately
 copy the raw `system` parameter into `gen_ai.system_instructions`. Schemas,
 request headers, provider options, and raw error messages are never recorded.
 The optional AI Gateway reference is a bounded opaque log ID; response headers
@@ -514,27 +479,18 @@ await traced.generateText({
 });
 ```
 
-For v7, the AI SDK filters runtime and per-tool context before the adapter sees
-it. Its allowlists are boolean maps, not arrays:
+For v7, put application context in `runtimeContext` and select telemetry-visible
+keys with the AI SDK's boolean-map allowlist:
 
 ```ts
 await generateText({
   model,
   prompt: "Will I need an umbrella?",
   runtimeContext: { requestId: "req-123", tenantId: "tenant-42" },
-  toolsContext: {
-    weather: { defaultUnit: "celsius", cacheHit: true }
-  },
   telemetry: {
     includeRuntimeContext: {
       requestId: true,
       tenantId: true
-    },
-    includeToolsContext: {
-      weather: {
-        defaultUnit: true,
-        cacheHit: true
-      }
     }
   }
 });

package/docs/resumable-streaming.md

@@ -2,7 +2,7 @@
 
 The `AIChatAgent` class provides **automatic resumable streaming** out of the box. When a client disconnects and reconnects during an active stream, the response automatically resumes from where it left off.
 
-This is client reconnect recovery, not Durable Object eviction recovery. If the Worker process or Durable Object is evicted while the model call is in flight, enable `chatRecovery` so the turn runs inside a recoverable fiber. `Think` enables `chatRecovery` by default; plain `AIChatAgent` subclasses opt in with `override chatRecovery = true`.
+This is client reconnect recovery, not Durable Object eviction recovery. Durable Object eviction recovery is also always enabled for `AIChatAgent` and `Think`: every turn runs inside a recoverable fiber. Use `chatRecovery` only to tune its budgets and terminal behavior.
 
 ## How It Works
 

package/docs/routing.md

@@ -96,6 +96,33 @@ export default {
 
 ---
 
+## Building Agent URLs
+
+Use `buildAgentPath()` when a server, external provider, or client needs the canonical pathname for a known root-first Agent identity. It handles the top-level route and every nested `/sub/...` hop:
+
+```typescript
+import { buildAgentPath, buildAgentUrl } from "agents";
+
+const address = [
+  { className: "Inbox", name: userId },
+  { className: "Chat", name: chatId }
+];
+
+buildAgentPath(address, { leafPath: "/callbacks/job" });
+// /agents/inbox/{userId}/sub/chat/{chatId}/callbacks/job
+
+buildAgentUrl("https://app.example.com", address, {
+  leafPath: "/callbacks/job"
+});
+// URL("https://app.example.com/agents/inbox/...")
+```
+
+Inside an Agent, `this.selfPath` has the required root-first shape. If the root Durable Object binding name differs from its class name, pass that binding name as `rootBinding`. The pathname works for both HTTP and WebSocket traffic. For a custom top-level prefix, pass the same `prefix` to `buildAgentPath()` and `routeAgentRequest()`.
+
+See [Sub-agents](./sub-agents.md#direct-http-and-websocket-urls) for callbacks, webhooks, custom routing, and name-encoding details.
+
+---
+
 ## Instance Naming Patterns
 
 The instance name (the last part of the URL) determines which agent instance handles the request. Each unique name gets its own isolated agent with its own state.

package/docs/scheduling.md

@@ -15,6 +15,91 @@ The scheduling system supports four modes:
 
 Under the hood, scheduling uses [Durable Object alarms](https://developers.cloudflare.com/durable-objects/api/alarms/) to wake the agent at the right time. Tasks are stored in a SQLite table and executed in order.
 
+## Scheduler Lifecycle primitive
+
+> **Experimental.** The `Scheduler` primitive and the `agents/lifecycle`
+> surface it builds on may change between releases. Agent's established
+> scheduling methods (`this.schedule()` and friends) are stable.
+
+`Scheduler` is a reusable Lifecycle capability. A plain Lifecycle Object can
+install it without extending `Agent`:
+
+```typescript
+import { DurableObject } from "cloudflare:workers";
+import { Lifecycle } from "agents/lifecycle";
+import { Scheduler, type Schedule } from "agents/schedules";
+
+export class ReminderObject extends DurableObject<Env> {
+  readonly scheduler = new Scheduler({
+    callbacks: {
+      sendReminder: (
+        payload: { message: string },
+        schedule: Schedule<{ message: string }>
+      ) => {
+        console.log(schedule.id, payload.message);
+      }
+    }
+  });
+
+  readonly lifecycle = Lifecycle.install(this).use(this.scheduler);
+
+  async createReminder(message: string): Promise<string> {
+    const schedule = await this.scheduler.set(300, "sendReminder", {
+      message
+    });
+    return schedule.id;
+  }
+}
+```
+
+Lifecycle owns the physical Durable Object alarm. Scheduler contributes its
+earliest pending task or hung-interval recheck. Lifecycle selects the earliest
+contribution from Scheduler, other capabilities, and the host, then rearms after
+every alarm phase. A future Fiber or MCP capability can contribute its own wake
+time without storing work in Scheduler or depending on it.
+
+Scheduler's primary API is small: callbacks are registered by name in the
+constructor, `set()` and `every()` create schedules typed against that
+registration, and `get()`, `list()`, and `cancel()` manage them. All of these
+are asynchronous and work inside routed sub-agents.
+
+Scheduler Lifecycle hooks run without ambient host context. Registered
+callbacks are user code, so they run inside the host invocation context with
+the Lifecycle Object available through `getCurrentAgent()`.
+
+## Using Scheduler through Agent
+
+Every `Agent` constructs and installs the same primitive at `this.scheduler`.
+Existing Agent applications continue to use the established methods:
+
+- `this.schedule()` and `this.scheduleEvery()` create schedules.
+- `this.getScheduleById()` and `this.listSchedules()` read schedules.
+- `this.cancelSchedule()` removes a schedule.
+
+These methods delegate to `this.scheduler`; no setup or migration is required.
+Agent registers no callbacks map — a composition-root resolver keeps
+`this.schedule(60, "methodName")` dispatching to Agent methods. Agent passes
+only policy options (retry defaults, hung-interval timeout, error routing) and
+adapts Lifecycle's event sink, facet transport, and host invocation boundary
+at its composition root — there is no Agent-specific Scheduler adapter. Scheduler contributes its next wake time to the same Lifecycle alarm
+selection as Agent keep-alive, fibers, sub-agent work, and deferred
+destruction.
+
+Import `Scheduler` and runtime schedule types from the dependency-light entry
+point:
+
+```typescript
+import {
+  Scheduler,
+  type Schedule,
+  type ScheduleCriteria
+} from "agents/schedules";
+```
+
+Natural-language parsing helpers use Zod and live under
+`agents/schedules/parser`. The previous `agents/schedule` path remains as a
+deprecated compatibility alias.
+
 ## Quick Start
 
 ```typescript
@@ -299,9 +384,9 @@ This is the recommended approach since you cannot forget to dispose the heartbea
 
 ### How it works
 
-`keepAlive()` uses an in-memory reference count and the Durable Object alarm system directly. Each call increments the count; the disposer decrements it. While the count is above zero, `_scheduleNextAlarm()` ensures an alarm fires every 30 seconds, which resets the inactivity timer. No schedule rows are created and no observability events are emitted — the heartbeat is invisible to `listSchedules()` and the `agents:schedule` diagnostics channel.
+`keepAlive()` uses an in-memory reference count. Each call increments the count; the disposer decrements it. While the count is above zero, Agent contributes a wake time every 30 seconds to Lifecycle. No schedule rows are created and no observability events are emitted, so the heartbeat is invisible to `listSchedules()` and the scheduling diagnostics channel.
 
-The heartbeat does not conflict with your own schedules — the alarm system multiplexes all schedules and the keepAlive heartbeat through a single alarm slot.
+The heartbeat does not conflict with scheduled work. Lifecycle selects one physical alarm from both contributions.
 
 Inside sub-agents, `keepAlive()` delegates that heartbeat ref to the top-level parent because facets do not have independent alarm slots. `keepAliveWhile()` works the same way because it calls `keepAlive()` and automatically disposes the delegated ref when the scoped work completes.
 
@@ -642,14 +727,14 @@ class TimezoneAgent extends Agent {
 
 ## AI-Assisted Scheduling
 
-The SDK includes utilities for parsing natural language scheduling requests with AI.
+The SDK includes utilities for parsing natural language scheduling requests with AI. Import them from `agents/schedules/parser`.
 
 ### getSchedulePrompt()
 
 Returns a system prompt for parsing natural language into scheduling parameters:
 
 ```typescript
-import { getSchedulePrompt, scheduleSchema } from "agents";
+import { getSchedulePrompt, scheduleSchema } from "agents/schedules/parser";
 import { generateObject } from "ai";
 import { openai } from "@ai-sdk/openai";
 
@@ -703,7 +788,7 @@ class SmartScheduler extends Agent {
 A Zod schema for validating parsed scheduling data:
 
 ```typescript
-import { scheduleSchema } from "agents";
+import { scheduleSchema } from "agents/schedules/parser";
 
 // The schema uses a discriminated union on `when.type`:
 // {
@@ -751,7 +836,81 @@ When using this schema with OpenAI models via the AI SDK, you must pass `provide
 
 ## API Reference
 
-### schedule()
+Two surfaces share these semantics: the experimental `Scheduler` primitive
+(`agents/schedules`, methods on the scheduler instance) and the stable `Agent`
+methods (on the Agent class, delegating to `this.scheduler`).
+
+### Scheduler primitive
+
+#### `new Scheduler(options?)`
+
+```typescript
+new Scheduler({
+  callbacks?,
+  retry?,
+  hungScheduleTimeoutSeconds?,
+  onError?
+});
+```
+
+- `callbacks` registers scheduled callbacks by name. `set()` and `every()`
+  type both the name and the payload against this map, and dispatch runs the
+  registered function — the typed scheduling surface and the runtime dispatch
+  target are the same object.
+- Lifecycle supplies storage, readiness, startup state, alarm coordination,
+  the host invocation boundary, events, and routing.
+- `retry` supplies callback retry defaults. The defaults are three attempts,
+  100 ms base delay, and 3,000 ms maximum delay.
+- `hungScheduleTimeoutSeconds` defaults to 30 seconds.
+- `onError` observes terminal callback failures outside ambient host context.
+
+Install the constructed object with `Lifecycle.use()` before use. Scheduler
+starts Lifecycle automatically when its asynchronous API is entered. It
+publishes `schedule:*` events through Lifecycle's best-effort event bus. A plain
+Lifecycle Object writes them to the existing `agents:schedule` diagnostics
+channel; `Agent` sends them through its existing observability implementation.
+
+#### set()
+
+```typescript
+async set(when, callback, payload?, options?): Promise<Schedule<Payload>>
+```
+
+Create a one-shot or cron schedule. `when`, `options`, idempotency, and return
+value follow [`schedule()`](#schedule) below. `callback` must be a name
+registered in the constructor's `callbacks` map, and `payload` is typed
+against that callback's first parameter.
+
+#### every()
+
+```typescript
+async every(intervalSeconds, callback, payload?, options?): Promise<Schedule<Payload>>
+```
+
+Create a fixed-interval schedule. Semantics follow
+[`scheduleEvery()`](#scheduleevery) below, and `every()` also accepts
+`options.idempotent` to opt out of interval dedup.
+
+#### get() / list() / cancel()
+
+```typescript
+async get(id): Promise<Schedule<unknown> | undefined>
+async list(criteria?): Promise<Schedule<unknown>[]>
+async cancel(id): Promise<boolean>
+```
+
+Read and cancel schedules — the primitive's equivalents of
+[`getScheduleById()`](#getschedulebyid), [`listSchedules()`](#listschedules),
+and [`cancelSchedule()`](#cancelschedule) below. (Internal synchronous
+variants on the Scheduler back Agent's deprecated `getSchedule()` and
+`getSchedules()`; they are not part of the primitive's contract.)
+
+### Agent methods
+
+Methods on the `Agent` class, delegating to `this.scheduler`. Callback names
+resolve to methods on the Agent.
+
+#### schedule()
 
 ```typescript
 async schedule<T = string>(
@@ -789,7 +948,7 @@ class MyAgent extends Agent {
 }
 ```
 
-### scheduleEvery()
+#### scheduleEvery()
 
 ```typescript
 async scheduleEvery<T = string>(
@@ -800,7 +959,8 @@ async scheduleEvery<T = string>(
 ): Promise<Schedule<T>>
 ```
 
-Schedule a task to run repeatedly at a fixed interval.
+Schedule a task to run repeatedly at a fixed interval. Idempotent by design
+(the primitive's `every()` accepts `options.idempotent` to opt out).
 
 **Parameters:**
 
@@ -819,7 +979,7 @@ Schedule a task to run repeatedly at a fixed interval.
 - If callback throws an error, the interval continues
 - Cancel with `cancelSchedule(id)` to stop the entire interval
 
-### getScheduleById()
+#### getScheduleById()
 
 ```typescript
 async getScheduleById(id: string): Promise<Schedule<unknown> | undefined>
@@ -827,7 +987,7 @@ async getScheduleById(id: string): Promise<Schedule<unknown> | undefined>
 
 Get a scheduled task by ID. This method works in both top-level agents and sub-agents.
 
-### listSchedules()
+#### listSchedules()
 
 ```typescript
 async listSchedules(criteria?: {
@@ -839,7 +999,7 @@ async listSchedules(criteria?: {
 
 Get scheduled tasks matching the criteria. This method works in both top-level agents and sub-agents.
 
-### getSchedule()
+#### getSchedule()
 
 ```typescript
 getSchedule<T = string>(id: string): Schedule<T> | undefined
@@ -847,7 +1007,7 @@ getSchedule<T = string>(id: string): Schedule<T> | undefined
 
 Deprecated. Get a scheduled task by ID synchronously. This method only works in top-level agents; use `await this.getScheduleById(id)` instead.
 
-### getSchedules()
+#### getSchedules()
 
 ```typescript
 getSchedules<T = string>(criteria?: {
@@ -859,7 +1019,7 @@ getSchedules<T = string>(criteria?: {
 
 Deprecated. Get scheduled tasks matching the criteria synchronously. This method only works in top-level agents; use `await this.listSchedules(criteria)` instead.
 
-### cancelSchedule()
+#### cancelSchedule()
 
 ```typescript
 async cancelSchedule(id: string): Promise<boolean>
@@ -867,7 +1027,7 @@ async cancelSchedule(id: string): Promise<boolean>
 
 Cancel a scheduled task. Returns `true` if cancelled, `false` if not found.
 
-### keepAlive()
+#### keepAlive()
 
 ```typescript
 async keepAlive(): Promise<() => void>
@@ -877,7 +1037,7 @@ Create an alarm-backed heartbeat that prevents the Durable Object from being evi
 
 See [Keeping the Agent Alive](#keeping-the-agent-alive) for usage details.
 
-### keepAliveWhile()
+#### keepAliveWhile()
 
 ```typescript
 async keepAliveWhile<T>(fn: () => Promise<T>): Promise<T>