feat(lifecycle): add composable Scheduler

[mattzcarey]

Summary

Add Scheduler, a reusable Lifecycle capability for persistent delayed, dated, cron, and interval callbacks, under agents/schedules.

A plain Lifecycle Object installs it with no wiring:

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;
  }
}

Scheduled callbacks are registered on the Scheduler itself, so set()/every() type both the callback name and the payload against the registration and dispatch runs the registered function — the typed scheduling surface and the runtime dispatch target are the same object by construction. Callbacks run inside the host invocation context (host available through getCurrentAgent()).

Agent constructs and installs the same primitive at this.scheduler, passing only policy (retry defaults, hung-interval timeout, error routing); a composition-root resolver keeps its historical name-based this.schedule(60, "methodName") dispatching to Agent methods. Existing this.schedule(), scheduleEvery(), get/list/cancel, retries, observability, sub-agent routing, OOM handling, and callback behavior remain compatible delegators.

Stability

agents/lifecycle and the capability surfaces built on it (Scheduler, MCPClientManager as an installed capability) are marked @experimental — the composition surface may change between releases. Agent's established APIs (this.schedule() and friends, agent.mcp) are stable and unaffected.

Capability services: the composition contract

LifecycleCapability grants every installed capability one standard service surface, and it is the whole contract — a capability configures nothing else:

• storage — the Durable Object's storage; each capability owns its own tables.
• ready() / starting() — startup coordination and state.
• alarms.rearm() / alarms.disabled() — shared-alarm coordination and teardown state.
• runInHostContext() — the one boundary for running capability-held user callbacks inside the host invocation context.
• events.emit() — best-effort telemetry under the capability's stable identity.
• routes — generic capability message routing between Lifecycles.

Host-specific bindings and protocol adapters stay explicit constructor dependencies. Scheduler is the first capability built purely on this surface; MCPClientManager now receives storage the same way.

Lifecycle-owned alarm

Lifecycle owns the single physical Durable Object alarm. A capability keeps its durable work in its own tables and optionally implements getNextAlarm() / onAlarm(); when its durable state changes it calls lifecycle.alarms.rearm(). Lifecycle serializes recalculation, reads contributions from all capabilities plus the host, and arms the earliest time. An exclusive contribution ({ time, exclusive: true }) replaces ordinary candidates while present — Agent uses this for pending teardown.

When the platform alarm fires, Lifecycle starts capabilities and the host if necessary, runs capability onAlarm() hooks in registration order, runs host onAlarm(), then rearms. Rearm requests during startup are coalesced. This is deliberately not a dependency on Scheduler: a future Fiber or MCP capability owns its own tables and projects its earliest required wake through the same contract.

Host adaptation happens only at a composition root

Three internal apertures adapt a Lifecycle to its host; a plain Lifecycle Object configures none of them:

• event sink — Agent routes capability events into its existing observability interface; plain objects publish to the existing agents:* diagnostics channels.
• route transport — Agent carries owner-scoped envelopes between facets through one generic RPC aperture; Scheduler routes facet CRUD and due-callback dispatch over it without facet-specific methods. Existing facet rows stay in the root table.
• host invoker — Agent wraps capability-run user callbacks (scheduled callbacks today, future capability callbacks tomorrow) in its tracing invocation boundary, so they get the same span scope as every other Agent entry point. A fourth, Scheduler-specific aperture — a callback-name resolver — carries Agent's name-based compatibility lookup without putting host-method dispatch on the generic service surface.

There is no Agent-specific Scheduler adapter.

Domain boundaries

• Lifecycle: physical alarm selection, serialization, dispatch, rearming, the host invocation boundary, capability-event publication.
• agents/schedules/schedule-timing: pure timing rules — parsing when inputs and interval bounds into a ScheduleTiming.
• Scheduler: schedule schema/migration, CRUD with owner scoping, idempotency, retries, due-row processing, event production, next-wake contribution. Public surface: new Scheduler({ callbacks, ...policy }), set/every (typed against the registration), get, list, cancel; internal synchronous reads back Agent's deprecated sync compat surface.
• Agent composition root: policy options and the apertures above.
• Host contribution: transitional alarm work not yet extracted into a capability (keep-alive, fiber recovery, facet checks, Think workflow notifications).

Only Lifecycle calls setAlarm() / deleteAlarm() in production package code.

Context

Capability hooks, alarm-contribution reads, and event delivery run outside ambient host context. User callbacks run through lifecycle.runInHostContext() inside the host invocation context — Lifecycle Object context standalone, Agent context (with tracing scope) under Agent.

Test structure

Tests mirror source modules (src/<module> ↔ src/tests/<module>) inside one shared workers vitest project — the previous standalone Lifecycle project (own vitest config, wrangler, worker) is gone; its plain-worker routing is exercised by calling routeAgentRequest(request, env, { props }) directly.

• tests/lifecycle/ — Lifecycle core, one file per functionality: runtime handlers, startup (including new failure-retry, use-after-start, duplicate-ID, and unbound-capability coverage), alarm arbitration, capability events, capability routing, host context, hibernating WebSockets, identity, disposal.
• tests/<module>/capability.test.ts — each capability's contract tests (tests/schedules/, tests/mcp/client-capability.test.ts).
• tests/capabilities/ — harness Durable Objects, one file per capability (harness.ts generic, lifecycle.ts, scheduler.ts, mcp-client.ts), the lower-level sibling of tests/agents/; see its AGENTS.md for the pattern.
• tests/shared/ — generic drivers (captureDiagnosticsEvents, captureConsoleWarnings).

Testing

Capability tests follow one repeatable pattern designed for a growing roster of capabilities. Four layers, no module mocks, no fake services for capability behavior:

1. Pure units — tests/schedules/timing.test.ts.
2. Capability alone — tests/schedules/capability.test.ts installs Scheduler on SchedulerHarnessObject, a minimal real Durable Object, and drives real Lifecycle startup, real storage, real platform alarms (runDurableObjectAlarm), host context inside callbacks, and the real diagnostics sink. This is the pattern for unit testing any capability.
3. Lifecycle integration — alarm arbitration across contributors, phase order, context boundaries, routing, identity, hibernating WebSockets, eviction recovery (real evictDurableObject()).
4. Host surface — the full Agent scheduling suites.

The standalone MCP manager suites (previously hand-rolled DurableObjectStorage mocks with string-matching fake SQL) now run on the same pattern: withCapabilityHarness() binds per-test-constructed managers to a real Lifecycle over real SQLite storage inside a bare CapabilityHarnessObject, with fresh managers over the same storage simulating hibernation wake-ups. Only explicit constructor dependencies (fetch stubs, OAuth provider fakes) remain mocked.

Example

examples/next/schedules — a server-only example installing Scheduler on a plain DurableObject: typed set(), cron and delayed reminders, list/cancel over HTTP, and a scheduled callback that runs with host context and records delivered reminders in the host's own table. Verified live under wrangler dev.

Package boundaries and module structure

• agents/schedules — dependency-light Scheduler primitive and runtime types (no Zod).
• agents/schedules/parser — Zod-based natural-language parsing helpers.
• agents/schedule — deprecated parser compatibility alias.
• src/mcp is no longer flat: the already-public ./mcp/client and ./mcp/server split is now real folder structure (src/mcp/client/, src/mcp/server/, shared types/rpc at the root). Public import paths are unchanged; only build entry points and dist layout moved.

Recovery and compatibility

Declared compatibility changes (also in the changeset):

• MCPClientManagerOptions.storage is removed; the manager receives storage from the Lifecycle it is installed on, so standalone construction with an explicit DurableObjectStorage is no longer supported.
• Scheduled callbacks now receive the documented parsed Schedule object as their second argument (previously the raw storage row, whose payload was an unparsed JSON string).
• Scheduler (new in this PR) registers callbacks in its constructor; Agent's name-based scheduling methods are unaffected.
• The internal _cf_*ForFacet schedule RPC methods are replaced by the generic _cf_routeLifecycle aperture (facets always run the same deployed script).
• Capability events emitted during startup are buffered and delivered after startup completes.

A brand-new Agent still creates cf_agents_schedules synchronously at construction — ensureScheduleTable is shared between Agent's schema initialization and Scheduler.onStart — so pre-startup synchronous reads and deploy-rollback windows behave exactly as on main (regression-tested).

Preserved behavior includes one-shot/cron/interval semantics; idempotent creation and lost-alarm rearming; callback retries and platform-transient deferral; alarm memory-limit circuit breaking; hung-interval recovery and duplicate warnings; sub-agent owner isolation and root callback routing; schedule migration/data preservation; keep-alive, fiber, facet-run, Think notification, and deferred-destroy alarm arbitration; explicit top-level destroy cleanup; existing Agent observability overrides and diagnostics-channel routing.

Verification

On the final branch state:

• Agent Workers: 1,908/1,908 across 107 files (includes the new lifecycle-core, capability, and timing suites)
• Think Workers: 886/886
• AI Chat Workers: 655/655
• repository typecheck: all projects (previously-broken standalone MCP test typings fixed)
• package build, exports, formatting, lint, sherif: green
• multi-agent adversarial review of the refactor diff (six lenses, two verifiers per finding): 16 candidate findings, 10 confirmed, all fixed — including reverting a constructor-time retry validation that would have bricked Durable Objects with historically tolerated invalid retry configs
• examples/next/schedules exercised live under wrangler dev (create → alarm delivery with host context → cancel)

[changeset-bot]

🦋 Changeset detected

Latest commit: 7359ea6

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 3 packages

Name	Type
agents	Minor
@cloudflare/think	Patch
@cloudflare/agent-think	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[pkg-pr-new]

Open in StackBlitz

agents

npm i https://pkg.pr.new/cloudflare/agents@1897

@cloudflare/ai-chat

npm i https://pkg.pr.new/cloudflare/agents/@cloudflare/ai-chat@1897

@cloudflare/channels

npm i https://pkg.pr.new/cloudflare/agents/@cloudflare/channels@1897

@cloudflare/codemode

npm i https://pkg.pr.new/cloudflare/agents/@cloudflare/codemode@1897

hono-agents

npm i https://pkg.pr.new/cloudflare/agents/hono-agents@1897

@cloudflare/shell

npm i https://pkg.pr.new/cloudflare/agents/@cloudflare/shell@1897

@cloudflare/think

npm i https://pkg.pr.new/cloudflare/agents/@cloudflare/think@1897

@cloudflare/voice

npm i https://pkg.pr.new/cloudflare/agents/@cloudflare/voice@1897

@cloudflare/worker-bundler

npm i https://pkg.pr.new/cloudflare/agents/@cloudflare/worker-bundler@1897

commit: 7359ea6

[devin-ai-integration]

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no bugs or issues to report.