agents 0.16.2 → 0.17.0

package/dist/index.js

@@ -1,11 +1,12 @@
+import { AGENT_TOOL_MILESTONE_PART, AGENT_TOOL_PROGRESS_PART } from "./agent-tool-types.js";
 import { __DO_NOT_USE_WILL_BREAK__agentContext } from "./internal_context.js";
 import { MessageType } from "./types.js";
 import { camelCaseToKebabCase, isInternalJsStubProp } from "./utils.js";
 import { createHeaderBasedEmailResolver, signAgentHeaders } from "./email.js";
-import { i as _classPrivateFieldInitSpec, n as _classPrivateFieldSet2, t as _classPrivateFieldGet2 } from "./classPrivateFieldGet2-CZ7QjTXN.js";
+import { i as _classPrivateFieldInitSpec, n as _classPrivateFieldSet2, t as _classPrivateFieldGet2 } from "./classPrivateFieldGet2-DZBYAB34.js";
 import { SUB_PREFIX, getSubAgentByName, parseSubAgentPath, routeSubAgentRequest } from "./sub-routing.js";
 import { isDurableObjectCodeUpdateReset, isErrorRetryable, isPlatformTransientError, tryN, validateRetryOptions } from "./retries.js";
-import { a as MCPConnectionState, c as RPC_DO_PREFIX, i as normalizeServerId, l as DisposableStore, n as MCP_SERVER_ID_MAX_LENGTH, t as MCPClientManager } from "./client-BXJ9n2f7.js";
+import { a as MCPConnectionState, c as RPC_DO_PREFIX, i as normalizeServerId, l as DisposableStore, n as MCP_SERVER_ID_MAX_LENGTH, t as MCPClientManager } from "./client-BZ-B3NhC.js";
 import { DurableObjectOAuthClientProvider } from "./mcp/do-oauth-client-provider.js";
 import { genericObservability } from "./observability/index.js";
 import { AsyncLocalStorage } from "node:async_hooks";
@@ -134,6 +135,18 @@ const FIBER_RECOVERY_MAX_BACKOFF_MS = 5 * 6e4;
 const FIBER_RECOVERY_BACKOFF_MAX_EXP = 20;
 const DEFAULT_AGENT_TOOL_REATTACH_NO_PROGRESS_TIMEOUT_MS = 12e4;
 const DEFAULT_AGENT_TOOL_REATTACH_MAX_WINDOW_MS = Number.POSITIVE_INFINITY;
+const DEFAULT_DETACHED_MAX_BUDGET_MS = 1440 * 60 * 1e3;
+const DEFAULT_DETACHED_NO_PROGRESS_BUDGET_MS = 3600 * 1e3;
+const DETACHED_DELIVERY_LEASE_MS = 6e4;
+const DETACHED_BACKBONE_CADENCE_S = [
+	5,
+	15,
+	30,
+	120
+];
+const DETACHED_LIVE_COUNT_WARN_THRESHOLD = 50;
+const DETACHED_RECONCILE_CALLBACK = "_cfDetachedReconcileTick";
+const DETACHED_NOTIFY_CALLBACK = "_cfDetachedNotifyFinish";
 const SUB_AGENT_IDENTITY_VERSION_LEGACY = "legacy";
 const SUB_AGENT_IDENTITY_VERSION_PATH_V2 = "path-v2";
 const SUB_AGENT_IDENTITY_PATH_V2_PREFIX = "cf-agents:v2:";
@@ -143,7 +156,7 @@ const SUB_AGENT_IDENTITY_PATH_V2_PREFIX = "cf-agents:v2:";
 * The constructor stores this as a row in cf_agents_state and checks it
 * on wake to skip DDL on established DOs.
 */
-const CURRENT_SCHEMA_VERSION = 9;
+const CURRENT_SCHEMA_VERSION = 11;
 const SCHEMA_VERSION_ROW_ID = "cf_schema_version";
 const STATE_ROW_ID = "cf_state_row_id";
 const STATE_WAS_CHANGED = "cf_state_was_changed";
@@ -205,7 +218,7 @@ const SUB_AGENT_OUTER_URL_HEADER = "x-cf-agents-subagent-url";
 * The set of all internal keys stored in connection state that must be
 * hidden from user code and preserved across setState calls.
 */
-const CF_INTERNAL_KEYS = new Set([
+const CF_INTERNAL_KEYS = /* @__PURE__ */ new Set([
 	CF_READONLY_KEY,
 	CF_NO_PROTOCOL_KEY,
 	CF_VOICE_IN_CALL_KEY,
@@ -312,7 +325,9 @@ const DEFAULT_AGENT_STATIC_OPTIONS = {
 	* `maxRecoveryWork` / `shouldKeepRecovering`. Set a finite value to impose a
 	* wall-clock cap (which also tears the child down on `window-exceeded`).
 	*/
-	agentToolReattachMaxWindowMs: DEFAULT_AGENT_TOOL_REATTACH_MAX_WINDOW_MS
+	agentToolReattachMaxWindowMs: DEFAULT_AGENT_TOOL_REATTACH_MAX_WINDOW_MS,
+	detachedMaxBudgetMs: DEFAULT_DETACHED_MAX_BUDGET_MS,
+	detachedNoProgressBudgetMs: DEFAULT_DETACHED_NO_PROGRESS_BUDGET_MS
 };
 /**
 * Parse the raw `retry_options` TEXT column from a SQLite row into a
@@ -437,7 +452,9 @@ var Agent = class Agent extends Server {
 			fiberRecoveryScanDeadlineMs: ctor.options?.fiberRecoveryScanDeadlineMs ?? DEFAULT_AGENT_STATIC_OPTIONS.fiberRecoveryScanDeadlineMs,
 			fiberRecoveryMaxAgeMs: ctor.options?.fiberRecoveryMaxAgeMs ?? DEFAULT_AGENT_STATIC_OPTIONS.fiberRecoveryMaxAgeMs,
 			agentToolReattachNoProgressTimeoutMs: ctor.options?.agentToolReattachNoProgressTimeoutMs ?? DEFAULT_AGENT_STATIC_OPTIONS.agentToolReattachNoProgressTimeoutMs,
-			agentToolReattachMaxWindowMs: ctor.options?.agentToolReattachMaxWindowMs ?? DEFAULT_AGENT_STATIC_OPTIONS.agentToolReattachMaxWindowMs
+			agentToolReattachMaxWindowMs: ctor.options?.agentToolReattachMaxWindowMs ?? DEFAULT_AGENT_STATIC_OPTIONS.agentToolReattachMaxWindowMs,
+			detachedMaxBudgetMs: ctor.options?.detachedMaxBudgetMs ?? DEFAULT_AGENT_STATIC_OPTIONS.detachedMaxBudgetMs,
+			detachedNoProgressBudgetMs: ctor.options?.detachedNoProgressBudgetMs ?? DEFAULT_AGENT_STATIC_OPTIONS.detachedNoProgressBudgetMs
 		};
 		return this._cachedOptions;
 	}
@@ -679,6 +696,17 @@ var Agent = class Agent extends Server {
 			addColumnIfNotExists("ALTER TABLE cf_agent_tool_runs ADD COLUMN output_json TEXT");
 			addColumnIfNotExists("ALTER TABLE cf_agent_tool_runs ADD COLUMN interrupted_reason TEXT");
 			addColumnIfNotExists("ALTER TABLE cf_agent_tool_runs ADD COLUMN child_still_running INTEGER");
+			addColumnIfNotExists("ALTER TABLE cf_agent_tool_runs ADD COLUMN detached INTEGER NOT NULL DEFAULT 0");
+			addColumnIfNotExists("ALTER TABLE cf_agent_tool_runs ADD COLUMN detached_on_finish TEXT");
+			addColumnIfNotExists("ALTER TABLE cf_agent_tool_runs ADD COLUMN detached_notify_source TEXT");
+			addColumnIfNotExists("ALTER TABLE cf_agent_tool_runs ADD COLUMN detached_max_budget_at INTEGER");
+			addColumnIfNotExists("ALTER TABLE cf_agent_tool_runs ADD COLUMN finish_claimed_at INTEGER");
+			addColumnIfNotExists("ALTER TABLE cf_agent_tool_runs ADD COLUMN finish_delivered_at INTEGER");
+			addColumnIfNotExists("ALTER TABLE cf_agent_tool_runs ADD COLUMN give_up_claimed_at INTEGER");
+			addColumnIfNotExists("ALTER TABLE cf_agent_tool_runs ADD COLUMN give_up_delivered_at INTEGER");
+			addColumnIfNotExists("ALTER TABLE cf_agent_tool_runs ADD COLUMN detached_no_progress_budget_ms INTEGER");
+			addColumnIfNotExists("ALTER TABLE cf_agent_tool_runs ADD COLUMN last_progress_at INTEGER");
+			addColumnIfNotExists("ALTER TABLE cf_agent_tool_runs ADD COLUMN detached_on_milestones TEXT");
 			this.sql`
         INSERT OR REPLACE INTO cf_agents_state (id, state)
         VALUES (${SCHEMA_VERSION_ROW_ID}, ${String(CURRENT_SCHEMA_VERSION)})
@@ -707,6 +735,8 @@ var Agent = class Agent extends Server {
 		this._managedFiberTerminalWaiters = /* @__PURE__ */ new Map();
 		this._runFiberRecoveryInProgress = false;
 		this._recoveryNoProgressScans = 0;
+		this._detachedBackboneArming = Promise.resolve();
+		this._detachedLiveCountWarned = false;
 		this._ParentClass = Object.getPrototypeOf(this).constructor;
 		this.initialState = DEFAULT_STATE;
 		this.observability = genericObservability;
@@ -2641,7 +2671,7 @@ var Agent = class Agent extends Server {
 		return true;
 	}
 	async deleteFibers(options) {
-		const terminalStatuses = [...this._normalizeFiberStatusFilter(options?.status) ?? new Set([
+		const terminalStatuses = [...this._normalizeFiberStatusFilter(options?.status) ?? /* @__PURE__ */ new Set([
 			"completed",
 			"aborted",
 			"error"
@@ -3138,6 +3168,25 @@ var Agent = class Agent extends Server {
 		return (await this._cf_resolveSubAgent(next.className, next.name))._cf_dispatchScheduledCallback(ownerPath, row);
 	}
 	/**
+	* 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
+	*/
+	async _cf_invokeAgentPath(targetPath, method, args) {
+		await this.__unsafe_ensureInitialized();
+		const selfPath = this.selfPath;
+		if (!this._isSameAgentPathPrefix(selfPath, targetPath)) throw new Error(`Workflow origin path does not descend from ${JSON.stringify(selfPath)}.`);
+		if (selfPath.length === targetPath.length) {
+			const fn = this[method];
+			if (isInternalJsStubProp(method) || method in Object.prototype || typeof fn !== "function") throw new Error(`Workflow origin method "${method}" is not callable on ${this.constructor.name}.`);
+			return await fn.apply(this, args);
+		}
+		const next = targetPath[selfPath.length];
+		if (!this.hasSubAgent(next.className, next.name)) throw new Error(`Workflow origin sub-agent ${next.className} "${next.name}" no longer exists.`);
+		return await (await this._cf_resolveSubAgent(next.className, next.name))._cf_invokeAgentPath(targetPath, method, args);
+	}
+	/**
 	* Recursively destroy a descendant facet identified by
 	* `targetPath`. Walks down from `selfPath` until reaching the
 	* target's immediate parent, where it cancels the target's
@@ -4075,11 +4124,40 @@ var Agent = class Agent extends Server {
 	}
 	async onAgentToolStart(_run) {}
 	async onAgentToolFinish(_run, _result) {}
+	/**
+	* 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.
+	*/
+	async onProgress(_run, _progress) {}
+	/**
+	* 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`.
+	*/
+	async reportProgress(_progress, _options) {
+		console.warn("[agents] reportProgress() is only supported on chat agents (@cloudflare/think, AIChatAgent) running as an agent tool; ignoring on base Agent.");
+	}
 	async runAgentTool(cls, options) {
 		const runId = options.runId ?? nanoid(12);
 		const agentType = cls.name;
+		const detached = this._parseDetachedOption(options.detached);
 		const existing = this._readAgentToolRun(runId);
 		if (existing) {
+			if (detached) {
+				if (!this._isAgentToolRowHardTerminal(existing.status)) await this._armDetachedBackbone();
+				return {
+					runId,
+					agentType,
+					status: "running"
+				};
+			}
 			if (existing.status === "completed" || existing.status === "error" || existing.status === "aborted") {
 				if (existing.status === "completed" && existing.output_json == null) try {
 					const child = await this.subAgent(cls, runId);
@@ -4151,14 +4229,22 @@ var Agent = class Agent extends Server {
 				error
 			};
 		}
+		const detachedMaxBudgetAt = detached ? startedAt + (detached.maxBudgetMs ?? this._resolvedOptions.detachedMaxBudgetMs) : null;
+		const detachedNoProgressBudgetMs = detached ? detached.noProgressBudgetMs ?? this._resolvedOptions.detachedNoProgressBudgetMs : null;
+		const detachedOnMilestonesJson = detached?.onMilestones ? JSON.stringify(detached.onMilestones) : null;
 		this.sql`
       INSERT INTO cf_agent_tool_runs (
         run_id, parent_tool_call_id, agent_type, input_preview,
-        input_redacted, status, display_metadata, display_order, started_at
+        input_redacted, status, display_metadata, display_order, started_at,
+        detached, detached_on_finish, detached_notify_source,
+        detached_max_budget_at, detached_no_progress_budget_ms,
+        detached_on_milestones
       ) VALUES (
         ${runId}, ${options.parentToolCallId ?? null}, ${agentType},
         ${inputPreviewJson}, 1, 'starting', ${displayJson}, ${displayOrder},
-        ${startedAt}
+        ${startedAt}, ${detached ? 1 : 0}, ${detached?.onFinishName ?? null},
+        ${detached?.notifySource ?? null}, ${detachedMaxBudgetAt},
+        ${detachedNoProgressBudgetMs}, ${detachedOnMilestonesJson}
       )
     `;
 		const runInfo = {
@@ -4168,6 +4254,7 @@ var Agent = class Agent extends Server {
 			inputPreview,
 			status: "starting",
 			display: options.display,
+			...detached?.notifySource !== void 0 ? { notifySource: detached.notifySource } : {},
 			displayOrder,
 			startedAt
 		};
@@ -4184,6 +4271,17 @@ var Agent = class Agent extends Server {
 		const adapter = this._asAgentToolChildAdapter(child);
 		const childStart = await adapter.startAgentToolRun(options.input, { runId });
 		this._markAgentToolRunning(runId);
+		if (detached) {
+			if (options.signal) console.warn(`[agents] runAgentTool: \`signal\` is ignored for a detached run (${runId}); a detached child must outlive the spawning turn. Use cancelAgentTool(runId) to cancel it.`);
+			await this._armDetachedBackbone({ resetCadence: true });
+			this._maybeWarnDetachedLiveCount();
+			this.ctx.waitUntil(this._detachedFastPath(runInfo, cls, runId));
+			return {
+				runId,
+				agentType,
+				status: "running"
+			};
+		}
 		let sequence = 1;
 		let parentAbortListener;
 		if (options.signal) if (options.signal.aborted) {
@@ -4252,6 +4350,332 @@ var Agent = class Agent extends Server {
 			if (parentAbortListener && options.signal) options.signal.removeEventListener("abort", parentAbortListener);
 		}
 	}
+	/**
+	* 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.
+	*/
+	async cancelAgentTool(runId, reason) {
+		const row = this._readAgentToolRun(runId);
+		if (!row) return;
+		if (this._isAgentToolRowHardTerminal(row.status)) return;
+		const isDetached = row.detached === 1;
+		const message = reason instanceof Error ? reason.message : String(reason ?? "cancelled by parent");
+		try {
+			const child = await this._cf_resolveSubAgent(row.agent_type, runId);
+			await this._asAgentToolChildAdapter(child).cancelAgentToolRun(runId, reason);
+		} catch {}
+		if (!isDetached) return;
+		await this._deliverDetachedTerminal(runId, "finish", {
+			runId,
+			agentType: row.agent_type,
+			status: "aborted",
+			error: message
+		});
+	}
+	/**
+	* 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`).
+	*/
+	_parseDetachedOption(detached) {
+		if (!detached) return null;
+		if (detached === true) return {};
+		let onFinishName = detached.onFinish;
+		const notifySource = typeof detached.notify === "object" ? detached.notify.source : void 0;
+		if (onFinishName !== void 0) {
+			if (typeof this[onFinishName] !== "function") throw new Error(`runAgentTool: detached.onFinish "${onFinishName}" is not a method on ${this.constructor.name}. Pass the NAME of a method (e.g. "onImportDone"), not a closure — closures cannot be rehydrated after the Durable Object is evicted.`);
+		} else if (detached.notify) {
+			if (typeof this[DETACHED_NOTIFY_CALLBACK] === "function") onFinishName = DETACHED_NOTIFY_CALLBACK;
+		}
+		return {
+			...onFinishName !== void 0 ? { onFinishName } : {},
+			...notifySource !== void 0 ? { notifySource } : {},
+			...detached.maxBudgetMs !== void 0 ? { maxBudgetMs: detached.maxBudgetMs } : {},
+			...detached.noProgressBudgetMs !== void 0 ? { noProgressBudgetMs: detached.noProgressBudgetMs } : {},
+			...(() => {
+				const raw = detached.onMilestones;
+				if (!raw) return {};
+				const names = Array.isArray(raw) ? raw : raw.names;
+				if (!Array.isArray(names) || names.length === 0) return {};
+				return { onMilestones: {
+					names,
+					mode: Array.isArray(raw) ? "narrate" : raw.mode ?? "narrate"
+				} };
+			})()
+		};
+	}
+	_isAgentToolRowHardTerminal(status) {
+		return status === "completed" || status === "error" || status === "aborted";
+	}
+	_hasOutstandingDetachedRuns() {
+		return (this.sql`
+      SELECT COUNT(*) AS n FROM cf_agent_tool_runs
+      WHERE detached = 1 AND finish_delivered_at IS NULL
+    `[0]?.n ?? 0) > 0;
+	}
+	/** Detached runs still holding a concurrency slot (non-terminal). */
+	_liveDetachedRunCount() {
+		return this.sql`
+      SELECT COUNT(*) AS n FROM cf_agent_tool_runs
+      WHERE detached = 1 AND status IN ('starting', 'running')
+    `[0]?.n ?? 0;
+	}
+	/**
+	* 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.
+	*/
+	_maybeWarnDetachedLiveCount() {
+		const liveCount = this._liveDetachedRunCount();
+		if (liveCount < DETACHED_LIVE_COUNT_WARN_THRESHOLD) {
+			this._detachedLiveCountWarned = false;
+			return;
+		}
+		if (this._detachedLiveCountWarned) return;
+		this._detachedLiveCountWarned = true;
+		this._emit("agent_tool:detached:live_count_warning", {
+			liveCount,
+			threshold: DETACHED_LIVE_COUNT_WARN_THRESHOLD
+		});
+		console.warn(`[agents] ${liveCount} detached agent-tool runs are live on this agent (threshold ${DETACHED_LIVE_COUNT_WARN_THRESHOLD}). Detached runs hold a concurrency slot until they finish — make sure they are completing or being cancelled, or lower \`maxConcurrentAgentTools\`.`);
+	}
+	/**
+	* 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.
+	*/
+	async _detachedFastPath(runInfo, cls, runId) {
+		try {
+			const child = await this.subAgent(cls, runId);
+			const adapter = this._asAgentToolChildAdapter(child);
+			let sequence = 1;
+			if (adapter.tailAgentToolRun) {
+				const stream = await adapter.tailAgentToolRun(runId, { afterSequence: -1 });
+				sequence = (await this._forwardAgentToolStream(stream, runInfo.parentToolCallId, runId, sequence, void 0)).next;
+			}
+			const inspection = await adapter.inspectAgentToolRun(runId);
+			if (inspection && this._isAgentToolRowHardTerminal(inspection.status)) {
+				const result = this._terminalResultFromInspection(runInfo.agentType, inspection);
+				await this._deliverDetachedTerminal(runId, "finish", result, {
+					sequence,
+					serialize: true
+				}, inspection.completedAt);
+			}
+		} catch {}
+	}
+	/**
+	* 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).
+	*/
+	async _deliverDetachedTerminal(runId, kind, result, options, completedAt = Date.now()) {
+		const now = Date.now();
+		const leaseFloor = now - DETACHED_DELIVERY_LEASE_MS;
+		const claimQuery = kind === "finish" ? `UPDATE cf_agent_tool_runs
+             SET finish_claimed_at = ?
+             WHERE run_id = ?
+               AND finish_delivered_at IS NULL
+               AND (finish_claimed_at IS NULL OR finish_claimed_at < ?)` : `UPDATE cf_agent_tool_runs
+             SET give_up_claimed_at = ?
+             WHERE run_id = ?
+               AND give_up_delivered_at IS NULL
+               AND (give_up_claimed_at IS NULL OR give_up_claimed_at < ?)`;
+		if (this.ctx.storage.sql.exec(claimQuery, now, runId, leaseFloor).rowsWritten === 0) return;
+		const row = this._readAgentToolRun(runId);
+		if (!row) return;
+		this._updateAgentToolTerminal(runId, result, completedAt);
+		this._broadcastAgentToolTerminal(row.parent_tool_call_id ?? void 0, options?.sequence ?? Date.now(), result);
+		const runInfo = this._agentToolRunInfoFromRow(row, result.status, completedAt);
+		const lifecycle = {
+			status: result.status,
+			...result.summary !== void 0 ? { summary: result.summary } : {},
+			...result.error !== void 0 ? { error: result.error } : {},
+			...result.reason !== void 0 ? { reason: result.reason } : {},
+			...result.childStillRunning !== void 0 ? { childStillRunning: result.childStillRunning } : {}
+		};
+		const invoke = async () => {
+			try {
+				await this.onAgentToolFinish(runInfo, lifecycle);
+			} catch (error) {
+				await this._safeRunOnError(error);
+			}
+			const callbackName = row.detached_on_finish;
+			if (callbackName) {
+				const callback = this[callbackName];
+				if (typeof callback === "function") try {
+					await callback.bind(this)(runInfo, lifecycle);
+				} catch (error) {
+					this._emit("agent_tool:detached:delivery_failed", {
+						runId,
+						kind,
+						status: result.status,
+						callback: callbackName,
+						error: error instanceof Error ? error.message : String(error)
+					});
+					await this._safeRunOnError(error);
+					throw error;
+				}
+			}
+		};
+		await this._runDetachedDelivery(invoke, { serialize: options?.serialize });
+		if (kind === "finish") this.sql`
+        UPDATE cf_agent_tool_runs
+        SET finish_delivered_at = ${Date.now()}
+        WHERE run_id = ${runId}
+      `;
+		else this.sql`
+        UPDATE cf_agent_tool_runs
+        SET give_up_delivered_at = ${Date.now()}
+        WHERE run_id = ${runId}
+      `;
+	}
+	async _safeRunOnError(error) {
+		try {
+			await this.onError(error);
+		} catch {}
+	}
+	/**
+	* 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.
+	*/
+	async _runDetachedDelivery(invoke, _options) {
+		if (__DO_NOT_USE_WILL_BREAK__agentContext.getStore()?.agent) {
+			await invoke();
+			return;
+		}
+		await __DO_NOT_USE_WILL_BREAK__agentContext.run({
+			agent: this,
+			connection: void 0,
+			request: void 0,
+			email: void 0
+		}, invoke);
+	}
+	/**
+	* 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.
+	*/
+	async _armDetachedBackbone(options) {
+		const run = this._detachedBackboneArming.then(() => this._armDetachedBackboneInner(options));
+		this._detachedBackboneArming = run.then(() => void 0, () => void 0);
+		return run;
+	}
+	async _armDetachedBackboneInner(options) {
+		const armed = (await this.listSchedules()).filter((schedule) => schedule.callback === DETACHED_RECONCILE_CALLBACK);
+		if (armed.length > 0 && !options?.resetCadence) {
+			for (const schedule of armed.slice(1)) await this.cancelSchedule(schedule.id);
+			return;
+		}
+		for (const schedule of armed) await this.cancelSchedule(schedule.id);
+		await this.schedule(DETACHED_BACKBONE_CADENCE_S[0], DETACHED_RECONCILE_CALLBACK, { cadenceIndex: 0 });
+	}
+	/**
+	* 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).
+	*/
+	async _cfDetachedReconcileTick(payload) {
+		const rows = this.sql`
+      SELECT run_id, parent_tool_call_id, agent_type, input_preview, status,
+             summary, output_json, error_message, interrupted_reason,
+             child_still_running, display_metadata, display_order,
+             started_at, completed_at, detached, detached_on_finish,
+             detached_notify_source, detached_max_budget_at,
+             detached_no_progress_budget_ms, last_progress_at,
+             detached_on_milestones,
+             finish_claimed_at, finish_delivered_at, give_up_claimed_at,
+             give_up_delivered_at
+      FROM cf_agent_tool_runs
+      WHERE detached = 1 AND finish_delivered_at IS NULL
+      ORDER BY started_at ASC
+    `;
+		for (const row of rows) {
+			const runId = row.run_id;
+			let inspection = null;
+			try {
+				const child = await this._cf_resolveSubAgent(row.agent_type, runId);
+				inspection = await this._asAgentToolChildAdapter(child).inspectAgentToolRun(runId);
+			} catch {}
+			if (inspection?.milestones && row.detached_on_milestones) {
+				const milestoneRunInfo = this._agentToolRunInfoFromRow(row);
+				for (const milestone of inspection.milestones) this._maybeDeliverDetachedMilestone(row, milestoneRunInfo, milestone);
+			}
+			if (inspection && this._isAgentToolRowHardTerminal(inspection.status)) {
+				const result = this._terminalResultFromInspection(row.agent_type, inspection);
+				await this._deliverDetachedTerminal(runId, "finish", result, {
+					sequence: Date.now(),
+					serialize: true
+				}, inspection.completedAt);
+				continue;
+			}
+			const now = Date.now();
+			const budgetAt = row.detached_max_budget_at;
+			const latestMilestone = inspection?.milestones?.length ? inspection.milestones[inspection.milestones.length - 1].at : void 0;
+			const signalTimes = [
+				inspection?.progress?.at,
+				latestMilestone,
+				row.last_progress_at
+			].filter((t) => typeof t === "number");
+			const lastSignalAt = signalTimes.length > 0 ? Math.max(...signalTimes) : void 0;
+			const noProgressBudgetMs = row.detached_no_progress_budget_ms;
+			const overAbsolute = budgetAt !== null && now >= budgetAt;
+			const overNoProgress = typeof noProgressBudgetMs === "number" && noProgressBudgetMs > 0 && Number.isFinite(noProgressBudgetMs) && typeof lastSignalAt === "number" && now - lastSignalAt >= noProgressBudgetMs;
+			if ((overAbsolute || overNoProgress) && row.give_up_delivered_at === null) {
+				let childTornDown = false;
+				try {
+					const child = await this._cf_resolveSubAgent(row.agent_type, runId);
+					await this._asAgentToolChildAdapter(child).cancelAgentToolRun(runId, overAbsolute ? "detached budget exceeded" : "detached run went silent past its no-progress window");
+					childTornDown = true;
+				} catch {}
+				await this._deliverDetachedTerminal(runId, "give_up", {
+					runId,
+					agentType: row.agent_type,
+					status: "interrupted",
+					error: overAbsolute ? "detached run exceeded its budget before completing" : "detached run went silent past its no-progress window",
+					reason: overAbsolute ? "budget-exceeded" : "no-progress",
+					childStillRunning: !childTornDown
+				}, { serialize: true });
+			}
+		}
+		if (this._hasOutstandingDetachedRuns()) {
+			const currentIndex = typeof payload?.cadenceIndex === "number" ? payload.cadenceIndex : 0;
+			const nextIndex = Math.min(currentIndex + 1, DETACHED_BACKBONE_CADENCE_S.length - 1);
+			await this.schedule(DETACHED_BACKBONE_CADENCE_S[nextIndex], DETACHED_RECONCILE_CALLBACK, { cadenceIndex: nextIndex });
+		}
+	}
 	hasAgentToolRun(classOrName, runId) {
 		const agentType = typeof classOrName === "string" ? classOrName : classOrName.name;
 		return (this.sql`
@@ -4311,7 +4735,10 @@ var Agent = class Agent extends Server {
       SELECT run_id, parent_tool_call_id, agent_type, input_preview, status,
              summary, output_json, error_message, interrupted_reason,
              child_still_running, display_metadata, display_order,
-             started_at, completed_at
+             started_at, completed_at, detached, detached_on_finish,
+             detached_notify_source, detached_max_budget_at,
+             finish_claimed_at, finish_delivered_at, give_up_claimed_at,
+             give_up_delivered_at
       FROM cf_agent_tool_runs
       WHERE run_id = ${runId}
       LIMIT 1
@@ -4351,6 +4778,7 @@ var Agent = class Agent extends Server {
 			inputPreview: this._parseAgentToolJson(row.input_preview),
 			status,
 			display: this._parseAgentToolJson(row.display_metadata),
+			...row.detached_notify_source != null ? { notifySource: row.detached_notify_source } : {},
 			displayOrder: row.display_order,
 			startedAt: row.started_at,
 			completedAt
@@ -4509,6 +4937,7 @@ var Agent = class Agent extends Server {
 					runId,
 					body: chunk.body
 				});
+				this._observeForwardedProgress(runId, chunk.body);
 				forwardedSinceProgress = true;
 				armIdle();
 			};
@@ -4598,6 +5027,76 @@ var Agent = class Agent extends Server {
 	* called repeatedly while a child streams.
 	*/
 	async _onAgentToolStreamProgress() {}
+	/**
+	* 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.
+	*/
+	_observeForwardedProgress(runId, body) {
+		let parsed;
+		try {
+			parsed = JSON.parse(body);
+		} catch {
+			return;
+		}
+		if (!parsed) return;
+		const isMilestone = parsed.type === AGENT_TOOL_MILESTONE_PART;
+		if (parsed.type !== "data-agent-progress" && !isMilestone) return;
+		const data = parsed.data ?? {};
+		const at = Date.now();
+		const snapshot = {
+			...typeof data.fraction === "number" ? { fraction: data.fraction } : {},
+			...typeof data.message === "string" ? { message: data.message } : {},
+			...typeof data.phase === "string" ? { phase: data.phase } : {},
+			...isMilestone && typeof data.name === "string" ? { milestone: data.name } : {},
+			...data.data !== void 0 ? { data: data.data } : {},
+			at
+		};
+		const row = this._readAgentToolRun(runId);
+		if (!row) return;
+		if (row.detached) try {
+			this.sql`
+          UPDATE cf_agent_tool_runs SET last_progress_at = ${at}
+          WHERE run_id = ${runId}
+        `;
+		} catch {}
+		const runInfo = this._agentToolRunInfoFromRow(row);
+		Promise.resolve(this.onProgress(runInfo, snapshot)).catch((error) => {
+			console.error(`[agents] onProgress hook threw for run ${runId}:`, error instanceof Error ? error.message : String(error));
+		});
+		if (isMilestone && typeof data.name === "string") this._maybeDeliverDetachedMilestone(row, runInfo, {
+			name: data.name,
+			sequence: typeof data.sequence === "number" ? data.sequence : 0,
+			at: typeof data.at === "number" ? data.at : at,
+			...data.data !== void 0 ? { data: data.data } : {}
+		});
+	}
+	/**
+	* 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).
+	*/
+	_maybeDeliverDetachedMilestone(row, runInfo, milestone) {
+		const configured = this._parseAgentToolJson(row.detached_on_milestones ?? null);
+		const names = Array.isArray(configured) ? configured : configured?.names;
+		const mode = Array.isArray(configured) ? "narrate" : configured?.mode ?? "narrate";
+		if (!Array.isArray(names) || !names.includes(milestone.name)) return;
+		Promise.resolve(this._deliverDetachedMilestone(runInfo, milestone, mode)).catch((error) => {
+			console.error(`[agents] detached milestone delivery threw for run ${runInfo.runId} (${milestone.name}):`, error instanceof Error ? error.message : String(error));
+		});
+	}
+	/**
+	* 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.
+	*/
+	async _deliverDetachedMilestone(_run, _milestone, _mode) {}
 	_broadcastAgentToolTerminal(parentToolCallId, sequence, result, replay, connection) {
 		if (result.status === "completed") this._broadcastAgentToolEvent(parentToolCallId, sequence, {
 			kind: "finished",
@@ -4828,7 +5327,7 @@ var Agent = class Agent extends Server {
              child_still_running, display_metadata, display_order,
              started_at, completed_at
       FROM cf_agent_tool_runs
-      WHERE status IN ('starting', 'running')
+      WHERE status IN ('starting', 'running') AND detached = 0
       ORDER BY started_at ASC
     `;
 		const runIds = options?.runIds !== void 0 ? new Set(options.runIds) : void 0;
@@ -4967,6 +5466,7 @@ var Agent = class Agent extends Server {
 				runIds: options?.runIds
 			});
 			await this._runDeferredAgentToolFinishHooks(recoveredAgentToolFinishes);
+			if (this._hasOutstandingDetachedRuns()) await this._armDetachedBackbone();
 		})().catch(async (error) => {
 			this._emit("agent_tool:recovery:failed", { error: error instanceof Error ? error.message : String(error) });
 			try {
@@ -5305,10 +5805,29 @@ var Agent = class Agent extends Server {
 	* 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
@@ -5322,14 +5841,15 @@ var Agent = class Agent extends Server {
 	async runWorkflow(workflowName, params, options) {
 		const workflow = this._findWorkflowBindingByName(workflowName);
 		if (!workflow) throw new Error(`Workflow binding '${workflowName}' not found in environment`);
-		const agentBindingName = options?.agentBinding ?? this._findAgentBindingName();
-		if (!agentBindingName) throw new Error("Could not detect Agent binding name from class name. Pass it explicitly via options.agentBinding");
+		const agentOrigin = this._workflowOrigin(options);
+		if (!agentOrigin) throw new Error("Could not detect Agent binding name from class name. Pass it explicitly via options.agentBinding");
 		const workflowId = options?.id ?? `wf_${nanoid()}`;
 		const augmentedParams = {
 			...params,
 			__agentName: this.name,
-			__agentBinding: agentBindingName,
-			__workflowName: workflowName
+			__agentBinding: agentOrigin.kind === "agent" ? agentOrigin.binding : agentOrigin.rootBinding,
+			__workflowName: workflowName,
+			__agentOrigin: agentOrigin
 		};
 		const instance = await workflow.create({
 			id: workflowId,
@@ -5871,12 +6391,28 @@ var Agent = class Agent extends Server {
 			completedAt: row.completed_at ? /* @__PURE__ */ new Date(row.completed_at * 1e3) : null
 		};
 	}
-	/**
-	* Find the binding name for this Agent's namespace by matching class name.
-	* Returns undefined if no match found - use options.agentBinding as fallback.
-	*/
-	_findAgentBindingName() {
-		const className = this._ParentClass.name;
+	_workflowOrigin(options) {
+		if (this._isFacet) {
+			const root = this._parentPath[0];
+			const rootBindingName = options?.agentBinding ?? (root ? this._findAgentBindingNameForClass(root.className) : void 0);
+			if (!rootBindingName) return void 0;
+			return {
+				kind: "facet",
+				version: 1,
+				rootBinding: rootBindingName,
+				path: this.selfPath.map((step) => ({ ...step }))
+			};
+		}
+		const agentBindingName = options?.agentBinding ?? this._findAgentBindingNameForClass(this._ParentClass.name);
+		if (!agentBindingName) return void 0;
+		return {
+			kind: "agent",
+			version: 1,
+			binding: agentBindingName,
+			name: this.name
+		};
+	}
+	_findAgentBindingNameForClass(className) {
 		for (const [key, value] of Object.entries(this.env)) if (value && typeof value === "object" && "idFromName" in value && typeof value.idFromName === "function") {
 			if (key === className || camelCaseToKebabCase(key) === camelCaseToKebabCase(className)) return key;
 		}
@@ -5914,7 +6450,9 @@ var Agent = class Agent extends Server {
 	}
 	/**
 	* 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
@@ -6448,6 +6986,6 @@ var StreamingResponse = class {
 	}
 };
 //#endregion
-export { Agent, DEFAULT_AGENT_STATIC_OPTIONS, DurableObjectOAuthClientProvider, MCP_SERVER_ID_MAX_LENGTH, MessageType, SUB_PREFIX, SqlError, StreamingResponse, __DO_NOT_USE_WILL_BREAK__agentContext, callable, camelCaseToKebabCase, createHeaderBasedEmailResolver, getAgentByName, getCurrentAgent, getSubAgentByName, isDurableObjectCodeUpdateReset, isPlatformTransientError, normalizeServerId, parseSubAgentPath, routeAgentEmail, routeAgentRequest, routeSubAgentRequest, unstable_callable };
+export { AGENT_TOOL_MILESTONE_PART, AGENT_TOOL_PROGRESS_PART, Agent, DEFAULT_AGENT_STATIC_OPTIONS, DurableObjectOAuthClientProvider, MCP_SERVER_ID_MAX_LENGTH, MessageType, SUB_PREFIX, SqlError, StreamingResponse, __DO_NOT_USE_WILL_BREAK__agentContext, callable, camelCaseToKebabCase, createHeaderBasedEmailResolver, getAgentByName, getCurrentAgent, getSubAgentByName, isDurableObjectCodeUpdateReset, isPlatformTransientError, normalizeServerId, parseSubAgentPath, routeAgentEmail, routeAgentRequest, routeSubAgentRequest, unstable_callable };
 
 //# sourceMappingURL=index.js.map