agents 0.16.1 → 0.17.0

package/dist/{agent-tool-types-NofdbL9X.d.ts → agent-tool-types-Cd1TZPfB.d.ts}

@@ -4,19 +4,18 @@ import {
   n as Observability,
   r as ObservabilityEvent,
   s as MCPObservabilityEvent
-} from "./index-B7IbEeze.js";
+} from "./index-CcbnKkNh.js";
 import { t as AgentMcpOAuthProvider } from "./do-oauth-client-provider-D4ZwyBDu.js";
 import {
-  _ as WorkflowPage,
-  g as WorkflowInfo,
-  h as WorkflowEventPayload,
-  l as WorkflowCallback,
-  s as RunWorkflowOptions,
-  y as WorkflowQueryCriteria
-} from "./workflow-types-SrZK_o9p.js";
+  _ as WorkflowEventPayload,
+  d as WorkflowCallback,
+  l as RunWorkflowOptions,
+  v as WorkflowInfo,
+  x as WorkflowQueryCriteria,
+  y as WorkflowPage
+} from "./workflow-types-Baz_PO5v.js";
 import { t as MessageType } from "./types-6Zo2zfoO.js";
 import { r as EmailResolver } from "./email-CL27preh.js";
-import { ToolSet, UIMessage } from "ai";
 import { RpcTarget } from "cloudflare:workers";
 import {
   Connection,
@@ -29,6 +28,7 @@ import {
   WSMessage,
   WSMessage as WSMessage$1
 } from "partyserver";
+import { z } from "zod";
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import {
   SSEClientTransport,
@@ -57,7 +57,7 @@ import {
   Resource,
   ResourceTemplate,
   ServerCapabilities,
-  Tool as Tool$1
+  Tool
 } from "@modelcontextprotocol/sdk/types.js";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import {
@@ -819,8 +819,16 @@ declare class MCPClientConnection {
   connectionError: string | null;
   lastConnectedTransport: BaseTransportType | undefined;
   instructions?: string;
-  tools: Tool$1[];
+  tools: Tool[];
   private _transport?;
+  /**
+   * Transport that received the 401 during the initial connect attempt.
+   * Kept so finishAuth() runs on the transport that captured the resource
+   * metadata URL from the WWW-Authenticate header — a fresh transport would
+   * rediscover from defaults and exchange the code at the wrong token
+   * endpoint when the authorization server is not at the default location.
+   */
+  private _pendingAuthTransport?;
   prompts: Prompt[];
   resources: Resource[];
   resourceTemplates: ResourceTemplate[];
@@ -884,7 +892,7 @@ declare class MCPClientConnection {
    * Notification handler registration for tools
    * Should only be called if serverCapabilities.tools exists
    */
-  registerTools(): Promise<Tool$1[]>;
+  registerTools(): Promise<Tool[]>;
   /**
    * Notification handler registration for resources
    * Should only be called if serverCapabilities.resources exists
@@ -1074,6 +1082,22 @@ type MCPServerRow = {
 };
 //#endregion
 //#region src/mcp/client.d.ts
+type MCPAITool = {
+  description?: string;
+  title?: string;
+  execute: (
+    args: Record<string, unknown>,
+    options?: unknown
+  ) => Promise<unknown>;
+  inputSchema: z.ZodType;
+  outputSchema?: z.ZodType;
+};
+/**
+ * Structural tool set returned by {@link MCPClientManager.getAITools}.
+ * Compatible with the AI SDK without importing its types into the core
+ * `agents` declaration graph.
+ */
+type MCPAIToolSet = Record<string, MCPAITool>;
 /** Maximum length of a normalized MCP server id. */
 declare const MCP_SERVER_ID_MAX_LENGTH = 64;
 /**
@@ -1435,13 +1459,13 @@ declare class MCPClientManager {
    * @param filter - Optional filter to scope results to specific servers
    * @returns a set of tools that you can use with the AI SDK
    */
-  getAITools(filter?: MCPServerFilter): ToolSet;
+  getAITools(filter?: MCPServerFilter): MCPAIToolSet;
   /**
    * @deprecated this has been renamed to getAITools(), and unstable_getAITools will be removed in the next major version
    * @param filter - Optional filter to scope results to specific servers
    * @returns a set of tools that you can use with the AI SDK
    */
-  unstable_getAITools(filter?: MCPServerFilter): ToolSet;
+  unstable_getAITools(filter?: MCPServerFilter): MCPAIToolSet;
   /**
    * Closes all active in-memory connections to MCP servers.
    *
@@ -1719,7 +1743,9 @@ declare class MCPClientManager {
                   uri: string;
                   text: string;
                   mimeType?: string | undefined;
-                  _meta?: Record<string, unknown> | undefined;
+                  _meta /** Include only connections matching this server ID (or IDs). */?/** Include only connections matching this server ID (or IDs). */ :
+                    | Record<string, unknown>
+                    | undefined;
                 }
               | {
                   uri: string;
@@ -1758,7 +1784,11 @@ declare class MCPClientManager {
             icons?:
               | {
                   src: string;
-                  mimeType?: string | undefined;
+                  mimeType?/**
+                   * Event that fires whenever any MCP server state changes (registered, connected, removed, etc.)
+                   * This is useful for broadcasting server state to clients.
+                   */
+                  : string | undefined;
                   sizes?: string[] | undefined;
                   theme?: "light" | "dark" | undefined;
                 }[]
@@ -1781,7 +1811,7 @@ declare class MCPClientManager {
   }>;
 }
 type NamespacedData = {
-  tools: (Tool$1 & {
+  tools: (Tool & {
     serverId: string;
   })[];
   prompts: (Prompt & {
@@ -2069,6 +2099,9 @@ type ScheduleStorageRow = {
   owner_path?: string | null;
   owner_path_key?: string | null;
 };
+type DetachedReconcilePayload = {
+  cadenceIndex?: number;
+};
 type ScheduleCriteria = {
   id?: string;
   type?: "scheduled" | "delayed" | "cron" | "interval";
@@ -2197,7 +2230,7 @@ type MCPServersState = {
   servers: {
     [id: string]: MCPServer;
   };
-  tools: (Tool$1 & {
+  tools: (Tool & {
     serverId: string;
   })[];
   prompts: (Prompt & {
@@ -2314,6 +2347,8 @@ declare const DEFAULT_AGENT_STATIC_OPTIONS: {
    * wall-clock cap (which also tears the child down on `window-exceeded`).
    */
   agentToolReattachMaxWindowMs: number;
+  detachedMaxBudgetMs: number;
+  detachedNoProgressBudgetMs: number;
 };
 /**
  * Configuration options for the Agent.
@@ -2377,6 +2412,30 @@ interface AgentStaticOptions {
    * also disables the ceiling.
    */
   agentToolReattachMaxWindowMs?: number;
+  /**
+   * Absolute safety ceiling in milliseconds for a DETACHED ("background")
+   * agent-tool run dispatched via `runAgentTool(cls, { detached: ... })`
+   * (rfc-detached-agent-tools). A detached run has no awaiting parent turn, so
+   * on expiry the parent gives up watching — delivers the completion hook with
+   * `interrupted` / `budget-exceeded` and tears the child down — rather than
+   * holding a concurrency slot + live facet forever. Unlike the re-attach
+   * window this defaults to a FINITE value (24h) precisely because an abandoned
+   * detached run has no observer to notice the leak. Override per-run via
+   * `detached: { maxBudgetMs }`.
+   */
+  detachedMaxBudgetMs?: number;
+  /**
+   * Resetting no-progress window in milliseconds for a DETACHED agent-tool run
+   * (rfc-detached-agent-tools §progress). Once the child has emitted at least
+   * one `reportProgress` signal, the parent gives up if the run then goes
+   * silent for this long; the window resets on every subsequent signal. A child
+   * that never reports progress is bounded only by `detachedMaxBudgetMs` — we
+   * never give up on a run merely for taking a long time, only for going silent
+   * after it began reporting. Default: 1h. Set `0`/`Infinity` to disable (rely
+   * on the absolute ceiling only). Override per-run via
+   * `detached: { noProgressBudgetMs }`.
+   */
+  detachedNoProgressBudgetMs?: number;
 }
 declare function getCurrentAgent<
   T extends Agent<Cloudflare.Env> = Agent<Cloudflare.Env>
@@ -2484,6 +2543,10 @@ declare class Agent<
   private _recoveryNoProgressScans;
   /** @internal Single-flight background recovery for parent agent-tool rows. */
   private _agentToolRunRecoveryPromise;
+  /** @internal Serializes detached-backbone arming against concurrent dispatch. */
+  private _detachedBackboneArming;
+  /** @internal Edge-trigger latch for the live-detached-count warning. */
+  private _detachedLiveCountWarned;
   private _ParentClass;
   readonly mcp: MCPClientManager;
   /**
@@ -3294,6 +3357,17 @@ declare class Agent<
     ownerPath: ReadonlyArray<AgentPathStep>,
     row: ScheduleStorageRow
   ): Promise<boolean>;
+  /**
+   * Invoke an RPC method on this Agent or a descendant facet identified
+   * by a root-first path. Used by AgentWorkflow to route callbacks and
+   * `this.agent` calls back to the exact sub-agent that started a workflow.
+   * @internal
+   */
+  _cf_invokeAgentPath(
+    targetPath: ReadonlyArray<AgentPathStep>,
+    method: string,
+    args: unknown[]
+  ): Promise<unknown>;
   /**
    * Recursively destroy a descendant facet identified by
    * `targetPath`. Walks down from `selfPath` until reaching the
@@ -3666,10 +3740,132 @@ declare class Agent<
     _run: AgentToolRunInfo,
     _result: AgentToolLifecycleResult
   ): Promise<void>;
+  /**
+   * Parent hook fired (best-effort) whenever a child agent-tool run emits a
+   * `reportProgress` signal that is forwarded through this parent's tail. Use it
+   * to meter / steer / surface progress server-side. Fires for both awaited and
+   * detached runs; it is NOT durable — after eviction a detached run's latest
+   * snapshot is read from `inspectAgentToolRun().progress` on reconcile instead.
+   */
+  onProgress(
+    _run: AgentToolRunInfo,
+    _progress: AgentToolProgressSnapshot
+  ): Promise<void>;
+  /**
+   * Emit an ephemeral progress signal from a sub-agent that is currently running
+   * as an agent tool. Rides the child's active turn stream as a transient
+   * `data-agent-progress` part (re-broadcast to the parent's clients + surfaced
+   * in `useAgentToolEvents`) and persists a latest-wins snapshot for recovery /
+   * inspection. A no-op (with a dev warning) on the base `Agent`, which has no
+   * streaming turn — overridden by chat hosts (`@cloudflare/think`,
+   * `AIChatAgent`). See `design/rfc-detached-agent-tools.md`.
+   */
+  reportProgress<T = unknown>(
+    _progress: AgentToolProgress<T>,
+    _options?: {
+      persist?: boolean;
+    }
+  ): Promise<void>;
+  runAgentTool<Input = unknown>(
+    cls: ChatCapableAgentClass,
+    options: RunAgentToolOptions<Input> & {
+      detached: true | DetachedAgentToolConfig;
+    }
+  ): Promise<DetachedRunAgentToolResult>;
   runAgentTool<Input = unknown, Output = unknown>(
     cls: ChatCapableAgentClass,
     options: RunAgentToolOptions<Input>
   ): Promise<RunAgentToolResult<Output>>;
+  /**
+   * Cancel an agent-tool run by id. Idempotent: cancelling an already-terminal
+   * run is a no-op. Detached runs deliver through the guarded ledger so a wired
+   * `onFinish` fires once with `status: "aborted"`; awaited runs leave terminal
+   * observation to the awaiting/recovery path, avoiding duplicate finish hooks.
+   */
+  cancelAgentTool(runId: string, reason?: unknown): Promise<void>;
+  /**
+   * Parse + validate the `detached` option. Returns `null` for a non-detached
+   * run, or the normalized config (with the validated `onFinish` method name)
+   * for a detached one. Throws if `onFinish` does not name a method on this
+   * agent — closures cannot survive Durable Object eviction, so the durable
+   * hook is referenced by method name (the same contract as `schedule`).
+   */
+  private _parseDetachedOption;
+  private _isAgentToolRowHardTerminal;
+  private _hasOutstandingDetachedRuns;
+  /** Detached runs still holding a concurrency slot (non-terminal). */
+  private _liveDetachedRunCount;
+  /**
+   * Edge-triggered warning when live detached runs cross
+   * `DETACHED_LIVE_COUNT_WARN_THRESHOLD`. Fires once on the up-crossing and
+   * re-arms only after the count falls back below the threshold, so a parent
+   * accumulating long-lived background runs surfaces a signal without spamming.
+   */
+  private _maybeWarnDetachedLiveCount;
+  /**
+   * Warm fast path for a detached run: tail the child to terminal (so the
+   * parent re-broadcasts its live stream to clients) and deliver the completion
+   * with low latency while the isolate stays alive. Best-effort — the durable
+   * `_cfDetachedReconcileTick` backbone is the guarantee; anything this misses
+   * (eviction, a child that has not yet reached terminal) the backbone collects.
+   */
+  private _detachedFastPath;
+  /**
+   * Single delivery funnel for a detached terminal. Both the warm fast path and
+   * the durable backbone route through here, with INDEPENDENT ledger slots for
+   * `finish` (the real terminal) vs `give_up` (budget exhausted). Each slot is
+   * delivered at-least-once via a claim + lease:
+   *
+   * - Concurrent double-fire is prevented by the guarded CAS claim (RETURNING
+   *   yields the row only to the winner).
+   * - A crash after the side effect but before `*_delivered_at` is written lets
+   *   the lease expire so a later reconcile re-delivers — hence handlers must be
+   *   idempotent.
+   * - Two slots, not one, because `interrupted` is SOFT: a give-up followed by a
+   *   real completion is legitimate, and a single shared "delivered" bit would
+   *   dedupe the child's real late result away (the #1752 production incident).
+   */
+  private _deliverDetachedTerminal;
+  private _safeRunOnError;
+  /**
+   * Run a detached terminal delivery (the `onAgentToolFinish` + per-run
+   * `onFinish` callbacks) in an appropriate execution context. The base `Agent`
+   * has no turn queue, so it only establishes `agentContext` — a handler that
+   * calls `runAgentTool` / `setState` therefore works regardless of where the
+   * delivery fired from.
+   *
+   * Chat-layer subclasses (`@cloudflare/think`, `@cloudflare/ai-chat`) override
+   * this to additionally serialize delivery against their turn queue when
+   * `serialize` is set: a fast-path push or backbone tick can land mid-turn, and
+   * a state-mutating `onFinish` running concurrently with an active LLM turn is a
+   * data race. The fast path and backbone never run synchronously inside a turn
+   * (they fire from `waitUntil` / a scheduled alarm), so enqueuing them on the
+   * turn queue is deadlock-free. An explicit `cancelAgentTool` runs with
+   * `serialize` unset because it may be called from inside the very turn that
+   * triggers it, where enqueuing would self-deadlock.
+   */
+  protected _runDetachedDelivery(
+    invoke: () => Promise<void>,
+    _options?: {
+      serialize?: boolean;
+    }
+  ): Promise<void>;
+  /**
+   * Arm the self-scheduling detached reconcile backbone. Existing schedules are
+   * reused for recovery/startup calls, but a fresh detached dispatch resets the
+   * pending cadence to the fast end so new work is noticed promptly.
+   */
+  private _armDetachedBackbone;
+  private _armDetachedBackboneInner;
+  /**
+   * Durable backbone for detached runs. Runs on a self-rescheduling alarm:
+   * collects any detached run that has reached terminal but was not yet
+   * delivered (e.g. the parent was evicted before the fast path landed), gives
+   * up on any run past its absolute budget (tearing the child down), and
+   * reschedules itself while any detached run remains undelivered — cancelling
+   * itself once everything has settled (zero steady-state cost).
+   */
+  _cfDetachedReconcileTick(payload?: DetachedReconcilePayload): Promise<void>;
   hasAgentToolRun<T extends Agent>(
     cls: SubAgentClass<T>,
     runId: string
@@ -3726,6 +3922,34 @@ declare class Agent<
    * called repeatedly while a child streams.
    */
   protected _onAgentToolStreamProgress(): Promise<void>;
+  /**
+   * Best-effort observation of a forwarded child chunk: if it is a reserved
+   * `data-agent-progress` frame, refresh the cached liveness timestamp on the
+   * run row (a hint for a still-warm parent) and fire the public `onProgress`
+   * hook. Never throws into the forward loop — the child's own persisted
+   * snapshot (read via `inspectAgentToolRun`) remains authoritative for the
+   * resetting no-progress budget after eviction.
+   */
+  private _observeForwardedProgress;
+  /**
+   * Deliver a milestone notification IF this run opted into it via
+   * `detached: { onMilestones }` and the milestone name is in that set. Routes
+   * to the overridable `_deliverDetachedMilestone` seam (a no-op on the base
+   * `Agent`; chat hosts inject an idempotent synthetic chat message).
+   */
+  private _maybeDeliverDetachedMilestone;
+  /**
+   * Overridable seam for the `detached: { onMilestones }` convenience. The base
+   * `Agent` has no chat surface, so this is a no-op; chat hosts
+   * (`@cloudflare/think`, `AIChatAgent`) override it to submit an idempotent
+   * synthetic message keyed on `(runId, milestone.name)`. Called from both the
+   * warm tail and the backbone reconcile, so it MUST be idempotent.
+   */
+  protected _deliverDetachedMilestone(
+    _run: AgentToolRunInfo,
+    _milestone: AgentToolMilestone,
+    _mode: "react" | "narrate"
+  ): Promise<void>;
   private _broadcastAgentToolTerminal;
   private _asAgentToolChildAdapter;
   private _agentToolClassByName;
@@ -3931,10 +4155,29 @@ declare class Agent<
    * Start a workflow and track it in this Agent's database.
    * Automatically injects agent identity into the workflow params.
    *
+   * The originating Agent identity is persisted in the workflow params so
+   * callbacks (`this.agent` RPC, progress/completion/error, state updates)
+   * route back to the exact Agent or sub-agent facet that started the run.
+   * Note the following constraints:
+   *
+   * - **Resolution is by name.** Callbacks re-resolve the originating Agent via
+   *   `getAgentByName(...)`. Agents addressed by a raw Durable Object id
+   *   (`idFromString`/`get(id)`) rather than by name will not receive
+   *   callbacks on the same instance.
+   * - **Sub-agent runs are facet-local.** A workflow started from a sub-agent
+   *   is tracked in that facet's own storage; the parent's `getWorkflows()` /
+   *   `getWorkflowById()` do not see it. Aggregate across facets yourself if
+   *   you need a combined view.
+   * - **Class names must survive bundling.** The originating path is keyed by
+   *   `constructor.name`. Ensure your bundler preserves class names
+   *   (e.g. esbuild `keepNames: true`) so callbacks can be routed.
+   *
    * @template P - Type of params to pass to the workflow
    * @param workflowName - Name of the workflow binding in env (e.g., 'MY_WORKFLOW')
    * @param params - Params to pass to the workflow
-   * @param options - Optional workflow options
+   * @param options - Optional workflow options. For sub-agents, pass
+   *   `agentBinding` as the **root** Agent's Durable Object binding name, not a
+   *   child binding.
    * @returns The workflow instance ID
    *
    * @example
@@ -4204,16 +4447,15 @@ declare class Agent<
    * Convert a database row to WorkflowInfo
    */
   private _rowToWorkflowInfo;
-  /**
-   * Find the binding name for this Agent's namespace by matching class name.
-   * Returns undefined if no match found - use options.agentBinding as fallback.
-   */
-  private _findAgentBindingName;
+  private _workflowOrigin;
+  private _findAgentBindingNameForClass;
   private _findBindingNameForNamespace;
   private _restoreRpcMcpServers;
   /**
    * Handle a callback from a workflow.
-   * Called when the Agent receives a callback at /_workflow/callback.
+   * Invoked via the internal `_workflow_handleCallback` RPC whenever an
+   * {@link AgentWorkflow} reports progress, completion, an error, or a custom
+   * event back to its originating Agent (or sub-agent facet).
    * Override this to handle all callback types in one place.
    *
    * @param callback - The callback payload
@@ -4532,6 +4774,10 @@ type AgentToolTerminalStatus = Extract<
  * - `inspect-failed` — inspecting the child failed during parent recovery.
  * - `recovery-deadline` — the overall parent-recovery deadline elapsed before
  *   this run could be reconciled.
+ * - `budget-exceeded` — a detached run's absolute `maxBudgetMs` ceiling elapsed
+ *   before it reached a terminal. The parent gave up watching and tore the
+ *   child down. Like `window-exceeded` this is a soft seal: a child that
+ *   completes anyway can still repair the run and re-fire the completion hook.
  */
 type AgentToolInterruptedReason =
   | "no-progress"
@@ -4539,7 +4785,8 @@ type AgentToolInterruptedReason =
   | "not-tailable"
   | "inspect-timeout"
   | "inspect-failed"
-  | "recovery-deadline";
+  | "recovery-deadline"
+  | "budget-exceeded";
 /**
  * Structured failure envelope an `agentTool()` returns when a sub-agent run
  * does not complete. Instead of an opaque error string the parent model would
@@ -4572,6 +4819,70 @@ type AgentToolDisplayMetadata = {
   name?: string;
   icon?: string;
 } & Record<string, unknown>;
+/**
+ * Reserved chunk type a sub-agent emits via `reportProgress` while it runs.
+ * Rides the child's own UI-message stream as a **transient** data part, so it
+ * re-broadcasts to the parent's clients (via the parent's tail) and surfaces in
+ * `useAgentToolEvents` without persisting into the child's stored message parts.
+ * See `design/rfc-detached-agent-tools.md` §"Progress and milestone signaling".
+ */
+declare const AGENT_TOOL_PROGRESS_PART = "data-agent-progress";
+/**
+ * Reserved chunk type a sub-agent emits via `reportProgress({ milestone })`.
+ * Unlike the ephemeral progress part this rides the child's stream as a
+ * **persisted** data part, so it survives eviction, replays on drill-in, and
+ * re-resolves milestone waiters. See `design/rfc-detached-agent-tools.md`.
+ */
+declare const AGENT_TOOL_MILESTONE_PART = "data-agent-milestone";
+/**
+ * Ephemeral progress signal a running sub-agent emits with `reportProgress`. The
+ * well-known fields drive generic UI (a bar + status line) with no per-app
+ * convention; `data` is an app-specific escape hatch that is **live-only** by
+ * default (not persisted) unless `reportProgress(p, { persist: true })`. Naming a
+ * `milestone` promotes the signal to the **durable** tier: it persists as one row
+ * per milestone, replays, and (with `data`) is retained.
+ */
+type AgentToolProgress<T = unknown> = {
+  /** 0..1 — drives a progress bar. */ fraction?: number /** Human-readable status line, e.g. "Ingested 40k/80k rows". */;
+  message?: string /** Coarse stage label, e.g. "scaffolding" | "deploying". */;
+  phase?: string;
+  /**
+   * Present ⇒ a **durable** milestone: persisted, replayable, and surfaced as a
+   * distinct row in `AgentToolRunState.milestones` / `inspectAgentToolRun`. Use
+   * for named phase boundaries ("schema-ready", "preview-ready", "deployed").
+   */
+  milestone?: string /** App-specific payload; live-only for progress, persisted for milestones. */;
+  data?: T;
+};
+/**
+ * A durable milestone a sub-agent reached, projected onto `AgentToolRunState`
+ * and `inspectAgentToolRun`. `sequence` is monotonic per run so replay/live
+ * races dedupe on `(runId, sequence)`.
+ */
+type AgentToolMilestone = {
+  name: string /** Monotonic per-run ordinal; dedupe key for replay vs live races. */;
+  sequence: number /** Epoch ms the milestone was reached. */;
+  at: number /** App-specific payload carried with the milestone (persisted). */;
+  data?: unknown;
+};
+/**
+ * Latest progress snapshot persisted on the child run row and surfaced through
+ * `inspectAgentToolRun` + `AgentToolRunState`. Only the safe-to-inspect fields
+ * are retained by default; `at` is the emit timestamp (drives the resetting
+ * no-progress budget).
+ */
+type AgentToolProgressSnapshot = {
+  fraction?: number;
+  message?: string;
+  phase?: string;
+  /**
+   * Set when this signal was a durable milestone (`reportProgress({ milestone })`).
+   * Lets an `onProgress` consumer branch on milestone vs. ephemeral progress.
+   */
+  milestone?: string /** Epoch ms of the latest signal. */;
+  at: number /** Present only when the emitter opted into persisting `data`. */;
+  data?: unknown;
+};
 type AgentToolRunInfo = {
   runId: string;
   parentToolCallId?: string;
@@ -4579,6 +4890,11 @@ type AgentToolRunInfo = {
   inputPreview?: unknown;
   status: AgentToolRunStatus;
   display?: AgentToolDisplayMetadata;
+  /**
+   * Caller-controlled `metadata.source` for chat-agent `detached.notify`
+   * completions. Present only for detached notify runs that supplied one.
+   */
+  notifySource?: string;
   displayOrder: number;
   startedAt: number;
   completedAt?: number;
@@ -4594,7 +4910,80 @@ type AgentToolLifecycleResult = {
    */
   childStillRunning?: boolean;
 };
-type RunAgentToolOptions<Input = unknown> = {
+/**
+ * Configuration for a detached ("background") agent-tool run. See
+ * `design/rfc-detached-agent-tools.md`.
+ *
+ * Callbacks are referenced by **method name** on the dispatching agent (the same
+ * durable, eviction-surviving pattern as `Agent.schedule`) — never closures,
+ * which cannot be rehydrated after the Durable Object is evicted.
+ *
+ * `Self` is threaded from `runAgentTool(cls, options)` so the method names are
+ * type-checked against the calling agent's own methods.
+ */
+type DetachedAgentToolConfig<Self = Record<string, unknown>> = {
+  /**
+   * Method invoked once per terminal delivery. Branch on `result.status`:
+   * `"completed" | "error" | "aborted" | "interrupted"`. A budget give-up
+   * arrives as `status: "interrupted"` with `reason: "budget-exceeded"`; because
+   * `interrupted` is soft, a child that later completes can fire the hook again
+   * with `"completed"`, so a give-up never hides a late real result. Make the
+   * handler idempotent.
+   */
+  onFinish?: Extract<keyof Self, string>;
+  /**
+   * Absolute safety ceiling — a backstop against a child that runs forever. On
+   * expiry the parent gives up watching (delivers `onFinish` with
+   * `interrupted` / `budget-exceeded`) and tears the child down. Defaults to the
+   * parent-level `detachedMaxBudgetMs`.
+   */
+  maxBudgetMs?: number;
+  /**
+   * Per-run override of the resetting no-progress window (ms). Once the child
+   * emits its first `reportProgress`, the parent gives up if it then goes silent
+   * for this long (resets on each signal). Defaults to the parent-level
+   * `detachedNoProgressBudgetMs` (1h). `0`/`Infinity` disables it.
+   */
+  noProgressBudgetMs?: number;
+  /**
+   * Chat-agent convenience (`@cloudflare/think` / `AIChatAgent`): when the run
+   * finishes, inject a message into the chat so the model can react to the
+   * result, instead of you wiring `onFinish` by hand. Sugar that auto-targets
+   * the agent's `_cfDetachedNotifyFinish` hook; ignored on a base `Agent` that
+   * does not implement it, and ignored when `onFinish` is also set (an explicit
+   * `onFinish` wins). Pass `{ source }` to fit the injected message into your
+   * app's existing metadata taxonomy. Override `formatDetachedCompletion()` to
+   * customize the injected text.
+   */
+  notify?:
+    | boolean
+    | {
+        source?: string;
+      };
+  /**
+   * Chat-agent convenience: milestone names that, when the detached run reaches
+   * them, surface an idempotent synthetic message in the chat BEFORE the run
+   * finishes. Each `(runId, name)` fires at most once (idempotency-keyed),
+   * whether observed live or reconciled after eviction. Override the wording via
+   * `formatDetachedMilestone()`. Requires a chat host (`@cloudflare/think`); a
+   * no-op on a base `Agent`.
+   *
+   * Two delivery modes (the string-array shorthand defaults to `"narrate"`):
+   * - `"narrate"` (default) — inject a synthetic **assistant** message directly
+   *   (no inference): a cheap, honest status line ("Found 2 sources…") that does
+   *   not trigger a model turn. Best for pure progress narration.
+   * - `"react"` — inject a **user-role** turn so the model responds to the
+   *   milestone (steer, start dependent work, narrate with context). Costs a
+   *   model turn. Opt in for milestones the agent should *act on*.
+   */
+  onMilestones?:
+    | string[]
+    | {
+        names: string[];
+        mode?: "react" | "narrate";
+      };
+};
+type RunAgentToolOptions<Input = unknown, Self = Record<string, unknown>> = {
   input: Input;
   runId?: string;
   parentToolCallId?: string;
@@ -4602,6 +4991,30 @@ type RunAgentToolOptions<Input = unknown> = {
   signal?: AbortSignal;
   inputPreview?: unknown;
   display?: AgentToolDisplayMetadata;
+  /**
+   * Run the sub-agent **detached**: dispatch it, let the current turn continue,
+   * and (optionally) get a durable callback when it finishes. `true` is
+   * fire-and-forget (observe via `agent-tool-event` frames + the global
+   * `onAgentToolFinish` hook); an object adds the targeted, eviction-surviving
+   * `onFinish` callback. A detached run does NOT inherit `options.signal` — it
+   * must outlive the spawning turn; cancel it explicitly via `cancelAgentTool`.
+   */
+  detached?: boolean | DetachedAgentToolConfig<Self>;
+};
+/**
+ * Result of dispatching a detached run. Returns immediately after dispatch
+ * rather than after completion.
+ */
+type DetachedRunAgentToolResult = {
+  runId: string;
+  agentType: string;
+  /**
+   * `"running"` on a successful dispatch; `"error"` if dispatch itself failed
+   * (e.g. the `maxConcurrentAgentTools` cap was exceeded — rejected
+   * synchronously, no child started, no callback wired).
+   */
+  status: "running" | "error";
+  error?: string;
 };
 type RunAgentToolResult<Output = unknown> = {
   runId: string;
@@ -4634,6 +5047,19 @@ type AgentToolRunInspection<Output = unknown> = {
   error?: string;
   startedAt: number;
   completedAt?: number;
+  /**
+   * Latest progress snapshot the child has persisted, so a rehydrated parent
+   * (recovery / backbone reconcile) can reconstruct "where is this run" and
+   * reset the resetting no-progress budget without having tailed the live
+   * stream. Absent until the child emits its first `reportProgress`.
+   */
+  progress?: AgentToolProgressSnapshot;
+  /**
+   * Durable milestones the child has persisted, ordered by `sequence`. Lets a
+   * rehydrated parent (recovery / backbone reconcile) replay milestone-gated
+   * work and milestone notifications without having observed the live stream.
+   */
+  milestones?: AgentToolMilestone[];
 };
 type AgentToolStoredChunk = {
   sequence: number;
@@ -4713,7 +5139,10 @@ type AgentToolEventMessage = {
   replay?: true;
   event: AgentToolEvent;
 };
-type AgentToolRunState = {
+type AgentToolRunPart = {
+  type: string;
+};
+type AgentToolRunState<Part extends AgentToolRunPart = AgentToolRunPart> = {
   runId: string;
   agentType: string;
   parentToolCallId?: string;
@@ -4721,7 +5150,15 @@ type AgentToolRunState = {
   order: number;
   display?: AgentToolDisplayMetadata;
   status: "running" | "completed" | "error" | "aborted" | "interrupted";
-  parts: UIMessage["parts"];
+  /**
+   * Message parts reconstructed from the child agent's streamed chunks.
+   *
+   * The default stays framework-neutral so importing `agents` does not require
+   * an AI SDK peer. AI SDK consumers can use
+   * `AgentToolRunState<UIMessage["parts"][number]>` when they need its exact
+   * discriminated union.
+   */
+  parts: Part[];
   summary?: string;
   error?: string;
   /**
@@ -4731,120 +5168,141 @@ type AgentToolRunState = {
    */
   reason?: AgentToolInterruptedReason;
   childStillRunning?: boolean;
+  /**
+   * Latest progress snapshot, projected from the child's transient
+   * `data-agent-progress` signals so a UI can render a bar / ETA / phase label
+   * for a running (especially detached / background) run without drilling in.
+   */
+  progress?: AgentToolProgressSnapshot;
+  /**
+   * Durable milestones the run has reached, ordered by `sequence` (deduped
+   * across replay/live races). Drives milestone chips / a phase timeline.
+   */
+  milestones?: AgentToolMilestone[];
   subAgent: {
     agent: string;
     name: string;
   };
 };
-type AgentToolEventState = {
-  runsById: Record<string, AgentToolRunState>;
-  runsByToolCallId: Record<string, AgentToolRunState[]>;
-  unboundRuns: AgentToolRunState[];
+type AgentToolEventState<Part extends AgentToolRunPart = AgentToolRunPart> = {
+  runsById: Record<string, AgentToolRunState<Part>>;
+  runsByToolCallId: Record<string, AgentToolRunState<Part>[]>;
+  unboundRuns: AgentToolRunState<Part>[];
 };
 //#endregion
 export {
-  StreamingResponse as $,
-  DeleteFibersOptions as A,
-  McpAgent as At,
-  MCPServerMessage as B,
-  WorkerTransportOptions as Bt,
-  AgentNamespace as C,
-  RPCClientTransportOptions as Ct,
-  Connection$1 as D,
-  ElicitRequest$1 as Dt,
-  CallableMetadata as E,
-  RPC_DO_PREFIX as Et,
-  FiberRecoveryContext as F,
-  experimental_createMcpHandler as Ft,
-  RoutingRetryOptions as G,
-  SUB_PREFIX as Gt,
-  QueueItem as H,
-  StreamableHTTPEdgeClientTransport as Ht,
-  FiberRecoveryResult as I,
-  McpAuthContext as It,
-  SendEmailOptions as J,
-  parseSubAgentPath as Jt,
-  Schedule as K,
-  SubAgentPathMatch as Kt,
-  FiberStatus as L,
-  getMcpAuthContext as Lt,
-  EmailSendBinding as M,
-  DurableObjectEventStore as Mt,
-  FiberContext as N,
-  CreateMcpHandlerOptions as Nt,
-  ConnectionContext$1 as O,
-  ElicitRequestSchema$1 as Ot,
-  FiberInspection as P,
-  createMcpHandler as Pt,
-  StateUpdateMessage as Q,
-  ListFibersOptions as R,
-  TransportState as Rt,
-  AgentGetOptions as S,
-  RPCClientTransport as St,
-  AgentStaticOptions as T,
-  RPCServerTransportOptions as Tt,
-  RPCRequest as U,
-  McpClientOptions as Ut,
-  MCPServersState as V,
-  SSEEdgeClientTransport as Vt,
-  RPCResponse as W,
-  TransportType as Wt,
-  StartFiberOptions as X,
-  SqlError as Y,
-  routeSubAgentRequest as Yt,
-  StartFiberResult as Z,
-  RunAgentToolResult as _,
-  MCPServerOptions as _t,
-  AgentToolEventState as a,
-  getCurrentAgent as at,
-  Agent as b,
-  getNamespacedData as bt,
-  AgentToolLifecycleResult as c,
-  unstable_callable as ct,
-  AgentToolRunState as d,
-  MCPClientOAuthCallbackConfig as dt,
-  SubAgentClass as et,
-  AgentToolRunStatus as f,
-  MCPClientOAuthResult as ft,
-  RunAgentToolOptions as g,
-  MCPServerFilter as gt,
-  ChatCapableAgentClass as h,
-  MCPOAuthCallbackResult as ht,
-  AgentToolEventMessage as i,
-  getAgentByName as it,
-  EmailRoutingOptions as j,
-  ClearableEventStore as jt,
-  DEFAULT_AGENT_STATIC_OPTIONS as k,
-  ElicitResult$1 as kt,
-  AgentToolRunInfo as l,
-  MCPClientManager as lt,
-  AgentToolTerminalStatus as m,
-  MCPDiscoverResult as mt,
-  AgentToolDisplayMetadata as n,
-  WSMessage$1 as nt,
-  AgentToolFailure as o,
-  routeAgentEmail as ot,
-  AgentToolStoredChunk as p,
-  MCPConnectionResult as pt,
-  ScheduleCriteria as q,
-  getSubAgentByName as qt,
-  AgentToolEvent as r,
-  callable as rt,
-  AgentToolInterruptedReason as s,
-  routeAgentRequest as st,
-  AgentToolChildAdapter as t,
-  SubAgentStub as tt,
-  AgentToolRunInspection as u,
-  MCPClientManagerOptions as ut,
-  AddMcpServerOptions as v,
-  MCP_SERVER_ID_MAX_LENGTH as vt,
-  AgentOptions as w,
-  RPCServerTransport as wt,
-  AgentContext as x,
-  normalizeServerId as xt,
-  AddRpcMcpServerOptions as y,
-  RegisterServerOptions as yt,
-  MCPServer as z,
-  WorkerTransport as zt
+  RoutingRetryOptions as $,
+  McpClientOptions as $t,
+  AgentGetOptions as A,
+  getNamespacedData as At,
+  EmailSendBinding as B,
+  McpAgent as Bt,
+  DetachedRunAgentToolResult as C,
+  MCPConnectionResult as Ct,
+  AddRpcMcpServerOptions as D,
+  MCPServerOptions as Dt,
+  AddMcpServerOptions as E,
+  MCPServerFilter as Et,
+  Connection$1 as F,
+  RPCServerTransportOptions as Ft,
+  FiberStatus as G,
+  experimental_createMcpHandler as Gt,
+  FiberInspection as H,
+  DurableObjectEventStore as Ht,
+  ConnectionContext$1 as I,
+  RPC_DO_PREFIX as It,
+  MCPServerMessage as J,
+  TransportState as Jt,
+  ListFibersOptions as K,
+  McpAuthContext as Kt,
+  DEFAULT_AGENT_STATIC_OPTIONS as L,
+  ElicitRequest$1 as Lt,
+  AgentOptions as M,
+  RPCClientTransport as Mt,
+  AgentStaticOptions as N,
+  RPCClientTransportOptions as Nt,
+  Agent as O,
+  MCP_SERVER_ID_MAX_LENGTH as Ot,
+  CallableMetadata as P,
+  RPCServerTransport as Pt,
+  RPCResponse as Q,
+  StreamableHTTPEdgeClientTransport as Qt,
+  DeleteFibersOptions as R,
+  ElicitRequestSchema$1 as Rt,
+  DetachedAgentToolConfig as S,
+  MCPClientOAuthResult as St,
+  RunAgentToolResult as T,
+  MCPOAuthCallbackResult as Tt,
+  FiberRecoveryContext as U,
+  CreateMcpHandlerOptions as Ut,
+  FiberContext as V,
+  ClearableEventStore as Vt,
+  FiberRecoveryResult as W,
+  createMcpHandler as Wt,
+  QueueItem as X,
+  WorkerTransportOptions as Xt,
+  MCPServersState as Y,
+  WorkerTransport as Yt,
+  RPCRequest as Z,
+  SSEEdgeClientTransport as Zt,
+  AgentToolRunState as _,
+  MCPAITool as _t,
+  AgentToolEvent as a,
+  routeSubAgentRequest as an,
+  StartFiberResult as at,
+  AgentToolTerminalStatus as b,
+  MCPClientManagerOptions as bt,
+  AgentToolFailure as c,
+  SubAgentClass as ct,
+  AgentToolMilestone as d,
+  callable as dt,
+  TransportType as en,
+  Schedule as et,
+  AgentToolProgress as f,
+  getAgentByName as ft,
+  AgentToolRunPart as g,
+  unstable_callable as gt,
+  AgentToolRunInspection as h,
+  routeAgentRequest as ht,
+  AgentToolDisplayMetadata as i,
+  parseSubAgentPath as in,
+  StartFiberOptions as it,
+  AgentNamespace as j,
+  normalizeServerId as jt,
+  AgentContext as k,
+  RegisterServerOptions as kt,
+  AgentToolInterruptedReason as l,
+  SubAgentStub as lt,
+  AgentToolRunInfo as m,
+  routeAgentEmail as mt,
+  AGENT_TOOL_PROGRESS_PART as n,
+  SubAgentPathMatch as nn,
+  SendEmailOptions as nt,
+  AgentToolEventMessage as o,
+  StateUpdateMessage as ot,
+  AgentToolProgressSnapshot as p,
+  getCurrentAgent as pt,
+  MCPServer as q,
+  getMcpAuthContext as qt,
+  AgentToolChildAdapter as r,
+  getSubAgentByName as rn,
+  SqlError as rt,
+  AgentToolEventState as s,
+  StreamingResponse as st,
+  AGENT_TOOL_MILESTONE_PART as t,
+  SUB_PREFIX as tn,
+  ScheduleCriteria as tt,
+  AgentToolLifecycleResult as u,
+  WSMessage$1 as ut,
+  AgentToolRunStatus as v,
+  MCPAIToolSet as vt,
+  RunAgentToolOptions as w,
+  MCPDiscoverResult as wt,
+  ChatCapableAgentClass as x,
+  MCPClientOAuthCallbackConfig as xt,
+  AgentToolStoredChunk as y,
+  MCPClientManager as yt,
+  EmailRoutingOptions as z,
+  ElicitResult$1 as zt
 };
-//# sourceMappingURL=agent-tool-types-NofdbL9X.d.ts.map
+//# sourceMappingURL=agent-tool-types-Cd1TZPfB.d.ts.map