agents 0.3.9 → 0.4.0

package/dist/react.js

@@ -1,5 +1,5 @@
-import { t as MessageType } from "./types-BITaDFf-.js";
-import { t as camelCaseToKebabCase } from "./utils-B49TmLCI.js";
+import { MessageType } from "./types.js";
+import { camelCaseToKebabCase } from "./utils.js";
 import { usePartySocket } from "partysocket/react";
 import { use, useCallback, useEffect, useMemo, useRef, useState } from "react";
 
@@ -49,7 +49,8 @@ const _testUtils = {
 	getCacheEntry,
 	deleteCacheEntry,
 	clearCache: () => queryCache.clear(),
-	createStubProxy
+	createStubProxy,
+	createCacheKey
 };
 function useAgent(options) {
 	const agentNamespace = camelCaseToKebabCase(options.agent);
@@ -60,8 +61,12 @@ function useAgent(options) {
 		options.name,
 		queryDeps
 	]);
+	const cacheKeyRef = useRef(cacheKey);
+	cacheKeyRef.current = cacheKey;
 	const ttl = cacheTtl ?? 300 * 1e3;
 	const [cacheInvalidatedAt, setCacheInvalidatedAt] = useState(0);
+	const isAsyncQuery = query && typeof query === "function";
+	const [awaitingQueryRefresh, setAwaitingQueryRefresh] = useState(false);
 	const queryPromise = useMemo(() => {
 		if (!query || typeof query !== "function") return null;
 		const cached = getCacheEntry(cacheKey);
@@ -103,6 +108,9 @@ function useAgent(options) {
 			resolvedQuery = queryResult;
 		}
 	} else resolvedQuery = query;
+	useEffect(() => {
+		if (awaitingQueryRefresh && resolvedQuery !== void 0) setAwaitingQueryRefresh(false);
+	}, [awaitingQueryRefresh, resolvedQuery]);
 	const [identity, setIdentity] = useState({
 		name: options.name || "default",
 		agent: agentNamespace,
@@ -123,20 +131,23 @@ function useAgent(options) {
 		};
 	};
 	if (!readyRef.current) resetReady();
+	const socketOptions = options.basePath ? {
+		basePath: options.basePath,
+		path: options.path,
+		query: resolvedQuery,
+		...restOptions
+	} : {
+		party: agentNamespace,
+		prefix: "agents",
+		room: options.name || "default",
+		path: options.path,
+		query: resolvedQuery,
+		...restOptions
+	};
+	const socketEnabled = !awaitingQueryRefresh && (restOptions.enabled ?? true);
 	const agent = usePartySocket({
-		...options.basePath ? {
-			basePath: options.basePath,
-			path: options.path,
-			query: resolvedQuery,
-			...restOptions
-		} : {
-			party: agentNamespace,
-			prefix: "agents",
-			room: options.name || "default",
-			path: options.path,
-			query: resolvedQuery,
-			...restOptions
-		},
+		...socketOptions,
+		enabled: socketEnabled,
 		onMessage: (message) => {
 			if (typeof message.data === "string") {
 				let parsedMessage;
@@ -177,6 +188,10 @@ function useAgent(options) {
 					options.onStateUpdate?.(parsedMessage.state, "server");
 					return;
 				}
+				if (parsedMessage.type === MessageType.CF_AGENT_STATE_ERROR) {
+					options.onStateUpdateError?.(parsedMessage.error);
+					return;
+				}
 				if (parsedMessage.type === MessageType.CF_AGENT_MCP_SERVERS) {
 					options.onMcpUpdate?.(parsedMessage.mcp);
 					return;
@@ -211,6 +226,9 @@ function useAgent(options) {
 				...prev,
 				identified: false
 			}));
+			if (isAsyncQuery) setAwaitingQueryRefresh(true);
+			deleteCacheEntry(cacheKeyRef.current);
+			setCacheInvalidatedAt(Date.now());
 			const error = /* @__PURE__ */ new Error("Connection closed");
 			for (const pending of pendingCallsRef.current.values()) {
 				pending.reject(error);

package/dist/react.js.map

@@ -1 +1 @@
-{"version":3,"file":"react.js","names":[],"sources":["../src/react.tsx"],"sourcesContent":["import type { PartySocket } from \"partysocket\";\nimport { usePartySocket } from \"partysocket/react\";\nimport { useCallback, useRef, use, useMemo, useState, useEffect } from \"react\";\nimport type { Agent, MCPServersState, RPCRequest, RPCResponse } from \"./\";\nimport type { StreamOptions } from \"./client\";\nimport { camelCaseToKebabCase } from \"./utils\";\nimport type { Method, RPCMethod } from \"./serializable\";\nimport { MessageType } from \"./types\";\n\ntype QueryObject = Record<string, string | null>;\n\ninterface CacheEntry {\n  promise: Promise<QueryObject>;\n  expiresAt: number;\n}\n\nconst queryCache = new Map<string, CacheEntry>();\n\nfunction createCacheKey(\n  agentNamespace: string,\n  name: string | undefined,\n  deps: unknown[]\n): string {\n  return JSON.stringify([agentNamespace, name || \"default\", ...deps]);\n}\n\nfunction getCacheEntry(key: string): CacheEntry | undefined {\n  const entry = queryCache.get(key);\n  if (!entry) return undefined;\n\n  if (Date.now() >= entry.expiresAt) {\n    queryCache.delete(key);\n    return undefined;\n  }\n\n  return entry;\n}\n\nfunction setCacheEntry(\n  key: string,\n  promise: Promise<QueryObject>,\n  cacheTtl: number\n): CacheEntry {\n  const entry: CacheEntry = {\n    promise,\n    expiresAt: Date.now() + cacheTtl\n  };\n  queryCache.set(key, entry);\n  return entry;\n}\n\nfunction deleteCacheEntry(key: string): void {\n  queryCache.delete(key);\n}\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 */\nfunction createStubProxy<T = Record<string, Method>>(\n  call: (method: string, args: unknown[]) => unknown\n): T {\n  // biome-ignore lint/suspicious/noExplicitAny: proxy needs any for dynamic method access\n  return new Proxy<any>(\n    {},\n    {\n      get: (_target, method) => {\n        // Skip internal JavaScript methods that shouldn't trigger RPC calls.\n        // These are commonly accessed by console.log, JSON.stringify, and other\n        // serialization utilities.\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// Export for testing purposes\nexport const _testUtils = {\n  queryCache,\n  setCacheEntry,\n  getCacheEntry,\n  deleteCacheEntry,\n  clearCache: () => queryCache.clear(),\n  createStubProxy\n};\n\n/**\n * Options for the useAgent hook\n * @template State Type of the Agent's state\n */\nexport type UseAgentOptions<State = unknown> = Omit<\n  Parameters<typeof usePartySocket>[0],\n  \"party\" | \"room\" | \"query\"\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  /** Query parameters - can be static object or async function */\n  query?: QueryObject | (() => Promise<QueryObject>);\n  /** Dependencies for async query caching */\n  queryDeps?: unknown[];\n  /** Cache TTL in milliseconds for auth tokens/time-sensitive data */\n  cacheTtl?: number;\n  /** Called when the Agent's state is updated */\n  onStateUpdate?: (state: State, source: \"server\" | \"client\") => void;\n  /** Called when MCP server state is updated */\n  onMcpUpdate?: (mcpServers: MCPServersState) => 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\ntype AllOptional<T> = T extends [infer A, ...infer R]\n  ? undefined extends A\n    ? AllOptional<R>\n    : false\n  : true; // no params means optional by default\n\ntype 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// all methods of the Agent, excluding the ones that are declared in the base Agent class\n// biome-ignore lint: suppressions/parse\ntype AgentMethods<T> = Omit<RPCMethods<T>, keyof Agent<any, any>>;\n\ntype 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\ntype RequiredAgentMethods<T> = Omit<\n  AgentMethods<T>,\n  keyof OptionalAgentMethods<T>\n>;\n\ntype AgentPromiseReturnType<T, K extends keyof AgentMethods<T>> =\n  // biome-ignore lint: suppressions/parse\n  ReturnType<AgentMethods<T>[K]> extends Promise<any>\n    ? ReturnType<AgentMethods<T>[K]>\n    : Promise<ReturnType<AgentMethods<T>[K]>>;\n\ntype OptionalArgsAgentMethodCall<AgentT> = <\n  K extends keyof OptionalAgentMethods<AgentT>\n>(\n  method: K,\n  args?: Parameters<OptionalAgentMethods<AgentT>[K]>,\n  streamOptions?: StreamOptions\n) => AgentPromiseReturnType<AgentT, K>;\n\ntype RequiredArgsAgentMethodCall<AgentT> = <\n  K extends keyof RequiredAgentMethods<AgentT>\n>(\n  method: K,\n  args: Parameters<RequiredAgentMethods<AgentT>[K]>,\n  streamOptions?: StreamOptions\n) => AgentPromiseReturnType<AgentT, K>;\n\ntype AgentMethodCall<AgentT> = OptionalArgsAgentMethodCall<AgentT> &\n  RequiredArgsAgentMethodCall<AgentT>;\n\ntype UntypedAgentMethodCall = <T = unknown>(\n  method: string,\n  args?: unknown[],\n  streamOptions?: StreamOptions\n) => Promise<T>;\n\ntype AgentStub<T> = {\n  [K in keyof AgentMethods<T>]: (\n    ...args: Parameters<AgentMethods<T>[K]>\n  ) => AgentPromiseReturnType<AgentMethods<T>, K>;\n};\n\n// we neet to use Method instead of RPCMethod here for retro-compatibility\ntype UntypedAgentStub = Record<string, Method>;\n\n/**\n * React hook for connecting to an Agent\n */\nexport function useAgent<State = unknown>(\n  options: UseAgentOptions<State>\n): PartySocket & {\n  agent: string;\n  name: string;\n  identified: boolean;\n  ready: Promise<void>;\n  setState: (state: State) => void;\n  call: UntypedAgentMethodCall;\n  stub: UntypedAgentStub;\n};\nexport function useAgent<\n  AgentT extends {\n    get state(): State;\n  },\n  State\n>(\n  options: UseAgentOptions<State>\n): PartySocket & {\n  agent: string;\n  name: string;\n  identified: boolean;\n  ready: Promise<void>;\n  setState: (state: State) => void;\n  call: AgentMethodCall<AgentT>;\n  stub: AgentStub<AgentT>;\n};\nexport function useAgent<State>(\n  options: UseAgentOptions<unknown>\n): PartySocket & {\n  agent: string;\n  name: string;\n  identified: boolean;\n  ready: Promise<void>;\n  setState: (state: State) => void;\n  call: UntypedAgentMethodCall | AgentMethodCall<unknown>;\n  stub: UntypedAgentStub;\n} {\n  const agentNamespace = camelCaseToKebabCase(options.agent);\n  const { query, queryDeps, cacheTtl, ...restOptions } = options;\n\n  // Keep track of pending RPC calls\n  const pendingCallsRef = useRef(\n    new Map<\n      string,\n      {\n        resolve: (value: unknown) => void;\n        reject: (error: Error) => void;\n        stream?: StreamOptions;\n      }\n    >()\n  );\n\n  const cacheKey = useMemo(\n    () => createCacheKey(agentNamespace, options.name, queryDeps || []),\n    [agentNamespace, options.name, queryDeps]\n  );\n\n  const ttl = cacheTtl ?? 5 * 60 * 1000;\n\n  // Track cache invalidation to force re-render when TTL expires\n  const [cacheInvalidatedAt, setCacheInvalidatedAt] = useState<number>(0);\n\n  // Get or create the query promise\n  // biome-ignore lint/correctness/useExhaustiveDependencies: cacheInvalidatedAt intentionally forces re-evaluation when TTL expires\n  const queryPromise = useMemo(() => {\n    if (!query || typeof query !== \"function\") {\n      return null;\n    }\n\n    // Always check cache first to deduplicate concurrent requests\n    const cached = getCacheEntry(cacheKey);\n    if (cached) {\n      return cached.promise;\n    }\n\n    // Create new promise\n    const promise = query().catch((error) => {\n      console.error(\n        `[useAgent] Query failed for agent \"${options.agent}\":`,\n        error\n      );\n      deleteCacheEntry(cacheKey);\n      throw error;\n    });\n\n    // Always cache to deduplicate concurrent requests\n    setCacheEntry(cacheKey, promise, ttl);\n\n    return promise;\n  }, [cacheKey, query, options.agent, ttl, cacheInvalidatedAt]);\n\n  // Schedule cache invalidation when TTL expires\n  useEffect(() => {\n    if (!queryPromise || ttl <= 0) return;\n\n    const entry = getCacheEntry(cacheKey);\n    if (!entry) return;\n\n    const timeUntilExpiry = entry.expiresAt - Date.now();\n\n    // Always set a timer (with min 0ms) to ensure cleanup function is returned\n    const timer = setTimeout(\n      () => {\n        deleteCacheEntry(cacheKey);\n        setCacheInvalidatedAt(Date.now());\n      },\n      Math.max(0, timeUntilExpiry)\n    );\n\n    return () => clearTimeout(timer);\n  }, [cacheKey, queryPromise, ttl]);\n\n  let resolvedQuery: QueryObject | undefined;\n\n  if (query) {\n    if (typeof query === \"function\") {\n      // Use React's use() to resolve the promise\n      const queryResult = use(queryPromise!);\n\n      // Check for non-primitive values and warn\n      if (queryResult) {\n        for (const [key, value] of Object.entries(queryResult)) {\n          if (\n            value !== null &&\n            value !== undefined &&\n            typeof value !== \"string\" &&\n            typeof value !== \"number\" &&\n            typeof value !== \"boolean\"\n          ) {\n            console.warn(\n              `[useAgent] Query parameter \"${key}\" is an object and will be converted to \"[object Object]\". ` +\n                \"Query parameters should be string, number, boolean, or null.\"\n            );\n          }\n        }\n        resolvedQuery = queryResult;\n      }\n    } else {\n      // Sync query - use directly\n      resolvedQuery = query;\n    }\n  }\n\n  // Store identity in React state for reactivity\n  const [identity, setIdentity] = useState({\n    name: options.name || \"default\",\n    agent: agentNamespace,\n    identified: false\n  });\n\n  // Track previous identity for change detection\n  const previousIdentityRef = useRef<{\n    name: string | null;\n    agent: string | null;\n  }>({ name: null, agent: null });\n\n  // Ready promise - resolves when identity is received, resets on close\n  const readyRef = useRef<\n    { promise: Promise<void>; resolve: () => void } | undefined\n  >(undefined);\n\n  const resetReady = () => {\n    let resolve: () => void;\n    const promise = new Promise<void>((r) => {\n      resolve = r;\n    });\n    readyRef.current = { promise, resolve: resolve! };\n  };\n\n  if (!readyRef.current) {\n    resetReady();\n  }\n\n  // If basePath is provided, use it directly; otherwise construct from agent/name\n  const socketOptions = options.basePath\n    ? {\n        basePath: options.basePath,\n        path: options.path,\n        query: resolvedQuery,\n        ...restOptions\n      }\n    : {\n        party: agentNamespace,\n        prefix: \"agents\",\n        room: options.name || \"default\",\n        path: options.path,\n        query: resolvedQuery,\n        ...restOptions\n      };\n\n  const agent = usePartySocket({\n    ...socketOptions,\n    onMessage: (message) => {\n      if (typeof message.data === \"string\") {\n        let parsedMessage: Record<string, unknown>;\n        try {\n          parsedMessage = JSON.parse(message.data);\n        } catch (_error) {\n          // silently ignore invalid messages for now\n          // TODO: log errors with log levels\n          return options.onMessage?.(message);\n        }\n        if (parsedMessage.type === MessageType.CF_AGENT_IDENTITY) {\n          const oldName = previousIdentityRef.current.name;\n          const oldAgent = previousIdentityRef.current.agent;\n          const newName = parsedMessage.name as string;\n          const newAgent = parsedMessage.agent as string;\n\n          // Update reactive state (triggers re-render)\n          setIdentity({ name: newName, agent: newAgent, identified: true });\n\n          // Resolve ready promise\n          readyRef.current?.resolve();\n\n          // Detect identity change on reconnect\n          if (\n            oldName !== null &&\n            oldAgent !== null &&\n            (oldName !== newName || oldAgent !== newAgent)\n          ) {\n            if (options.onIdentityChange) {\n              options.onIdentityChange(oldName, newName, oldAgent, newAgent);\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          // Track for next change detection\n          previousIdentityRef.current = { name: newName, agent: newAgent };\n\n          // Call onIdentity callback\n          options.onIdentity?.(newName, newAgent);\n          return;\n        }\n        if (parsedMessage.type === MessageType.CF_AGENT_STATE) {\n          options.onStateUpdate?.(parsedMessage.state as State, \"server\");\n          return;\n        }\n        if (parsedMessage.type === MessageType.CF_AGENT_MCP_SERVERS) {\n          options.onMcpUpdate?.(parsedMessage.mcp as MCPServersState);\n          return;\n        }\n        if (parsedMessage.type === MessageType.RPC) {\n          const response = parsedMessage as RPCResponse;\n          const pending = pendingCallsRef.current.get(response.id);\n          if (!pending) return;\n\n          if (!response.success) {\n            pending.reject(new Error(response.error));\n            pendingCallsRef.current.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              pendingCallsRef.current.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            pendingCallsRef.current.delete(response.id);\n          }\n          return;\n        }\n      }\n      options.onMessage?.(message);\n    },\n    onClose: (event: CloseEvent) => {\n      // Reset ready state for next connection\n      resetReady();\n      setIdentity((prev) => ({ ...prev, identified: false }));\n\n      // Reject all pending calls (consistent with AgentClient behavior)\n      const error = new Error(\"Connection closed\");\n      for (const pending of pendingCallsRef.current.values()) {\n        pending.reject(error);\n        pending.stream?.onError?.(\"Connection closed\");\n      }\n      pendingCallsRef.current.clear();\n\n      // Call user's onClose if provided\n      options.onClose?.(event);\n    }\n  }) as PartySocket & {\n    agent: string;\n    name: string;\n    identified: boolean;\n    ready: Promise<void>;\n    setState: (state: State) => void;\n    call: UntypedAgentMethodCall;\n    stub: UntypedAgentStub;\n  };\n  // Create the call method\n  const call = useCallback(\n    <T = unknown,>(\n      method: string,\n      args: unknown[] = [],\n      streamOptions?: StreamOptions\n    ): Promise<T> => {\n      return new Promise((resolve, reject) => {\n        const id = crypto.randomUUID();\n        pendingCallsRef.current.set(id, {\n          reject,\n          resolve: resolve as (value: unknown) => void,\n          stream: streamOptions\n        });\n\n        const request: RPCRequest = {\n          args,\n          id,\n          method,\n          type: MessageType.RPC\n        };\n\n        agent.send(JSON.stringify(request));\n      });\n    },\n    [agent]\n  );\n\n  agent.setState = (state: State) => {\n    agent.send(JSON.stringify({ state, type: MessageType.CF_AGENT_STATE }));\n    options.onStateUpdate?.(state, \"client\");\n  };\n\n  agent.call = call;\n  // Use reactive identity state (updates on identity message)\n  agent.agent = identity.agent;\n  agent.name = identity.name;\n  agent.identified = identity.identified;\n  agent.ready = readyRef.current!.promise;\n  agent.stub = createStubProxy(call);\n\n  // warn if agent isn't in lowercase\n  if (identity.agent !== identity.agent.toLowerCase()) {\n    console.warn(\n      \"Agent name: \" +\n        identity.agent +\n        \" should probably be in lowercase. Received: \" +\n        identity.agent\n    );\n  }\n\n  return agent;\n}\n"],"mappings":"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"}
+{"version":3,"file":"react.js","names":[],"sources":["../src/react.tsx"],"sourcesContent":["import type { PartySocket } from \"partysocket\";\nimport { usePartySocket } from \"partysocket/react\";\nimport { useCallback, useRef, use, useMemo, useState, useEffect } from \"react\";\nimport type { Agent, MCPServersState, RPCRequest, RPCResponse } from \"./\";\nimport type { StreamOptions } from \"./client\";\nimport { camelCaseToKebabCase } from \"./utils\";\nimport type { Method, RPCMethod } from \"./serializable\";\nimport { MessageType } from \"./types\";\n\ntype QueryObject = Record<string, string | null>;\n\ninterface CacheEntry {\n  promise: Promise<QueryObject>;\n  expiresAt: number;\n}\n\nconst queryCache = new Map<string, CacheEntry>();\n\nfunction createCacheKey(\n  agentNamespace: string,\n  name: string | undefined,\n  deps: unknown[]\n): string {\n  return JSON.stringify([agentNamespace, name || \"default\", ...deps]);\n}\n\nfunction getCacheEntry(key: string): CacheEntry | undefined {\n  const entry = queryCache.get(key);\n  if (!entry) return undefined;\n\n  if (Date.now() >= entry.expiresAt) {\n    queryCache.delete(key);\n    return undefined;\n  }\n\n  return entry;\n}\n\nfunction setCacheEntry(\n  key: string,\n  promise: Promise<QueryObject>,\n  cacheTtl: number\n): CacheEntry {\n  const entry: CacheEntry = {\n    promise,\n    expiresAt: Date.now() + cacheTtl\n  };\n  queryCache.set(key, entry);\n  return entry;\n}\n\nfunction deleteCacheEntry(key: string): void {\n  queryCache.delete(key);\n}\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 */\nfunction 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        // Skip internal JavaScript methods that shouldn't trigger RPC calls.\n        // These are commonly accessed by console.log, JSON.stringify, and other\n        // serialization utilities.\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// Export for testing purposes\nexport const _testUtils = {\n  queryCache,\n  setCacheEntry,\n  getCacheEntry,\n  deleteCacheEntry,\n  clearCache: () => queryCache.clear(),\n  createStubProxy,\n  createCacheKey\n};\n\n/**\n * Options for the useAgent hook\n * @template State Type of the Agent's state\n */\nexport type UseAgentOptions<State = unknown> = Omit<\n  Parameters<typeof usePartySocket>[0],\n  \"party\" | \"room\" | \"query\"\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  /** Query parameters - can be static object or async function */\n  query?: QueryObject | (() => Promise<QueryObject>);\n  /** Dependencies for async query caching */\n  queryDeps?: unknown[];\n  /** Cache TTL in milliseconds for auth tokens/time-sensitive data */\n  cacheTtl?: number;\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  /** Called when MCP server state is updated */\n  onMcpUpdate?: (mcpServers: MCPServersState) => 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\ntype AllOptional<T> = T extends [infer A, ...infer R]\n  ? undefined extends A\n    ? AllOptional<R>\n    : false\n  : true; // no params means optional by default\n\ntype 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// all methods of the Agent, excluding the ones that are declared in the base Agent class\n// oxlint-disable-next-line @typescript-eslint/no-explicit-any -- generic agent type constraint\ntype AgentMethods<T> = Omit<RPCMethods<T>, keyof Agent<any, any>>;\n\ntype 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\ntype RequiredAgentMethods<T> = Omit<\n  AgentMethods<T>,\n  keyof OptionalAgentMethods<T>\n>;\n\ntype 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\ntype OptionalArgsAgentMethodCall<AgentT> = <\n  K extends keyof OptionalAgentMethods<AgentT>\n>(\n  method: K,\n  args?: Parameters<OptionalAgentMethods<AgentT>[K]>,\n  streamOptions?: StreamOptions\n) => AgentPromiseReturnType<AgentT, K>;\n\ntype RequiredArgsAgentMethodCall<AgentT> = <\n  K extends keyof RequiredAgentMethods<AgentT>\n>(\n  method: K,\n  args: Parameters<RequiredAgentMethods<AgentT>[K]>,\n  streamOptions?: StreamOptions\n) => AgentPromiseReturnType<AgentT, K>;\n\ntype AgentMethodCall<AgentT> = OptionalArgsAgentMethodCall<AgentT> &\n  RequiredArgsAgentMethodCall<AgentT>;\n\ntype UntypedAgentMethodCall = <T = unknown>(\n  method: string,\n  args?: unknown[],\n  streamOptions?: StreamOptions\n) => Promise<T>;\n\ntype AgentStub<T> = {\n  [K in keyof AgentMethods<T>]: (\n    ...args: Parameters<AgentMethods<T>[K]>\n  ) => AgentPromiseReturnType<AgentMethods<T>, K>;\n};\n\n// we neet to use Method instead of RPCMethod here for retro-compatibility\ntype UntypedAgentStub = Record<string, Method>;\n\n/**\n * React hook for connecting to an Agent\n */\nexport function useAgent<State = unknown>(\n  options: UseAgentOptions<State>\n): PartySocket & {\n  agent: string;\n  name: string;\n  identified: boolean;\n  ready: Promise<void>;\n  setState: (state: State) => void;\n  call: UntypedAgentMethodCall;\n  stub: UntypedAgentStub;\n};\nexport function useAgent<\n  AgentT extends {\n    get state(): State;\n  },\n  State\n>(\n  options: UseAgentOptions<State>\n): PartySocket & {\n  agent: string;\n  name: string;\n  identified: boolean;\n  ready: Promise<void>;\n  setState: (state: State) => void;\n  call: AgentMethodCall<AgentT>;\n  stub: AgentStub<AgentT>;\n};\nexport function useAgent<State>(\n  options: UseAgentOptions<unknown>\n): PartySocket & {\n  agent: string;\n  name: string;\n  identified: boolean;\n  ready: Promise<void>;\n  setState: (state: State) => void;\n  call: UntypedAgentMethodCall | AgentMethodCall<unknown>;\n  stub: UntypedAgentStub;\n} {\n  const agentNamespace = camelCaseToKebabCase(options.agent);\n  const { query, queryDeps, cacheTtl, ...restOptions } = options;\n\n  // Keep track of pending RPC calls\n  const pendingCallsRef = useRef(\n    new Map<\n      string,\n      {\n        resolve: (value: unknown) => void;\n        reject: (error: Error) => void;\n        stream?: StreamOptions;\n      }\n    >()\n  );\n\n  const cacheKey = useMemo(\n    () => createCacheKey(agentNamespace, options.name, queryDeps || []),\n    [agentNamespace, options.name, queryDeps]\n  );\n\n  // Track current cache key in a ref for use in onClose handler.\n  // This ensures we invalidate the correct cache entry when the connection closes,\n  // even if the component re-renders with different props before onClose fires.\n  // We update synchronously during render (not in useEffect) to avoid race\n  // conditions where onClose could fire before the effect runs.\n  const cacheKeyRef = useRef(cacheKey);\n  cacheKeyRef.current = cacheKey;\n\n  const ttl = cacheTtl ?? 5 * 60 * 1000;\n\n  // Track cache invalidation to force re-render when TTL expires\n  const [cacheInvalidatedAt, setCacheInvalidatedAt] = useState<number>(0);\n\n  // Disable socket while waiting for async query to refresh after disconnect\n  const isAsyncQuery = query && typeof query === \"function\";\n  const [awaitingQueryRefresh, setAwaitingQueryRefresh] = useState(false);\n\n  // Get or create the query promise\n  const queryPromise = useMemo(() => {\n    if (!query || typeof query !== \"function\") {\n      return null;\n    }\n\n    // Always check cache first to deduplicate concurrent requests\n    const cached = getCacheEntry(cacheKey);\n    if (cached) {\n      return cached.promise;\n    }\n\n    // Create new promise\n    const promise = query().catch((error) => {\n      console.error(\n        `[useAgent] Query failed for agent \"${options.agent}\":`,\n        error\n      );\n      deleteCacheEntry(cacheKey);\n      throw error;\n    });\n\n    // Always cache to deduplicate concurrent requests\n    setCacheEntry(cacheKey, promise, ttl);\n\n    return promise;\n  }, [cacheKey, query, options.agent, ttl, cacheInvalidatedAt]);\n\n  // Schedule cache invalidation when TTL expires\n  useEffect(() => {\n    if (!queryPromise || ttl <= 0) return;\n\n    const entry = getCacheEntry(cacheKey);\n    if (!entry) return;\n\n    const timeUntilExpiry = entry.expiresAt - Date.now();\n\n    // Always set a timer (with min 0ms) to ensure cleanup function is returned\n    const timer = setTimeout(\n      () => {\n        deleteCacheEntry(cacheKey);\n        setCacheInvalidatedAt(Date.now());\n      },\n      Math.max(0, timeUntilExpiry)\n    );\n\n    return () => clearTimeout(timer);\n  }, [cacheKey, queryPromise, ttl]);\n\n  let resolvedQuery: QueryObject | undefined;\n\n  if (query) {\n    if (typeof query === \"function\") {\n      // Use React's use() to resolve the promise\n      const queryResult = use(queryPromise!);\n\n      // Check for non-primitive values and warn\n      if (queryResult) {\n        for (const [key, value] of Object.entries(queryResult)) {\n          if (\n            value !== null &&\n            value !== undefined &&\n            typeof value !== \"string\" &&\n            typeof value !== \"number\" &&\n            typeof value !== \"boolean\"\n          ) {\n            console.warn(\n              `[useAgent] Query parameter \"${key}\" is an object and will be converted to \"[object Object]\". ` +\n                \"Query parameters should be string, number, boolean, or null.\"\n            );\n          }\n        }\n        resolvedQuery = queryResult;\n      }\n    } else {\n      // Sync query - use directly\n      resolvedQuery = query;\n    }\n  }\n\n  // Re-enable socket after async query resolves\n  useEffect(() => {\n    if (awaitingQueryRefresh && resolvedQuery !== undefined) {\n      setAwaitingQueryRefresh(false);\n    }\n  }, [awaitingQueryRefresh, resolvedQuery]);\n\n  // Store identity in React state for reactivity\n  const [identity, setIdentity] = useState({\n    name: options.name || \"default\",\n    agent: agentNamespace,\n    identified: false\n  });\n\n  // Track previous identity for change detection\n  const previousIdentityRef = useRef<{\n    name: string | null;\n    agent: string | null;\n  }>({ name: null, agent: null });\n\n  // Ready promise - resolves when identity is received, resets on close\n  const readyRef = useRef<\n    { promise: Promise<void>; resolve: () => void } | undefined\n  >(undefined);\n\n  const resetReady = () => {\n    let resolve: () => void;\n    const promise = new Promise<void>((r) => {\n      resolve = r;\n    });\n    readyRef.current = { promise, resolve: resolve! };\n  };\n\n  if (!readyRef.current) {\n    resetReady();\n  }\n\n  // If basePath is provided, use it directly; otherwise construct from agent/name\n  const socketOptions = options.basePath\n    ? {\n        basePath: options.basePath,\n        path: options.path,\n        query: resolvedQuery,\n        ...restOptions\n      }\n    : {\n        party: agentNamespace,\n        prefix: \"agents\",\n        room: options.name || \"default\",\n        path: options.path,\n        query: resolvedQuery,\n        ...restOptions\n      };\n\n  const socketEnabled = !awaitingQueryRefresh && (restOptions.enabled ?? true);\n\n  const agent = usePartySocket({\n    ...socketOptions,\n    enabled: socketEnabled,\n    onMessage: (message) => {\n      if (typeof message.data === \"string\") {\n        let parsedMessage: Record<string, unknown>;\n        try {\n          parsedMessage = JSON.parse(message.data);\n        } catch (_error) {\n          // silently ignore invalid messages for now\n          // TODO: log errors with log levels\n          return options.onMessage?.(message);\n        }\n        if (parsedMessage.type === MessageType.CF_AGENT_IDENTITY) {\n          const oldName = previousIdentityRef.current.name;\n          const oldAgent = previousIdentityRef.current.agent;\n          const newName = parsedMessage.name as string;\n          const newAgent = parsedMessage.agent as string;\n\n          // Update reactive state (triggers re-render)\n          setIdentity({ name: newName, agent: newAgent, identified: true });\n\n          // Resolve ready promise\n          readyRef.current?.resolve();\n\n          // Detect identity change on reconnect\n          if (\n            oldName !== null &&\n            oldAgent !== null &&\n            (oldName !== newName || oldAgent !== newAgent)\n          ) {\n            if (options.onIdentityChange) {\n              options.onIdentityChange(oldName, newName, oldAgent, newAgent);\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          // Track for next change detection\n          previousIdentityRef.current = { name: newName, agent: newAgent };\n\n          // Call onIdentity callback\n          options.onIdentity?.(newName, newAgent);\n          return;\n        }\n        if (parsedMessage.type === MessageType.CF_AGENT_STATE) {\n          options.onStateUpdate?.(parsedMessage.state as State, \"server\");\n          return;\n        }\n        if (parsedMessage.type === MessageType.CF_AGENT_STATE_ERROR) {\n          options.onStateUpdateError?.(parsedMessage.error as string);\n          return;\n        }\n        if (parsedMessage.type === MessageType.CF_AGENT_MCP_SERVERS) {\n          options.onMcpUpdate?.(parsedMessage.mcp as MCPServersState);\n          return;\n        }\n        if (parsedMessage.type === MessageType.RPC) {\n          const response = parsedMessage as RPCResponse;\n          const pending = pendingCallsRef.current.get(response.id);\n          if (!pending) return;\n\n          if (!response.success) {\n            pending.reject(new Error(response.error));\n            pendingCallsRef.current.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              pendingCallsRef.current.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            pendingCallsRef.current.delete(response.id);\n          }\n          return;\n        }\n      }\n      options.onMessage?.(message);\n    },\n    onClose: (event: CloseEvent) => {\n      // Reset ready state for next connection\n      resetReady();\n      setIdentity((prev) => ({ ...prev, identified: false }));\n\n      // Pause reconnection for async queries until fresh query params are ready\n      if (isAsyncQuery) {\n        setAwaitingQueryRefresh(true);\n      }\n\n      // Invalidate cache and trigger re-render to fetch fresh query params\n      deleteCacheEntry(cacheKeyRef.current);\n      setCacheInvalidatedAt(Date.now());\n\n      // Reject all pending calls (consistent with AgentClient behavior)\n      const error = new Error(\"Connection closed\");\n      for (const pending of pendingCallsRef.current.values()) {\n        pending.reject(error);\n        pending.stream?.onError?.(\"Connection closed\");\n      }\n      pendingCallsRef.current.clear();\n\n      // Call user's onClose if provided\n      options.onClose?.(event);\n    }\n  }) as PartySocket & {\n    agent: string;\n    name: string;\n    identified: boolean;\n    ready: Promise<void>;\n    setState: (state: State) => void;\n    call: UntypedAgentMethodCall;\n    stub: UntypedAgentStub;\n  };\n  // Create the call method\n  const call = useCallback(\n    <T = unknown>(\n      method: string,\n      args: unknown[] = [],\n      streamOptions?: StreamOptions\n    ): Promise<T> => {\n      return new Promise((resolve, reject) => {\n        const id = crypto.randomUUID();\n        pendingCallsRef.current.set(id, {\n          reject,\n          resolve: resolve as (value: unknown) => void,\n          stream: streamOptions\n        });\n\n        const request: RPCRequest = {\n          args,\n          id,\n          method,\n          type: MessageType.RPC\n        };\n\n        agent.send(JSON.stringify(request));\n      });\n    },\n    [agent]\n  );\n\n  agent.setState = (state: State) => {\n    agent.send(JSON.stringify({ state, type: MessageType.CF_AGENT_STATE }));\n    options.onStateUpdate?.(state, \"client\");\n  };\n\n  agent.call = call;\n  // Use reactive identity state (updates on identity message)\n  agent.agent = identity.agent;\n  agent.name = identity.name;\n  agent.identified = identity.identified;\n  agent.ready = readyRef.current!.promise;\n  agent.stub = createStubProxy(call);\n\n  // warn if agent isn't in lowercase\n  if (identity.agent !== identity.agent.toLowerCase()) {\n    console.warn(\n      \"Agent name: \" +\n        identity.agent +\n        \" should probably be in lowercase. Received: \" +\n        identity.agent\n    );\n  }\n\n  return agent;\n}\n"],"mappings":"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"}

package/dist/types.d.ts

@@ -1,2 +1,15 @@
-import { t as MessageType } from "./types-DSSHBW6w.js";
+//#region src/types.d.ts
+/**
+ * Enum for message types to improve type safety and maintainability
+ */
+declare enum MessageType {
+  CF_AGENT_MCP_SERVERS = "cf_agent_mcp_servers",
+  CF_MCP_AGENT_EVENT = "cf_mcp_agent_event",
+  CF_AGENT_STATE = "cf_agent_state",
+  CF_AGENT_STATE_ERROR = "cf_agent_state_error",
+  CF_AGENT_IDENTITY = "cf_agent_identity",
+  RPC = "rpc"
+}
+//#endregion
 export { MessageType };
+//# sourceMappingURL=types.d.ts.map

package/dist/types.js

@@ -1,3 +1,17 @@
-import { t as MessageType } from "./types-BITaDFf-.js";
+//#region src/types.ts
+/**
+* Enum for message types to improve type safety and maintainability
+*/
+let MessageType = /* @__PURE__ */ function(MessageType) {
+	MessageType["CF_AGENT_MCP_SERVERS"] = "cf_agent_mcp_servers";
+	MessageType["CF_MCP_AGENT_EVENT"] = "cf_mcp_agent_event";
+	MessageType["CF_AGENT_STATE"] = "cf_agent_state";
+	MessageType["CF_AGENT_STATE_ERROR"] = "cf_agent_state_error";
+	MessageType["CF_AGENT_IDENTITY"] = "cf_agent_identity";
+	MessageType["RPC"] = "rpc";
+	return MessageType;
+}({});
 
-export { MessageType };
+//#endregion
+export { MessageType };
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","names":[],"sources":["../src/types.ts"],"sourcesContent":["/**\n * Enum for message types to improve type safety and maintainability\n */\nexport enum MessageType {\n  CF_AGENT_MCP_SERVERS = \"cf_agent_mcp_servers\",\n  CF_MCP_AGENT_EVENT = \"cf_mcp_agent_event\",\n  CF_AGENT_STATE = \"cf_agent_state\",\n  CF_AGENT_STATE_ERROR = \"cf_agent_state_error\",\n  CF_AGENT_IDENTITY = \"cf_agent_identity\",\n  RPC = \"rpc\"\n}\n"],"mappings":";;;;AAGA,IAAY,oDAAL;AACL;AACA;AACA;AACA;AACA;AACA"}

package/dist/utils.js

@@ -1,3 +1,16 @@
-import { t as camelCaseToKebabCase } from "./utils-B49TmLCI.js";
+//#region src/utils.ts
+/**
+* Convert a camelCase string to a kebab-case string
+* @param str The string to convert
+* @returns The kebab-case string
+*/
+function camelCaseToKebabCase(str) {
+	if (str === str.toUpperCase() && str !== str.toLowerCase()) return str.toLowerCase().replace(/_/g, "-");
+	let kebabified = str.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`);
+	kebabified = kebabified.startsWith("-") ? kebabified.slice(1) : kebabified;
+	return kebabified.replace(/_/g, "-").replace(/-$/, "");
+}
 
-export { camelCaseToKebabCase };
+//#endregion
+export { camelCaseToKebabCase };
+//# sourceMappingURL=utils.js.map

package/dist/utils.js.map

@@ -0,0 +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"}

package/dist/workflow-types.d.ts

@@ -1,27 +1,238 @@
 import {
-  S as WorkflowTrackingRow,
-  _ as WorkflowPage,
-  a as ApprovalEventPayload,
-  b as WorkflowRejectedError,
-  c as WaitForApprovalOptions,
-  d as WorkflowCallbackType,
-  f as WorkflowCompleteCallback,
-  g as WorkflowInfo,
-  h as WorkflowEventPayload,
-  i as AgentWorkflowStep,
-  l as WorkflowCallback,
-  m as WorkflowEventCallback,
-  n as AgentWorkflowInternalParams,
-  o as DefaultProgress,
-  p as WorkflowErrorCallback,
-  r as AgentWorkflowParams,
-  s as RunWorkflowOptions,
-  t as AgentWorkflowEvent,
-  u as WorkflowCallbackBase,
-  v as WorkflowProgressCallback,
-  x as WorkflowStatus,
-  y as WorkflowQueryCriteria
-} from "./workflow-types-Z_Oem1FJ.js";
+  WorkflowEvent,
+  WorkflowSleepDuration,
+  WorkflowStep
+} from "cloudflare:workers";
+
+//#region src/workflow-types.d.ts
+/**
+ * Type alias for WorkflowEvent in AgentWorkflow context.
+ * Identical to WorkflowEvent - provided for naming consistency with AgentWorkflowStep.
+ */
+type AgentWorkflowEvent<Params = unknown> = WorkflowEvent<Params>;
+/**
+ * Extended WorkflowStep with durable Agent communication methods.
+ * All added methods on this interface are durable - they're idempotent and won't
+ * repeat on workflow retry.
+ */
+interface AgentWorkflowStep extends WorkflowStep {
+  /**
+   * Report successful completion to the Agent (durable).
+   * Triggers onWorkflowComplete() on the Agent.
+   * @param result - Optional result data
+   */
+  reportComplete<T = unknown>(result?: T): Promise<void>;
+  /**
+   * Report an error to the Agent (durable).
+   * Triggers onWorkflowError() on the Agent.
+   * @param error - Error or error message
+   */
+  reportError(error: Error | string): Promise<void>;
+  /**
+   * Send a custom event to the Agent (durable).
+   * Triggers onWorkflowEvent() on the Agent.
+   * @param event - Custom event payload
+   */
+  sendEvent<T = unknown>(event: T): Promise<void>;
+  /**
+   * Update the Agent's state entirely (durable).
+   * This will replace the Agent's state and broadcast to all connected clients.
+   * @param state - New state to set
+   */
+  updateAgentState(state: unknown): Promise<void>;
+  /**
+   * Merge partial state into the Agent's existing state (durable).
+   * Performs a shallow merge and broadcasts to all connected clients.
+   * @param partialState - Partial state to merge
+   */
+  mergeAgentState(partialState: Record<string, unknown>): Promise<void>;
+  /**
+   * Reset the Agent's state to its initialState (durable).
+   * Broadcasts the reset state to all connected clients.
+   */
+  resetAgentState(): Promise<void>;
+}
+/**
+ * Internal parameters injected by runWorkflow() to identify the originating Agent
+ */
+type AgentWorkflowInternalParams = {
+  /** Name/ID of the Agent that started this workflow */ __agentName: string /** Environment binding name for the Agent's namespace */;
+  __agentBinding: string /** Workflow binding name (for callbacks) */;
+  __workflowName: string;
+};
+/**
+ * Combined workflow params: user params + internal agent params
+ */
+type AgentWorkflowParams<T = unknown> = T & AgentWorkflowInternalParams;
+/**
+ * Workflow callback types for Agent-Workflow communication
+ */
+type WorkflowCallbackType = "progress" | "complete" | "error" | "event";
+/**
+ * Base callback structure sent from Workflow to Agent
+ */
+type WorkflowCallbackBase = {
+  /** Workflow binding name */ workflowName: string /** ID of the workflow instance */;
+  workflowId: string /** Type of callback */;
+  type: WorkflowCallbackType /** Timestamp when callback was sent */;
+  timestamp: number;
+};
+/**
+ * Default progress type - covers common use cases.
+ * Developers can define their own progress type for domain-specific needs.
+ */
+type DefaultProgress = {
+  /** Current step name */ step?: string /** Step/overall status */;
+  status?:
+    | "pending"
+    | "running"
+    | "complete"
+    | "error" /** Human-readable message */;
+  message?: string /** Progress percentage (0-1) */;
+  percent?: number /** Allow additional custom fields */;
+  [key: string]: unknown;
+};
+/**
+ * Progress callback - reports workflow progress with typed payload
+ */
+type WorkflowProgressCallback<P = DefaultProgress> = WorkflowCallbackBase & {
+  type: "progress" /** Typed progress data */;
+  progress: P;
+};
+/**
+ * Complete callback - workflow finished successfully
+ */
+type WorkflowCompleteCallback = WorkflowCallbackBase & {
+  type: "complete" /** Result of the workflow */;
+  result?: unknown;
+};
+/**
+ * Error callback - workflow encountered an error
+ */
+type WorkflowErrorCallback = WorkflowCallbackBase & {
+  type: "error" /** Error message */;
+  error: string;
+};
+/**
+ * Event callback - custom event from workflow
+ */
+type WorkflowEventCallback = WorkflowCallbackBase & {
+  type: "event" /** Custom event payload */;
+  event: unknown;
+};
+/**
+ * Union of all callback types
+ */
+type WorkflowCallback<P = DefaultProgress> =
+  | WorkflowProgressCallback<P>
+  | WorkflowCompleteCallback
+  | WorkflowErrorCallback
+  | WorkflowEventCallback;
+/**
+ * Workflow status values - derived from Cloudflare's InstanceStatus
+ */
+type WorkflowStatus = InstanceStatus["status"];
+/**
+ * Row structure for cf_agents_workflows tracking table
+ */
+type WorkflowTrackingRow = {
+  /** Internal row ID (UUID) */ id: string /** Cloudflare Workflow instance ID */;
+  workflow_id: string /** Workflow binding name */;
+  workflow_name: string /** Current workflow status */;
+  status: WorkflowStatus /** JSON-serialized metadata for querying */;
+  metadata: string | null /** Error name if workflow failed */;
+  error_name: string | null /** Error message if workflow failed */;
+  error_message: string | null /** Unix timestamp when workflow was created */;
+  created_at: number /** Unix timestamp when workflow was last updated */;
+  updated_at: number /** Unix timestamp when workflow completed (null if not complete) */;
+  completed_at: number | null;
+};
+/**
+ * Options for runWorkflow()
+ */
+type RunWorkflowOptions = {
+  /** Custom workflow instance ID (auto-generated if not provided) */ id?: string /** Optional metadata for querying (stored as JSON) */;
+  metadata?: Record<
+    string,
+    unknown
+  > /** Agent binding name (auto-detected from class name if not provided) */;
+  agentBinding?: string;
+};
+/**
+ * Event payload for sendWorkflowEvent()
+ */
+type WorkflowEventPayload = {
+  /** Event type name */ type: string /** Event payload data */;
+  payload: unknown;
+};
+/**
+ * Parsed workflow tracking info returned by getWorkflow()
+ */
+type WorkflowInfo = {
+  /** Internal row ID */ id: string /** Cloudflare Workflow instance ID */;
+  workflowId: string /** Workflow binding name */;
+  workflowName: string /** Current workflow status */;
+  status: WorkflowStatus /** Metadata (parsed from JSON) */;
+  metadata: Record<string, unknown> | null /** Error info if workflow failed */;
+  error: {
+    name: string;
+    message: string;
+  } | null /** When workflow was created */;
+  createdAt: Date /** When workflow was last updated */;
+  updatedAt: Date /** When workflow completed (null if not complete) */;
+  completedAt: Date | null;
+};
+/**
+ * Criteria for querying tracked workflows
+ */
+type WorkflowQueryCriteria = {
+  /** Filter by status */ status?:
+    | WorkflowStatus
+    | WorkflowStatus[] /** Filter by workflow binding name */;
+  workflowName?: string /** Filter by metadata key-value pairs (exact match) */;
+  metadata?: Record<
+    string,
+    string | number | boolean
+  > /** Limit number of results (default 50, max 100) */;
+  limit?: number /** Order by created_at */;
+  orderBy?:
+    | "asc"
+    | "desc" /** Cursor for pagination (from previous WorkflowPage.nextCursor) */;
+  cursor?: string;
+};
+/**
+ * Paginated result from getWorkflows()
+ */
+type WorkflowPage = {
+  /** Workflows for this page */ workflows: WorkflowInfo[] /** Total count of workflows matching the criteria (ignoring pagination) */;
+  total: number /** Cursor for next page, or null if no more pages */;
+  nextCursor: string | null;
+};
+/**
+ * Standard approval event payload used by approveWorkflow/rejectWorkflow
+ */
+type ApprovalEventPayload = {
+  /** Whether the workflow was approved */ approved: boolean /** Optional reason for approval/rejection */;
+  reason?: string /** Optional additional metadata */;
+  metadata?: Record<string, unknown>;
+};
+/**
+ * Options for waitForApproval()
+ */
+type WaitForApprovalOptions = {
+  /** Step name for waitForEvent (default: "wait-for-approval") */ stepName?: string /** Timeout duration (e.g., "7 days") */;
+  timeout?: WorkflowSleepDuration /** Event type to wait for (default: "approval") */;
+  eventType?: string;
+};
+/**
+ * Error thrown when a workflow is rejected via rejectWorkflow()
+ */
+declare class WorkflowRejectedError extends Error {
+  readonly reason?: string | undefined;
+  readonly workflowId?: string | undefined;
+  constructor(reason?: string | undefined, workflowId?: string | undefined);
+}
+//#endregion
 export {
   AgentWorkflowEvent,
   AgentWorkflowInternalParams,
@@ -46,3 +257,4 @@ export {
   WorkflowStatus,
   WorkflowTrackingRow
 };
+//# sourceMappingURL=workflow-types.d.ts.map

package/dist/workflows.d.ts

@@ -1,28 +1,26 @@
-import "./internal_context-CEu5ji80.js";
-import "./email-8ljcpvwV.js";
-import "./client-Ba-xntmv.js";
+import "./client-storage-Cvy5r9FG.js";
 import {
-  S as WorkflowTrackingRow,
-  _ as WorkflowPage,
-  a as ApprovalEventPayload,
-  b as WorkflowRejectedError,
-  c as WaitForApprovalOptions,
-  d as WorkflowCallbackType,
-  f as WorkflowCompleteCallback,
-  g as WorkflowInfo,
-  h as WorkflowEventPayload,
-  i as AgentWorkflowStep,
-  l as WorkflowCallback,
-  m as WorkflowEventCallback,
-  o as DefaultProgress,
-  p as WorkflowErrorCallback,
-  r as AgentWorkflowParams,
-  s as RunWorkflowOptions,
-  t as AgentWorkflowEvent,
-  v as WorkflowProgressCallback,
-  x as WorkflowStatus,
-  y as WorkflowQueryCriteria
-} from "./workflow-types-Z_Oem1FJ.js";
+  AgentWorkflowEvent,
+  AgentWorkflowParams,
+  AgentWorkflowStep,
+  ApprovalEventPayload,
+  DefaultProgress,
+  RunWorkflowOptions,
+  WaitForApprovalOptions,
+  WorkflowCallback,
+  WorkflowCallbackType,
+  WorkflowCompleteCallback,
+  WorkflowErrorCallback,
+  WorkflowEventCallback,
+  WorkflowEventPayload,
+  WorkflowInfo,
+  WorkflowPage,
+  WorkflowProgressCallback,
+  WorkflowQueryCriteria,
+  WorkflowRejectedError,
+  WorkflowStatus,
+  WorkflowTrackingRow
+} from "./workflow-types.js";
 import { Agent } from "./index.js";
 import { WorkflowEntrypoint } from "cloudflare:workers";
 

package/dist/workflows.js

@@ -1,8 +1,5 @@
-import "./email-XHsSYsTO.js";
-import "./internal_context-D9eKFth1.js";
-import "./client-BA8NJB6l.js";
-import "./do-oauth-client-provider-DDg8QrEA.js";
-import { o as getAgentByName } from "./src-CqnVUbg1.js";
+import "./client-connection-CGMuV62J.js";
+import { getAgentByName } from "./index.js";
 import { WorkflowRejectedError } from "./workflow-types.js";
 import { WorkflowEntrypoint } from "cloudflare:workers";