add task management system with lifecycle tracking

[whoiskatrin]

adds a task system to the agents sdk so we can run long operations with proper tracking and updates. includes a @task() decorator, workflow support, a unified client api for real-time status, and server-side task management. tasks are persisted, can be canceled, and stream progress and events over websockets

[changeset-bot]

⚠️ No Changeset found

Latest commit: 2f93bbe

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

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

[pkg-pr-new]

Open in StackBlitz

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

commit: 2f93bbe

[claude]

Claude Code Review

Summary: Well-architected task system with solid lifecycle tracking. A few substantive issues to address.

Issues Found

1. Race Condition in Task Abort Controller Cleanup (packages/agents/src/task.ts:888-890)
The abort controller is cleaned up immediately in complete(), fail(), and abort() methods, but _executeTask may still reference it during timeout checks. If a task completes while a timeout check is in progress, this could cause issues.

2. Missing Workflow Tests
No test coverage found for the workflow integration (workflow.ts, AgentWorkflow class). This is a critical component that needs tests for:

• Workflow dispatch and lifecycle
• Update batching behavior
• Agent callback retry logic
• Error handling paths

3. Retry Logic Issue in _executeTask (packages/agents/src/index.ts:1145-1192)
The exponential backoff with deadline checking uses await setTimeout() in a loop checking every second. This could drift or accumulate timing errors. Consider using a single timeout or alarm-based approach.

4. Task Deadline Cache Never Invalidated on Timeout Update (packages/agents/src/task.ts:344)
The deadlineCache is populated when a task starts running but only cleaned up on completion/failure/abort. If a task's deadline is somehow modified while running (though unlikely), the cache would be stale.

5. Incomplete Validation in _validateWorkflowUpdate (packages/agents/src/index.ts)
Referenced but implementation not shown in diff. Ensure this validates:

• taskId exists in tasks table
• status transitions are valid (e.g., can't complete an already failed task)
• Required fields based on status

6. SQL Injection Protection (packages/agents/src/task.ts:810-838)
The dynamic query building in list() uses string concatenation with a fallback to JS filtering. The comment says "TODO: Refactor to use ctx.storage.sql.exec for dynamic query support". This TODO should be addressed or the JS fallback should be the primary path with a clear comment explaining why.

Minor Observations

• Example app uses hardcoded OpenAI calls - fine for demo
• Good use of observability hooks throughout
• Deadline-based timeout checking is cleaner than setTimeout accumulation
• Rate limiting logic in _syncTaskToState is well-thought-out

Recommendation

Address issues #1, #2, #5, and #6 before merging. Issues #3 and #4 are lower priority but should be tracked.