agents/dist/react.d.ts

A home for your AI agents

import { Method, RPCMethod } from "./serializable.js";
import { StreamOptions } from "./client.js";
import "./internal_context-CEu5ji80.js";
import "./email-8ljcpvwV.js";
import "./client-DV1CZKqa.js";
import "./workflow-types-Z_Oem1FJ.js";
import { Agent, MCPServersState } from "./index.js";
import { PartySocket } from "partysocket";
import { usePartySocket } from "partysocket/react";

//#region src/react.d.ts
type QueryObject = Record<string, string | null>;
interface CacheEntry {
  promise: Promise<QueryObject>;
  expiresAt: number;
}
declare function createCacheKey(
  agentNamespace: string,
  name: string | undefined,
  deps: unknown[]
): string;
declare function getCacheEntry(key: string): CacheEntry | undefined;
declare function setCacheEntry(
  key: string,
  promise: Promise<QueryObject>,
  cacheTtl: number
): CacheEntry;
declare function deleteCacheEntry(key: string): void;
/**
 * Creates a proxy that wraps RPC method calls.
 * Internal JS methods (toJSON, then, etc.) return undefined to avoid
 * triggering RPC calls during serialization (e.g., console.log)
 */
declare function createStubProxy<T = Record<string, Method>>(
  call: (method: string, args: unknown[]) => unknown
): T;
declare const _testUtils: {
  queryCache: Map<string, CacheEntry>;
  setCacheEntry: typeof setCacheEntry;
  getCacheEntry: typeof getCacheEntry;
  deleteCacheEntry: typeof deleteCacheEntry;
  clearCache: () => void;
  createStubProxy: typeof createStubProxy;
  createCacheKey: typeof createCacheKey;
};
/**
 * Options for the useAgent hook
 * @template State Type of the Agent's state
 */
type UseAgentOptions<State = unknown> = Omit<
  Parameters<typeof usePartySocket>[0],
  "party" | "room" | "query"
> & {
  /** Name of the agent to connect to (ignored if basePath is set) */ agent: string; /** Name of the specific Agent instance (ignored if basePath is set) */
  name?: string;
  /**
   * Full URL path - bypasses agent/name URL construction.
   * When set, the client connects to this path directly.
   * Server must handle routing manually (e.g., with getAgentByName + fetch).
   * @example
   * // Client connects to /user, server routes based on session
   * useAgent({ agent: "UserAgent", basePath: "user" })
   */
  basePath?: string; /** Query parameters - can be static object or async function */
  query?:
    | QueryObject
    | (() => Promise<QueryObject>); /** Dependencies for async query caching */
  queryDeps?: unknown[]; /** Cache TTL in milliseconds for auth tokens/time-sensitive data */
  cacheTtl?: number; /** Called when the Agent's state is updated */
  onStateUpdate?: (
    state: State,
    source: "server" | "client"
  ) => void; /** Called when MCP server state is updated */
  onMcpUpdate?: (mcpServers: MCPServersState) => void;
  /**
   * Called when the server sends the agent's identity on connect.
   * Useful when using basePath, as the actual instance name is determined server-side.
   * @param name The actual agent instance name
   * @param agent The agent class name (kebab-case)
   */
  onIdentity?: (name: string, agent: string) => void;
  /**
   * Called when identity changes on reconnect (different instance than before).
   * If not provided and identity changes, a warning will be logged.
   * @param oldName Previous instance name
   * @param newName New instance name
   * @param oldAgent Previous agent class name
   * @param newAgent New agent class name
   */
  onIdentityChange?: (
    oldName: string,
    newName: string,
    oldAgent: string,
    newAgent: string
  ) => void;
  /**
   * Additional path to append to the URL.
   * Works with both standard routing and basePath.
   * @example
   * // With basePath: /user/settings
   * { basePath: "user", path: "settings" }
   * // Standard: /agents/my-agent/room/settings
   * { agent: "MyAgent", name: "room", path: "settings" }
   */
  path?: string;
};
type AllOptional<T> = T extends [infer A, ...infer R]
  ? undefined extends A
    ? AllOptional<R>
    : false
  : true;
type RPCMethods<T> = {
  [K in keyof T as T[K] extends RPCMethod<T[K]> ? K : never]: RPCMethod<T[K]>;
};
type OptionalParametersMethod<T extends RPCMethod> =
  AllOptional<Parameters<T>> extends true ? T : never;
type AgentMethods<T> = Omit<RPCMethods<T>, keyof Agent<any, any>>;
type OptionalAgentMethods<T> = {
  [K in keyof AgentMethods<T> as AgentMethods<T>[K] extends OptionalParametersMethod<
    AgentMethods<T>[K]
  >
    ? K
    : never]: OptionalParametersMethod<AgentMethods<T>[K]>;
};
type RequiredAgentMethods<T> = Omit<
  AgentMethods<T>,
  keyof OptionalAgentMethods<T>
>;
type AgentPromiseReturnType<T, K extends keyof AgentMethods<T>> =
  ReturnType<AgentMethods<T>[K]> extends Promise<any>
    ? ReturnType<AgentMethods<T>[K]>
    : Promise<ReturnType<AgentMethods<T>[K]>>;
type OptionalArgsAgentMethodCall<AgentT> = <
  K extends keyof OptionalAgentMethods<AgentT>
>(
  method: K,
  args?: Parameters<OptionalAgentMethods<AgentT>[K]>,
  streamOptions?: StreamOptions
) => AgentPromiseReturnType<AgentT, K>;
type RequiredArgsAgentMethodCall<AgentT> = <
  K extends keyof RequiredAgentMethods<AgentT>
>(
  method: K,
  args: Parameters<RequiredAgentMethods<AgentT>[K]>,
  streamOptions?: StreamOptions
) => AgentPromiseReturnType<AgentT, K>;
type AgentMethodCall<AgentT> = OptionalArgsAgentMethodCall<AgentT> &
  RequiredArgsAgentMethodCall<AgentT>;
type UntypedAgentMethodCall = <T = unknown>(
  method: string,
  args?: unknown[],
  streamOptions?: StreamOptions
) => Promise<T>;
type AgentStub<T> = {
  [K in keyof AgentMethods<T>]: (
    ...args: Parameters<AgentMethods<T>[K]>
  ) => AgentPromiseReturnType<AgentMethods<T>, K>;
};
type UntypedAgentStub = Record<string, Method>;
/**
 * React hook for connecting to an Agent
 */
declare function useAgent<State = unknown>(
  options: UseAgentOptions<State>
): PartySocket & {
  agent: string;
  name: string;
  identified: boolean;
  ready: Promise<void>;
  setState: (state: State) => void;
  call: UntypedAgentMethodCall;
  stub: UntypedAgentStub;
};
declare function useAgent<
  AgentT extends {
    get state(): State;
  },
  State
>(
  options: UseAgentOptions<State>
): PartySocket & {
  agent: string;
  name: string;
  identified: boolean;
  ready: Promise<void>;
  setState: (state: State) => void;
  call: AgentMethodCall<AgentT>;
  stub: AgentStub<AgentT>;
};
//#endregion
export { UseAgentOptions, _testUtils, useAgent };
//# sourceMappingURL=react.d.ts.map