fix(agents): initialize cold native RPC calls - #2005
Open
cjol wants to merge 5 commits into
Open
Conversation
…bject RPC methods run on a cold instance. Fixes #1990. ## Why - Native Durable Object RPC invokes methods directly, bypassing the PartyServer entry points that normally run `onStart()`. A method that wakes an evicted Agent can therefore observe missing session state, stale caches, unrestored MCP connections, or incomplete recovery. - `getAgentByName()` cannot provide a lasting guarantee because stubs outlive the in-memory instances they address. Eviction or deployment can make any later RPC the next cold-start entry point. - Requiring every inherited and application-defined RPC method to call `__unsafe_ensureInitialized()` would expose framework lifecycle concerns to users and leave room for inconsistent coverage. - Eagerly starting the lifecycle from the base constructor would run before derived fields and constructors finish. Instead, this change extends the existing method-context wrapper, arms it after construction, and initializes only when a public application RPC is the cold entry point. ## Architectural Changes Before: ```text native RPC -> application method | +-> may observe pre-onStart state ``` After: ```text native RPC -> Agent invocation wrapper -> PartyServer initialization -> application method | +-> lifecycle/control-plane methods retain their existing dispatch ``` - Agent tracks whether RPC initialization is constructing, pending, starting, or started so startup extension points can call public methods without recursively initializing. - Prototype discovery now wraps inherited Agent and application methods while preserving callable metadata and the nearest property descriptor. - PartyServer lifecycle and control-plane methods, plus underscore-prefixed framework internals, remain outside the application RPC wrapper. ## Code Changes - `agents` initializes cold public application RPC calls through `__unsafe_ensureInitialized()` and delays arming the guard until derived construction completes. - `agents` preserves synchronous constructor-local calls, inherited descriptor shadowing, and existing WebSocket `@callable` behavior. - `@cloudflare/think` marks its startup chain as in progress while it initializes session, workspace, message, protocol, and recovery state before invoking extension points. - The OAuth provider fixtures now use named IDs because their application RPCs enter Agent startup. An unbootstrapped `newUniqueId()` has no resolvable PartyServer name and is not a valid initialized Agent instance. - Patch changesets cover both `agents` and `@cloudflare/think`. ## Compatibility - Native Durable Object RPC does not require `@callable`. The decorator remains the explicit allowlist for RPC exposed through Agent WebSocket clients. - Agents addressed through `idFromName()` or `getByName()` initialize without an extra handshake. - A raw `newUniqueId()` or `idFromString()` instance must call `setName()` before its first application RPC. Once bootstrapped, PartyServer persists the name and recovers it after eviction. Previously, name-independent methods could appear to work by running against uninitialized Agent state.
🦋 Changeset detectedLatest commit: 781dce0 The changes in this PR will be included in the next version bump. This PR includes changesets to release 3 packages
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 |
![devin-ai-integration[bot]](https://avatars.githubusercontent.com/in/811515?s=60&v=4){kind=small}
agents
@cloudflare/ai-chat
@cloudflare/codemode
create-think
hono-agents
@cloudflare/shell
@cloudflare/think
@cloudflare/voice
@cloudflare/worker-bundler
commit: |
Contributor
|
I'll review this one |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This PR initializes Agent and Think instances before native Durable Object RPC methods run on a cold instance. Fixes #1990.
Why
onStart(). A method that wakes an evicted Agent can therefore observe missing session state, stale caches, unrestored MCP connections, or incomplete recovery.getAgentByName()cannot provide a lasting guarantee because stubs outlive the in-memory instances they address. Eviction or deployment can make any later RPC the next cold-start entry point.__unsafe_ensureInitialized()would expose framework lifecycle concerns to users and leave room for inconsistent coverage.Architectural Changes
Before:
After:
Code Changes
agentsinitializes cold public application RPC calls through__unsafe_ensureInitialized()and delays arming the guard until derived construction completes.agentspreserves synchronous constructor-local calls, inherited descriptor shadowing, and existing WebSocket@callablebehavior.@cloudflare/thinkmarks its startup chain as in progress while it initializes session, workspace, message, protocol, and recovery state before invoking extension points.newUniqueId()has no resolvable PartyServer name and is not a valid initialized Agent instance.agentsand@cloudflare/think.Compatibility
@callable. The decorator remains the explicit allowlist for RPC exposed through Agent WebSocket clients.idFromName()orgetByName()initialize without an extra handshake.newUniqueId()oridFromString()instance must callsetName()before its first application RPC. Once bootstrapped, PartyServer persists the name and recovers it after eviction. Previously, name-independent methods could appear to work by running against uninitialized Agent state.