agents 0.11.3 → 0.11.5

package/dist/sub-routing.js

@@ -0,0 +1,171 @@
+import { camelCaseToKebabCase, isInternalJsStubProp } from "./utils.js";
+//#region src/sub-routing.ts
+/**
+* Sub-agent routing primitives — external addressability for facets.
+*
+* The public surface:
+*   - `routeSubAgentRequest(req, parent, options?)` — the sub-agent
+*     analog of `routeAgentRequest`. Use in custom fetch handlers.
+*   - `getSubAgentByName(parent, Cls, name)` — the sub-agent analog
+*     of `getAgentByName`. Returns a typed RPC stub that proxies
+*     method calls through the parent. No `.fetch()` support —
+*     external HTTP/WS routing goes through `routeSubAgentRequest`.
+*
+* Internal:
+*   - `parseSubAgentPath(url)` — URL → `{ childClass, childName, remainingPath }`.
+*   - `forwardToFacet(req, parent, match)` — resolves `ctx.facets.get(...)`
+*     on the parent and returns `facetStub.fetch(rewrittenReq)`.
+*
+* @experimental The API surface may change before stabilizing.
+*/
+/**
+* URL segment marking a parent↔child boundary.
+*
+* Exposed as a constant so callers can build URLs symbolically, but
+* not configurable — the routing layer matches on the literal `sub`
+* token everywhere (parent fetch, client, helpers).
+*/
+const SUB_PREFIX = "sub";
+/**
+* Parse a URL and extract the first `/sub/{class}/{name}` segment,
+* if any. Recursive nesting is handled naturally: callers parse one
+* level at a time; the child then parses its own URL (which still
+* contains any deeper `/sub/...` markers).
+*
+* Names are URL-decoded. Classes are kebab-to-CamelCase converted
+* via a best-effort match against a provided lookup — pass
+* `ctx.exports` keys to get exact CamelCase; pass `undefined` for
+* a tolerant conversion without validation.
+*
+* Returns `null` when the URL doesn't contain the marker at a
+* recognized position, or when the marker has no following
+* class+name pair.
+*/
+function parseSubAgentPath(url, options) {
+	const parts = new URL(url).pathname.split("/").filter(Boolean);
+	for (let i = 0; i < parts.length; i++) {
+		if (parts[i] !== "sub") continue;
+		if (i + 2 >= parts.length) continue;
+		const classSegment = parts[i + 1];
+		const nameSegment = parts[i + 2];
+		const childClass = resolveClassName(classSegment, options?.knownClasses);
+		if (!childClass) continue;
+		let childName;
+		try {
+			childName = decodeURIComponent(nameSegment);
+		} catch {
+			continue;
+		}
+		const remainingParts = parts.slice(i + 3);
+		const remainingPath = remainingParts.length > 0 ? "/" + remainingParts.join("/") : "/";
+		return {
+			childClass,
+			childName,
+			remainingPath
+		};
+	}
+	return null;
+}
+/**
+* Best-effort kebab-to-CamelCase match. If `knownClasses` is
+* provided, returns the matching CamelCase entry (or null if no
+* match). If not, performs a naive kebab→CamelCase conversion.
+*/
+function resolveClassName(segment, knownClasses) {
+	if (knownClasses) return knownClasses.find((name) => camelCaseToKebabCase(name) === segment) ?? null;
+	return segment.split("-").map((s) => s.charAt(0).toUpperCase() + s.slice(1)).join("");
+}
+/**
+* Route a request into a sub-agent via its parent DO.
+*
+* Use this in a custom fetch handler when your URL shape doesn't
+* match the `/agents/{class}/{name}` default — you identify and
+* fetch the parent yourself, then let this helper parse the
+* `/sub/{child}/...` tail and forward it.
+*
+* Runs `onBeforeSubAgent` on the parent DO (authorization / request
+* mutation / short-circuit response).
+*
+* For the default `/agents/...` URL shape, use `routeAgentRequest`
+* instead — it handles the parent lookup and this dispatch in one
+* call.
+*
+* @example
+* ```ts
+* export default {
+*   async fetch(req, env) {
+*     const { parentName, rest } = myCustomParse(req.url);
+*     const parent = await getAgentByName(env.Inbox, parentName);
+*     return routeSubAgentRequest(req, parent, { fromPath: rest });
+*   }
+* };
+* ```
+*
+* @experimental The API surface may change before stabilizing.
+*/
+async function routeSubAgentRequest(req, parent, options) {
+	if (!parseSubAgentPath(options?.fromPath ? `http://placeholder${options.fromPath.startsWith("/") ? "" : "/"}${options.fromPath}` : req.url)) return new Response("Sub-agent path not found in request URL", { status: 400 });
+	const forwardReq = options?.fromPath !== void 0 ? new Request(rewritePathname(req.url, options.fromPath), req) : req;
+	return parent.fetch(forwardReq);
+}
+/**
+* Replace a URL's pathname (and optionally its search) while
+* preserving every other component. Matches how `_cf_forwardToFacet`
+* forwards requests — pathname is the only thing that changes by
+* default; if the replacement path carries its own query string,
+* that wins.
+*/
+function rewritePathname(url, fromPath) {
+	const normalized = fromPath.startsWith("/") ? fromPath : `/${fromPath}`;
+	const queryIdx = normalized.indexOf("?");
+	const pathOnly = queryIdx >= 0 ? normalized.slice(0, queryIdx) : normalized;
+	const querySuffix = queryIdx >= 0 ? normalized.slice(queryIdx) : "";
+	const rewritten = new URL(url);
+	rewritten.pathname = pathOnly;
+	if (querySuffix) rewritten.search = querySuffix;
+	return rewritten.toString();
+}
+/**
+* Get a typed RPC stub for a sub-agent from outside the parent DO.
+*
+* The returned stub proxies method calls through the parent via a
+* stateless per-call bridge (caller → parent → facet), so each
+* method invocation costs one extra RPC hop. Works across parent
+* hibernation — no cached references to go stale.
+*
+* Limitations:
+*   - RPC methods only. `.fetch()` is not supported (will throw).
+*     Use `routeSubAgentRequest` for external HTTP/WS.
+*   - Arguments and return values must be structured-cloneable,
+*     same as any DO RPC call.
+*   - Does not run `onBeforeSubAgent` on the parent — analogous to
+*     `getAgentByName` not running `onBeforeConnect`. The caller is
+*     assumed to have performed whatever access checks are needed.
+*
+* @example
+* ```ts
+* const inbox = await getAgentByName(env.MyInbox, userId);
+* const chat = await getSubAgentByName(inbox, MyChat, chatId);
+* await chat.addMessage({ role: "user", content: "hi" });
+* ```
+*
+* @experimental The API surface may change before stabilizing.
+*/
+async function getSubAgentByName(parent, cls, name) {
+	if (name.includes("\0")) throw new Error(`Sub-agent name contains null character (\\0), which is reserved.`);
+	const bridge = parent;
+	const className = cls?.name;
+	if (!className) throw new Error(`getSubAgentByName: could not determine class name from ${cls}. Ensure you are passing the class constructor (e.g. getSubAgentByName(parent, MyChat, name)), not a string or undefined.`);
+	return new Proxy({}, { get(_target, prop) {
+		if (isInternalJsStubProp(prop)) return void 0;
+		if (typeof prop !== "string") return void 0;
+		if (prop === "fetch") return () => {
+			throw new Error("getSubAgentByName returns an RPC-only stub — .fetch() is not supported. Use routeSubAgentRequest() or the /agents/{parent}/{name}/sub/{child}/{name} URL for external HTTP/WS routing.");
+		};
+		return async (...args) => bridge._cf_invokeSubAgent(className, name, prop, args);
+	} });
+}
+//#endregion
+export { SUB_PREFIX, getSubAgentByName, parseSubAgentPath, routeSubAgentRequest };
+
+//# sourceMappingURL=sub-routing.js.map

package/dist/sub-routing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sub-routing.js","names":[],"sources":["../src/sub-routing.ts"],"sourcesContent":["/**\n * Sub-agent routing primitives — external addressability for facets.\n *\n * The public surface:\n *   - `routeSubAgentRequest(req, parent, options?)` — the sub-agent\n *     analog of `routeAgentRequest`. Use in custom fetch handlers.\n *   - `getSubAgentByName(parent, Cls, name)` — the sub-agent analog\n *     of `getAgentByName`. Returns a typed RPC stub that proxies\n *     method calls through the parent. No `.fetch()` support —\n *     external HTTP/WS routing goes through `routeSubAgentRequest`.\n *\n * Internal:\n *   - `parseSubAgentPath(url)` — URL → `{ childClass, childName, remainingPath }`.\n *   - `forwardToFacet(req, parent, match)` — resolves `ctx.facets.get(...)`\n *     on the parent and returns `facetStub.fetch(rewrittenReq)`.\n *\n * @experimental The API surface may change before stabilizing.\n */\n\nimport { camelCaseToKebabCase, isInternalJsStubProp } from \"./utils\";\nimport type { Agent, SubAgentClass, SubAgentStub } from \"./index\";\n\n/**\n * URL segment marking a parent↔child boundary.\n *\n * Exposed as a constant so callers can build URLs symbolically, but\n * not configurable — the routing layer matches on the literal `sub`\n * token everywhere (parent fetch, client, helpers).\n */\nexport const SUB_PREFIX = \"sub\";\n\nexport interface SubAgentPathMatch {\n  /** CamelCase class name of the child, as it appears in `ctx.exports`. */\n  childClass: string;\n  /** URL-decoded child name. */\n  childName: string;\n  /**\n   * Request path to forward to the child, with the\n   * `/sub/{class}/{name}` segment stripped. Always begins with `/`;\n   * may itself contain further `/sub/...` markers when a\n   * recursively nested sub-agent is being routed.\n   */\n  remainingPath: string;\n}\n\n/**\n * Parse a URL and extract the first `/sub/{class}/{name}` segment,\n * if any. Recursive nesting is handled naturally: callers parse one\n * level at a time; the child then parses its own URL (which still\n * contains any deeper `/sub/...` markers).\n *\n * Names are URL-decoded. Classes are kebab-to-CamelCase converted\n * via a best-effort match against a provided lookup — pass\n * `ctx.exports` keys to get exact CamelCase; pass `undefined` for\n * a tolerant conversion without validation.\n *\n * Returns `null` when the URL doesn't contain the marker at a\n * recognized position, or when the marker has no following\n * class+name pair.\n */\nexport function parseSubAgentPath(\n  url: string,\n  options?: {\n    /** CamelCase class names to match against (usually `ctx.exports` keys). */\n    knownClasses?: readonly string[];\n  }\n): SubAgentPathMatch | null {\n  const pathname = new URL(url).pathname;\n  const parts = pathname.split(\"/\").filter(Boolean);\n\n  // Walk every occurrence of the `sub` segment — a plain\n  // `indexOf(SUB_PREFIX)` would mis-match when the literal token\n  // appears earlier in the URL (parent instance name == \"sub\", a\n  // `basePath` segment that happens to be \"sub\", etc). We return\n  // the first position where `parts[i+1]` resolves to a valid\n  // class, which pins the real parent↔child boundary.\n  for (let i = 0; i < parts.length; i++) {\n    if (parts[i] !== SUB_PREFIX) continue;\n    if (i + 2 >= parts.length) continue;\n\n    const classSegment = parts[i + 1];\n    const nameSegment = parts[i + 2];\n\n    const childClass = resolveClassName(classSegment, options?.knownClasses);\n    if (!childClass) continue;\n\n    let childName: string;\n    try {\n      childName = decodeURIComponent(nameSegment);\n    } catch {\n      continue;\n    }\n\n    const remainingParts = parts.slice(i + 3);\n    const remainingPath =\n      remainingParts.length > 0 ? \"/\" + remainingParts.join(\"/\") : \"/\";\n\n    return { childClass, childName, remainingPath };\n  }\n\n  return null;\n}\n\n/**\n * Best-effort kebab-to-CamelCase match. If `knownClasses` is\n * provided, returns the matching CamelCase entry (or null if no\n * match). If not, performs a naive kebab→CamelCase conversion.\n */\nfunction resolveClassName(\n  segment: string,\n  knownClasses?: readonly string[]\n): string | null {\n  if (knownClasses) {\n    const match = knownClasses.find(\n      (name) => camelCaseToKebabCase(name) === segment\n    );\n    return match ?? null;\n  }\n  return segment\n    .split(\"-\")\n    .map((s) => s.charAt(0).toUpperCase() + s.slice(1))\n    .join(\"\");\n}\n\n// ── routeSubAgentRequest ───────────────────────────────────────────\n\n/**\n * Minimal parent-side shape that `routeSubAgentRequest` relies on:\n * something fetchable (a DO stub, a sub-agent stub, etc.).\n *\n * @internal\n */\ninterface FetchableParent {\n  fetch(req: Request): Promise<Response>;\n}\n\n/**\n * Route a request into a sub-agent via its parent DO.\n *\n * Use this in a custom fetch handler when your URL shape doesn't\n * match the `/agents/{class}/{name}` default — you identify and\n * fetch the parent yourself, then let this helper parse the\n * `/sub/{child}/...` tail and forward it.\n *\n * Runs `onBeforeSubAgent` on the parent DO (authorization / request\n * mutation / short-circuit response).\n *\n * For the default `/agents/...` URL shape, use `routeAgentRequest`\n * instead — it handles the parent lookup and this dispatch in one\n * call.\n *\n * @example\n * ```ts\n * export default {\n *   async fetch(req, env) {\n *     const { parentName, rest } = myCustomParse(req.url);\n *     const parent = await getAgentByName(env.Inbox, parentName);\n *     return routeSubAgentRequest(req, parent, { fromPath: rest });\n *   }\n * };\n * ```\n *\n * @experimental The API surface may change before stabilizing.\n */\nexport async function routeSubAgentRequest(\n  req: Request,\n  parent: unknown,\n  options?: {\n    /**\n     * Path to route on. Defaults to `req.url`'s pathname. Useful\n     * when your outer URL is custom (e.g. `/api/v1/...`) and you\n     * want to route the sub-agent tail without rewriting the\n     * Request first.\n     */\n    fromPath?: string;\n  }\n): Promise<Response> {\n  // We don't know the parent's ctx.exports from here, so parse with\n  // a permissive resolver. If the class doesn't exist, the parent's\n  // bridge will 404. This lets us keep the helper self-contained.\n  const pathForParsing = options?.fromPath\n    ? `http://placeholder${options.fromPath.startsWith(\"/\") ? \"\" : \"/\"}${options.fromPath}`\n    : req.url;\n\n  const match = parseSubAgentPath(pathForParsing);\n  if (!match) {\n    return new Response(\"Sub-agent path not found in request URL\", {\n      status: 400\n    });\n  }\n\n  // Hand the request to the parent so `onBeforeSubAgent` fires in\n  // the parent's isolate. The parent's `fetch` handler recognizes\n  // the marker internally — we preserve the original request URL\n  // (possibly rewritten by `fromPath`) so the parent's parse sees\n  // the same match.\n  //\n  // Key subtlety: when rewriting the pathname via `fromPath`, we\n  // mutate the *original* URL's pathname instead of constructing a\n  // new URL from scratch. `new URL(\"/path\", baseWithQuery)` discards\n  // the base's search; we want the caller's query params (e.g. auth\n  // tokens, PartySocket's `_pk=...` handshake key) to survive.\n  // Mirrors how `_cf_forwardToFacet` rewrites only pathname when\n  // handing off to the child facet. If `fromPath` itself contains a\n  // `?query` segment, that overrides the original.\n  const forwardReq =\n    options?.fromPath !== undefined\n      ? new Request(rewritePathname(req.url, options.fromPath), req)\n      : req;\n\n  return (parent as FetchableParent).fetch(forwardReq);\n}\n\n/**\n * Replace a URL's pathname (and optionally its search) while\n * preserving every other component. Matches how `_cf_forwardToFacet`\n * forwards requests — pathname is the only thing that changes by\n * default; if the replacement path carries its own query string,\n * that wins.\n */\nfunction rewritePathname(url: string, fromPath: string): string {\n  const normalized = fromPath.startsWith(\"/\") ? fromPath : `/${fromPath}`;\n  const queryIdx = normalized.indexOf(\"?\");\n  const pathOnly = queryIdx >= 0 ? normalized.slice(0, queryIdx) : normalized;\n  const querySuffix = queryIdx >= 0 ? normalized.slice(queryIdx) : \"\";\n\n  const rewritten = new URL(url);\n  rewritten.pathname = pathOnly;\n  if (querySuffix) {\n    rewritten.search = querySuffix; // URL setter keeps the `?` prefix\n  }\n  return rewritten.toString();\n}\n\n// ── getSubAgentByName ──────────────────────────────────────────────\n\n/**\n * Parent-side RPC bridge shape that `getSubAgentByName` relies on.\n *\n * @internal\n */\ninterface SubAgentInvokeEndpoint {\n  _cf_invokeSubAgent(\n    className: string,\n    name: string,\n    method: string,\n    args: unknown[]\n  ): Promise<unknown>;\n}\n\n/**\n * Get a typed RPC stub for a sub-agent from outside the parent DO.\n *\n * The returned stub proxies method calls through the parent via a\n * stateless per-call bridge (caller → parent → facet), so each\n * method invocation costs one extra RPC hop. Works across parent\n * hibernation — no cached references to go stale.\n *\n * Limitations:\n *   - RPC methods only. `.fetch()` is not supported (will throw).\n *     Use `routeSubAgentRequest` for external HTTP/WS.\n *   - Arguments and return values must be structured-cloneable,\n *     same as any DO RPC call.\n *   - Does not run `onBeforeSubAgent` on the parent — analogous to\n *     `getAgentByName` not running `onBeforeConnect`. The caller is\n *     assumed to have performed whatever access checks are needed.\n *\n * @example\n * ```ts\n * const inbox = await getAgentByName(env.MyInbox, userId);\n * const chat = await getSubAgentByName(inbox, MyChat, chatId);\n * await chat.addMessage({ role: \"user\", content: \"hi\" });\n * ```\n *\n * @experimental The API surface may change before stabilizing.\n */\nexport async function getSubAgentByName<T extends Agent>(\n  parent: unknown,\n  cls: SubAgentClass<T>,\n  name: string\n): Promise<SubAgentStub<T>> {\n  if (name.includes(\"\\0\")) {\n    throw new Error(\n      `Sub-agent name contains null character (\\\\0), which is reserved.`\n    );\n  }\n\n  const bridge = parent as SubAgentInvokeEndpoint;\n  const className = cls?.name;\n  if (!className) {\n    throw new Error(\n      `getSubAgentByName: could not determine class name from ${cls}. ` +\n        `Ensure you are passing the class constructor (e.g. getSubAgentByName(parent, MyChat, name)), not a string or undefined.`\n    );\n  }\n\n  return new Proxy(\n    {},\n    {\n      get(_target, prop) {\n        // JS / runtime / test-framework probes (thenable check,\n        // serialization, inspection, matcher duck-typing) must NOT\n        // dispatch an RPC — returning `undefined` is the contract\n        // the inner `createStubProxy` uses for `useAgent` stubs.\n        // Without this guard, `JSON.stringify(stub)`, `console.log`,\n        // Vitest matchers, and `await stub` would all trigger bogus\n        // `_cf_invokeSubAgent` calls that fail with \"Method not found\".\n        if (isInternalJsStubProp(prop)) return undefined;\n        if (typeof prop !== \"string\") return undefined;\n        // `.fetch` gets a dedicated error so users who try to use\n        // the stub for HTTP/WS get a helpful pointer.\n        if (prop === \"fetch\") {\n          return () => {\n            throw new Error(\n              `getSubAgentByName returns an RPC-only stub — .fetch() is ` +\n                `not supported. Use routeSubAgentRequest() or the ` +\n                `/agents/{parent}/{name}/sub/{child}/{name} URL for ` +\n                `external HTTP/WS routing.`\n            );\n          };\n        }\n        return async (...args: unknown[]) =>\n          bridge._cf_invokeSubAgent(className, name, prop, args);\n      }\n    }\n  ) as SubAgentStub<T>;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;AA6BA,MAAa,aAAa;;;;;;;;;;;;;;;;AA+B1B,SAAgB,kBACd,KACA,SAI0B;CAE1B,MAAM,QADW,IAAI,IAAI,IAAI,CAAC,SACP,MAAM,IAAI,CAAC,OAAO,QAAQ;AAQjD,MAAK,IAAI,IAAI,GAAG,IAAI,MAAM,QAAQ,KAAK;AACrC,MAAI,MAAM,OAAA,MAAmB;AAC7B,MAAI,IAAI,KAAK,MAAM,OAAQ;EAE3B,MAAM,eAAe,MAAM,IAAI;EAC/B,MAAM,cAAc,MAAM,IAAI;EAE9B,MAAM,aAAa,iBAAiB,cAAc,SAAS,aAAa;AACxE,MAAI,CAAC,WAAY;EAEjB,IAAI;AACJ,MAAI;AACF,eAAY,mBAAmB,YAAY;UACrC;AACN;;EAGF,MAAM,iBAAiB,MAAM,MAAM,IAAI,EAAE;EACzC,MAAM,gBACJ,eAAe,SAAS,IAAI,MAAM,eAAe,KAAK,IAAI,GAAG;AAE/D,SAAO;GAAE;GAAY;GAAW;GAAe;;AAGjD,QAAO;;;;;;;AAQT,SAAS,iBACP,SACA,cACe;AACf,KAAI,aAIF,QAHc,aAAa,MACxB,SAAS,qBAAqB,KAAK,KAAK,QAC1C,IACe;AAElB,QAAO,QACJ,MAAM,IAAI,CACV,KAAK,MAAM,EAAE,OAAO,EAAE,CAAC,aAAa,GAAG,EAAE,MAAM,EAAE,CAAC,CAClD,KAAK,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA2Cb,eAAsB,qBACpB,KACA,QACA,SASmB;AASnB,KAAI,CADU,kBAJS,SAAS,WAC5B,qBAAqB,QAAQ,SAAS,WAAW,IAAI,GAAG,KAAK,MAAM,QAAQ,aAC3E,IAAI,IAEuC,CAE7C,QAAO,IAAI,SAAS,2CAA2C,EAC7D,QAAQ,KACT,CAAC;CAiBJ,MAAM,aACJ,SAAS,aAAa,KAAA,IAClB,IAAI,QAAQ,gBAAgB,IAAI,KAAK,QAAQ,SAAS,EAAE,IAAI,GAC5D;AAEN,QAAQ,OAA2B,MAAM,WAAW;;;;;;;;;AAUtD,SAAS,gBAAgB,KAAa,UAA0B;CAC9D,MAAM,aAAa,SAAS,WAAW,IAAI,GAAG,WAAW,IAAI;CAC7D,MAAM,WAAW,WAAW,QAAQ,IAAI;CACxC,MAAM,WAAW,YAAY,IAAI,WAAW,MAAM,GAAG,SAAS,GAAG;CACjE,MAAM,cAAc,YAAY,IAAI,WAAW,MAAM,SAAS,GAAG;CAEjE,MAAM,YAAY,IAAI,IAAI,IAAI;AAC9B,WAAU,WAAW;AACrB,KAAI,YACF,WAAU,SAAS;AAErB,QAAO,UAAU,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6C7B,eAAsB,kBACpB,QACA,KACA,MAC0B;AAC1B,KAAI,KAAK,SAAS,KAAK,CACrB,OAAM,IAAI,MACR,mEACD;CAGH,MAAM,SAAS;CACf,MAAM,YAAY,KAAK;AACvB,KAAI,CAAC,UACH,OAAM,IAAI,MACR,0DAA0D,IAAI,2HAE/D;AAGH,QAAO,IAAI,MACT,EAAE,EACF,EACE,IAAI,SAAS,MAAM;AAQjB,MAAI,qBAAqB,KAAK,CAAE,QAAO,KAAA;AACvC,MAAI,OAAO,SAAS,SAAU,QAAO,KAAA;AAGrC,MAAI,SAAS,QACX,cAAa;AACX,SAAM,IAAI,MACR,yLAID;;AAGL,SAAO,OAAO,GAAG,SACf,OAAO,mBAAmB,WAAW,MAAM,MAAM,KAAK;IAE3D,CACF"}

package/dist/utils.d.ts

@@ -1,4 +1,24 @@
 //#region src/utils.d.ts
+/**
+ * Property keys that JavaScript runtimes and test frameworks probe
+ * on arbitrary objects (serialization, thenable check, inspection,
+ * matcher duck-typing). When an RPC-stub Proxy is accessed by
+ * `JSON.stringify`, `console.log`, `await`, Vitest matchers, etc.,
+ * it hits one of these — we must return `undefined` instead of a
+ * call-wrapper to avoid firing a bogus RPC for a method the child
+ * doesn't implement.
+ *
+ * @internal
+ */
+declare const INTERNAL_JS_STUB_PROPS: ReadonlySet<string>;
+/**
+ * True when the property access is a JS-internal probe that must
+ * NOT dispatch an RPC call. Catches all symbol keys plus the named
+ * set above.
+ *
+ * @internal
+ */
+declare function isInternalJsStubProp(prop: string | symbol): boolean;
 /**
  * Convert a camelCase string to a kebab-case string
  * @param str The string to convert
@@ -6,5 +26,5 @@
  */
 declare function camelCaseToKebabCase(str: string): string;
 //#endregion
-export { camelCaseToKebabCase };
+export { INTERNAL_JS_STUB_PROPS, camelCaseToKebabCase, isInternalJsStubProp };
 //# sourceMappingURL=utils.d.ts.map

package/dist/utils.js

@@ -1,5 +1,40 @@
 //#region src/utils.ts
 /**
+* Property keys that JavaScript runtimes and test frameworks probe
+* on arbitrary objects (serialization, thenable check, inspection,
+* matcher duck-typing). When an RPC-stub Proxy is accessed by
+* `JSON.stringify`, `console.log`, `await`, Vitest matchers, etc.,
+* it hits one of these — we must return `undefined` instead of a
+* call-wrapper to avoid firing a bogus RPC for a method the child
+* doesn't implement.
+*
+* @internal
+*/
+const INTERNAL_JS_STUB_PROPS = new Set([
+	"toJSON",
+	"then",
+	"catch",
+	"finally",
+	"valueOf",
+	"toString",
+	"constructor",
+	"prototype",
+	"$$typeof",
+	"@@toStringTag",
+	"asymmetricMatch",
+	"nodeType"
+]);
+/**
+* True when the property access is a JS-internal probe that must
+* NOT dispatch an RPC call. Catches all symbol keys plus the named
+* set above.
+*
+* @internal
+*/
+function isInternalJsStubProp(prop) {
+	return typeof prop === "symbol" || INTERNAL_JS_STUB_PROPS.has(prop);
+}
+/**
 * Convert a camelCase string to a kebab-case string
 * @param str The string to convert
 * @returns The kebab-case string
@@ -11,6 +46,6 @@ function camelCaseToKebabCase(str) {
 	return kebabified.replace(/_/g, "-").replace(/-$/, "");
 }
 //#endregion
-export { camelCaseToKebabCase };
+export { INTERNAL_JS_STUB_PROPS, camelCaseToKebabCase, isInternalJsStubProp };
 
 //# sourceMappingURL=utils.js.map

package/dist/utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"utils.js","names":[],"sources":["../src/utils.ts"],"sourcesContent":["/**\n * Convert a camelCase string to a kebab-case string\n * @param str The string to convert\n * @returns The kebab-case string\n */\nexport function camelCaseToKebabCase(str: string): string {\n  // If string is all uppercase, convert to lowercase\n  if (str === str.toUpperCase() && str !== str.toLowerCase()) {\n    return str.toLowerCase().replace(/_/g, \"-\");\n  }\n\n  // Otherwise handle camelCase to kebab-case\n  let kebabified = str.replace(\n    /[A-Z]/g,\n    (letter) => `-${letter.toLowerCase()}`\n  );\n  kebabified = kebabified.startsWith(\"-\") ? kebabified.slice(1) : kebabified;\n  // Convert any remaining underscores to hyphens and remove trailing -'s\n  return kebabified.replace(/_/g, \"-\").replace(/-$/, \"\");\n}\n"],"mappings":";;;;;;AAKA,SAAgB,qBAAqB,KAAqB;AAExD,KAAI,QAAQ,IAAI,aAAa,IAAI,QAAQ,IAAI,aAAa,CACxD,QAAO,IAAI,aAAa,CAAC,QAAQ,MAAM,IAAI;CAI7C,IAAI,aAAa,IAAI,QACnB,WACC,WAAW,IAAI,OAAO,aAAa,GACrC;AACD,cAAa,WAAW,WAAW,IAAI,GAAG,WAAW,MAAM,EAAE,GAAG;AAEhE,QAAO,WAAW,QAAQ,MAAM,IAAI,CAAC,QAAQ,MAAM,GAAG"}
+{"version":3,"file":"utils.js","names":[],"sources":["../src/utils.ts"],"sourcesContent":["/**\n * Property keys that JavaScript runtimes and test frameworks probe\n * on arbitrary objects (serialization, thenable check, inspection,\n * matcher duck-typing). When an RPC-stub Proxy is accessed by\n * `JSON.stringify`, `console.log`, `await`, Vitest matchers, etc.,\n * it hits one of these — we must return `undefined` instead of a\n * call-wrapper to avoid firing a bogus RPC for a method the child\n * doesn't implement.\n *\n * @internal\n */\nexport const INTERNAL_JS_STUB_PROPS: ReadonlySet<string> = new Set([\n  \"toJSON\",\n  \"then\",\n  \"catch\",\n  \"finally\",\n  \"valueOf\",\n  \"toString\",\n  \"constructor\",\n  \"prototype\",\n  \"$$typeof\",\n  \"@@toStringTag\",\n  \"asymmetricMatch\",\n  \"nodeType\"\n]);\n\n/**\n * True when the property access is a JS-internal probe that must\n * NOT dispatch an RPC call. Catches all symbol keys plus the named\n * set above.\n *\n * @internal\n */\nexport function isInternalJsStubProp(prop: string | symbol): boolean {\n  return typeof prop === \"symbol\" || INTERNAL_JS_STUB_PROPS.has(prop);\n}\n\n/**\n * Convert a camelCase string to a kebab-case string\n * @param str The string to convert\n * @returns The kebab-case string\n */\nexport function camelCaseToKebabCase(str: string): string {\n  // If string is all uppercase, convert to lowercase\n  if (str === str.toUpperCase() && str !== str.toLowerCase()) {\n    return str.toLowerCase().replace(/_/g, \"-\");\n  }\n\n  // Otherwise handle camelCase to kebab-case\n  let kebabified = str.replace(\n    /[A-Z]/g,\n    (letter) => `-${letter.toLowerCase()}`\n  );\n  kebabified = kebabified.startsWith(\"-\") ? kebabified.slice(1) : kebabified;\n  // Convert any remaining underscores to hyphens and remove trailing -'s\n  return kebabified.replace(/_/g, \"-\").replace(/-$/, \"\");\n}\n"],"mappings":";;;;;;;;;;;;AAWA,MAAa,yBAA8C,IAAI,IAAI;CACjE;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACD,CAAC;;;;;;;;AASF,SAAgB,qBAAqB,MAAgC;AACnE,QAAO,OAAO,SAAS,YAAY,uBAAuB,IAAI,KAAK;;;;;;;AAQrE,SAAgB,qBAAqB,KAAqB;AAExD,KAAI,QAAQ,IAAI,aAAa,IAAI,QAAQ,IAAI,aAAa,CACxD,QAAO,IAAI,aAAa,CAAC,QAAQ,MAAM,IAAI;CAI7C,IAAI,aAAa,IAAI,QACnB,WACC,WAAW,IAAI,OAAO,aAAa,GACrC;AACD,cAAa,WAAW,WAAW,IAAI,GAAG,WAAW,MAAM,EAAE,GAAG;AAEhE,QAAO,WAAW,QAAQ,MAAM,IAAI,CAAC,QAAQ,MAAM,GAAG"}

package/dist/workflows.d.ts

@@ -1,4 +1,4 @@
-import { r as Agent } from "./index-D49HdAiY.js";
+import { r as Agent } from "./index-DabjI66m.js";
 import {
   S as WorkflowTrackingRow,
   _ as WorkflowPage,

package/package.json

@@ -9,7 +9,7 @@
     "durable objects"
   ],
   "type": "module",
-  "version": "0.11.3",
+  "version": "0.11.5",
   "license": "MIT",
   "repository": {
     "directory": "packages/agents",
@@ -29,46 +29,37 @@
     "@modelcontextprotocol/sdk": "1.29.0",
     "@rolldown/plugin-babel": "^0.2.3",
     "cron-schedule": "^6.0.0",
-    "json-schema": "^0.4.0",
-    "json-schema-to-typescript": "^15.0.4",
     "mimetext": "^3.0.28",
     "nanoid": "^5.1.9",
     "partyserver": "^0.4.1",
-    "partysocket": "1.1.16",
-    "picomatch": "^4.0.4",
+    "partysocket": "1.1.18",
     "yargs": "^18.0.0"
   },
   "devDependencies": {
-    "@ai-sdk/openai": "^3.0.53",
-    "@ai-sdk/react": "^3.0.166",
-    "@cloudflare/workers-oauth-provider": "^0.4.0",
-    "@tanstack/ai": "^0.10.2",
+    "@ai-sdk/react": "^3.0.170",
+    "@tanstack/ai": "^0.11.0",
     "@types/react": "^19.2.14",
     "@types/yargs": "^17.0.35",
+    "@vitest/browser-playwright": "^4.1.4",
     "@x402/core": "^2.10.0",
     "@x402/evm": "^2.10.0",
-    "ai": "^6.0.164",
+    "ai": "^6.0.168",
     "react": "^19.2.5",
     "vitest-browser-react": "^2.2.0",
     "zod": "^4.3.6"
   },
   "peerDependencies": {
-    "@ai-sdk/react": "^3.0.0",
     "@cloudflare/ai-chat": ">=0.0.8 <1.0.0",
     "@cloudflare/codemode": ">=0.0.7 <1.0.0",
-    "@tanstack/ai": "^0.10.2",
+    "@tanstack/ai": ">=0.10.2 <1.0.0",
     "@x402/core": "^2.0.0",
     "@x402/evm": "^2.0.0",
     "ai": "^6.0.0",
     "react": "^19.0.0",
-    "viem": ">=2.0.0",
     "vite": ">=6.0.0 <9.0.0",
     "zod": "^4.0.0"
   },
   "peerDependenciesMeta": {
-    "@ai-sdk/react": {
-      "optional": true
-    },
     "@cloudflare/ai-chat": {
       "optional": true
     },
@@ -84,9 +75,6 @@
     "@x402/evm": {
       "optional": true
     },
-    "viem": {
-      "optional": true
-    },
     "vite": {
       "optional": true
     }
@@ -158,6 +146,11 @@
       "import": "./dist/experimental/memory/utils/index.js",
       "require": "./dist/experimental/memory/utils/index.js"
     },
+    "./experimental/webmcp": {
+      "types": "./dist/experimental/webmcp.d.ts",
+      "import": "./dist/experimental/webmcp.js",
+      "require": "./dist/experimental/webmcp.js"
+    },
     "./x402": {
       "types": "./dist/mcp/x402.d.ts",
       "import": "./dist/mcp/x402.js",
@@ -238,6 +231,7 @@
     "test:browser": "vitest run --config src/browser-tests/vitest.config.ts",
     "test:workers": "vitest --project workers",
     "test:chat": "vitest --project chat",
+    "test:webmcp": "vitest --project webmcp",
     "test:x402": "vitest --project x402",
     "test:e2e": "vitest --run -c src/e2e-tests/vitest.config.ts"
   }