agents 0.4.1 → 0.5.1

package/dist/index.d.ts

@@ -3,13 +3,15 @@ import {
   __DO_NOT_USE_WILL_BREAK__agentContext
 } from "./internal_context.js";
 import { EmailResolver, createHeaderBasedEmailResolver } from "./email.js";
+import { RetryOptions } from "./retries.js";
 import {
   l as TransportType,
   r as MCPConnectionState
-} from "./client-storage-Cvy5r9FG.js";
+} from "./client-storage-D633wI1S.js";
 import {
   AgentMcpOAuthProvider,
-  AgentsOAuthProvider
+  AgentsOAuthProvider,
+  DurableObjectOAuthClientProvider
 } from "./mcp/do-oauth-client-provider.js";
 import { MCPClientManager } from "./mcp/client.js";
 import {
@@ -119,6 +121,7 @@ type QueueItem<T = string> = {
   payload: T;
   callback: keyof Agent<Cloudflare.Env>;
   created_at: number;
+  retry?: RetryOptions;
 };
 /**
  * Represents a scheduled task within an Agent
@@ -127,7 +130,8 @@ type QueueItem<T = string> = {
 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;
+  payload: T /** Retry options for callback execution */;
+  retry?: RetryOptions;
 } & (
   | {
       /** Type of schedule for one-time execution at a specific time */ type: "scheduled" /** Timestamp when the task should execute */;
@@ -174,7 +178,7 @@ type MCPServer = {
   name: string;
   server_url: string;
   auth_url: string | null;
-  state: MCPConnectionState;
+  state: MCPConnectionState /** May contain untrusted content from external OAuth providers. Escape appropriately for your output context. */;
   error: string | null;
   instructions: string | null;
   capabilities: ServerCapabilities | null;
@@ -197,7 +201,8 @@ type AddMcpServerOptions = {
   transport?: {
     /** Custom headers for authentication (e.g., bearer tokens, CF Access) */ headers?: HeadersInit /** Transport type: "sse", "streamable-http", or "auto" (default) */;
     type?: TransportType;
-  };
+  } /** Retry options for connection and reconnection attempts */;
+  retry?: RetryOptions;
 };
 /**
  * Default options for Agent configuration.
@@ -211,16 +216,26 @@ declare const DEFAULT_AGENT_STATIC_OPTIONS: {
    * and force-reset. Increase this if you have callbacks that legitimately
    * take longer than 30 seconds.
    */
-  hungScheduleTimeoutSeconds: number;
+  hungScheduleTimeoutSeconds: number /** Default retry options for schedule(), queue(), and this.retry() */;
+  retry: {
+    maxAttempts: number;
+    baseDelayMs: number;
+    maxDelayMs: number;
+  };
 };
-type ResolvedAgentOptions = typeof DEFAULT_AGENT_STATIC_OPTIONS;
 /**
  * Configuration options for the Agent.
  * Override in subclasses via `static options`.
  * All fields are optional - defaults are applied at runtime.
  * Note: `hibernate` defaults to `true` if not specified.
  */
-type AgentStaticOptions = Partial<ResolvedAgentOptions>;
+interface AgentStaticOptions {
+  hibernate?: boolean;
+  sendIdentityOnConnect?: boolean;
+  hungScheduleTimeoutSeconds?: number;
+  /** Default retry options for schedule(), queue(), and this.retry(). */
+  retry?: RetryOptions;
+}
 declare function getCurrentAgent<
   T extends Agent<Cloudflare.Env> = Agent<Cloudflare.Env>
 >(): {
@@ -257,8 +272,8 @@ declare class Agent<
   private _destroyed;
   /**
    * Stores raw state accessors for wrapped connections.
-   * Used by setConnectionReadonly/isConnectionReadonly to read/write the
-   * _cf_readonly flag without going through the user-facing state/setState.
+   * Used by internal flag methods (readonly, no-protocol) to read/write
+   * _cf_-prefixed keys without going through the user-facing state/setState.
    */
   private _rawStateAccessors;
   /**
@@ -289,8 +304,11 @@ declare class Agent<
    */
   static options: AgentStaticOptions;
   /**
-   * Resolved options (merges defaults with subclass overrides)
+   * Resolved options (merges defaults with subclass overrides).
+   * Cached after first access — static options never change during the
+   * lifetime of a Durable Object instance.
    */
+  private _cachedOptions?;
   private get _resolvedOptions();
   /**
    * The observability implementation to use for the Agent
@@ -312,6 +330,14 @@ declare class Agent<
    * Check for workflows referencing unknown bindings and warn with migration suggestion.
    */
   private _checkOrphanedWorkflows;
+  /**
+   * Broadcast a protocol message only to connections that have protocol
+   * messages enabled. Connections where shouldSendProtocolMessages returned
+   * false are excluded automatically.
+   * @param msg The JSON-encoded protocol message
+   * @param excludeIds Additional connection IDs to exclude (e.g. the source)
+   */
+  private _broadcastProtocol;
   private _setStateInternal;
   /**
    * Update the Agent's state
@@ -320,11 +346,16 @@ declare class Agent<
    */
   setState(state: State): void;
   /**
-   * Wraps connection.state and connection.setState so that the internal
-   * _cf_readonly flag is hidden from user code and cannot be accidentally
-   * overwritten. Must be called before any user code sees the connection.
+   * Wraps connection.state and connection.setState so that internal
+   * _cf_-prefixed flags (readonly, no-protocol) are hidden from user code
+   * and cannot be accidentally overwritten.
    *
    * Idempotent — safe to call multiple times on the same connection.
+   * After hibernation, the _rawStateAccessors WeakMap is empty but the
+   * connection's state getter still reads from the persisted WebSocket
+   * attachment. Calling this method re-captures the raw getter so that
+   * predicate methods (isConnectionReadonly, isConnectionProtocolEnabled)
+   * work correctly post-hibernation.
    */
   private _ensureConnectionWrapped;
   /**
@@ -334,7 +365,10 @@ declare class Agent<
    */
   setConnectionReadonly(connection: Connection$1, readonly?: boolean): void;
   /**
-   * Check if a connection is marked as readonly
+   * Check if a connection is marked as readonly.
+   *
+   * Safe to call after hibernation — re-wraps the connection if the
+   * in-memory accessor cache was cleared.
    * @param connection The connection to check
    * @returns True if the connection is readonly
    */
@@ -349,6 +383,42 @@ declare class Agent<
     _connection: Connection$1,
     _ctx: ConnectionContext$1
   ): boolean;
+  /**
+   * Override this method to control whether protocol messages are sent to a
+   * connection. Protocol messages include identity (CF_AGENT_IDENTITY), state
+   * sync (CF_AGENT_STATE), and MCP server lists (CF_AGENT_MCP_SERVERS).
+   *
+   * When this returns `false` for a connection, that connection will not
+   * receive any protocol text frames — neither on connect nor via broadcasts.
+   * This is useful for binary-only clients (e.g. MQTT devices) that cannot
+   * handle JSON text frames.
+   *
+   * The connection can still send and receive regular messages, use RPC, and
+   * participate in all non-protocol communication.
+   *
+   * @param _connection The connection that is being established
+   * @param _ctx Connection context (includes the upgrade request)
+   * @returns True if protocol messages should be sent (default), false to suppress them
+   */
+  shouldSendProtocolMessages(
+    _connection: Connection$1,
+    _ctx: ConnectionContext$1
+  ): boolean;
+  /**
+   * Check if a connection has protocol messages enabled.
+   * Protocol messages include identity, state sync, and MCP server lists.
+   *
+   * Safe to call after hibernation — re-wraps the connection if the
+   * in-memory accessor cache was cleared.
+   * @param connection The connection to check
+   * @returns True if the connection receives protocol messages
+   */
+  isConnectionProtocolEnabled(connection: Connection$1): boolean;
+  /**
+   * Mark a connection as having protocol messages disabled.
+   * Called internally when shouldSendProtocolMessages returns false.
+   */
+  private _setConnectionNoProtocol;
   /**
    * Called before the Agent's state is persisted and broadcast.
    * Override to validate or reject an update by throwing an error.
@@ -426,54 +496,89 @@ declare class Agent<
    * Render content (not implemented in base class)
    */
   render(): void;
+  /**
+   * Retry an async operation with exponential backoff and jitter.
+   * Retries on all errors by default. Use `shouldRetry` to bail early on non-retryable errors.
+   *
+   * @param fn The async function to retry. Receives the current attempt number (1-indexed).
+   * @param options Retry configuration.
+   * @param options.maxAttempts Maximum number of attempts (including the first). Falls back to static options, then 3.
+   * @param options.baseDelayMs Base delay in ms for exponential backoff. Falls back to static options, then 100.
+   * @param options.maxDelayMs Maximum delay cap in ms. Falls back to static options, then 3000.
+   * @param options.shouldRetry Predicate called with the error and next attempt number. Return false to stop retrying immediately. Default: retry all errors.
+   * @returns The result of fn on success.
+   * @throws The last error if all attempts fail or shouldRetry returns false.
+   */
+  retry<T>(
+    fn: (attempt: number) => Promise<T>,
+    options?: RetryOptions & {
+      /** Return false to stop retrying a specific error. Receives the error and the next attempt number. Default: retry all errors. */ shouldRetry?: (
+        err: unknown,
+        nextAttempt: number
+      ) => boolean;
+    }
+  ): Promise<T>;
   /**
    * Queue a task to be executed in the future
-   * @param payload Payload to pass to the callback
    * @param callback Name of the method to call
+   * @param payload Payload to pass to the callback
+   * @param options Options for the queued task
+   * @param options.retry Retry options for the callback execution
    * @returns The ID of the queued task
    */
-  queue<T = unknown>(callback: keyof this, payload: T): Promise<string>;
+  queue<T = unknown>(
+    callback: keyof this,
+    payload: T,
+    options?: {
+      retry?: RetryOptions;
+    }
+  ): Promise<string>;
   private _flushingQueue;
   private _flushQueue;
   /**
    * Dequeue a task by ID
    * @param id ID of the task to dequeue
    */
-  dequeue(id: string): Promise<void>;
+  dequeue(id: string): void;
   /**
    * Dequeue all tasks
    */
-  dequeueAll(): Promise<void>;
+  dequeueAll(): void;
   /**
    * Dequeue all tasks by callback
    * @param callback Name of the callback to dequeue
    */
-  dequeueAllByCallback(callback: string): Promise<void>;
+  dequeueAllByCallback(callback: string): void;
   /**
    * Get a queued task by ID
    * @param id ID of the task to get
    * @returns The task or undefined if not found
    */
-  getQueue(id: string): Promise<QueueItem<string> | undefined>;
+  getQueue(id: string): QueueItem<string> | undefined;
   /**
    * Get all queues by key and value
    * @param key Key to filter by
    * @param value Value to filter by
    * @returns Array of matching QueueItem objects
    */
-  getQueues(key: string, value: string): Promise<QueueItem<string>[]>;
+  getQueues(key: string, value: string): QueueItem<string>[];
   /**
    * 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
+   * @param options Options for the scheduled task
+   * @param options.retry Retry options for the callback execution
    * @returns Schedule object representing the scheduled task
    */
   schedule<T = string>(
     when: Date | string | number,
     callback: keyof this,
-    payload?: T
+    payload?: T,
+    options?: {
+      retry?: RetryOptions;
+    }
   ): Promise<Schedule<T>>;
   /**
    * Schedule a task to run repeatedly at a fixed interval
@@ -481,12 +586,17 @@ declare class Agent<
    * @param intervalSeconds Number of seconds between executions
    * @param callback Name of the method to call
    * @param payload Data to pass to the callback
+   * @param options Options for the scheduled task
+   * @param options.retry Retry options for the callback execution
    * @returns Schedule object representing the scheduled task
    */
   scheduleEvery<T = string>(
     intervalSeconds: number,
     callback: keyof this,
-    payload?: T
+    payload?: T,
+    options?: {
+      retry?: RetryOptions;
+    }
   ): Promise<Schedule<T>>;
   /**
    * Get a scheduled task by ID
@@ -494,7 +604,7 @@ declare class Agent<
    * @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>;
+  getSchedule<T = string>(id: string): Schedule<T> | undefined;
   /**
    * Get scheduled tasks matching the given criteria
    * @template T Type of the payload data
@@ -1124,6 +1234,7 @@ export {
   type Connection,
   type ConnectionContext,
   DEFAULT_AGENT_STATIC_OPTIONS,
+  DurableObjectOAuthClientProvider,
   EmailRoutingOptions,
   MCPServer,
   MCPServerMessage,
@@ -1131,6 +1242,7 @@ export {
   QueueItem,
   RPCRequest,
   RPCResponse,
+  type RetryOptions,
   Schedule,
   SqlError,
   StateUpdateMessage,