Migrate facet bootstrap to explicit FacetStartupOptions.id

.changeset/agents-facet-explicit-id.md

@@ -0,0 +1,20 @@
+---
+"agents": patch
+---
+
+Migrate facet (sub-agent) bootstrap to the documented Cloudflare facet API: pass `id: parentNs.idFromName(name)` to `ctx.facets.get()` so the facet has its own `ctx.id.name`. Drops the `__ps_name` storage write and `setName()` bootstrap from `_cf_initAsFacet`.
+
+**Why this matters.** Facets spawned without an explicit `id` inherit the parent DO's `ctx.id`, so on a facet `ctx.id.name` was the _parent's_ name and `this.name` silently misreported as the parent's name. Anything that read `this.name` from inside a sub-agent (including `selfPath`, `parentPath`, and any user code) was getting the wrong value. With the explicit `id` passed at facet creation time, the runtime gives the facet a real `ctx.id.name === name` and PartyServer's existing 0.5.x `name` getter resolves `this.name` correctly without any override mechanism, storage write, or cold-wake hydrate cost. Cold-wake recovery happens for free because `idFromName` is deterministic and the factory re-runs on resume.
+
+This requires `partyserver` ≥ 0.5.3 (bumped in this release); 0.5.3 is byte-identical to 0.5.2 at runtime, only adds documentation and test coverage of the explicit-`id` facet pattern.
+
+Other changes:
+
+- **New error path.** If `subAgent()` is called from a parent class that isn't bound as a Durable Object namespace, the framework now throws a descriptive error pointing at `wrangler.jsonc`. If `this.constructor.name` looks minified (e.g. `_a`), the message includes a bundler-config hint about preserving class names.
+- **Defensive runtime check.** `_cf_initAsFacet` now asserts `this.name === name` so any future bug in the parent's id construction surfaces immediately instead of silently mis-identifying the facet.
+- **`alarm()` docstring** clarified to reflect the new resolution path (`this.name` from `ctx.id.name`, not from a storage hydrate).
+- **MCP test cleanup.** Vestigial `setName("default")` + explicit `onStart()` call pairs in `oauth2-mcp-client`, `wait-connections-e2e`, and `create-oauth-provider` test files have been removed; they were originally needed for partyserver 0.4.x bootstrap but became actual `ctx.id.name` mismatches under partyserver 0.5.x.
+
+Backward-compatible for all public APIs: `subAgent()`, `parentAgent()`, `hasSubAgent()`, `listSubAgents()`, `deleteSubAgent()`, and `abortSubAgent()` keep their signatures and semantics. The change is purely in the facet bootstrap internals; the user-facing effect is that `this.name` inside a sub-agent now correctly reports the sub-agent's own name (was previously the parent's name when run against partyserver 0.5.x).
+
+See cloudflare/partykit#386 for the partyserver-side documentation companion.

docs/sub-agents.md

@@ -102,6 +102,11 @@ The child class must:
 - Be registered under `new_sqlite_classes` in `wrangler.jsonc`
 - _Not_ share a name with the reserved token `"Sub"` (any class whose kebab-cased name equals `"sub"` is rejected; it would collide with the `/sub/` URL separator)
 
+The parent class also has requirements that are implicit for normal usage but worth knowing if you hit the related error:
+
+- Be bound as a Durable Object namespace in `wrangler.jsonc durable_objects.bindings`. (Top-level agents always are — this matters only if you try to call `subAgent()` from a class that's exported but unbound.)
+- Have its class name preserved by your bundler. The framework looks the parent up via `ctx.exports[this.constructor.name].idFromName(name)` to give the child its own `ctx.id.name`. If your bundler minifies class identifiers (e.g. esbuild without `keepNames: true`), `this.constructor.name` becomes a short id like `_a` and the lookup fails. The framework throws a descriptive error in that case pointing at the bundler config.
+
 ### `this.deleteSubAgent(Cls, name)`
 
 Abort a running sub-agent and permanently wipe its storage. Idempotent — safe to call for a never-spawned or already-deleted child.
@@ -284,7 +289,7 @@ When a client connects to `/agents/{parent}/{name}/sub/{child}/{childName}`:
 
 ### Hibernation
 
-Sub-agents hibernate when idle, same as any Durable Object. `this.parentPath` is persisted during `_cf_initAsFacet` and restored on wake.
+Sub-agents hibernate when idle, same as any Durable Object. `this.name` is restored automatically from the facet's `ctx.id` (the runtime carries it across eviction). `this.parentPath` is persisted during `_cf_initAsFacet` and restored on wake.
 
 ## Scheduling in sub-agents (coming soon)
 

examples/a2a/package.json

@@ -19,16 +19,16 @@
     "workers-ai-provider": "*"
   },
   "devDependencies": {
-    "@cloudflare/vite-plugin": "^1.33.0",
-    "@cloudflare/workers-types": "^4.20260420.1",
+    "@cloudflare/vite-plugin": "^1.33.2",
+    "@cloudflare/workers-types": "^4.20260425.1",
     "@tailwindcss/vite": "^4",
     "@types/node": "^25.6.0",
     "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
     "@vitejs/plugin-react": "^6.0.1",
-    "tailwindcss": "^4.2.2",
+    "tailwindcss": "^4.2.4",
     "typescript": "^6.0.3",
-    "vite": "^8.0.9",
-    "wrangler": "^4.84.0"
+    "vite": "^8.0.10",
+    "wrangler": "^4.85.0"
   }
 }

examples/ai-chat/package.json

@@ -17,20 +17,20 @@
     "ai": "^6.0.168",
     "react": "^19.2.5",
     "react-dom": "^19.2.5",
-    "workers-ai-provider": "^3.1.11",
+    "workers-ai-provider": "^3.1.12",
     "zod": "^4.3.6"
   },
   "devDependencies": {
-    "@cloudflare/vite-plugin": "^1.33.0",
-    "@cloudflare/workers-types": "^4.20260420.1",
+    "@cloudflare/vite-plugin": "^1.33.2",
+    "@cloudflare/workers-types": "^4.20260425.1",
     "@tailwindcss/vite": "^4",
     "@types/node": "^25.6.0",
     "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
     "@vitejs/plugin-react": "^6.0.1",
-    "tailwindcss": "^4.2.2",
+    "tailwindcss": "^4.2.4",
     "typescript": "^6.0.3",
-    "vite": "^8.0.9",
-    "wrangler": "^4.84.0"
+    "vite": "^8.0.10",
+    "wrangler": "^4.85.0"
   }
 }

examples/assistant/package.json

@@ -20,20 +20,20 @@
     "ai": "^6.0.168",
     "react": "^19.2.5",
     "react-dom": "^19.2.5",
-    "workers-ai-provider": "^3.1.11",
+    "workers-ai-provider": "^3.1.12",
     "zod": "^4.3.6"
   },
   "devDependencies": {
-    "@cloudflare/vite-plugin": "^1.33.0",
-    "@cloudflare/workers-types": "^4.20260420.1",
+    "@cloudflare/vite-plugin": "^1.33.2",
+    "@cloudflare/workers-types": "^4.20260425.1",
     "@tailwindcss/vite": "^4",
     "@types/node": "^25.6.0",
     "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
     "@vitejs/plugin-react": "^6.0.1",
-    "tailwindcss": "^4.2.2",
+    "tailwindcss": "^4.2.4",
     "typescript": "^6.0.3",
-    "vite": "^8.0.9",
-    "wrangler": "^4.84.0"
+    "vite": "^8.0.10",
+    "wrangler": "^4.85.0"
   }
 }

examples/auth-agent/package.json

@@ -17,19 +17,19 @@
     "ai": "^6.0.168",
     "react": "^19.2.5",
     "react-dom": "^19.2.5",
-    "workers-ai-provider": "^3.1.11"
+    "workers-ai-provider": "^3.1.12"
   },
   "devDependencies": {
-    "@cloudflare/vite-plugin": "^1.33.0",
-    "@cloudflare/workers-types": "^4.20260420.1",
+    "@cloudflare/vite-plugin": "^1.33.2",
+    "@cloudflare/workers-types": "^4.20260425.1",
     "@tailwindcss/vite": "^4",
     "@types/node": "^25.6.0",
     "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
     "@vitejs/plugin-react": "^6.0.1",
-    "tailwindcss": "^4.2.2",
+    "tailwindcss": "^4.2.4",
     "typescript": "^6.0.3",
-    "vite": "^8.0.9",
-    "wrangler": "^4.84.0"
+    "vite": "^8.0.10",
+    "wrangler": "^4.85.0"
   }
 }

examples/codemode-mcp-openapi/package.json

@@ -13,9 +13,9 @@
     "agents": "*"
   },
   "devDependencies": {
-    "@cloudflare/workers-types": "^4.20260420.1",
+    "@cloudflare/workers-types": "^4.20260425.1",
     "@types/node": "^25.6.0",
     "typescript": "^6.0.3",
-    "wrangler": "^4.84.0"
+    "wrangler": "^4.85.0"
   }
 }

examples/codemode-mcp/package.json

@@ -15,9 +15,9 @@
     "zod": "^4.3.6"
   },
   "devDependencies": {
-    "@cloudflare/workers-types": "^4.20260420.1",
+    "@cloudflare/workers-types": "^4.20260425.1",
     "@types/node": "^25.6.0",
     "typescript": "^6.0.3",
-    "wrangler": "^4.84.0"
+    "wrangler": "^4.85.0"
   }
 }

examples/codemode/package.json

@@ -24,16 +24,16 @@
     "zod": "^4.3.6"
   },
   "devDependencies": {
-    "@cloudflare/vite-plugin": "^1.33.0",
-    "@cloudflare/workers-types": "^4.20260420.1",
+    "@cloudflare/vite-plugin": "^1.33.2",
+    "@cloudflare/workers-types": "^4.20260425.1",
     "@tailwindcss/vite": "^4",
     "@types/node": "^25.6.0",
     "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
     "@vitejs/plugin-react": "^6.0.1",
-    "tailwindcss": "^4.2.2",
+    "tailwindcss": "^4.2.4",
     "typescript": "^6.0.3",
-    "vite": "^8.0.9",
-    "wrangler": "^4.84.0"
+    "vite": "^8.0.10",
+    "wrangler": "^4.85.0"
   }
 }

examples/cross-domain/package.json

@@ -17,14 +17,14 @@
     "react-dom": "^19.2.5"
   },
   "devDependencies": {
-    "@cloudflare/workers-types": "^4.20260420.1",
+    "@cloudflare/workers-types": "^4.20260425.1",
     "@types/node": "^25.6.0",
     "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
     "@vitejs/plugin-react": "^6.0.1",
     "concurrently": "^9.2.1",
     "typescript": "^6.0.3",
-    "vite": "^8.0.9",
-    "wrangler": "^4.84.0"
+    "vite": "^8.0.10",
+    "wrangler": "^4.85.0"
   }
 }

examples/dynamic-tools/package.json

@@ -17,19 +17,19 @@
     "ai": "^6.0.168",
     "react": "^19.2.5",
     "react-dom": "^19.2.5",
-    "workers-ai-provider": "^3.1.11"
+    "workers-ai-provider": "^3.1.12"
   },
   "devDependencies": {
-    "@cloudflare/vite-plugin": "^1.33.0",
-    "@cloudflare/workers-types": "^4.20260420.1",
+    "@cloudflare/vite-plugin": "^1.33.2",
+    "@cloudflare/workers-types": "^4.20260425.1",
     "@tailwindcss/vite": "^4",
     "@types/node": "^25.6.0",
     "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
     "@vitejs/plugin-react": "^6.0.1",
-    "tailwindcss": "^4.2.2",
+    "tailwindcss": "^4.2.4",
     "typescript": "^6.0.3",
-    "vite": "^8.0.9",
-    "wrangler": "^4.84.0"
+    "vite": "^8.0.10",
+    "wrangler": "^4.85.0"
   }
 }

examples/dynamic-workers-playground/package.json

@@ -18,16 +18,16 @@
     "react-dom": "^19.2.5"
   },
   "devDependencies": {
-    "@cloudflare/vite-plugin": "^1.33.0",
-    "@cloudflare/workers-types": "^4.20260420.1",
+    "@cloudflare/vite-plugin": "^1.33.2",
+    "@cloudflare/workers-types": "^4.20260425.1",
     "@tailwindcss/vite": "^4",
     "@types/node": "^25.6.0",
     "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
     "@vitejs/plugin-react": "^6.0.1",
-    "tailwindcss": "^4.2.2",
+    "tailwindcss": "^4.2.4",
     "typescript": "^6.0.3",
-    "vite": "^8.0.9",
-    "wrangler": "^4.84.0"
+    "vite": "^8.0.10",
+    "wrangler": "^4.85.0"
   }
 }

examples/dynamic-workers/package.json

@@ -16,16 +16,16 @@
     "react-dom": "^19.2.5"
   },
   "devDependencies": {
-    "@cloudflare/vite-plugin": "^1.33.0",
-    "@cloudflare/workers-types": "^4.20260420.1",
+    "@cloudflare/vite-plugin": "^1.33.2",
+    "@cloudflare/workers-types": "^4.20260425.1",
     "@tailwindcss/vite": "^4",
     "@types/node": "^25.6.0",
     "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
     "@vitejs/plugin-react": "^6.0.1",
-    "tailwindcss": "^4.2.2",
+    "tailwindcss": "^4.2.4",
     "typescript": "^6.0.3",
-    "vite": "^8.0.9",
-    "wrangler": "^4.84.0"
+    "vite": "^8.0.10",
+    "wrangler": "^4.85.0"
   }
 }

examples/elevenlabs-starter/package.json

@@ -12,28 +12,28 @@
   "dependencies": {
     "@cloudflare/ai-chat": "*",
     "@cloudflare/kumo": "^1.19.0",
-    "@elevenlabs/elevenlabs-js": "^2.43.0",
+    "@elevenlabs/elevenlabs-js": "^2.44.0",
     "@phosphor-icons/react": "^2.1.10",
     "@streamdown/code": "^1.1.1",
     "agents": "*",
     "ai": "^6.0.168",
     "react": "^19.2.5",
     "react-dom": "^19.2.5",
     "streamdown": "^2.5.0",
-    "workers-ai-provider": "^3.1.11",
+    "workers-ai-provider": "^3.1.12",
     "zod": "^4.3.6"
   },
   "devDependencies": {
-    "@cloudflare/vite-plugin": "^1.33.0",
-    "@cloudflare/workers-types": "^4.20260420.1",
+    "@cloudflare/vite-plugin": "^1.33.2",
+    "@cloudflare/workers-types": "^4.20260425.1",
     "@tailwindcss/vite": "^4",
     "@types/node": "^25.6.0",
     "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
     "@vitejs/plugin-react": "^6.0.1",
-    "tailwindcss": "^4.2.2",
+    "tailwindcss": "^4.2.4",
     "typescript": "^6.0.3",
-    "vite": "^8.0.9",
-    "wrangler": "^4.84.0"
+    "vite": "^8.0.10",
+    "wrangler": "^4.85.0"
   }
 }

examples/email-agent/package.json

@@ -18,17 +18,17 @@
     "react-dom": "^19.2.5"
   },
   "devDependencies": {
-    "@cloudflare/vite-plugin": "^1.33.0",
-    "@cloudflare/workers-types": "^4.20260420.1",
+    "@cloudflare/vite-plugin": "^1.33.2",
+    "@cloudflare/workers-types": "^4.20260425.1",
     "@tailwindcss/vite": "^4",
     "@types/node": "^25.6.0",
     "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
     "@vitejs/plugin-react": "^6.0.1",
-    "tailwindcss": "^4.2.2",
+    "tailwindcss": "^4.2.4",
     "typescript": "^6.0.3",
-    "vite": "^8.0.9",
-    "wrangler": "^4.84.0"
+    "vite": "^8.0.10",
+    "wrangler": "^4.85.0"
   },
   "keywords": [],
   "license": "ISC",

examples/github-webhook/package.json

@@ -15,14 +15,14 @@
     "react-dom": "^19.2.5"
   },
   "devDependencies": {
-    "@cloudflare/vite-plugin": "^1.33.0",
-    "@cloudflare/workers-types": "^4.20260420.1",
+    "@cloudflare/vite-plugin": "^1.33.2",
+    "@cloudflare/workers-types": "^4.20260425.1",
     "@types/node": "^25.6.0",
     "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
     "@vitejs/plugin-react": "^6.0.1",
     "typescript": "^6.0.3",
-    "vite": "^8.0.9",
-    "wrangler": "^4.84.0"
+    "vite": "^8.0.10",
+    "wrangler": "^4.85.0"
   }
 }

examples/mcp-client/package.json

@@ -17,16 +17,16 @@
     "react-dom": "^19.2.5"
   },
   "devDependencies": {
-    "@cloudflare/vite-plugin": "^1.33.0",
-    "@cloudflare/workers-types": "^4.20260420.1",
+    "@cloudflare/vite-plugin": "^1.33.2",
+    "@cloudflare/workers-types": "^4.20260425.1",
     "@tailwindcss/vite": "^4",
     "@types/node": "^25.6.0",
     "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
     "@vitejs/plugin-react": "^6.0.1",
-    "tailwindcss": "^4.2.2",
+    "tailwindcss": "^4.2.4",
     "typescript": "^6.0.3",
-    "vite": "^8.0.9",
-    "wrangler": "^4.84.0"
+    "vite": "^8.0.10",
+    "wrangler": "^4.85.0"
   }
 }

examples/mcp-elicitation/package.json

@@ -18,16 +18,16 @@
     "zod": "^4.3.6"
   },
   "devDependencies": {
-    "@cloudflare/vite-plugin": "^1.33.0",
-    "@cloudflare/workers-types": "^4.20260420.1",
+    "@cloudflare/vite-plugin": "^1.33.2",
+    "@cloudflare/workers-types": "^4.20260425.1",
     "@tailwindcss/vite": "^4",
     "@types/node": "^25.6.0",
     "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
     "@vitejs/plugin-react": "^6.0.1",
-    "tailwindcss": "^4.2.2",
+    "tailwindcss": "^4.2.4",
     "typescript": "^6.0.3",
-    "vite": "^8.0.9",
-    "wrangler": "^4.84.0"
+    "vite": "^8.0.10",
+    "wrangler": "^4.85.0"
   }
 }