Enable alarm-backed APIs in sub-agents (#1418)

* Add sub-agent alarm recovery support

Made-with: Cursor

* Tighten facet cleanup bookkeeping

Made-with: Cursor

* Hide internal schedule storage fields

Made-with: Cursor

* Stabilize destroy cleanup schema test

Made-with: Cursor

Author: threepointone

.changeset/facet-schedules.md

@@ -0,0 +1,7 @@
+---
+"agents": patch
+---
+
+Allow sub-agents to use alarm-backed APIs by delegating the physical Durable Object alarm to the top-level parent while executing logical work inside the owning sub-agent. This enables `schedule()`, `scheduleEvery()`, `cancelSchedule()`, `getScheduleById()`, `listSchedules()`, `keepAlive()`, `keepAliveWhile()`, `runFiber()`, and Think chat recovery inside sub-agents.
+
+Sub-agent schedules are scoped to the calling child, so sibling sub-agents cannot cancel each other's schedules by id. The deprecated synchronous `getSchedule()` and `getSchedules()` APIs now throw inside sub-agents; use the async alternatives instead. Destroying a sub-agent now delegates cleanup through the parent so parent-owned schedules and descendant fiber recovery leases are removed consistently.

design/rfc-helper-sub-agent-orchestration.md

@@ -128,6 +128,13 @@ The framework-provided runner owns the protocol bridge:
 - read stored chunks, final text, and stream errors for replay/result synthesis
 - prevent concurrent framework-driven turns on one agent tool instance
 
+Sub-agent scheduling is now available through the normal `Agent` scheduling
+APIs. Facets still do not own independent physical alarm slots, but the
+top-level parent stores child-owned schedule rows with an owner path and routes
+callbacks back into the owning child when the alarm fires. This matters for
+agent-tool recovery: a child can schedule recovered continuations from inside
+the facet, and that callback runs with the child as `this`.
+
 There should not be a separate public base class for agent tools unless the
 implementation later proves it needs one. The shared base class extracted in
 `examples/agents-as-tools` is prototype structure, not proposed public API.
@@ -655,11 +662,19 @@ call as interrupted. Imperative `runAgentTool(...)` calls have a cleaner
 recovery story because application code can inspect the run later without
 reconstructing an in-flight LLM turn.
 
-Today, facets still have lifecycle limits: no independent alarms, and
-`keepAlive()` is a soft no-op inside facets. The first implementation should
-therefore guarantee durable replay and honest terminal/interrupted state, while
-designing the run metadata and observer API so `detached` and full live reattach
-can be added when facet recovery improves.
+Sub-agent schedules and delegated keepAlive remove the earlier blockers for
+child-side recovery. A facet still does not own an independent physical alarm,
+but a child can schedule logical callbacks through the top-level parent's alarm,
+hold a root-owned heartbeat ref while work is active, and register facet fibers
+in a small root-side index. Think chat recovery and `runFiber()` therefore work
+for long-lived agent-tool facets even when the child is otherwise idle: the root
+alarm routes recovery checks back into the child that owns the fiber row.
+
+The remaining V1 limitation is not "facets cannot recover"; it is "the parent
+observer may be gone." V1 should still guarantee durable replay and honest
+terminal/interrupted state. `detached` and full live reattach are observer
+features that can be added once `tailAgentToolRun` / live-tail support exists,
+without changing the public `runAgentTool` / `agentTool` surface.
 
 ### Imperative API: `runAgentTool`
 
@@ -951,10 +966,12 @@ leave an orphaned child transcript that is no longer reachable through replay or
 drill-in. If a future API allows registry-only deletion, it must make that
 orphaning behavior explicit.
 
-V1 should defer automatic TTL, count-based GC, background alarms, and
-`retain: false` on `runAgentTool`. Those are useful policy knobs, but the first
-implementation only needs the reliable primitive that applications can call from
-their own lifecycle code.
+V1 should defer automatic TTL, count-based GC, and `retain: false` on
+`runAgentTool`. Those are useful policy knobs, but the first implementation only
+needs the reliable primitive that applications can call from their own lifecycle
+code. Sub-agent scheduling means the framework is no longer blocked on a
+mechanism for future background GC; the remaining question is what retention
+policy to choose.
 
 ### Think and AIChatAgent
 
@@ -1083,7 +1100,10 @@ retaining the child facet and parent registry row. Cleanup should be explicit.
 Deferred. Time-based and count-based cleanup are useful, but they are policy
 decisions and may depend on account, workspace, or chat-history lifecycle.
 Shipping `clearAgentToolRuns(...)` first gives applications a reliable primitive
-without committing to scheduler behavior or default retention windows.
+without committing to default retention windows. Sub-agent scheduling means a
+future TTL/GC implementation can run from either the parent or a retained
+agent-tool facet, but the retention policy should still be explicit rather than
+hidden in V1 defaults.
 
 ### Ship only protocol types, no client hook
 
@@ -1151,7 +1171,7 @@ The implementation does not need to land all at once. A reasonable order is:
    docs and examples.
 4. Ergonomics: `defineAgentTool(...)` or class-level reusable contracts;
    richer error shape; structured-output convenience.
-5. Live-tail reattach when facet recovery improves; `detached` observer state;
+5. Live-tail reattach via `tailAgentToolRun`; `detached` observer state;
    tracing/cost integrations.
 
 After Phase 1 lands, `examples/agents-as-tools` should be rewritten on top of

design/sub-agent-routing.md

@@ -17,7 +17,11 @@ They are implemented on top of workerd facets (`ctx.facets`) and have:
 - their own WebSocket clients (once addressed through `/sub/...`)
 - colocation with the parent on the same machine
 
-They do **not** have independent alarms today — `schedule()` is unsupported on facets, and `keepAlive()` is a soft no-op.
+They do **not** have independent alarm slots today. Sub-agent `schedule()` and
+`scheduleEvery()` calls are logical child schedules stored in the top-level
+parent's scheduler table with an owner path. When the parent alarm fires, the
+SDK routes the due callback back through the facet tree and executes it inside
+the owning sub-agent.
 
 ## Addressing
 
@@ -115,9 +119,23 @@ RPC if you need parent-side side effects.
 
 ## Lifecycle caveats
 
-- `schedule()` / `scheduleEvery()` / `cancelSchedule()` are unsupported on facets.
-- `keepAlive()` is a soft no-op on facets.
-- `deleteSubAgent()` is idempotent.
+- `schedule()` / `scheduleEvery()` / `cancelSchedule()` work on facets, but the
+  top-level parent owns the physical alarm.
+- `getScheduleById()` / `listSchedules()` work on facets by delegating to the
+  top-level parent.
+- `getSchedule()` / `getSchedules()` are deprecated synchronous storage reads
+  and throw on facets.
+- `keepAlive()` and `keepAliveWhile()` work on facets by delegating their
+  heartbeat ref to the top-level parent. Facets still do not get an independent
+  physical alarm slot.
+- `runFiber()` works on facets. Fiber rows and snapshots live in the child
+  SQLite database, while the root parent keeps a small index of active facet
+  fibers so alarm housekeeping can route recovery checks back into idle
+  children.
+- Think chat recovery works on facets; recovered continuations can schedule from
+  the child and are routed through the top-level parent's alarm.
+- `deleteSubAgent()` is idempotent and removes pending schedules for that
+  descendant tree before deleting the facet.
 - Class names whose kebab-case equals `"sub"` are rejected (e.g. `Sub`, `SUB`,
   `Sub_`) because they collide with the `/sub/` URL separator.
 
@@ -126,6 +144,9 @@ RPC if you need parent-side side effects.
 - **Good:** direct child connections, low-latency parent↔child RPC, clean
   parent/index + child/leaf app structure.
 - **Good:** parent-owned registry gives us strict gating and enumeration for free.
-- **Tradeoff:** no independent alarms on facets yet.
+- **Good:** sub-agent code can use the normal scheduling API even though the
+  parent owns the runtime alarm.
+- **Tradeoff:** no independent physical alarms on facets yet; the root parent
+  multiplexes schedules for the whole facet tree.
 - **Tradeoff:** `parentAgent(Cls)` only does the one-hop case; deeper ancestor
   lookup stays explicit.

docs/agent-class.md

@@ -293,7 +293,7 @@ Tasks are stored in the `cf_agents_queues` SQL table and are automatically flush
 
 ### `this.schedule` and friends
 
-Agents support scheduled execution of methods by wrapping the Durable Object's `alarm()`. The available methods are `this.schedule`, `this.getSchedule`, `this.getSchedules`, `this.cancelSchedule`. Schedules can be one-time, delayed, or recurring (using cron expressions).
+Agents support scheduled execution of methods by wrapping the Durable Object's `alarm()`. The available methods are `this.schedule`, `this.getScheduleById`, `this.listSchedules`, `this.cancelSchedule`, and the deprecated synchronous `this.getSchedule` / `this.getSchedules`. Schedules can be one-time, delayed, or recurring (using cron expressions).
 
 Since DOs only allow one alarm at a time, the `Agent` class works around this by managing multiple schedules in SQL and using a single alarm.
 
@@ -450,7 +450,7 @@ class MyAgent extends Agent {
 
 ### `this.keepAlive`
 
-`this.keepAlive()` prevents the Durable Object from being evicted due to inactivity by creating a 30-second heartbeat schedule. Returns a disposer function to stop the heartbeat. For scoped work, use `this.keepAliveWhile(fn)` which automatically cleans up when the function completes. See [Keeping the Agent Alive](./scheduling.md#keeping-the-agent-alive) for full documentation.
+`this.keepAlive()` prevents the Durable Object from being evicted due to inactivity by holding an alarm-backed heartbeat ref. Returns a disposer function to stop the heartbeat. For scoped work, use `this.keepAliveWhile(fn)` which automatically cleans up when the function completes. See [Keeping the Agent Alive](./scheduling.md#keeping-the-agent-alive) for full documentation.
 
 ### Routing
 

docs/durable-execution.md

@@ -81,7 +81,7 @@ try {
 
 While any `keepAlive` ref is held, an alarm fires every 30 seconds that resets the inactivity timer. When all disposers are called, alarms stop and the DO can go idle naturally.
 
-The heartbeat is invisible to `getSchedules()` — no schedule rows are created. It does not conflict with your own schedules; the alarm system multiplexes all schedules and the keepAlive heartbeat through a single alarm slot.
+The heartbeat is invisible to `listSchedules()` — no schedule rows are created. It does not conflict with your own schedules; the alarm system multiplexes all schedules and the keepAlive heartbeat through a single alarm slot.
 
 ### Configurable interval
 
@@ -169,6 +169,14 @@ runFiber("work", fn)
 
 Both recovery paths call the same hook. The alarm path is critical for background agents that have no incoming client connections — the persisted alarm wakes the agent on its own.
 
+#### Sub-agents
+
+Fibers also work inside sub-agents. The fiber row and snapshots are stored in the sub-agent's own SQLite database, and `onFiberRecovered()` runs with the sub-agent as `this`.
+
+Sub-agents do not have independent alarm slots, so the top-level parent owns the physical heartbeat. When a sub-agent starts a fiber, the parent stores a small root-side index entry for that facet and fiber ID. Root alarm housekeeping uses that index to route recovery checks back into the owning sub-agent, even if the child has no client connection or incoming RPC.
+
+This keeps recovery local to the child while preserving the single physical alarm slot owned by the parent. A recovered continuation can use `schedule()` from inside the facet; the parent owns the physical alarm and routes the callback back to the child.
+
 #### Error during execution
 
 ```

docs/long-running-agents.md

@@ -514,7 +514,9 @@ export class ProjectManager extends Agent<ProjectState> {
 }
 ```
 
-Sub-agents have their own state and lifecycle, but not full parity with top-level Durable Objects yet. In particular, they do **not** have their own alarms today — `schedule()` / `scheduleEvery()` are not supported on facets yet (support is coming soon). Put scheduled work on the parent and let it dispatch into children by RPC. The parent also does not need to stay awake while the child handles request-scoped work; once the child is woken it can complete the current turn independently.
+Sub-agents have their own state and lifecycle. They can schedule their own logical callbacks and run durable fibers; the top-level parent owns the physical alarm and routes scheduled work back into the child. Recovery rows live in the child's SQLite database, so `onFiberRecovered()` and Think `chatRecovery` run with the child as `this`.
+
+Sub-agents still do not have independent physical alarm slots. The root parent keeps a small index of active child fibers, and its alarm routes recovery checks back into idle children. The parent does not need to stay awake while the child handles request-scoped work; once the child is woken it can complete the current turn independently.
 
 For a full user-facing guide to the routing primitive (`subAgent`, `onBeforeSubAgent`, `useAgent({ sub })`, `parentAgent`, `hasSubAgent`, `listSubAgents`), see [Sub-agents](./sub-agents.md).
 
@@ -622,7 +624,7 @@ A long-running agent eventually completes its purpose. The project ships, the in
 export class ProjectManager extends Agent<ProjectState> {
   async completeProject() {
     // Cancel remaining schedules
-    const schedules = this.getSchedules();
+    const schedules = await this.listSchedules();
     for (const schedule of schedules) {
       await this.cancelSchedule(schedule.id);
     }

docs/scheduling.md

@@ -269,7 +269,7 @@ async syncData() {
 
 Durable Objects are evicted after a period of inactivity (typically 70-140 seconds with no incoming requests, WebSocket messages, or alarms). During long-running operations — streaming LLM responses, waiting on external APIs, running multi-step computations — the agent can be evicted mid-flight.
 
-`keepAlive()` prevents this by creating a 30-second heartbeat schedule that keeps the agent active until you are done:
+`keepAlive()` prevents this by holding an alarm-backed heartbeat ref that keeps the agent active until you are done:
 
 ```typescript
 const dispose = await this.keepAlive();
@@ -299,10 +299,12 @@ 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 `getSchedules()` and the `agents:schedule` diagnostics channel.
+`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.
 
 The heartbeat does not conflict with your own schedules — the alarm system multiplexes all schedules and the keepAlive heartbeat through a single alarm slot.
 
+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.
+
 ### Multiple concurrent callers
 
 Each `keepAlive()` call returns an independent disposer:
@@ -340,7 +342,7 @@ dispose2(); // Ref count reaches 0 — agent can go idle
 Retrieve a scheduled task by its ID:
 
 ```typescript
-const schedule = await this.getSchedule(scheduleId);
+const schedule = await this.getScheduleById(scheduleId);
 
 if (schedule) {
   console.log(
@@ -359,24 +361,24 @@ Query scheduled tasks with optional filters:
 
 ```typescript
 // Get all scheduled tasks
-const allSchedules = this.getSchedules();
+const allSchedules = await this.listSchedules();
 
 // Get only cron jobs
-const cronJobs = this.getSchedules({ type: "cron" });
+const cronJobs = await this.listSchedules({ type: "cron" });
 
 // Get tasks in the next hour
-const upcoming = this.getSchedules({
+const upcoming = await this.listSchedules({
   timeRange: {
     start: new Date(),
     end: new Date(Date.now() + 60 * 60 * 1000)
   }
 });
 
 // Get a specific task by ID
-const specific = this.getSchedules({ id: "abc123" });
+const specific = await this.listSchedules({ id: "abc123" });
 
 // Combine filters
-const upcomingCronJobs = this.getSchedules({
+const upcomingCronJobs = await this.listSchedules({
   type: "cron",
   timeRange: {
     start: new Date(),
@@ -399,6 +401,8 @@ if (cancelled) {
 }
 ```
 
+`cancelSchedule(id)` only matches schedules owned by the agent it is called on. A top-level agent cannot cancel a sub-agent's schedules by id, and a sub-agent cannot reach a sibling's schedules. To clear every schedule under a sub-agent (and any of its descendants), call `parent.deleteSubAgent(Cls, name)` from the parent — that bulk-cancels the prefix and tears the sub-agent down.
+
 **Example: Cancellable reminders**
 
 ```typescript
@@ -504,7 +508,7 @@ class PollingAgent extends Agent {
 
   async stopPolling() {
     // Cancel all polling schedules
-    const schedules = this.getSchedules({ type: "delayed" });
+    const schedules = await this.listSchedules({ type: "delayed" });
     for (const schedule of schedules) {
       if (schedule.callback === "poll") {
         await this.cancelSchedule(schedule.id);
@@ -815,13 +819,33 @@ 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()
+
+```typescript
+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()
+
+```typescript
+async listSchedules(criteria?: {
+  id?: string;
+  type?: "scheduled" | "delayed" | "cron" | "interval";
+  timeRange?: { start?: Date; end?: Date };
+}): Promise<Schedule<unknown>[]>
+```
+
+Get scheduled tasks matching the criteria. This method works in both top-level agents and sub-agents.
+
 ### getSchedule()
 
 ```typescript
 getSchedule<T = string>(id: string): Schedule<T> | undefined
 ```
 
-Get a scheduled task by ID. This method is synchronous.
+Deprecated. Get a scheduled task by ID synchronously. This method only works in top-level agents; use `await this.getScheduleById(id)` instead.
 
 ### getSchedules()
 
@@ -833,7 +857,7 @@ getSchedules<T = string>(criteria?: {
 }): Schedule<T>[]
 ```
 
-Get scheduled tasks matching the criteria. This method is synchronous.
+Deprecated. Get scheduled tasks matching the criteria synchronously. This method only works in top-level agents; use `await this.listSchedules(criteria)` instead.
 
 ### cancelSchedule()
 
@@ -849,7 +873,7 @@ Cancel a scheduled task. Returns `true` if cancelled, `false` if not found.
 async keepAlive(): Promise<() => void>
 ```
 
-Create a 30-second heartbeat schedule that prevents the Durable Object from being evicted due to inactivity. Returns a disposer function that cancels the heartbeat when called. The disposer is idempotent — calling it multiple times is safe.
+Create an alarm-backed heartbeat that prevents the Durable Object from being evicted due to inactivity. Returns a disposer function that cancels the heartbeat when called. The disposer is idempotent — calling it multiple times is safe.
 
 See [Keeping the Agent Alive](#keeping-the-agent-alive) for usage details.