agents 0.0.2 → 0.0.38

package/dist/client.d.ts

@@ -0,0 +1,84 @@
+import {
+  PartySocketOptions,
+  PartyFetchOptions,
+  PartySocket,
+} from "partysocket";
+
+/**
+ * Options for creating an AgentClient
+ */
+type AgentClientOptions<State = unknown> = Omit<
+  PartySocketOptions,
+  "party" | "room"
+> & {
+  /** Name of the agent to connect to */
+  agent: string;
+  /** Name of the specific Agent instance */
+  name?: string;
+  /** Called when the Agent's state is updated */
+  onStateUpdate?: (state: State, source: "server" | "client") => void;
+};
+/**
+ * Options for streaming RPC calls
+ */
+type StreamOptions = {
+  /** Called when a chunk of data is received */
+  onChunk?: (chunk: unknown) => void;
+  /** Called when the stream ends */
+  onDone?: (finalChunk: unknown) => void;
+  /** Called when an error occurs */
+  onError?: (error: string) => void;
+};
+/**
+ * Options for the agentFetch function
+ */
+type AgentClientFetchOptions = Omit<PartyFetchOptions, "party" | "room"> & {
+  /** Name of the agent to connect to */
+  agent: string;
+  /** Name of the specific Agent instance */
+  name?: string;
+};
+/**
+ * WebSocket client for connecting to an Agent
+ */
+declare class AgentClient<State = unknown> extends PartySocket {
+  #private;
+  /**
+   * @deprecated Use agentFetch instead
+   */
+  static fetch(_opts: PartyFetchOptions): Promise<Response>;
+  agent: string;
+  name: string;
+  constructor(options: AgentClientOptions<State>);
+  setState(state: State): void;
+  /**
+   * Call a method on the Agent
+   * @param method Name of the method to call
+   * @param args Arguments to pass to the method
+   * @param streamOptions Options for handling streaming responses
+   * @returns Promise that resolves with the method's return value
+   */
+  call<T = unknown>(
+    method: string,
+    args?: unknown[],
+    streamOptions?: StreamOptions
+  ): Promise<T>;
+}
+/**
+ * Make an HTTP request to an Agent
+ * @param opts Connection options
+ * @param init Request initialization options
+ * @returns Promise resolving to a Response
+ */
+declare function agentFetch(
+  opts: AgentClientFetchOptions,
+  init?: RequestInit
+): Promise<Response>;
+
+export {
+  AgentClient,
+  type AgentClientFetchOptions,
+  type AgentClientOptions,
+  type StreamOptions,
+  agentFetch,
+};

package/dist/client.js

@@ -0,0 +1,138 @@
+import {
+  __privateAdd,
+  __privateGet,
+  __privateSet
+} from "./chunk-HMLY7DHA.js";
+
+// src/client.ts
+import {
+  PartySocket
+} from "partysocket";
+var _options, _pendingCalls;
+var AgentClient = class extends PartySocket {
+  constructor(options) {
+    super({
+      prefix: "agents",
+      party: options.agent,
+      room: options.name || "default",
+      ...options
+    });
+    __privateAdd(this, _options);
+    __privateAdd(this, _pendingCalls, /* @__PURE__ */ new Map());
+    this.agent = options.agent;
+    this.name = options.name || "default";
+    __privateSet(this, _options, options);
+    if (this.agent !== this.agent.toLowerCase()) {
+      console.warn(
+        `Agent name: ${this.agent} should probably be in lowercase. Received: ${this.agent}`
+      );
+    }
+    if (this.name !== this.name.toLowerCase()) {
+      console.warn(
+        `Agent instance name: ${this.name} should probably be in lowercase. Received: ${this.name}`
+      );
+    }
+    this.addEventListener("message", (event) => {
+      if (typeof event.data === "string") {
+        let parsedMessage;
+        try {
+          parsedMessage = JSON.parse(event.data);
+        } catch (error) {
+          return;
+        }
+        if (parsedMessage.type === "cf_agent_state") {
+          __privateGet(this, _options).onStateUpdate?.(parsedMessage.state, "server");
+          return;
+        }
+        if (parsedMessage.type === "rpc") {
+          const response = parsedMessage;
+          const pending = __privateGet(this, _pendingCalls).get(response.id);
+          if (!pending) return;
+          if (!response.success) {
+            pending.reject(new Error(response.error));
+            __privateGet(this, _pendingCalls).delete(response.id);
+            pending.stream?.onError?.(response.error);
+            return;
+          }
+          if ("done" in response) {
+            if (response.done) {
+              pending.resolve(response.result);
+              __privateGet(this, _pendingCalls).delete(response.id);
+              pending.stream?.onDone?.(response.result);
+            } else {
+              pending.stream?.onChunk?.(response.result);
+            }
+          } else {
+            pending.resolve(response.result);
+            __privateGet(this, _pendingCalls).delete(response.id);
+          }
+        }
+      }
+    });
+  }
+  /**
+   * @deprecated Use agentFetch instead
+   */
+  static fetch(_opts) {
+    throw new Error(
+      "AgentClient.fetch is not implemented, use agentFetch instead"
+    );
+  }
+  setState(state) {
+    this.send(JSON.stringify({ type: "cf_agent_state", state }));
+    __privateGet(this, _options).onStateUpdate?.(state, "client");
+  }
+  /**
+   * Call a method on the Agent
+   * @param method Name of the method to call
+   * @param args Arguments to pass to the method
+   * @param streamOptions Options for handling streaming responses
+   * @returns Promise that resolves with the method's return value
+   */
+  async call(method, args = [], streamOptions) {
+    return new Promise((resolve, reject) => {
+      const id = Math.random().toString(36).slice(2);
+      __privateGet(this, _pendingCalls).set(id, {
+        resolve: (value) => resolve(value),
+        reject,
+        stream: streamOptions,
+        type: null
+      });
+      const request = {
+        type: "rpc",
+        id,
+        method,
+        args
+      };
+      this.send(JSON.stringify(request));
+    });
+  }
+};
+_options = new WeakMap();
+_pendingCalls = new WeakMap();
+function agentFetch(opts, init) {
+  if (opts.agent !== opts.agent.toLowerCase()) {
+    console.warn(
+      `Agent name: ${opts.agent} should probably be in lowercase. Received: ${opts.agent}`
+    );
+  }
+  if (opts.name && opts.name !== opts.name.toLowerCase()) {
+    console.warn(
+      `Agent instance name: ${opts.name} should probably be in lowercase. Received: ${opts.name}`
+    );
+  }
+  return PartySocket.fetch(
+    {
+      prefix: "agents",
+      party: opts.agent,
+      room: opts.name || "default",
+      ...opts
+    },
+    init
+  );
+}
+export {
+  AgentClient,
+  agentFetch
+};
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/client.ts"],"sourcesContent":["import {\n  PartySocket,\n  type PartySocketOptions,\n  type PartyFetchOptions,\n} from \"partysocket\";\nimport type { RPCRequest, RPCResponse } from \"./\";\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 */\n  agent: string;\n  /** Name of the specific Agent instance */\n  name?: string;\n  /** Called when the Agent's state is updated */\n  onStateUpdate?: (state: State, source: \"server\" | \"client\") => void;\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 the agentFetch function\n */\nexport type AgentClientFetchOptions = Omit<\n  PartyFetchOptions,\n  \"party\" | \"room\"\n> & {\n  /** Name of the agent to connect to */\n  agent: string;\n  /** Name of the specific Agent instance */\n  name?: string;\n};\n\n/**\n * WebSocket client for connecting to an Agent\n */\nexport class AgentClient<State = unknown> 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  #options: AgentClientOptions<State>;\n  #pendingCalls = new Map<\n    string,\n    {\n      resolve: (value: unknown) => void;\n      reject: (error: Error) => void;\n      stream?: StreamOptions;\n      type?: unknown;\n    }\n  >();\n\n  constructor(options: AgentClientOptions<State>) {\n    super({\n      prefix: \"agents\",\n      party: options.agent,\n      room: options.name || \"default\",\n      ...options,\n    });\n    this.agent = options.agent;\n    this.name = options.name || \"default\";\n    this.#options = options;\n\n    // warn if agent or name isn't in lowercase\n    if (this.agent !== this.agent.toLowerCase()) {\n      console.warn(\n        `Agent name: ${this.agent} should probably be in lowercase. Received: ${this.agent}`\n      );\n    }\n    if (this.name !== this.name.toLowerCase()) {\n      console.warn(\n        `Agent instance name: ${this.name} should probably be in lowercase. Received: ${this.name}`\n      );\n    }\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 === \"cf_agent_state\") {\n          this.#options.onStateUpdate?.(parsedMessage.state as State, \"server\");\n          return;\n        }\n        if (parsedMessage.type === \"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\n  setState(state: State) {\n    this.send(JSON.stringify({ type: \"cf_agent_state\", state }));\n    this.#options.onStateUpdate?.(state, \"client\");\n  }\n\n  /**\n   * Call a method on the Agent\n   * @param method Name of the method to call\n   * @param args Arguments to pass to the method\n   * @param streamOptions Options for handling streaming responses\n   * @returns Promise that resolves with the method's return value\n   */\n  async call<T = unknown>(\n    method: string,\n    args: unknown[] = [],\n    streamOptions?: StreamOptions\n  ): Promise<T> {\n    return new Promise<T>((resolve, reject) => {\n      const id = Math.random().toString(36).slice(2);\n      this.#pendingCalls.set(id, {\n        resolve: (value: unknown) => resolve(value as T),\n        reject,\n        stream: streamOptions,\n        type: null as T,\n      });\n\n      const request: RPCRequest = {\n        type: \"rpc\",\n        id,\n        method,\n        args,\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  // warn if agent or name isn't in lowercase\n  if (opts.agent !== opts.agent.toLowerCase()) {\n    console.warn(\n      `Agent name: ${opts.agent} should probably be in lowercase. Received: ${opts.agent}`\n    );\n  }\n  if (opts.name && opts.name !== opts.name.toLowerCase()) {\n    console.warn(\n      `Agent instance name: ${opts.name} should probably be in lowercase. Received: ${opts.name}`\n    );\n  }\n\n  return PartySocket.fetch(\n    {\n      prefix: \"agents\",\n      party: opts.agent,\n      room: opts.name || \"default\",\n      ...opts,\n    },\n    init\n  );\n}\n"],"mappings":"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","names":[]}

package/dist/index.d.ts

@@ -0,0 +1,302 @@
+import { Server, Connection, PartyServerOptions } from "partyserver";
+export { Connection, ConnectionContext, WSMessage } from "partyserver";
+import { WorkflowEntrypoint as WorkflowEntrypoint$1 } from "cloudflare:workers";
+
+/**
+ * RPC request message from client
+ */
+type RPCRequest = {
+  type: "rpc";
+  id: string;
+  method: string;
+  args: unknown[];
+};
+/**
+ * State update message from client
+ */
+type StateUpdateMessage = {
+  type: "cf_agent_state";
+  state: unknown;
+};
+/**
+ * RPC response message to client
+ */
+type RPCResponse = {
+  type: "rpc";
+  id: string;
+} & (
+  | {
+      success: true;
+      result: unknown;
+      done?: false;
+    }
+  | {
+      success: true;
+      result: unknown;
+      done: true;
+    }
+  | {
+      success: false;
+      error: string;
+    }
+);
+/**
+ * Metadata for a callable method
+ */
+type CallableMetadata = {
+  /** Optional description of what the method does */
+  description?: string;
+  /** Whether the method supports streaming responses */
+  streaming?: boolean;
+};
+/**
+ * Decorator that marks a method as callable by clients
+ * @param metadata Optional metadata about the callable method
+ */
+declare function unstable_callable(
+  metadata?: CallableMetadata
+): <This, Args extends unknown[], Return>(
+  target: (this: This, ...args: Args) => Return,
+  context: ClassMethodDecoratorContext
+) => (this: This, ...args: Args) => Return;
+/**
+ * A class for creating workflow entry points that can be used with Cloudflare Workers
+ */
+declare class WorkflowEntrypoint extends WorkflowEntrypoint$1 {}
+/**
+ * Represents a scheduled task within an Agent
+ * @template T Type of the payload data
+ */
+type Schedule<T = string> = {
+  /** Unique identifier for the schedule */
+  id: string;
+  /** Name of the method to be called */
+  callback: string;
+  /** Data to be passed to the callback */
+  payload: T;
+} & (
+  | {
+      /** Type of schedule for one-time execution at a specific time */
+      type: "scheduled";
+      /** Timestamp when the task should execute */
+      time: number;
+    }
+  | {
+      /** Type of schedule for delayed execution */
+      type: "delayed";
+      /** Timestamp when the task should execute */
+      time: number;
+      /** Number of seconds to delay execution */
+      delayInSeconds: number;
+    }
+  | {
+      /** Type of schedule for recurring execution based on cron expression */
+      type: "cron";
+      /** Timestamp for the next execution */
+      time: number;
+      /** Cron expression defining the schedule */
+      cron: string;
+    }
+);
+/**
+ * Base class for creating Agent implementations
+ * @template Env Environment type containing bindings
+ * @template State State type to store within the Agent
+ */
+declare class Agent<Env, State = unknown> extends Server<Env> {
+  #private;
+  /**
+   * Initial state for the Agent
+   * Override to provide default state values
+   */
+  initialState: State;
+  /**
+   * Current state of the Agent
+   */
+  get state(): State;
+  /**
+   * Agent configuration options
+   */
+  static options: {
+    /** Whether the Agent should hibernate when inactive */
+    hibernate: boolean;
+  };
+  /**
+   * Execute SQL queries against the Agent's database
+   * @template T Type of the returned rows
+   * @param strings SQL query template strings
+   * @param values Values to be inserted into the query
+   * @returns Array of query results
+   */
+  sql<T = Record<string, string | number | boolean | null>>(
+    strings: TemplateStringsArray,
+    ...values: (string | number | boolean | null)[]
+  ): T[];
+  constructor(ctx: AgentContext, env: Env);
+  /**
+   * Update the Agent's state
+   * @param state New state to set
+   */
+  setState(state: State): void;
+  /**
+   * Called when the Agent's state is updated
+   * @param state Updated state
+   * @param source Source of the state update ("server" or a client connection)
+   */
+  onStateUpdate(state: State | undefined, source: Connection | "server"): void;
+  /**
+   * Called when the Agent receives an email
+   * @param email Email message to process
+   */
+  onEmail(email: ForwardableEmailMessage): void;
+  onError(connection: Connection, error: unknown): void | Promise<void>;
+  onError(error: unknown): void | Promise<void>;
+  /**
+   * Render content (not implemented in base class)
+   */
+  render(): void;
+  /**
+   * Schedule a task to be executed in the future
+   * @template T Type of the payload data
+   * @param when When to execute the task (Date, seconds delay, or cron expression)
+   * @param callback Name of the method to call
+   * @param payload Data to pass to the callback
+   * @returns Schedule object representing the scheduled task
+   */
+  schedule<T = string>(
+    when: Date | string | number,
+    callback: keyof this,
+    payload?: T
+  ): Promise<Schedule<T>>;
+  /**
+   * Get a scheduled task by ID
+   * @template T Type of the payload data
+   * @param id ID of the scheduled task
+   * @returns The Schedule object or undefined if not found
+   */
+  getSchedule<T = string>(id: string): Promise<Schedule<T> | undefined>;
+  /**
+   * Get scheduled tasks matching the given criteria
+   * @template T Type of the payload data
+   * @param criteria Criteria to filter schedules
+   * @returns Array of matching Schedule objects
+   */
+  getSchedules<T = string>(criteria?: {
+    description?: string;
+    id?: string;
+    type?: "scheduled" | "delayed" | "cron";
+    timeRange?: {
+      start?: Date;
+      end?: Date;
+    };
+  }): Schedule<T>[];
+  /**
+   * Cancel a scheduled task
+   * @param id ID of the task to cancel
+   * @returns true if the task was cancelled, false otherwise
+   */
+  cancelSchedule(id: string): Promise<boolean>;
+  /**
+   * Method called when an alarm fires
+   * Executes any scheduled tasks that are due
+   */
+  alarm(): Promise<void>;
+  /**
+   * Destroy the Agent, removing all state and scheduled tasks
+   */
+  destroy(): Promise<void>;
+}
+/**
+ * Namespace for creating Agent instances
+ * @template Agentic Type of the Agent class
+ */
+type AgentNamespace<Agentic extends Agent<unknown>> =
+  DurableObjectNamespace<Agentic>;
+/**
+ * Agent's durable context
+ */
+type AgentContext = DurableObjectState;
+/**
+ * Configuration options for Agent routing
+ */
+type AgentOptions<Env> = PartyServerOptions<Env> & {
+  /**
+   * Whether to enable CORS for the Agent
+   */
+  cors?: boolean | HeadersInit | undefined;
+};
+/**
+ * Route a request to the appropriate Agent
+ * @param request Request to route
+ * @param env Environment containing Agent bindings
+ * @param options Routing options
+ * @returns Response from the Agent or undefined if no route matched
+ */
+declare function routeAgentRequest<Env>(
+  request: Request,
+  env: Env,
+  options?: AgentOptions<Env>
+): Promise<Response | null>;
+/**
+ * Route an email to the appropriate Agent
+ * @param email Email message to route
+ * @param env Environment containing Agent bindings
+ * @param options Routing options
+ */
+declare function routeAgentEmail<Env>(
+  email: ForwardableEmailMessage,
+  env: Env,
+  options?: AgentOptions<Env>
+): Promise<void>;
+/**
+ * Get or create an Agent by name
+ * @template Env Environment type containing bindings
+ * @template T Type of the Agent class
+ * @param namespace Agent namespace
+ * @param name Name of the Agent instance
+ * @param options Options for Agent creation
+ * @returns Promise resolving to an Agent instance stub
+ */
+declare function getAgentByName<Env, T extends Agent<Env>>(
+  namespace: AgentNamespace<T>,
+  name: string,
+  options?: {
+    jurisdiction?: DurableObjectJurisdiction;
+    locationHint?: DurableObjectLocationHint;
+  }
+): Promise<DurableObjectStub<T>>;
+/**
+ * A wrapper for streaming responses in callable methods
+ */
+declare class StreamingResponse {
+  #private;
+  constructor(connection: Connection, id: string);
+  /**
+   * Send a chunk of data to the client
+   * @param chunk The data to send
+   */
+  send(chunk: unknown): void;
+  /**
+   * End the stream and send the final chunk (if any)
+   * @param finalChunk Optional final chunk of data to send
+   */
+  end(finalChunk?: unknown): void;
+}
+
+export {
+  Agent,
+  type AgentContext,
+  type AgentNamespace,
+  type AgentOptions,
+  type CallableMetadata,
+  type RPCRequest,
+  type RPCResponse,
+  type Schedule,
+  type StateUpdateMessage,
+  StreamingResponse,
+  WorkflowEntrypoint,
+  getAgentByName,
+  routeAgentEmail,
+  routeAgentRequest,
+  unstable_callable,
+};

package/dist/index.js

@@ -0,0 +1,20 @@
+import {
+  Agent,
+  StreamingResponse,
+  WorkflowEntrypoint,
+  getAgentByName,
+  routeAgentEmail,
+  routeAgentRequest,
+  unstable_callable
+} from "./chunk-X6BBKLSC.js";
+import "./chunk-HMLY7DHA.js";
+export {
+  Agent,
+  StreamingResponse,
+  WorkflowEntrypoint,
+  getAgentByName,
+  routeAgentEmail,
+  routeAgentRequest,
+  unstable_callable
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/react.d.ts

@@ -0,0 +1,39 @@
+import { PartySocket } from "partysocket";
+import { usePartySocket } from "partysocket/react";
+import { StreamOptions } from "./client.js";
+
+/**
+ * Options for the useAgent hook
+ * @template State Type of the Agent's state
+ */
+type UseAgentOptions<State = unknown> = Omit<
+  Parameters<typeof usePartySocket>[0],
+  "party" | "room"
+> & {
+  /** Name of the agent to connect to */
+  agent: string;
+  /** Name of the specific Agent instance */
+  name?: string;
+  /** Called when the Agent's state is updated */
+  onStateUpdate?: (state: State, source: "server" | "client") => void;
+};
+/**
+ * React hook for connecting to an Agent
+ * @template State Type of the Agent's state
+ * @param options Connection options
+ * @returns WebSocket connection with setState and call methods
+ */
+declare function useAgent<State = unknown>(
+  options: UseAgentOptions<State>
+): PartySocket & {
+  agent: string;
+  name: string;
+  setState: (state: State) => void;
+  call: <T = unknown>(
+    method: string,
+    args?: unknown[],
+    streamOptions?: StreamOptions
+  ) => Promise<T>;
+};
+
+export { type UseAgentOptions, useAgent };

package/dist/react.js

@@ -0,0 +1,97 @@
+import "./chunk-HMLY7DHA.js";
+
+// src/react.tsx
+import { usePartySocket } from "partysocket/react";
+import { useCallback, useRef } from "react";
+function useAgent(options) {
+  const pendingCallsRef = useRef(
+    /* @__PURE__ */ new Map()
+  );
+  const call = useCallback(
+    (method, args = [], streamOptions) => {
+      return new Promise((resolve, reject) => {
+        const id = Math.random().toString(36).slice(2);
+        pendingCallsRef.current.set(id, {
+          resolve,
+          reject,
+          stream: streamOptions
+        });
+        const request = {
+          type: "rpc",
+          id,
+          method,
+          args
+        };
+        agent.send(JSON.stringify(request));
+      });
+    },
+    []
+  );
+  const agent = usePartySocket({
+    prefix: "agents",
+    party: options.agent,
+    room: options.name || "default",
+    ...options,
+    onMessage: (message) => {
+      if (typeof message.data === "string") {
+        let parsedMessage;
+        try {
+          parsedMessage = JSON.parse(message.data);
+        } catch (error) {
+          return options.onMessage?.(message);
+        }
+        if (parsedMessage.type === "cf_agent_state") {
+          options.onStateUpdate?.(parsedMessage.state, "server");
+          return;
+        }
+        if (parsedMessage.type === "rpc") {
+          const response = parsedMessage;
+          const pending = pendingCallsRef.current.get(response.id);
+          if (!pending) return;
+          if (!response.success) {
+            pending.reject(new Error(response.error));
+            pendingCallsRef.current.delete(response.id);
+            pending.stream?.onError?.(response.error);
+            return;
+          }
+          if ("done" in response) {
+            if (response.done) {
+              pending.resolve(response.result);
+              pendingCallsRef.current.delete(response.id);
+              pending.stream?.onDone?.(response.result);
+            } else {
+              pending.stream?.onChunk?.(response.result);
+            }
+          } else {
+            pending.resolve(response.result);
+            pendingCallsRef.current.delete(response.id);
+          }
+          return;
+        }
+      }
+      options.onMessage?.(message);
+    }
+  });
+  agent.setState = (state) => {
+    agent.send(JSON.stringify({ type: "cf_agent_state", state }));
+    options.onStateUpdate?.(state, "client");
+  };
+  agent.call = call;
+  agent.agent = options.agent;
+  agent.name = options.name || "default";
+  if (agent.agent !== agent.agent.toLowerCase()) {
+    console.warn(
+      `Agent name: ${agent.agent} should probably be in lowercase. Received: ${agent.agent}`
+    );
+  }
+  if (agent.name !== agent.name.toLowerCase()) {
+    console.warn(
+      `Agent instance name: ${agent.name} should probably be in lowercase. Received: ${agent.name}`
+    );
+  }
+  return agent;
+}
+export {
+  useAgent
+};
+//# sourceMappingURL=react.js.map