Schedule fixes #653

deathbyknowledge · 2025-11-17T10:16:26Z

`this.destroy()` in handlers

Currently, calling this.destroy inside a schedule won't clean up the Agent properly. There are 2 issues at play:

this.destroy deletes all tables from SQLITE (and all other storage). This causes an error in the alarm handler since the Agent alarm tries to update the cf_agent_schedules table after the schedule callback is run.
this.ctx.abort throws an uncatchable error to force DO eviction. When this happens inside the alarm handler the runtime attempts a re-try.

To address both, this PR:

Sets an in-memory flag this.destroyed = true from within this.destroy to skip SQLITE updates in the alarm handler whenever it's set.
Now yields this.ctx.abort to the event loop so we don't throw the error in the alarm handler's context. Since we're always in a single-threaded runtime we ensure that the handler completes before the this.ctx.abort task in the event loop is executed.
(IO ops after this.destroy could see this.ctx.abort being called before completion but adding anything after this.destroy is an anti-pattern anyway so I think it's fine)

Fixes #616.

`this.ctx.blockConcurrencyWhile(...)` in constructor

Inside the Agent there's a manual call to await this.alarm() (for which we use the bCW) to run due schedules. Since we're using this.ctx.storage.setAlarm internally, the alarm method is called by the runtime after the constructor anyway, so we can get rid of our manual call.

So basically:
BEFORE: constructor() -> await this.alarm() (called manually) -> alarm() (called by the runtime)
NOW: constructor() -> alarm() (called by the runtime)

Fixes #600

PS: There are 2 seemingly unrelated changes included:

this._scheduleNextAlarm wasn't taking into account schedules for now (e.g. this.schedule(0, "destroy")).
Set observability = undefined in the test DOs to reduce stdout noise.

changeset-bot · 2025-11-17T10:16:29Z

🦋 Changeset detected

Latest commit: 8dffadb

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

This PR includes changesets to release 1 package

Name	Type
agents	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

claude · 2025-11-17T10:17:51Z

Claude Code Review

Issues found:

Race condition in destroy flag checks (packages/agents/src/index.ts:1317, 1326, 1334)
- The _destroyed checks are placed after SQL operations that can fail when tables are dropped
- If destroy() runs between executing a schedule callback and the SQL UPDATE/DELETE, those operations will throw
- Move the if (this._destroyed) return; check to the beginning of the alarm loop (after line 1275) to short-circuit before any DB operations
Test reliability issue (packages/agents/src/tests/alarms.test.ts:22)
- 50ms timeout is arbitrary and may cause flaky tests on slower CI environments
- Consider using vi.advanceTimersByTime() with fake timers, or increase timeout to 200-500ms
Missing test coverage:
- No test verifying that cron schedules are properly updated (not deleted) when _destroyed=true
- No test for the blockConcurrencyWhile removal fix (issue Schedules can't process long AI requests #600)
- No test for immediate schedules (this.schedule(0, ...))

Suggested fix for #1:

// After line 1275, add early return:
if (result && Array.isArray(result)) {
  for (const row of result) {
    if (this._destroyed) return; // Check at loop start
    
    const callback = this[row.callback as keyof Agent<Env>];
    // ... rest of loop
    
    // Remove the three other _destroyed checks since we check at loop start

Otherwise the approach is sound and properly addresses the reported issues.

pkg-pr-new · 2025-11-17T10:18:10Z

Open in StackBlitz

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

commit: 8dffadb

Add a destroyed flag and yield context abort functionality.

Updates documentation to reflect that destroy() can now be safely called within scheduled task callbacks. The Agent properly handles cleanup by: - Setting an internal flag to skip remaining database updates - Yielding ctx.abort() to the event loop for clean alarm handler completion This addresses the fix in cloudflare/agents#653 where calling destroy() inside a schedule previously caused errors. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>

threepointone · 2025-11-17T10:55:00Z

📚 Documentation has been updated to reflect these changes.

Documentation PR: cloudflare/cloudflare-docs#26558

The following documentation pages have been updated:

/agents/concepts/agent-class/ - Updated destroy() method documentation to note it can be safely called within scheduled tasks
/agents/api-reference/schedule-tasks/ - Added note about calling destroy() in scheduled task callbacks

The documentation now explains that when destroy() is called from within a schedule callback:

An internal flag is set to skip remaining database updates
ctx.abort() is yielded to the event loop to ensure clean alarm handler completion

Updates documentation to reflect that destroy() can now be safely called from within scheduled task callbacks. The Agent SDK now: - Sets an internal flag to prevent database updates after destruction - Defers ctx.abort() to the event loop to allow handlers to complete Related to cloudflare/agents#653 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>

threepointone · 2025-11-17T10:55:44Z

Documentation has been updated to reflect this change in cloudflare-docs#26558.

Updates schedule-tasks.mdx to reflect changes from cloudflare/agents#653: - Add example showing immediate task scheduling (delay = 0) - Document safe usage of destroy() within scheduled callbacks - Explain that Agent SDK defers destruction to ensure scheduled tasks complete Addresses the fix for issue #616 where calling destroy() inside a schedule would cause errors and retry loops. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>

threepointone · 2025-11-17T10:57:44Z

📚 Documentation Updated

The documentation has been updated to reflect the changes in this PR.

Updated documentation:

Schedule tasks - Added section on lifecycle management with scheduled tasks and immediate scheduling examples

Cloudflare Docs PR: cloudflare/cloudflare-docs#26558

Changes include:

Documentation of safe destroy() usage within scheduled callbacks
Example showing immediate task scheduling (delay = 0)
Explanation of how the Agent SDK defers destruction to ensure scheduled tasks complete successfully

This comment was automatically generated by the documentation sync workflow.

threepointone · 2025-11-17T13:05:44Z

Documentation Sync

📚 Documentation has been synced to cloudflare-docs

Docs PR: cloudflare/cloudflare-docs#26558

Changes synced:

Updated destroy() method documentation to clarify behavior when called within scheduled tasks
Added example showing destroy() working correctly in scheduled callbacks
Documented support for immediate schedules (0 second delay)
Added lifecycle management section with self-destructing agent example

The documentation now reflects the fixes for calling destroy() in scheduled contexts and the support for immediate schedule execution.

threepointone · 2025-11-17T13:14:11Z

Documentation for this PR has been updated in cloudflare/cloudflare-docs#26558

threepointone · 2025-11-17T13:18:15Z

📚 Documentation update: cloudflare/cloudflare-docs#26558

This PR documents the schedule bug fixes, including:

Support for immediate schedule execution (delay=0)
Safe destroy() calls within scheduled callbacks
Internal implementation details (destroyed flag and event loop yielding)

mattzcarey

looks good. I was seeing this all the time for the playground :))

threepointone

some notes, will stamp after clarification.

threepointone · 2025-11-18T09:20:55Z

.changeset/neat-beds-cheat.md

+"agents": patch
+---
+
+add destroyed flag and yield ctx.abort


this isn't clear, can you make it just a bit clearer what it does?

packages/agents/src/tests/alarms.test.ts

threepointone · 2025-11-18T09:22:49Z

packages/agents/src/tests/worker.ts

 }

 export class TestCaseSensitiveAgent extends Agent<Env> {
+  observability = undefined;


why removing observability on all these agents?

They flood stdout with logs about schedules, connections etc. I've never found them particularly useful (at least in the test runs).

There's still a lot of workerd internal logs but I appreciate less noise unless others find them useful

fair. tbh I'm very unhappy with our observability stuff anyway, I want to rip it all out.

threepointone · 2025-11-18T09:24:32Z

packages/agents/src/index.ts

-      `;
-
-        // execute any pending alarms and schedule the next alarm
-        await this.alarm();


really wish I could remember why we did this. but I'll keep an.eye out for it.

add destroyed flag and yield abort

5c0c76c

deathbyknowledge added 2 commits November 17, 2025 11:18

Implement destroyed flag and context abort

7977d49

Add a destroyed flag and yield context abort functionality.

add test and fix immediate schedules

c2b5ce2

threepointone mentioned this pull request Nov 17, 2025

add destroyed flag and yield ctx.abort cloudflare/cloudflare-docs#26558

Open

remove manual alarm call in constructor

9e279fe

deathbyknowledge marked this pull request as ready for review November 17, 2025 13:12

deathbyknowledge changed the title ~~add destroyed flag and yield ctx.abort~~ Schedule fixes Nov 17, 2025

mattzcarey approved these changes Nov 17, 2025

View reviewed changes

This was referenced Nov 17, 2025

Impossible to fully delete agent via a schedule #616

Closed

Schedules can't process long AI requests #600

Closed

threepointone reviewed Nov 18, 2025

View reviewed changes

update test + better changeset

8dffadb

deathbyknowledge requested a review from threepointone November 18, 2025 10:51

threepointone approved these changes Nov 18, 2025

View reviewed changes

deathbyknowledge merged commit 412321b into main Nov 18, 2025
12 checks passed

deathbyknowledge deleted the allow-destroy-in-schedules branch November 18, 2025 10:55

threepointone mentioned this pull request Nov 18, 2025

Version Packages #657

Open

Schedule fixes #653

Schedule fixes #653

Conversation

deathbyknowledge commented Nov 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

this.destroy() in handlers

this.ctx.blockConcurrencyWhile(...) in constructor

Uh oh!

changeset-bot bot commented Nov 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

claude bot commented Nov 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Claude Code Review

Uh oh!

pkg-pr-new bot commented Nov 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

threepointone commented Nov 17, 2025

Uh oh!

threepointone commented Nov 17, 2025

Uh oh!

threepointone commented Nov 17, 2025

📚 Documentation Updated

Uh oh!

threepointone commented Nov 17, 2025

Documentation Sync

Changes synced:

Uh oh!

threepointone commented Nov 17, 2025

Uh oh!

threepointone commented Nov 17, 2025

Uh oh!

mattzcarey left a comment

Choose a reason for hiding this comment

Uh oh!

threepointone left a comment

Choose a reason for hiding this comment

Uh oh!

threepointone Nov 18, 2025

Choose a reason for hiding this comment

Uh oh!

deathbyknowledge Nov 18, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

threepointone Nov 18, 2025

Choose a reason for hiding this comment

Uh oh!

deathbyknowledge Nov 18, 2025

Choose a reason for hiding this comment

Uh oh!

threepointone Nov 18, 2025

Choose a reason for hiding this comment

Uh oh!

threepointone Nov 18, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

deathbyknowledge commented Nov 17, 2025 •

edited

Loading

`this.destroy()` in handlers

`this.ctx.blockConcurrencyWhile(...)` in constructor

changeset-bot bot commented Nov 17, 2025 •

edited

Loading

claude bot commented Nov 17, 2025 •

edited

Loading

pkg-pr-new bot commented Nov 17, 2025 •

edited

Loading