feat: add Agent.keepAliveWhile() scoped callback API

[threepointone]

Summary

Adds keepAliveWhile(fn) to the Agent class — a scoped version of keepAlive() that runs an async function while keeping the Durable Object alive, and automatically cleans up the heartbeat when the function completes (or throws).

This builds on the keepAlive() method (from #1029) and is now the recommended way to prevent idle eviction during long-running work.

Motivation

The manual keepAlive() + disposer pattern requires developers to remember to call the disposer in a finally block. keepAliveWhile(fn) makes this structural — you cannot forget to clean up:

// Before (manual)
const dispose = await this.keepAlive();
try {
  await longWork();
} finally {
  dispose();
}

// After (scoped — recommended)
await this.keepAliveWhile(async () => {
  await longWork();
});

Both APIs remain available. keepAlive() is still useful when the lifetime spans multiple event callbacks (e.g., onConnect → onClose).

Changes

File	What changed
packages/agents/src/index.ts	Added keepAliveWhile<T>(fn) method
packages/ai-chat/src/index.ts	_reply() now uses keepAliveWhile() instead of manual keepAlive() + .finally()
packages/agents/src/experimental/forever.ts	Added keepAliveWhile to AgentLike Pick type
packages/ai-chat/src/experimental/forever.ts	Added keepAliveWhile to AIChatAgentLike Pick type
packages/agents/src/tests/agents/keep-alive.ts	Added runWithKeepAliveWhile() and runWithKeepAliveWhileError() test methods
packages/agents/src/tests/keep-alive.test.ts	2 new tests: success path (returns result + cleans up) and error path (cleans up despite throw)
docs/scheduling.md	Documented keepAliveWhile() in the "Keeping the Agent Alive" section and API reference
docs/agent-class.md	Updated one-liner to mention keepAliveWhile
.changeset/keep-alive-agent.md	Updated to cover both methods

Notes for reviewers

• keepAliveWhile is intentionally simple — 7 lines, delegates entirely to keepAlive() with try/finally. No new scheduling primitives.
• AIChatAgent _reply() is now cleaner: this.keepAliveWhile(() => this._tryCatchChat(...)) replaces the previous keepAlive() + .finally(() => dispose()) pattern.
• The experimental fiber module still uses keepAlive() directly in _startFiber — this is intentional because the disposer needs to be passed through the retry loop across multiple _runFiber iterations. keepAliveWhile does not fit that pattern.
• Generic return type — keepAliveWhile<T>(fn: () => Promise<T>): Promise<T> preserves the caller's return type, so const result = await this.keepAliveWhile(async () => 42) correctly infers number.

Testing

• 6 keepAlive tests total (4 for keepAlive(), 2 for keepAliveWhile())
• All 290 existing tests pass
• 45/45 projects typecheck
• Build clean, exports valid, formatting clean, lint clean

[changeset-bot]

⚠️ No Changeset found

Latest commit: f9f442e

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 changesets to release 2 packages

Name	Type
agents	Minor
@cloudflare/ai-chat	Patch

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/agents@1033

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

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

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

commit: cf3d2ee