Motivation

Several native Durable Object RPC entry points on an Agent depend on the caller having resolved the stub through getAgentByName() / getServerByName(), whose setName() round-trip is what runs onStart() before the first call. A surface reached on a stub that skipped that round-trip could execute before onStart() completed — seeing un-hydrated facet state, an un-restored MCP client, or a schema that a hook expected to exist.

This makes every RPC entry surface self-sufficient: it initializes itself before running, so init ordering no longer rides on the resolution-time round-trip. That is also the prerequisite for later dropping the round-trip on prop-less resolution.

This is pure hardening — no public API changes and no change to documented resolution semantics. getAgentByName / getServerByName keep their existing behavior (including the props round-trip).

The guarantee

Every RPC entry surface now runs onStart() before executing, mirroring the guard that _cf_invokeAgentPath already used:

• _onEmail
• the sub-agent bridges _cf_invokeSubAgent / _cf_invokeSubAgentPath
• the schedule / fiber dispatch callbacks _cf_dispatchScheduledCallback / _cf_checkRunFibersForFacet
• the WebSocket-forwarding facet handlers _cf_handleSubAgentWebSocket{Connect,Message,Close}
• every root facet RPC method: schedules (_cf_scheduleForFacet, _cf_scheduleEveryForFacet, _cf_cancelScheduleForFacet, _cf_getScheduleForFacet, _cf_listSchedulesForFacet, _cf_cleanupFacetPrefix), keepAlive (_cf_acquireFacetKeepAlive, _cf_releaseFacetKeepAlive), facet-run registration (_cf_registerFacetRun, _cf_unregisterFacetRun), _cf_destroyDescendantFacet, _cf_broadcastToSubAgent, and the sub-agent connection routing methods (_cf_subAgentConnectionMetas, _cf_sendToSubAgentConnection, _cf_closeSubAgentConnection, _cf_setSubAgentConnectionState).

User-defined RPC methods on cold stubs also initialize before running, via a synchronous fast path in the _autoWrapCustomMethods wrapper (withAgentContext).

MCP storage helpers (McpAgent.getInitializeRequest / setInitializeRequest / stream-id helpers, onSSEMcpMessage) are intentionally left unchanged: they are only ever reached through getAgentByName(..., { props }), which keeps its setName round-trip in this change, so they are always invoked on an already-initialized stub.

Re-entrancy and correctness design

The wrapper must add init without regressing local-call semantics. It handles:

• Synchronous returns preserved. The warm path is a synchronous _selfInitCompleted flag check; an already-initialized wrapped method called locally returns its value synchronously (it does not start returning a promise). Cold entry is inherently async — it only happens across an RPC boundary.
• Re-entrancy during onStart(). The framework's onStart() runs inside the agent's ALS context, so a wrapped method it calls locally takes the existing agent === this fast path and runs directly — it never re-triggers init (which would deadlock the in-flight init or double-run onStart()).
• Concurrent cold RPCs init exactly once. The in-flight init promise is memoized, so two concurrent cold RPCs share a single onStart() run rather than double-triggering it.
• Init failure does not hang. On failure the memo is cleared and the error is surfaced to the caller, so the next call retries rather than replaying a cached rejection. partyserver catches an onStart() throw inside blockConcurrencyWhile and rethrows it afterward, so the DO is not reset and the next entry re-runs onStart().
• Hibernation-safe. Both signals are in-memory only, so a woken (cold) instance re-initializes, which is correct.
• Raw-id addressing unchanged. Self-init is gated on name-addressed DOs (ctx.id.name defined). A raw-id DO (newUniqueId() / idFromString() without a setName() bootstrap) has no resolvable name — the case partyserver's name getter throws on — so the wrapper preserves the historical behavior of invoking the method without forcing init there.

Internal zero-round-trip resolution

Because every reachable surface is now self-sufficient, the internal resolution sites that only ever invoke self-initializing methods and never pass props resolve their stub directly (a new internal getAgentStubByName helper that mirrors getServerByName's jurisdiction / locationHint handling but issues zero RPCs) instead of paying the setName round-trip:

• _rootAlarmOwner (used by ~9 schedule/keepAlive/broadcast call sites)
• parentAgent (top-level and facet-proxy branches)
• AgentWorkflow's agent resolution (top-level and facet origins)
• email routing

The public getAgentByName / getServerByName are untouched.

Tests

New src/tests/self-init.test.ts (with test agents in src/tests/agents/self-init.ts):

• a user-defined RPC method invoked on a cold stub obtained via raw env.NS.get(idFromName(...)) initializes (onStart ran, schema created in onStart is usable, this.name correct);
• onStart calling its own wrapped method does not deadlock or double-init (onStart runs exactly once);
• two concurrent cold RPCs init exactly once;
• a synchronous wrapped method called after init (both directly and locally from another method) returns synchronously, not a promise;
• _onEmail on a cold stub (routed via routeAgentEmail, which now resolves zero-RTT) initializes before dispatch.

The init-failure behavior is documented inline rather than asserted: an onStart() that rejects inside partyserver's blockConcurrencyWhile makes the runtime log an "uncaught (in promise)" that the workers test pool reports as an unhandled error and fails the run. That artifact reproduces identically on the pre-existing getServerByName round-trip path, so it is a test-harness limitation, not a behavior this change introduces. The behavior itself (RPC rejects, does not hang, retries) was verified manually.

Full agents package test suite passes (2279 tests), plus pnpm run check.