Fiber improvements: configurable keepAlive, E2E tests, type safety, docs

[threepointone]

Summary

This branch improves the experimental fiber system across several dimensions: testability, type safety, developer experience, and documentation accuracy.

Configurable keepAliveIntervalMs

• Added keepAliveIntervalMs to AgentStaticOptions (default 30s, matching existing behavior)
• _scheduleNextAlarm() now uses this._resolvedOptions.keepAliveIntervalMs instead of a hardcoded constant
• Enables E2E test workers to set a 2s interval for fast alarm-based recovery instead of waiting 30s

Comprehensive E2E fiber tests

Since workerd now persists alarm state to disk (cloudflare/workerd#6104), alarms survive process restarts — matching production behavior. The E2E test suite leverages this with 5 real-eviction scenarios (SIGKILL + restart, no manual triggerAlarm() workaround):

Test	What it validates
Automatic recovery via persisted alarm	Core scenario: spawn fiber, kill, restart, automatic recovery
Checkpoint preservation through real kill	Snapshot survives SIGKILL, fiber resumes from last checkpoint
Multiple concurrent fiber recovery	2+ fibers all recover after a single kill/restart
Completed fiber survives restart	Completed fibers aren't spuriously re-executed
Recovery fires onFiberRecovered hook	Hook is called with correct metadata on recovery

Added test:e2e script to packages/agents/package.json.

Fiber unit tests re-enabled in CI

The 28 fiber unit tests in packages/agents/src/tests/fiber.test.ts were excluded from CI because they hung. Root cause: tests spawned slowWork with 5-10 second durations, then simulated eviction without stopping the background execution. Stale setTimeout timers held keepAlive refs, generating alarm chains the vitest worker pool couldn't shut down.

Fix: shortened all slowWork durations from 5000-10000ms to 500ms (tests only need fibers "running" at the moment of eviction) and set keepAliveIntervalMs: 2_000 on the test agent. Removed the exclusion from vitest.config.ts — fiber tests now run in CI.

spawnFiber type safety

Changed FiberMethods.spawnFiber parameter from methodName: string to methodName: keyof this & string. TypeScript's polymorphic this resolves to the concrete class at the call site, giving users autocomplete for their method names.

Experimental warning moved to first use

Moved the console.warn from the withFibers constructor to spawnFiber() (fires once). Think agents that only use chat never see the experimental warning.

Flaky test fixes (ai-chat)

• client-tool-duplicate-message.test.ts: Replaced 17 instances of setTimeout(200) with waitForIdleForTest() — waits for actual processing instead of a fixed timer
• message-concurrency.test.ts: Increased streaming duration in the merge test so req-merge-1 is definitely still active when overlapping requests arrive

Docs updated

• experimental/forever.md: Rewrote Layer 1 (was describing unshipped scheduleEvery/_cf_fiberHeartbeat mechanism), alarm interaction, tradeoffs section, and open questions (now "resolved decisions")
• design/think.md: Fixed cf_agents_schedules description
• forever.ts: Fixed checkFibers JSDoc
• forever-fibers/README.md: Added real eviction testing note

Test plan

• npx nx run agents:test:workers — 903 tests pass (including 28 fiber unit tests, previously excluded)
• npm run test:e2e -w packages/agents — 5 E2E fiber eviction tests pass
• npx tsc --noEmit -p packages/agents/tsconfig.json — clean
• npx tsc --noEmit -p packages/think/tsconfig.json — clean
• npx tsc --noEmit -p packages/agents/src/tests/tsconfig.json — clean
• npx tsc --noEmit -p packages/think/src/tests/tsconfig.json — clean
• ai-chat test suite passes (client-tool-duplicate-message, message-concurrency)

Made with Cursor

---

[changeset-bot]

⚠️ No Changeset found

Latest commit: 56d76d7

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

agents

npm i https://pkg.pr.new/agents@1252

@cloudflare/ai-chat

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

@cloudflare/codemode

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

hono-agents

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

@cloudflare/shell

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

@cloudflare/think

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

@cloudflare/voice

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

@cloudflare/worker-bundler

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

commit: 56d76d7

[devin-ai-integration]

✅ Devin Review: No Issues Found

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

View in Devin Review to see 5 additional findings.