Migrate facet bootstrap to explicit FacetStartupOptions.id

[threepointone]

Summary

Migrates facet bootstrap in Agent from the __ps_name storage-write hack to the documented Cloudflare facet API: pass id: parentNs.idFromName(name) to ctx.facets.get() so the facet gets its own ctx.id.name. PartyServer's existing 0.5.x name getter then resolves this.name correctly without any override mechanism, storage write, or cold-wake hydrate cost.

Closes #1385.

Background

partyserver 0.5.0 made this.name resolve from ctx.id.name natively, eliminating the need for setName() round-trips for normal idFromName/getByName DOs. That change initially missed facets — but for a different reason than #1385 originally diagnosed.

The original issue assumed facets have ctx.id.name === undefined and proposed that setName(facetName) should be the bootstrap primitive. Investigation showed that's wrong: facets spawned via ctx.facets.get(name, factory) without an explicit id in FacetStartupOptions inherit the parent DO's ctx.id — including ctx.id.name. So on a facet, ctx.id.name was the parent's name, and this.name silently misreported. With partyserver 0.5.x's strict setName() guard (throws on ctx.id.name mismatch), the proposed setName(facetName) migration would have failed immediately.

The actual fix lives at the call site, not in partyserver. FacetStartupOptions.id is optional and documented — when supplied, the facet sees that id as its own ctx.id. Pass id: ctx.exports[ParentClassName].idFromName(facetName) to ctx.facets.get() and the facet gets a real ctx.id.name === facetName. Partyserver's existing name getter then does the right thing automatically.

See:

• cloudflare/partykit#386 (partyserver 0.5.3) — docs and end-to-end test coverage of the explicit-id facet pattern. Zero runtime change.
• #1385 — original investigation and updated comment with current findings.

What ships

This PR is split across two commits for review clarity:

Commit 1 — chore(deps): bump partyserver to ^0.5.3 and roll up other dep updates

• Bumps partyserver from ^0.4.1 to ^0.5.3 across the workspace.
• Rolls up other dep updates that landed during this maintenance pass (@cloudflare/vite-plugin, @cloudflare/vitest-pool-workers, @cloudflare/workers-types, @openai/agents, @vitest/*, nx).
• No code changes; just package.json + package-lock.json.
• Non-breaking on its own — partyserver 0.5.3 is byte-identical to 0.5.2 at runtime.

Commit 2 — Migrate facet bootstrap to explicit FacetStartupOptions.id

Code changes (packages/agents/src/index.ts):

• _cf_resolveSubAgent now passes id: parentNs.idFromName(name) where parentNs = ctx.exports[this.constructor.name]. The parent agent is always bound (it's the entry-point DO), so its namespace is always available via ctx.exports. The id is opaque + a name; nothing routes through the namespace at runtime for facets.
• _cf_initAsFacet drops the __ps_name storage write entirely and drops the setName(name) call. Just persists cf_agents_is_facet and cf_agents_parent_path, then __unsafe_ensureInitialized() to fire onStart().
• Adds a defensive this.name !== name guard inside _cf_initAsFacet so any future bug in the parent's id construction surfaces with a clear error instead of silently mis-identifying the facet.
• New error path: if the parent class isn't bound as a DO namespace, throw a descriptive error pointing at wrangler.jsonc. If this.constructor.name looks minified (heuristic regex ^_*[a-z][a-z0-9]{0,2}$), append a bundler-config hint (e.g. esbuild keepNames: true).
• alarm() docstring: updated to reflect that this.name resolves from ctx.id.name on the happy path (including for facets).

Test coverage:

• New error-path tests in tests/sub-agent.test.ts plus TestUnboundParentAgent and TestMinifiedNameParentAgent fixtures (parent classes exported under a different name from their declaration). Both error paths now have regression guards.
• Existing test "should set this.name to the facet name" already covers the happy path; it would have caught the original bug under partyserver 0.5.x with the old __ps_name approach.

MCP test cleanup:

• Removes vestigial setName("default") + explicit onStart() call pairs from create-oauth-provider, oauth2-mcp-client, and wait-connections-e2e tests. These were originally needed for partyserver 0.4.x bootstrap but became actual ctx.id.name mismatches under 0.5.x's strict guard. Renamed setName args to match idFromName names where the test addresses by name.

Test plan

• npx vitest run --project workers passes — 1008 tests, 7 skipped, 0 failures (up from 1006 — the 2 new error-path tests)
• npm run check passes — 75 typecheck projects green, format/lint clean, exports valid
• Targeted sub-agent / alarm / MCP tests (139 tests across 8 files) verified independently
• Validated against published partyserver@0.5.3 from npm
• Reviewer to spot-check the new error message wording

Made with Cursor

---

[changeset-bot]

🦋 Changeset detected

Latest commit: 3fef2aa

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
agents	Patch

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]

✅ 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.

[pkg-pr-new]

Open in StackBlitz

agents

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

@cloudflare/ai-chat

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

@cloudflare/codemode

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

hono-agents

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

@cloudflare/shell

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

@cloudflare/think

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

@cloudflare/voice

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

@cloudflare/worker-bundler

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

commit: 3fef2aa