agents 0.5.1 → 0.7.0

package/dist/index.d.ts

@@ -5,14 +5,15 @@ import {
 import { EmailResolver, createHeaderBasedEmailResolver } from "./email.js";
 import { RetryOptions } from "./retries.js";
 import {
-  l as TransportType,
-  r as MCPConnectionState
-} from "./client-storage-D633wI1S.js";
+  r as MCPConnectionState,
+  w as TransportType
+} from "./client-storage-tusTuoSF.js";
 import {
   AgentMcpOAuthProvider,
   AgentsOAuthProvider,
   DurableObjectOAuthClientProvider
 } from "./mcp/do-oauth-client-provider.js";
+import { McpAgent } from "./mcp/index.js";
 import { MCPClientManager } from "./mcp/client.js";
 import {
   RunWorkflowOptions,
@@ -204,6 +205,12 @@ type AddMcpServerOptions = {
   } /** Retry options for connection and reconnection attempts */;
   retry?: RetryOptions;
 };
+/**
+ * Options for adding an MCP server via RPC (Durable Object binding)
+ */
+type AddRpcMcpServerOptions = {
+  /** Props to pass to the McpAgent instance */ props?: Record<string, unknown>;
+};
 /**
  * Default options for Agent configuration.
  * Child classes can override specific options without spreading.
@@ -314,6 +321,11 @@ declare class Agent<
    * The observability implementation to use for the Agent
    */
   observability?: Observability;
+  /**
+   * Emit an observability event with auto-generated timestamp.
+   * @internal
+   */
+  private _emit;
   /**
    * Execute SQL queries against the Agent's database
    * @template T Type of the returned rows
@@ -625,6 +637,53 @@ declare class Agent<
    * @returns true if the task was cancelled, false if the task was not found
    */
   cancelSchedule(id: string): Promise<boolean>;
+  /**
+   * Keep the Durable Object alive via alarm heartbeats.
+   * Returns a disposer function that stops the heartbeat when called.
+   *
+   * Use this when you have long-running work and need to prevent the
+   * DO from going idle (eviction after ~70-140s of inactivity).
+   * The heartbeat fires every 30 seconds via the scheduling system.
+   *
+   * @experimental This API may change between releases.
+   *
+   * @example
+   * ```ts
+   * const dispose = await this.keepAlive();
+   * try {
+   *   // ... long-running work ...
+   * } finally {
+   *   dispose();
+   * }
+   * ```
+   */
+  keepAlive(): Promise<() => void>;
+  /**
+   * Run an async function while keeping the Durable Object alive.
+   * The heartbeat is automatically stopped when the function completes
+   * (whether it succeeds or throws).
+   *
+   * This is the recommended way to use keepAlive — it guarantees cleanup
+   * so you cannot forget to dispose the heartbeat.
+   *
+   * @experimental This API may change between releases.
+   *
+   * @example
+   * ```ts
+   * const result = await this.keepAliveWhile(async () => {
+   *   const data = await longRunningComputation();
+   *   return data;
+   * });
+   * ```
+   */
+  keepAliveWhile<T>(fn: () => Promise<T>): Promise<T>;
+  /**
+   * Internal no-op callback invoked by the keepAlive heartbeat schedule.
+   * Its only purpose is to keep the DO alive — the alarm machinery
+   * handles the rest.
+   * @internal
+   */
+  _cf_keepAliveHeartbeat(): Promise<void>;
   private _scheduleNextAlarm;
   /**
    * Method called when an alarm fires.
@@ -944,6 +1003,8 @@ declare class Agent<
    * Returns undefined if no match found - use options.agentBinding as fallback.
    */
   private _findAgentBindingName;
+  private _findBindingNameForNamespace;
+  private _restoreRpcMcpServers;
   /**
    * Handle a callback from a workflow.
    * Called when the Agent receives a callback at /_workflow/callback.
@@ -1023,29 +1084,30 @@ declare class Agent<
     state?: unknown
   ): void;
   /**
-   * Connect to a new MCP Server
+   * Connect to a new MCP Server via RPC (Durable Object binding)
    *
-   * @example
-   * // Simple usage
-   * await this.addMcpServer("github", "https://mcp.github.com");
+   * The binding name and props are persisted to storage so the connection
+   * is automatically restored after Durable Object hibernation.
    *
    * @example
-   * // With options (preferred for custom headers, transport, etc.)
-   * await this.addMcpServer("github", "https://mcp.github.com", {
-   *   transport: { headers: { "Authorization": "Bearer ..." } }
-   * });
+   * await this.addMcpServer("counter", env.MY_MCP);
+   * await this.addMcpServer("counter", env.MY_MCP, { props: { userId: "123" } });
+   */
+  addMcpServer<T extends McpAgent>(
+    serverName: string,
+    binding: DurableObjectNamespace<T>,
+    options?: AddRpcMcpServerOptions
+  ): Promise<{
+    id: string;
+    state: typeof MCPConnectionState.READY;
+  }>;
+  /**
+   * Connect to a new MCP Server via HTTP (SSE or Streamable HTTP)
    *
    * @example
-   * // Legacy 5-parameter signature (still supported)
-   * await this.addMcpServer("github", url, callbackHost, agentsPrefix, options);
-   *
-   * @param serverName Name of the MCP server
-   * @param url MCP Server URL
-   * @param callbackHostOrOptions Options object, or callback host string (legacy)
-   * @param agentsPrefix agents routing prefix if not using `agents` (legacy)
-   * @param options MCP client and transport options (legacy)
-   * @returns Server id and state - either "authenticating" with authUrl, or "ready"
-   * @throws If connection or discovery fails
+   * await this.addMcpServer("github", "https://mcp.github.com");
+   * await this.addMcpServer("github", "https://mcp.github.com", { transport: { type: "sse" } });
+   * await this.addMcpServer("github", url, callbackHost, agentsPrefix, options); // legacy
    */
   addMcpServer(
     serverName: string,
@@ -1068,7 +1130,6 @@ declare class Agent<
     | {
         id: string;
         state: typeof MCPConnectionState.READY;
-        authUrl?: undefined;
       }
   >;
   removeMcpServer(id: string): Promise<void>;
@@ -1223,6 +1284,7 @@ declare class StreamingResponse {
 //#endregion
 export {
   AddMcpServerOptions,
+  AddRpcMcpServerOptions,
   Agent,
   AgentContext,
   type AgentMcpOAuthProvider,