agents 0.11.4 → 0.11.5

package/dist/client.js.map

@@ -1 +1 @@
-{"version":3,"file":"client.js","names":[],"sources":["../src/client.ts"],"sourcesContent":["import {\n  type PartyFetchOptions,\n  PartySocket,\n  type PartySocketOptions\n} from \"partysocket\";\nimport type { Agent, RPCRequest, RPCResponse } from \"./\";\nimport type {\n  Method,\n  RPCMethod,\n  SerializableReturnValue,\n  SerializableValue\n} from \"./serializable\";\nimport { MessageType } from \"./types\";\nimport { camelCaseToKebabCase } from \"./utils\";\n\n/**\n * Options for creating an AgentClient\n */\nexport type AgentClientOptions<State = unknown> = Omit<\n  PartySocketOptions,\n  \"party\" | \"room\"\n> & {\n  /** Name of the agent to connect to (ignored if basePath is set) */\n  agent: string;\n  /** Name of the specific Agent instance (ignored if basePath is set) */\n  name?: string;\n  /**\n   * Full URL path - bypasses agent/name URL construction.\n   * When set, the client connects to this path directly.\n   * Server must handle routing manually (e.g., with getAgentByName + fetch).\n   * @example\n   * // Client connects to /user, server routes based on session\n   * useAgent({ agent: \"UserAgent\", basePath: \"user\" })\n   */\n  basePath?: string;\n  /** Called when the Agent's state is updated */\n  onStateUpdate?: (state: State, source: \"server\" | \"client\") => void;\n  /** Called when a state update fails (e.g., connection is readonly) */\n  onStateUpdateError?: (error: string) => void;\n  /**\n   * Called when the server sends the agent's identity on connect.\n   * Useful when using basePath, as the actual instance name is determined server-side.\n   * @param name The actual agent instance name\n   * @param agent The agent class name (kebab-case)\n   */\n  onIdentity?: (name: string, agent: string) => void;\n  /**\n   * Called when identity changes on reconnect (different instance than before).\n   * If not provided and identity changes, a warning will be logged.\n   * @param oldName Previous instance name\n   * @param newName New instance name\n   * @param oldAgent Previous agent class name\n   * @param newAgent New agent class name\n   */\n  onIdentityChange?: (\n    oldName: string,\n    newName: string,\n    oldAgent: string,\n    newAgent: string\n  ) => void;\n  /**\n   * Additional path to append to the URL.\n   * Works with both standard routing and basePath.\n   * @example\n   * // With basePath: /user/settings\n   * { basePath: \"user\", path: \"settings\" }\n   * // Standard: /agents/my-agent/room/settings\n   * { agent: \"MyAgent\", name: \"room\", path: \"settings\" }\n   */\n  path?: string;\n};\n\n/**\n * Options for streaming RPC calls\n */\nexport type StreamOptions = {\n  /** Called when a chunk of data is received */\n  onChunk?: (chunk: unknown) => void;\n  /** Called when the stream ends */\n  onDone?: (finalChunk: unknown) => void;\n  /** Called when an error occurs */\n  onError?: (error: string) => void;\n};\n\n/**\n * Options for RPC calls\n */\nexport type CallOptions = {\n  /** Timeout in milliseconds. If the call doesn't complete within this time, it will be rejected. */\n  timeout?: number;\n  /** Streaming options for handling streaming responses */\n  stream?: StreamOptions;\n};\n\n/**\n * Options for the agentFetch function\n */\nexport type AgentClientFetchOptions = Omit<\n  PartyFetchOptions,\n  \"party\" | \"room\"\n> & {\n  /** Name of the agent to connect to (ignored if basePath is set) */\n  agent: string;\n  /** Name of the specific Agent instance (ignored if basePath is set) */\n  name?: string;\n  /**\n   * Full URL path - bypasses agent/name URL construction.\n   * When set, the request is made to this path directly.\n   */\n  basePath?: string;\n};\n\n// ---- Shared RPC Type Utilities ----\n\ntype AllOptional<T> = T extends [infer A, ...infer R]\n  ? undefined extends A\n    ? AllOptional<R>\n    : false\n  : true;\n\nexport type RPCMethods<T> = {\n  [K in keyof T as T[K] extends RPCMethod<T[K]> ? K : never]: RPCMethod<T[K]>;\n};\n\ntype OptionalParametersMethod<T extends RPCMethod> =\n  AllOptional<Parameters<T>> extends true ? T : never;\n\n// oxlint-disable-next-line @typescript-eslint/no-explicit-any -- generic agent type constraint\nexport type AgentMethods<T> = Omit<RPCMethods<T>, keyof Agent<any, any>>;\n\nexport type OptionalAgentMethods<T> = {\n  [K in keyof AgentMethods<T> as AgentMethods<T>[K] extends OptionalParametersMethod<\n    AgentMethods<T>[K]\n  >\n    ? K\n    : never]: OptionalParametersMethod<AgentMethods<T>[K]>;\n};\n\nexport type RequiredAgentMethods<T> = Omit<\n  AgentMethods<T>,\n  keyof OptionalAgentMethods<T>\n>;\n\nexport type AgentPromiseReturnType<T, K extends keyof AgentMethods<T>> =\n  // oxlint-disable-next-line @typescript-eslint/no-explicit-any -- generic promise return type\n  ReturnType<AgentMethods<T>[K]> extends Promise<any>\n    ? ReturnType<AgentMethods<T>[K]>\n    : Promise<ReturnType<AgentMethods<T>[K]>>;\n\nexport type AgentStub<T> = {\n  [K in keyof AgentMethods<T>]: (\n    ...args: Parameters<AgentMethods<T>[K]>\n  ) => AgentPromiseReturnType<AgentMethods<T>, K>;\n};\n\nexport type UntypedAgentStub = Record<string, Method>;\n\ntype AgentClientStub<AgentT> = keyof AgentMethods<AgentT> extends never\n  ? UntypedAgentStub\n  : AgentStub<AgentT>;\n\ntype OptionalArgsAgentClientCall<AgentT> = <\n  K extends keyof OptionalAgentMethods<AgentT>\n>(\n  method: K,\n  args?: Parameters<OptionalAgentMethods<AgentT>[K]>,\n  options?: CallOptions | StreamOptions\n) => AgentPromiseReturnType<AgentT, K>;\n\ntype RequiredArgsAgentClientCall<AgentT> = <\n  K extends keyof RequiredAgentMethods<AgentT>\n>(\n  method: K,\n  args: Parameters<RequiredAgentMethods<AgentT>[K]>,\n  options?: CallOptions | StreamOptions\n) => AgentPromiseReturnType<AgentT, K>;\n\ntype TypedAgentClientCall<AgentT> = OptionalArgsAgentClientCall<AgentT> &\n  RequiredArgsAgentClientCall<AgentT>;\n\ntype UntypedAgentClientCall = {\n  <T extends SerializableReturnValue>(\n    method: string,\n    args?: SerializableValue[],\n    options?: CallOptions | StreamOptions\n  ): Promise<T>;\n  <T = unknown>(\n    method: string,\n    args?: unknown[],\n    options?: CallOptions | StreamOptions\n  ): Promise<T>;\n};\n\ntype AgentClientCall<AgentT> = keyof AgentMethods<AgentT> extends never\n  ? UntypedAgentClientCall\n  : TypedAgentClientCall<AgentT>;\n\n/**\n * Creates a proxy that wraps RPC method calls.\n * Internal JS methods (toJSON, then, etc.) return undefined to avoid\n * triggering RPC calls during serialization (e.g., console.log)\n */\nexport function createStubProxy<T = Record<string, Method>>(\n  call: (method: string, args: unknown[]) => unknown\n): T {\n  // oxlint-disable-next-line @typescript-eslint/no-explicit-any -- proxy needs any for dynamic method access\n  return new Proxy<any>(\n    {},\n    {\n      get: (_target, method) => {\n        if (\n          typeof method === \"symbol\" ||\n          method === \"toJSON\" ||\n          method === \"then\" ||\n          method === \"catch\" ||\n          method === \"finally\" ||\n          method === \"valueOf\" ||\n          method === \"toString\" ||\n          method === \"constructor\" ||\n          method === \"prototype\" ||\n          method === \"$$typeof\" ||\n          method === \"@@toStringTag\" ||\n          method === \"asymmetricMatch\" ||\n          method === \"nodeType\"\n        ) {\n          return undefined;\n        }\n        return (...args: unknown[]) => call(method as string, args);\n      }\n    }\n  );\n}\n\n/**\n * WebSocket client for connecting to an Agent\n */\nexport class AgentClient<\n  AgentT = unknown,\n  State = AgentT extends { get state(): infer S } ? S : AgentT\n> extends PartySocket {\n  /**\n   * @deprecated Use agentFetch instead\n   */\n  static fetch(_opts: PartyFetchOptions): Promise<Response> {\n    throw new Error(\n      \"AgentClient.fetch is not implemented, use agentFetch instead\"\n    );\n  }\n  agent: string;\n  name: string;\n  call: AgentClientCall<AgentT>;\n  stub: AgentClientStub<AgentT>;\n\n  /**\n   * The current agent state, updated on server broadcasts and client setState calls.\n   * Starts as undefined until the first state message is received from the server.\n   */\n  state: State | undefined = undefined;\n\n  /**\n   * Whether the client has received identity from the server.\n   * Becomes true after the first identity message is received.\n   * Resets to false on connection close.\n   */\n  identified = false;\n\n  /**\n   * Promise that resolves when identity has been received from the server.\n   * Useful for waiting before making calls that depend on knowing the instance.\n   * Resets on connection close so it can be awaited again after reconnect.\n   */\n  get ready(): Promise<void> {\n    return this._readyPromise;\n  }\n\n  private options: AgentClientOptions<State>;\n  private _pendingCalls = new Map<\n    string,\n    {\n      resolve: (value: unknown) => void;\n      reject: (error: Error) => void;\n      stream?: StreamOptions;\n    }\n  >();\n  private _readyPromise!: Promise<void>;\n  private _resolveReady!: () => void;\n  private _previousName: string | null = null;\n  private _previousAgent: string | null = null;\n\n  private _resetReady() {\n    this._readyPromise = new Promise((resolve) => {\n      this._resolveReady = resolve;\n    });\n  }\n\n  constructor(options: AgentClientOptions<State>) {\n    const agentNamespace = camelCaseToKebabCase(options.agent);\n\n    // If basePath is provided, use it directly; otherwise construct from agent/name\n    const socketOptions = options.basePath\n      ? { basePath: options.basePath, path: options.path, ...options }\n      : {\n          party: agentNamespace,\n          prefix: \"agents\",\n          room: options.name || \"default\",\n          path: options.path,\n          ...options\n        };\n\n    super(socketOptions);\n    this.agent = agentNamespace;\n    this.name = options.name || \"default\";\n    this.options = options;\n\n    // Initialize ready promise\n    this._resetReady();\n\n    this.addEventListener(\"message\", (event) => {\n      if (typeof event.data === \"string\") {\n        let parsedMessage: Record<string, unknown>;\n        try {\n          parsedMessage = JSON.parse(event.data);\n        } catch (_error) {\n          // silently ignore invalid messages for now\n          // TODO: log errors with log levels\n          return;\n        }\n        if (parsedMessage.type === MessageType.CF_AGENT_IDENTITY) {\n          const oldName = this._previousName;\n          const oldAgent = this._previousAgent;\n          const newName = parsedMessage.name as string;\n          const newAgent = parsedMessage.agent as string;\n\n          // Resolve ready/identified\n          this.identified = true;\n          this._resolveReady();\n\n          // Detect identity change on reconnect\n          if (\n            oldName !== null &&\n            oldAgent !== null &&\n            (oldName !== newName || oldAgent !== newAgent)\n          ) {\n            if (this.options.onIdentityChange) {\n              this.options.onIdentityChange(\n                oldName,\n                newName,\n                oldAgent,\n                newAgent\n              );\n            } else {\n              const agentChanged = oldAgent !== newAgent;\n              const nameChanged = oldName !== newName;\n              let changeDescription = \"\";\n              if (agentChanged && nameChanged) {\n                changeDescription = `agent \"${oldAgent}\" → \"${newAgent}\", instance \"${oldName}\" → \"${newName}\"`;\n              } else if (agentChanged) {\n                changeDescription = `agent \"${oldAgent}\" → \"${newAgent}\"`;\n              } else {\n                changeDescription = `instance \"${oldName}\" → \"${newName}\"`;\n              }\n              console.warn(\n                `[agents] Identity changed on reconnect: ${changeDescription}. ` +\n                  \"This can happen with server-side routing (e.g., basePath with getAgentByName) \" +\n                  \"where the instance is determined by auth/session. \" +\n                  \"Provide onIdentityChange callback to handle this explicitly, \" +\n                  \"or ignore if this is expected for your routing pattern.\"\n              );\n            }\n          }\n\n          // Always update from server identity (server is authoritative)\n          this._previousName = newName;\n          this._previousAgent = newAgent;\n          this.name = newName;\n          this.agent = newAgent;\n\n          // Call onIdentity callback\n          this.options.onIdentity?.(newName, newAgent);\n          return;\n        }\n        if (parsedMessage.type === MessageType.CF_AGENT_STATE) {\n          this.state = parsedMessage.state as State;\n          this.options.onStateUpdate?.(parsedMessage.state as State, \"server\");\n          return;\n        }\n        if (parsedMessage.type === MessageType.CF_AGENT_STATE_ERROR) {\n          this.options.onStateUpdateError?.(parsedMessage.error as string);\n          return;\n        }\n        if (parsedMessage.type === MessageType.RPC) {\n          const response = parsedMessage as RPCResponse;\n          const pending = this._pendingCalls.get(response.id);\n          if (!pending) return;\n\n          if (!response.success) {\n            pending.reject(new Error(response.error));\n            this._pendingCalls.delete(response.id);\n            pending.stream?.onError?.(response.error);\n            return;\n          }\n\n          // Handle streaming responses\n          if (\"done\" in response) {\n            if (response.done) {\n              pending.resolve(response.result);\n              this._pendingCalls.delete(response.id);\n              pending.stream?.onDone?.(response.result);\n            } else {\n              pending.stream?.onChunk?.(response.result);\n            }\n          } else {\n            // Non-streaming response\n            pending.resolve(response.result);\n            this._pendingCalls.delete(response.id);\n          }\n        }\n      }\n    });\n\n    // Clean up pending calls and reset ready state when connection closes\n    this.addEventListener(\"close\", () => {\n      // Reset ready state for next connection\n      this.identified = false;\n      this._resetReady();\n\n      // Reject any remaining pending calls (e.g., from unexpected disconnect)\n      this._rejectPendingCalls(\"Connection closed\");\n    });\n\n    this.call = this._callImpl.bind(this) as AgentClientCall<AgentT>;\n    this.stub = createStubProxy((method, args) =>\n      this._callImpl(method, args)\n    ) as AgentClientStub<AgentT>;\n  }\n\n  /**\n   * Reject all pending RPC calls with the given reason.\n   */\n  private _rejectPendingCalls(reason: string) {\n    const error = new Error(reason);\n    for (const pending of this._pendingCalls.values()) {\n      pending.reject(error);\n      pending.stream?.onError?.(reason);\n    }\n    this._pendingCalls.clear();\n  }\n\n  setState(state: State) {\n    this.send(JSON.stringify({ state, type: MessageType.CF_AGENT_STATE }));\n    this.state = state;\n    this.options.onStateUpdate?.(state, \"client\");\n  }\n\n  /**\n   * Close the connection and immediately reject all pending RPC calls.\n   * This provides immediate feedback on intentional close rather than\n   * waiting for the WebSocket close handshake to complete.\n   *\n   * Note: Any calls made after `close()` will be rejected when the\n   * underlying WebSocket close event fires.\n   */\n  close(code?: number, reason?: string) {\n    // Immediately reject all pending calls on intentional close\n    this._rejectPendingCalls(\"Connection closed\");\n\n    // Then close the underlying socket\n    super.close(code, reason);\n  }\n\n  /**\n   * Call a method on the Agent.\n   * When AgentT is provided, method names are inferred from the agent's methods.\n   * Falls back to untyped string-based calls when AgentT is not provided.\n   */\n  private async _callImpl(\n    method: string,\n    args: unknown[] = [],\n    options?: CallOptions | StreamOptions\n  ): Promise<unknown> {\n    return new Promise((resolve, reject) => {\n      const id = crypto.randomUUID();\n      let timeoutId: ReturnType<typeof setTimeout> | undefined;\n\n      // Detect legacy format: { onChunk?, onDone?, onError? } vs new format: { timeout?, stream? }\n      const isLegacyFormat =\n        options &&\n        (\"onChunk\" in options || \"onDone\" in options || \"onError\" in options);\n      const streamOptions = isLegacyFormat\n        ? (options as StreamOptions)\n        : (options as CallOptions | undefined)?.stream;\n      const timeout = isLegacyFormat\n        ? undefined\n        : (options as CallOptions | undefined)?.timeout;\n\n      // Set up timeout if specified\n      if (timeout) {\n        timeoutId = setTimeout(() => {\n          const pending = this._pendingCalls.get(id);\n          this._pendingCalls.delete(id);\n          const errorMessage = `RPC call to ${method} timed out after ${timeout}ms`;\n          pending?.stream?.onError?.(errorMessage);\n          reject(new Error(errorMessage));\n        }, timeout);\n      }\n\n      this._pendingCalls.set(id, {\n        reject: (e: Error) => {\n          if (timeoutId) clearTimeout(timeoutId);\n          reject(e);\n        },\n        resolve: (value: unknown) => {\n          if (timeoutId) clearTimeout(timeoutId);\n          resolve(value);\n        },\n        stream: streamOptions\n      });\n\n      const request: RPCRequest = {\n        args,\n        id,\n        method,\n        type: MessageType.RPC\n      };\n\n      this.send(JSON.stringify(request));\n    });\n  }\n}\n\n/**\n * Make an HTTP request to an Agent\n * @param opts Connection options\n * @param init Request initialization options\n * @returns Promise resolving to a Response\n */\nexport function agentFetch(opts: AgentClientFetchOptions, init?: RequestInit) {\n  const agentNamespace = camelCaseToKebabCase(opts.agent);\n\n  // If basePath is provided, use it directly; otherwise construct from agent/name\n  // When basePath is set, room/party aren't used by PartySocket (basePath replaces the URL)\n  if (opts.basePath) {\n    return PartySocket.fetch(\n      { basePath: opts.basePath, ...opts } as unknown as PartyFetchOptions,\n      init\n    );\n  }\n\n  return PartySocket.fetch(\n    {\n      party: agentNamespace,\n      prefix: \"agents\",\n      room: opts.name || \"default\",\n      ...opts\n    },\n    init\n  );\n}\n"],"mappings":"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"}
+{"version":3,"file":"client.js","names":[],"sources":["../src/client.ts"],"sourcesContent":["import {\n  type PartyFetchOptions,\n  PartySocket,\n  type PartySocketOptions\n} from \"partysocket\";\nimport type { Agent, RPCRequest, RPCResponse } from \"./\";\nimport type {\n  Method,\n  RPCMethod,\n  SerializableReturnValue,\n  SerializableValue\n} from \"./serializable\";\nimport { MessageType } from \"./types\";\nimport { camelCaseToKebabCase, isInternalJsStubProp } from \"./utils\";\n\n/**\n * Options for creating an AgentClient\n */\nexport type AgentClientOptions<State = unknown> = Omit<\n  PartySocketOptions,\n  \"party\" | \"room\"\n> & {\n  /** Name of the agent to connect to (ignored if basePath is set) */\n  agent: string;\n  /** Name of the specific Agent instance (ignored if basePath is set) */\n  name?: string;\n  /**\n   * Full URL path - bypasses agent/name URL construction.\n   * When set, the client connects to this path directly.\n   * Server must handle routing manually (e.g., with getAgentByName + fetch).\n   * @example\n   * // Client connects to /user, server routes based on session\n   * useAgent({ agent: \"UserAgent\", basePath: \"user\" })\n   */\n  basePath?: string;\n  /** Called when the Agent's state is updated */\n  onStateUpdate?: (state: State, source: \"server\" | \"client\") => void;\n  /** Called when a state update fails (e.g., connection is readonly) */\n  onStateUpdateError?: (error: string) => void;\n  /**\n   * Called when the server sends the agent's identity on connect.\n   * Useful when using basePath, as the actual instance name is determined server-side.\n   * @param name The actual agent instance name\n   * @param agent The agent class name (kebab-case)\n   */\n  onIdentity?: (name: string, agent: string) => void;\n  /**\n   * Called when identity changes on reconnect (different instance than before).\n   * If not provided and identity changes, a warning will be logged.\n   * @param oldName Previous instance name\n   * @param newName New instance name\n   * @param oldAgent Previous agent class name\n   * @param newAgent New agent class name\n   */\n  onIdentityChange?: (\n    oldName: string,\n    newName: string,\n    oldAgent: string,\n    newAgent: string\n  ) => void;\n  /**\n   * Additional path to append to the URL.\n   * Works with both standard routing and basePath.\n   * @example\n   * // With basePath: /user/settings\n   * { basePath: \"user\", path: \"settings\" }\n   * // Standard: /agents/my-agent/room/settings\n   * { agent: \"MyAgent\", name: \"room\", path: \"settings\" }\n   */\n  path?: string;\n};\n\n/**\n * Options for streaming RPC calls\n */\nexport type StreamOptions = {\n  /** Called when a chunk of data is received */\n  onChunk?: (chunk: unknown) => void;\n  /** Called when the stream ends */\n  onDone?: (finalChunk: unknown) => void;\n  /** Called when an error occurs */\n  onError?: (error: string) => void;\n};\n\n/**\n * Options for RPC calls\n */\nexport type CallOptions = {\n  /** Timeout in milliseconds. If the call doesn't complete within this time, it will be rejected. */\n  timeout?: number;\n  /** Streaming options for handling streaming responses */\n  stream?: StreamOptions;\n};\n\n/**\n * Options for the agentFetch function\n */\nexport type AgentClientFetchOptions = Omit<\n  PartyFetchOptions,\n  \"party\" | \"room\"\n> & {\n  /** Name of the agent to connect to (ignored if basePath is set) */\n  agent: string;\n  /** Name of the specific Agent instance (ignored if basePath is set) */\n  name?: string;\n  /**\n   * Full URL path - bypasses agent/name URL construction.\n   * When set, the request is made to this path directly.\n   */\n  basePath?: string;\n};\n\n// ---- Shared RPC Type Utilities ----\n\ntype AllOptional<T> = T extends [infer A, ...infer R]\n  ? undefined extends A\n    ? AllOptional<R>\n    : false\n  : true;\n\nexport type RPCMethods<T> = {\n  [K in keyof T as T[K] extends RPCMethod<T[K]> ? K : never]: RPCMethod<T[K]>;\n};\n\ntype OptionalParametersMethod<T extends RPCMethod> =\n  AllOptional<Parameters<T>> extends true ? T : never;\n\n// oxlint-disable-next-line @typescript-eslint/no-explicit-any -- generic agent type constraint\nexport type AgentMethods<T> = Omit<RPCMethods<T>, keyof Agent<any, any>>;\n\nexport type OptionalAgentMethods<T> = {\n  [K in keyof AgentMethods<T> as AgentMethods<T>[K] extends OptionalParametersMethod<\n    AgentMethods<T>[K]\n  >\n    ? K\n    : never]: OptionalParametersMethod<AgentMethods<T>[K]>;\n};\n\nexport type RequiredAgentMethods<T> = Omit<\n  AgentMethods<T>,\n  keyof OptionalAgentMethods<T>\n>;\n\nexport type AgentPromiseReturnType<T, K extends keyof AgentMethods<T>> =\n  // oxlint-disable-next-line @typescript-eslint/no-explicit-any -- generic promise return type\n  ReturnType<AgentMethods<T>[K]> extends Promise<any>\n    ? ReturnType<AgentMethods<T>[K]>\n    : Promise<ReturnType<AgentMethods<T>[K]>>;\n\nexport type AgentStub<T> = {\n  [K in keyof AgentMethods<T>]: (\n    ...args: Parameters<AgentMethods<T>[K]>\n  ) => AgentPromiseReturnType<AgentMethods<T>, K>;\n};\n\nexport type UntypedAgentStub = Record<string, Method>;\n\ntype AgentClientStub<AgentT> = keyof AgentMethods<AgentT> extends never\n  ? UntypedAgentStub\n  : AgentStub<AgentT>;\n\ntype OptionalArgsAgentClientCall<AgentT> = <\n  K extends keyof OptionalAgentMethods<AgentT>\n>(\n  method: K,\n  args?: Parameters<OptionalAgentMethods<AgentT>[K]>,\n  options?: CallOptions | StreamOptions\n) => AgentPromiseReturnType<AgentT, K>;\n\ntype RequiredArgsAgentClientCall<AgentT> = <\n  K extends keyof RequiredAgentMethods<AgentT>\n>(\n  method: K,\n  args: Parameters<RequiredAgentMethods<AgentT>[K]>,\n  options?: CallOptions | StreamOptions\n) => AgentPromiseReturnType<AgentT, K>;\n\ntype TypedAgentClientCall<AgentT> = OptionalArgsAgentClientCall<AgentT> &\n  RequiredArgsAgentClientCall<AgentT>;\n\ntype UntypedAgentClientCall = {\n  <T extends SerializableReturnValue>(\n    method: string,\n    args?: SerializableValue[],\n    options?: CallOptions | StreamOptions\n  ): Promise<T>;\n  <T = unknown>(\n    method: string,\n    args?: unknown[],\n    options?: CallOptions | StreamOptions\n  ): Promise<T>;\n};\n\ntype AgentClientCall<AgentT> = keyof AgentMethods<AgentT> extends never\n  ? UntypedAgentClientCall\n  : TypedAgentClientCall<AgentT>;\n\n/**\n * Creates a proxy that wraps RPC method calls.\n * Internal JS methods (toJSON, then, etc.) return undefined to avoid\n * triggering RPC calls during serialization (e.g., console.log)\n */\nexport function createStubProxy<T = Record<string, Method>>(\n  call: (method: string, args: unknown[]) => unknown\n): T {\n  // oxlint-disable-next-line @typescript-eslint/no-explicit-any -- proxy needs any for dynamic method access\n  return new Proxy<any>(\n    {},\n    {\n      get: (_target, method) => {\n        if (isInternalJsStubProp(method)) {\n          return undefined;\n        }\n        return (...args: unknown[]) => call(method as string, args);\n      }\n    }\n  );\n}\n\n/**\n * WebSocket client for connecting to an Agent\n */\nexport class AgentClient<\n  AgentT = unknown,\n  State = AgentT extends { get state(): infer S } ? S : AgentT\n> extends PartySocket {\n  /**\n   * @deprecated Use agentFetch instead\n   */\n  static fetch(_opts: PartyFetchOptions): Promise<Response> {\n    throw new Error(\n      \"AgentClient.fetch is not implemented, use agentFetch instead\"\n    );\n  }\n  agent: string;\n  name: string;\n  call: AgentClientCall<AgentT>;\n  stub: AgentClientStub<AgentT>;\n\n  /**\n   * The current agent state, updated on server broadcasts and client setState calls.\n   * Starts as undefined until the first state message is received from the server.\n   */\n  state: State | undefined = undefined;\n\n  /**\n   * Whether the client has received identity from the server.\n   * Becomes true after the first identity message is received.\n   * Resets to false on connection close.\n   */\n  identified = false;\n\n  /**\n   * Promise that resolves when identity has been received from the server.\n   * Useful for waiting before making calls that depend on knowing the instance.\n   * Resets on connection close so it can be awaited again after reconnect.\n   */\n  get ready(): Promise<void> {\n    return this._readyPromise;\n  }\n\n  private options: AgentClientOptions<State>;\n  private _pendingCalls = new Map<\n    string,\n    {\n      resolve: (value: unknown) => void;\n      reject: (error: Error) => void;\n      stream?: StreamOptions;\n    }\n  >();\n  private _readyPromise!: Promise<void>;\n  private _resolveReady!: () => void;\n  private _previousName: string | null = null;\n  private _previousAgent: string | null = null;\n\n  private _resetReady() {\n    this._readyPromise = new Promise((resolve) => {\n      this._resolveReady = resolve;\n    });\n  }\n\n  constructor(options: AgentClientOptions<State>) {\n    const agentNamespace = camelCaseToKebabCase(options.agent);\n\n    // If basePath is provided, use it directly; otherwise construct from agent/name\n    const socketOptions = options.basePath\n      ? { basePath: options.basePath, path: options.path, ...options }\n      : {\n          party: agentNamespace,\n          prefix: \"agents\",\n          room: options.name || \"default\",\n          path: options.path,\n          ...options\n        };\n\n    super(socketOptions);\n    this.agent = agentNamespace;\n    this.name = options.name || \"default\";\n    this.options = options;\n\n    // Initialize ready promise\n    this._resetReady();\n\n    this.addEventListener(\"message\", (event) => {\n      if (typeof event.data === \"string\") {\n        let parsedMessage: Record<string, unknown>;\n        try {\n          parsedMessage = JSON.parse(event.data);\n        } catch (_error) {\n          // silently ignore invalid messages for now\n          // TODO: log errors with log levels\n          return;\n        }\n        if (parsedMessage.type === MessageType.CF_AGENT_IDENTITY) {\n          const oldName = this._previousName;\n          const oldAgent = this._previousAgent;\n          const newName = parsedMessage.name as string;\n          const newAgent = parsedMessage.agent as string;\n\n          // Resolve ready/identified\n          this.identified = true;\n          this._resolveReady();\n\n          // Detect identity change on reconnect\n          if (\n            oldName !== null &&\n            oldAgent !== null &&\n            (oldName !== newName || oldAgent !== newAgent)\n          ) {\n            if (this.options.onIdentityChange) {\n              this.options.onIdentityChange(\n                oldName,\n                newName,\n                oldAgent,\n                newAgent\n              );\n            } else {\n              const agentChanged = oldAgent !== newAgent;\n              const nameChanged = oldName !== newName;\n              let changeDescription = \"\";\n              if (agentChanged && nameChanged) {\n                changeDescription = `agent \"${oldAgent}\" → \"${newAgent}\", instance \"${oldName}\" → \"${newName}\"`;\n              } else if (agentChanged) {\n                changeDescription = `agent \"${oldAgent}\" → \"${newAgent}\"`;\n              } else {\n                changeDescription = `instance \"${oldName}\" → \"${newName}\"`;\n              }\n              console.warn(\n                `[agents] Identity changed on reconnect: ${changeDescription}. ` +\n                  \"This can happen with server-side routing (e.g., basePath with getAgentByName) \" +\n                  \"where the instance is determined by auth/session. \" +\n                  \"Provide onIdentityChange callback to handle this explicitly, \" +\n                  \"or ignore if this is expected for your routing pattern.\"\n              );\n            }\n          }\n\n          // Always update from server identity (server is authoritative)\n          this._previousName = newName;\n          this._previousAgent = newAgent;\n          this.name = newName;\n          this.agent = newAgent;\n\n          // Call onIdentity callback\n          this.options.onIdentity?.(newName, newAgent);\n          return;\n        }\n        if (parsedMessage.type === MessageType.CF_AGENT_STATE) {\n          this.state = parsedMessage.state as State;\n          this.options.onStateUpdate?.(parsedMessage.state as State, \"server\");\n          return;\n        }\n        if (parsedMessage.type === MessageType.CF_AGENT_STATE_ERROR) {\n          this.options.onStateUpdateError?.(parsedMessage.error as string);\n          return;\n        }\n        if (parsedMessage.type === MessageType.RPC) {\n          const response = parsedMessage as RPCResponse;\n          const pending = this._pendingCalls.get(response.id);\n          if (!pending) return;\n\n          if (!response.success) {\n            pending.reject(new Error(response.error));\n            this._pendingCalls.delete(response.id);\n            pending.stream?.onError?.(response.error);\n            return;\n          }\n\n          // Handle streaming responses\n          if (\"done\" in response) {\n            if (response.done) {\n              pending.resolve(response.result);\n              this._pendingCalls.delete(response.id);\n              pending.stream?.onDone?.(response.result);\n            } else {\n              pending.stream?.onChunk?.(response.result);\n            }\n          } else {\n            // Non-streaming response\n            pending.resolve(response.result);\n            this._pendingCalls.delete(response.id);\n          }\n        }\n      }\n    });\n\n    // Clean up pending calls and reset ready state when connection closes\n    this.addEventListener(\"close\", () => {\n      // Reset ready state for next connection\n      this.identified = false;\n      this._resetReady();\n\n      // Reject any remaining pending calls (e.g., from unexpected disconnect)\n      this._rejectPendingCalls(\"Connection closed\");\n    });\n\n    this.call = this._callImpl.bind(this) as AgentClientCall<AgentT>;\n    this.stub = createStubProxy((method, args) =>\n      this._callImpl(method, args)\n    ) as AgentClientStub<AgentT>;\n  }\n\n  /**\n   * Reject all pending RPC calls with the given reason.\n   */\n  private _rejectPendingCalls(reason: string) {\n    const error = new Error(reason);\n    for (const pending of this._pendingCalls.values()) {\n      pending.reject(error);\n      pending.stream?.onError?.(reason);\n    }\n    this._pendingCalls.clear();\n  }\n\n  setState(state: State) {\n    this.send(JSON.stringify({ state, type: MessageType.CF_AGENT_STATE }));\n    this.state = state;\n    this.options.onStateUpdate?.(state, \"client\");\n  }\n\n  /**\n   * Close the connection and immediately reject all pending RPC calls.\n   * This provides immediate feedback on intentional close rather than\n   * waiting for the WebSocket close handshake to complete.\n   *\n   * Note: Any calls made after `close()` will be rejected when the\n   * underlying WebSocket close event fires.\n   */\n  close(code?: number, reason?: string) {\n    // Immediately reject all pending calls on intentional close\n    this._rejectPendingCalls(\"Connection closed\");\n\n    // Then close the underlying socket\n    super.close(code, reason);\n  }\n\n  /**\n   * Call a method on the Agent.\n   * When AgentT is provided, method names are inferred from the agent's methods.\n   * Falls back to untyped string-based calls when AgentT is not provided.\n   */\n  private async _callImpl(\n    method: string,\n    args: unknown[] = [],\n    options?: CallOptions | StreamOptions\n  ): Promise<unknown> {\n    return new Promise((resolve, reject) => {\n      const id = crypto.randomUUID();\n      let timeoutId: ReturnType<typeof setTimeout> | undefined;\n\n      // Detect legacy format: { onChunk?, onDone?, onError? } vs new format: { timeout?, stream? }\n      const isLegacyFormat =\n        options &&\n        (\"onChunk\" in options || \"onDone\" in options || \"onError\" in options);\n      const streamOptions = isLegacyFormat\n        ? (options as StreamOptions)\n        : (options as CallOptions | undefined)?.stream;\n      const timeout = isLegacyFormat\n        ? undefined\n        : (options as CallOptions | undefined)?.timeout;\n\n      // Set up timeout if specified\n      if (timeout) {\n        timeoutId = setTimeout(() => {\n          const pending = this._pendingCalls.get(id);\n          this._pendingCalls.delete(id);\n          const errorMessage = `RPC call to ${method} timed out after ${timeout}ms`;\n          pending?.stream?.onError?.(errorMessage);\n          reject(new Error(errorMessage));\n        }, timeout);\n      }\n\n      this._pendingCalls.set(id, {\n        reject: (e: Error) => {\n          if (timeoutId) clearTimeout(timeoutId);\n          reject(e);\n        },\n        resolve: (value: unknown) => {\n          if (timeoutId) clearTimeout(timeoutId);\n          resolve(value);\n        },\n        stream: streamOptions\n      });\n\n      const request: RPCRequest = {\n        args,\n        id,\n        method,\n        type: MessageType.RPC\n      };\n\n      this.send(JSON.stringify(request));\n    });\n  }\n}\n\n/**\n * Make an HTTP request to an Agent\n * @param opts Connection options\n * @param init Request initialization options\n * @returns Promise resolving to a Response\n */\nexport function agentFetch(opts: AgentClientFetchOptions, init?: RequestInit) {\n  const agentNamespace = camelCaseToKebabCase(opts.agent);\n\n  // If basePath is provided, use it directly; otherwise construct from agent/name\n  // When basePath is set, room/party aren't used by PartySocket (basePath replaces the URL)\n  if (opts.basePath) {\n    return PartySocket.fetch(\n      { basePath: opts.basePath, ...opts } as unknown as PartyFetchOptions,\n      init\n    );\n  }\n\n  return PartySocket.fetch(\n    {\n      party: agentNamespace,\n      prefix: \"agents\",\n      room: opts.name || \"default\",\n      ...opts\n    },\n    init\n  );\n}\n"],"mappings":"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"}

package/dist/{index-D9qo_Inc.d.ts → index-DabjI66m.d.ts}

@@ -1,5 +1,5 @@
 import { n as AgentEmail } from "./internal_context-BvuGZieY.js";
-import { t as RetryOptions } from "./retries-JlwH9mnV.js";
+import { t as RetryOptions } from "./retries-fLD8cGNf.js";
 import {
   n as Observability,
   r as ObservabilityEvent,
@@ -67,6 +67,122 @@ import { Server as Server$1 } from "@modelcontextprotocol/sdk/server/index.js";
 import { Client as Client$1 } from "@modelcontextprotocol/sdk/client";
 import { EventStore } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
 
+//#region src/sub-routing.d.ts
+/**
+ * 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).
+ */
+declare const SUB_PREFIX = "sub";
+interface SubAgentPathMatch {
+  /** CamelCase class name of the child, as it appears in `ctx.exports`. */
+  childClass: string;
+  /** URL-decoded child name. */
+  childName: string;
+  /**
+   * Request path to forward to the child, with the
+   * `/sub/{class}/{name}` segment stripped. Always begins with `/`;
+   * may itself contain further `/sub/...` markers when a
+   * recursively nested sub-agent is being routed.
+   */
+  remainingPath: string;
+}
+/**
+ * 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.
+ */
+declare function parseSubAgentPath(
+  url: string,
+  options?: {
+    /** CamelCase class names to match against (usually `ctx.exports` keys). */ knownClasses?: readonly string[];
+  }
+): SubAgentPathMatch | null;
+/**
+ * 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.
+ */
+declare function routeSubAgentRequest(
+  req: Request,
+  parent: unknown,
+  options?: {
+    /**
+     * Path to route on. Defaults to `req.url`'s pathname. Useful
+     * when your outer URL is custom (e.g. `/api/v1/...`) and you
+     * want to route the sub-agent tail without rewriting the
+     * Request first.
+     */
+    fromPath?: string;
+  }
+): Promise<Response>;
+/**
+ * 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.
+ */
+declare function getSubAgentByName<T extends Agent>(
+  parent: unknown,
+  cls: SubAgentClass<T>,
+  name: string
+): Promise<SubAgentStub<T>>;
+//#endregion
 //#region src/core/events.d.ts
 interface Disposable {
   dispose(): void;
@@ -1796,6 +1912,13 @@ declare class Agent<
   private _persistenceHookMode;
   /** True when this agent runs as a facet (sub-agent) inside a parent. */
   private _isFacet;
+  /**
+   * Ancestor chain, root-first. Empty for top-level DOs; populated at
+   * facet init time from the parent's own `selfPath`. Exposed publicly
+   * via the `parentPath` getter.
+   * @internal
+   */
+  private _parentPath;
   /** True while user's onStart() is executing. Used to warn about non-idempotent schedule() calls. */
   private _insideOnStart;
   /** Tracks callbacks already warned about during this onStart() to avoid log spam. */
@@ -1903,18 +2026,6 @@ declare class Agent<
    * @param excludeIds Additional connection IDs to exclude (e.g. the source)
    */
   private _broadcastProtocol;
-  /**
-   * When running as a facet, the parent DO owns the WebSocket registry
-   * (`ctx.getWebSockets()`). Iterating from the child isolate throws
-   * "Cannot perform I/O on behalf of a different Durable Object".
-   * Downstream callers (e.g. chat-streaming paths) invoke
-   * `this.broadcast()` directly, bypassing `_broadcastProtocol`'s
-   * guard, so override at the base to catch every path.
-   */
-  broadcast(
-    msg: string | ArrayBuffer | ArrayBufferView,
-    without?: string[]
-  ): void;
   private _setStateInternal;
   /**
    * Update the Agent's state
@@ -2293,6 +2404,12 @@ declare class Agent<
    * alarm system, without creating schedule rows or emitting observability
    * events. Configure via `static options = { keepAliveIntervalMs: 5000 }`.
    *
+   * No-op on facets. Facets share the parent's isolate and don't
+   * need a separate alarm heartbeat — the parent's own activity,
+   * any open WebSocket to the facet, and any in-flight Promise
+   * already keep the shared machine alive for the duration of
+   * real work.
+   *
    * @example
    * ```ts
    * const dispose = await this.keepAlive();
@@ -2385,6 +2502,90 @@ declare class Agent<
    * See {@link https://developers.cloudflare.com/agents/api-reference/schedule-tasks/}
    */
   alarm(): Promise<void>;
+  /**
+   * Intercept incoming HTTP/WS requests whose URL contains a
+   * `/sub/{child-class}/{child-name}` marker and forward them to
+   * the facet. The `onBeforeSubAgent` hook fires first (authorize,
+   * mutate, or short-circuit). If the hook doesn't return a
+   * Response, the framework resolves the facet and hands the
+   * request off.
+   *
+   * After a WebSocket upgrade completes, subsequent frames route
+   * directly to the child — the parent is only on the path for the
+   * initial request.
+   *
+   * @experimental The API surface may change before stabilizing.
+   */
+  fetch(request: Request): Promise<Response>;
+  /**
+   * Parent-side middleware hook. Fires before a request is
+   * forwarded into a facet sub-agent. Mirrors `onBeforeConnect` /
+   * `onBeforeRequest`.
+   *
+   *   - return `void` (default) → forward the original request
+   *   - return `Request`        → forward this (modified) request
+   *   - return `Response`       → return this response to the
+   *                               client; do not wake the child
+   *
+   * Default implementation: return void (permissive).
+   *
+   * The hook receives the **original** request with its URL intact —
+   * including the `/sub/{class}/{name}` segment. The routing
+   * decision for which facet to wake is fixed at parse time, so if
+   * you return a modified `Request`, its headers, body, method, and
+   * query string flow through to the child, but the **pathname**
+   * the child sees is always the tail after `/sub/{class}/{name}`.
+   * Customize via headers/body rather than URL-rewriting.
+   *
+   * WebSocket upgrade requests flow through this hook the same way as
+   * plain HTTP. If you return a mutated `Request`, make sure it still
+   * carries the original `Upgrade: websocket` and `Sec-WebSocket-*`
+   * headers — the simplest safe recipe is to clone the incoming
+   * request's headers (via `new Headers(req.headers)`) and only add
+   * or replace entries, rather than constructing a fresh `Headers`
+   * object from scratch.
+   *
+   * @experimental The API surface may change before stabilizing.
+   *
+   * @example
+   * ```ts
+   * class Inbox extends Agent {
+   *   override async onBeforeSubAgent(req, { className, name }) {
+   *     // Strict registry gate
+   *     if (!this.hasSubAgent(className, name)) {
+   *       return new Response("Not found", { status: 404 });
+   *     }
+   *   }
+   * }
+   * ```
+   */
+  onBeforeSubAgent(
+    _request: Request,
+    _child: {
+      className: string;
+      name: string;
+    }
+  ): Promise<Request | Response | void>;
+  /**
+   * Resolve the facet Fetcher for the match and forward the
+   * request to it with `/sub/{class}/{name}` stripped.
+   *
+   * @internal
+   */
+  private _cf_forwardToFacet;
+  /**
+   * Bridge method used by `getSubAgentByName`. Resolves the facet
+   * on each call (idempotent via `subAgent`) and dispatches one
+   * RPC method. Stateless — no cached references.
+   *
+   * @internal
+   */
+  _cf_invokeSubAgent(
+    className: string,
+    name: string,
+    method: string,
+    args: unknown[]
+  ): Promise<unknown>;
   /**
    * Initialize this agent as a facet in a single RPC.
    *
@@ -2395,14 +2596,95 @@ declare class Agent<
    * parent and triggered "Cannot perform I/O on behalf of a different
    * Durable Object" on the child.
    *
-   * Order matters: set `_isFacet` BEFORE triggering initialization, so
-   * the first `onStart()` run (which calls `broadcastMcpServers`) sees
-   * the flag and skips broadcasts that would touch the parent DO's
-   * WebSocket registry.
+   * We still set `_isFacet` eagerly (before `__unsafe_ensureInitialized`)
+   * so any code that legitimately branches on it — e.g. skipping
+   * parent-owned alarms in schedule guards — sees the flag during
+   * the first `onStart()` run. Broadcast paths no longer special-case
+   * facets, since facets can be directly addressed via sub-agent
+   * routing and have their own WebSocket connections.
    *
    * @internal Called by {@link subAgent}.
    */
-  _cf_initAsFacet(name: string): Promise<void>;
+  _cf_initAsFacet(
+    name: string,
+    parentPath?: ReadonlyArray<{
+      className: string;
+      name: string;
+    }>
+  ): Promise<void>;
+  /**
+   * Ancestor chain for this agent, root-first. Empty for top-level
+   * DOs. Populated at facet init time; survives hibernation.
+   *
+   * @example
+   * ```ts
+   * class Chat extends Agent {
+   *   onStart() {
+   *     console.log("chat started under:", this.parentPath);
+   *     // → [{ className: "Tenant", name: "acme" }, { className: "Inbox", name: "alice" }]
+   *   }
+   * }
+   * ```
+   *
+   * @experimental The API surface may change before stabilizing.
+   */
+  get parentPath(): ReadonlyArray<{
+    className: string;
+    name: string;
+  }>;
+  /**
+   * Ancestor chain + self, root-first. Convenient for logging.
+   *
+   * @experimental The API surface may change before stabilizing.
+   */
+  get selfPath(): ReadonlyArray<{
+    className: string;
+    name: string;
+  }>;
+  /**
+   * Resolve a typed RPC stub for this facet's **immediate** parent
+   * agent.
+   *
+   * Symmetric with `subAgent(Cls, name)`: while `subAgent` opens a
+   * stub from parent to child, `parentAgent` opens one from child
+   * to parent. Pass the direct parent's class reference — the
+   * framework verifies it matches the last entry of
+   * `this.parentPath` at runtime, then looks up `env[Cls.name]` to
+   * find the namespace binding.
+   *
+   * `this.parentPath` is root-first, so the direct parent is the
+   * **last** entry: `this.parentPath.at(-1)`. For grandparents and
+   * further ancestors, iterate `this.parentPath` and use
+   * `getAgentByName(env.X, this.parentPath[i].name)` directly.
+   *
+   * Assumes the standard "binding name matches class name" convention.
+   * If your `wrangler.jsonc` binds the parent under a different name
+   * (e.g. `{ class_name: "Inbox", name: "MY_INBOX" }`), call
+   * `getAgentByName(env.MY_INBOX, this.parentPath.at(-1)!.name)`
+   * directly instead.
+   *
+   * @experimental The API surface may change before stabilizing.
+   *
+   * @throws If this agent is not a facet (no parent).
+   * @throws If `Cls.name` doesn't match the recorded direct-parent
+   *         class (guards against accidentally reaching the wrong
+   *         DO, especially in nested Root → Mid → Leaf chains).
+   * @throws If no env binding named `Cls.name` is found.
+   *
+   * @example
+   * ```ts
+   * class Chat extends AIChatAgent<Env> {
+   *   async onChatMessage(...) {
+   *     const inbox = await this.parentAgent(Inbox);
+   *     const memory = await inbox.getSharedMemory("facts");
+   *     // ...
+   *   }
+   * }
+   * ```
+   */
+  parentAgent<T extends Agent>(
+    cls: SubAgentClass<T>
+  ): Promise<DurableObjectStub<T>>;
   /**
    * Get or create a named sub-agent — a child Durable Object (facet)
    * with its own isolated SQLite storage running on the same machine.
@@ -2427,6 +2709,16 @@ declare class Agent<
     cls: SubAgentClass<T>,
     name: string
   ): Promise<SubAgentStub<T>>;
+  /**
+   * Shared facet resolution — takes a CamelCase class name string
+   * (matching `ctx.exports`) rather than a class reference. Both
+   * `subAgent(cls, name)` and `_cf_invokeSubAgent(className, ...)`
+   * funnel through here so registry bookkeeping and the
+   * `_cf_initAsFacet` handshake are consistent.
+   *
+   * @internal
+   */
+  private _cf_resolveSubAgent;
   /**
    * Forcefully abort a running sub-agent. The child stops executing
    * immediately and will be restarted on next {@link subAgent} call.
@@ -2450,6 +2742,54 @@ declare class Agent<
    * @param name Name of the child to delete
    */
   deleteSubAgent(cls: SubAgentClass, name: string): void;
+  /** @internal */
+  private _subAgentRegistryReady;
+  /** @internal */
+  private _ensureSubAgentRegistry;
+  /** @internal */
+  private _recordSubAgent;
+  /** @internal */
+  private _forgetSubAgent;
+  /**
+   * Whether this agent has previously spawned (and not deleted) a
+   * sub-agent of the given class and name. Backed by an
+   * auto-maintained SQLite registry in the parent's storage.
+   *
+   * Intended for strict-registry access patterns in
+   * `onBeforeSubAgent` or similar gating logic.
+   *
+   * @experimental The API surface may change before stabilizing.
+   *
+   * @example
+   * ```ts
+   * async onBeforeSubAgent(req, { className, name }) {
+   *   if (!this.hasSubAgent(className, name)) {
+   *     return new Response("Not found", { status: 404 });
+   *   }
+   * }
+   * ```
+   */
+  hasSubAgent<T extends Agent>(cls: SubAgentClass<T>, name: string): boolean;
+  hasSubAgent(className: string, name: string): boolean;
+  /**
+   * List known sub-agents, optionally filtered by class. Reflects
+   * the registry rows written by {@link subAgent} and removed by
+   * {@link deleteSubAgent}.
+   *
+   * @experimental The API surface may change before stabilizing.
+   */
+  listSubAgents<T extends Agent>(
+    cls: SubAgentClass<T>
+  ): Array<{
+    className: string;
+    name: string;
+    createdAt: number;
+  }>;
+  listSubAgents(className?: string): Array<{
+    className: string;
+    name: string;
+    createdAt: number;
+  }>;
   /**
    * Destroy the Agent, removing all state and scheduled tasks
    */
@@ -3068,6 +3408,7 @@ export {
   RPCServerTransport as Y,
   RPC_DO_PREFIX as Z,
   MCPServerMessage as _,
+  parseSubAgentPath as _t,
   AgentNamespace as a,
   McpAuthContext as at,
   RPCRequest as b,
@@ -3079,7 +3420,9 @@ export {
   EmailRoutingOptions as f,
   McpClientOptions as ft,
   MCPServer as g,
+  getSubAgentByName as gt,
   FiberRecoveryContext as h,
+  SubAgentPathMatch as ht,
   AgentContext as i,
   experimental_createMcpHandler as it,
   getAgentByName as j,
@@ -3087,6 +3430,7 @@ export {
   Connection$1 as l,
   WorkerTransportOptions as lt,
   FiberContext as m,
+  SUB_PREFIX as mt,
   AddRpcMcpServerOptions as n,
   CreateMcpHandlerOptions as nt,
   AgentOptions as o,
@@ -3103,9 +3447,10 @@ export {
   ConnectionContext$1 as u,
   SSEEdgeClientTransport as ut,
   MCPServersState as v,
+  routeSubAgentRequest as vt,
   SqlError as w,
   RPCResponse as x,
   QueueItem as y,
   MCPClientOAuthResult as z
 };
-//# sourceMappingURL=index-D9qo_Inc.d.ts.map
+//# sourceMappingURL=index-DabjI66m.d.ts.map

package/dist/index.d.ts

@@ -1,5 +1,4 @@
 import { r as __DO_NOT_USE_WILL_BREAK__agentContext } from "./internal_context-BvuGZieY.js";
-import { t as RetryOptions } from "./retries-JlwH9mnV.js";
 import {
   A as callable,
   C as SendEmailOptions,
@@ -13,18 +12,22 @@ import {
   S as Schedule,
   T as StateUpdateMessage,
   _ as MCPServerMessage,
+  _t as parseSubAgentPath,
   a as AgentNamespace,
   b as RPCRequest,
   c as CallableMetadata,
   d as DEFAULT_AGENT_STATIC_OPTIONS,
   f as EmailRoutingOptions,
   g as MCPServer,
+  gt as getSubAgentByName,
   h as FiberRecoveryContext,
+  ht as SubAgentPathMatch,
   i as AgentContext,
   j as getAgentByName,
   k as WSMessage,
   l as Connection,
   m as FiberContext,
+  mt as SUB_PREFIX,
   n as AddRpcMcpServerOptions,
   o as AgentOptions,
   p as EmailSendBinding,
@@ -34,10 +37,12 @@ import {
   t as AddMcpServerOptions,
   u as ConnectionContext,
   v as MCPServersState,
+  vt as routeSubAgentRequest,
   w as SqlError,
   x as RPCResponse,
   y as QueueItem
-} from "./index-D9qo_Inc.js";
+} from "./index-DabjI66m.js";
+import { t as RetryOptions } from "./retries-fLD8cGNf.js";
 import {
   n as AgentsOAuthProvider,
   r as DurableObjectOAuthClientProvider,
@@ -72,12 +77,14 @@ export {
   RPCRequest,
   RPCResponse,
   RetryOptions,
+  SUB_PREFIX,
   Schedule,
   SendEmailOptions,
   SqlError,
   StateUpdateMessage,
   StreamingResponse,
   SubAgentClass,
+  SubAgentPathMatch,
   SubAgentStub,
   TransportType,
   WSMessage,
@@ -86,7 +93,10 @@ export {
   createHeaderBasedEmailResolver,
   getAgentByName,
   getCurrentAgent,
+  getSubAgentByName,
+  parseSubAgentPath,
   routeAgentEmail,
   routeAgentRequest,
+  routeSubAgentRequest,
   unstable_callable
 };