agents 0.14.1 → 0.14.3

package/dist/index.js

@@ -2,7 +2,7 @@ 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-D_obpP6O.js";
+import { i as _classPrivateFieldInitSpec, n as _classPrivateFieldSet2, t as _classPrivateFieldGet2 } from "./classPrivateFieldGet2-Beqsfu2Z.js";
 import { SUB_PREFIX, getSubAgentByName, parseSubAgentPath, routeSubAgentRequest } from "./sub-routing.js";
 import { isErrorRetryable, 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-FUizKzj2.js";
@@ -116,7 +116,8 @@ function getNextCronTime(cron) {
 const DEFAULT_KEEP_ALIVE_INTERVAL_MS = 3e4;
 const DEFAULT_AGENT_TOOL_RECOVERY_TIMEOUT_MS = 2e3;
 const DEFAULT_AGENT_TOOL_RECOVERY_TOTAL_TIMEOUT_MS = 5e3;
-const DEFAULT_AGENT_TOOL_REATTACH_TIMEOUT_MS = 12e4;
+const DEFAULT_AGENT_TOOL_REATTACH_NO_PROGRESS_TIMEOUT_MS = 12e4;
+const DEFAULT_AGENT_TOOL_REATTACH_MAX_WINDOW_MS = Number.POSITIVE_INFINITY;
 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:";
@@ -126,7 +127,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 = 8;
+const CURRENT_SCHEMA_VERSION = 9;
 const SCHEMA_VERSION_ROW_ID = "cf_schema_version";
 const STATE_ROW_ID = "cf_state_row_id";
 const STATE_WAS_CHANGED = "cf_state_was_changed";
@@ -275,7 +276,27 @@ const DEFAULT_AGENT_STATIC_OPTIONS = {
 	* up. Bounds repeated retries of a `onFiberRecovered()` hook that keeps
 	* throwing so a poison row cannot re-trigger forever across boots.
 	*/
-	fiberRecoveryMaxAgeMs: 1440 * 60 * 1e3
+	fiberRecoveryMaxAgeMs: 1440 * 60 * 1e3,
+	/**
+	* No-progress budget (ms) for re-attaching to a still-running agent-tool
+	* child after a deploy / parent recovery (#1630). Bounds how long the parent
+	* waits with NO forward progress from the child; it resets on every forwarded
+	* chunk, so a child that keeps streaming is never abandoned mid-flight. Only a
+	* genuinely silent/hung child seals `interrupted` after a full window. Raise
+	* for children with long quiet stretches between outputs.
+	*/
+	agentToolReattachNoProgressTimeoutMs: DEFAULT_AGENT_TOOL_REATTACH_NO_PROGRESS_TIMEOUT_MS,
+	/**
+	* Optional hard wall-clock ceiling (ms) on a single agent-tool re-attach
+	* (#1630). Caps the total wait even as the no-progress budget re-arms across
+	* stream-closes. Defaults to `Infinity` (no implicit cap), mirroring
+	* chat-recovery's `maxRecoveryWork` (#1672): a healthy, still-advancing child
+	* is followed for as long as it makes progress — a hung child is bounded by
+	* the no-progress budget, and a content-runaway by the child's own
+	* `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
 };
 /**
 * Parse the raw `retry_options` TEXT column from a SQLite row into a
@@ -428,7 +449,9 @@ var Agent = class Agent extends Server {
 			},
 			fiberRecoveryHookTimeoutMs: ctor.options?.fiberRecoveryHookTimeoutMs ?? DEFAULT_AGENT_STATIC_OPTIONS.fiberRecoveryHookTimeoutMs,
 			fiberRecoveryScanDeadlineMs: ctor.options?.fiberRecoveryScanDeadlineMs ?? DEFAULT_AGENT_STATIC_OPTIONS.fiberRecoveryScanDeadlineMs,
-			fiberRecoveryMaxAgeMs: ctor.options?.fiberRecoveryMaxAgeMs ?? DEFAULT_AGENT_STATIC_OPTIONS.fiberRecoveryMaxAgeMs
+			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
 		};
 		return this._cachedOptions;
 	}
@@ -655,6 +678,8 @@ var Agent = class Agent extends Server {
           summary TEXT,
           output_json TEXT,
           error_message TEXT,
+          interrupted_reason TEXT,
+          child_still_running INTEGER,
           display_metadata TEXT,
           display_order INTEGER NOT NULL DEFAULT 0,
           started_at INTEGER NOT NULL,
@@ -666,6 +691,8 @@ var Agent = class Agent extends Server {
         ON cf_agent_tool_runs(parent_tool_call_id, display_order)
       `;
 			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");
 			this.sql`
         INSERT OR REPLACE INTO cf_agents_state (id, state)
         VALUES (${SCHEMA_VERSION_ROW_ID}, ${String(CURRENT_SCHEMA_VERSION)})
@@ -680,12 +707,12 @@ var Agent = class Agent extends Server {
 		this._rawStateAccessors = /* @__PURE__ */ new WeakMap();
 		this._persistenceHookMode = "none";
 		this._isFacet = false;
-		this._suppressProtocolBroadcasts = false;
 		this._protocolBroadcastExcludeIds = /* @__PURE__ */ new Set();
 		this._cf_virtualSubAgentConnections = /* @__PURE__ */ new Map();
 		this._parentPath = [];
 		this._insideOnStart = false;
 		this._warnedScheduleInOnStart = /* @__PURE__ */ new Set();
+		this._warnedChatRecoveryInOnStart = false;
 		this._keepAliveRefs = 0;
 		this._facetKeepAliveTokens = /* @__PURE__ */ new Set();
 		this._runFiberActiveFibers = /* @__PURE__ */ new Set();
@@ -932,6 +959,7 @@ var Agent = class Agent extends Server {
 					this._checkOrphanedWorkflows();
 					await this._checkRunFibers();
 					const startupAgentToolRunIds = this._agentToolRunRecoveryRunIds();
+					const chatRecoveryBefore = this.chatRecovery;
 					this._insideOnStart = true;
 					this._warnedScheduleInOnStart.clear();
 					let result;
@@ -940,6 +968,12 @@ var Agent = class Agent extends Server {
 					} finally {
 						this._insideOnStart = false;
 					}
+					const chatRecoveryAfter = this.chatRecovery;
+					const chatRecoveryAfterMatters = typeof chatRecoveryAfter === "object" && chatRecoveryAfter !== null || chatRecoveryAfter === true;
+					if (!this._warnedChatRecoveryInOnStart && chatRecoveryBefore !== chatRecoveryAfter && chatRecoveryAfterMatters) {
+						this._warnedChatRecoveryInOnStart = true;
+						console.warn("[Agent] `chatRecovery` was assigned during onStart(). Chat recovery evaluates its budgets (and may seal an interrupted turn, firing onExhausted) on wake BEFORE onStart() runs, so a config set here is applied too late and the built-in defaults are used for the recovery that matters. Assign `chatRecovery` as a class field or in the constructor instead.");
+					}
 					this._scheduleAgentToolRunRecovery({ runIds: startupAgentToolRunIds });
 					return result;
 				});
@@ -976,7 +1010,6 @@ var Agent = class Agent extends Server {
 	* @param excludeIds Additional connection IDs to exclude (e.g. the source)
 	*/
 	_broadcastProtocol(msg, excludeIds = []) {
-		if (this._suppressProtocolBroadcasts) return;
 		const exclude = [...excludeIds, ...this._protocolBroadcastExcludeIds];
 		for (const conn of this.getConnections()) if (!this.isConnectionProtocolEnabled(conn)) exclude.push(conn.id);
 		this.broadcast(msg, exclude);
@@ -3387,6 +3420,7 @@ var Agent = class Agent extends Server {
 		if (this._isFacet) {
 			const stored = this._cf_virtualSubAgentConnections.get(id);
 			if (stored) return this._cf_createSubAgentBridgeConnection(stored.bridge, stored.meta);
+			return;
 		}
 		const connection = super.getConnection(id);
 		if (!connection || this._cf_connectionHasSubAgentTarget(connection)) return;
@@ -3395,6 +3429,7 @@ var Agent = class Agent extends Server {
 	*getConnections(tag) {
 		if (this._isFacet) {
 			for (const stored of this._cf_virtualSubAgentConnections.values()) if (!tag || stored.meta.tags.includes(tag)) yield this._cf_createSubAgentBridgeConnection(stored.bridge, stored.meta);
+			return;
 		}
 		for (const connection of super.getConnections(tag)) {
 			if (this._cf_connectionHasSubAgentTarget(connection)) continue;
@@ -3847,12 +3882,7 @@ var Agent = class Agent extends Server {
 			this.ctx.storage.put("cf_agents_facet_name", name),
 			this.ctx.storage.put("cf_agents_parent_path", parentPath)
 		]);
-		this._suppressProtocolBroadcasts = true;
-		try {
-			await this.__unsafe_ensureInitialized();
-		} finally {
-			this._suppressProtocolBroadcasts = false;
-		}
+		await this.__unsafe_ensureInitialized();
 	}
 	get name() {
 		return this._facetName ?? logicalNameFromPathV2Identity(super.name) ?? super.name;
@@ -4022,10 +4052,12 @@ var Agent = class Agent extends Server {
 				} catch {}
 				return this._resultFromAgentToolRow(existing);
 			}
+			let reattachReason;
+			let childTornDown = false;
 			try {
 				const child = await this.subAgent(cls, runId);
 				const adapter = this._asAgentToolChildAdapter(child);
-				const reattach = await this._reattachAgentToolRunToTerminal(adapter, existing, 1);
+				const reattach = await this._reattachAgentToolRunToTerminal(adapter, existing, 1, this._resolvedOptions.agentToolReattachNoProgressTimeoutMs, this._resolvedOptions.agentToolReattachMaxWindowMs);
 				if (reattach.result) {
 					await this._finishAgentToolRun(this._agentToolRunInfoFromRow(existing), reattach.result, {
 						sequence: reattach.sequence,
@@ -4033,8 +4065,13 @@ var Agent = class Agent extends Server {
 					});
 					return reattach.result;
 				}
+				reattachReason = reattach.reason;
+				childTornDown = await this._teardownGivenUpAgentToolChild(adapter, runId, reattach.reason);
 			} catch {}
-			return await this._replayAndInterruptAgentToolRun(existing, "Agent tool run was still running and could not be re-attached to a terminal result within the recovery budget.");
+			return await this._replayAndInterruptAgentToolRun(existing, this._interruptedMessageForReason(reattachReason), {
+				reason: reattachReason,
+				childStillRunning: !childTornDown
+			});
 		}
 		const displayOrder = options.displayOrder ?? 0;
 		const inputPreview = options.inputPreview ?? this._defaultAgentToolPreview(options.input);
@@ -4128,7 +4165,7 @@ var Agent = class Agent extends Server {
 		try {
 			if (adapter.tailAgentToolRun) {
 				const stream = await adapter.tailAgentToolRun(runId, { afterSequence: -1 });
-				sequence = await this._forwardAgentToolStream(stream, options.parentToolCallId, runId, sequence, options.signal);
+				sequence = (await this._forwardAgentToolStream(stream, options.parentToolCallId, runId, sequence, options.signal)).next;
 			} else {
 				const chunks = await adapter.getAgentToolChunks(runId);
 				sequence = this._broadcastAgentToolChunks(options.parentToolCallId, runId, chunks, sequence);
@@ -4232,13 +4269,28 @@ var Agent = class Agent extends Server {
 	_readAgentToolRun(runId) {
 		return this.sql`
       SELECT run_id, parent_tool_call_id, agent_type, input_preview, status,
-             summary, output_json, error_message, display_metadata, display_order,
+             summary, output_json, error_message, interrupted_reason,
+             child_still_running, display_metadata, display_order,
              started_at, completed_at
       FROM cf_agent_tool_runs
       WHERE run_id = ${runId}
       LIMIT 1
     `[0] ?? null;
 	}
+	/**
+	* Reconstruct the typed interrupted cause (`reason` / `childStillRunning`,
+	* #1630 follow-up) from a stored row so a row→result/event rebuild — e.g. a
+	* reconnect replay — carries the same fields a live client saw. Only
+	* `interrupted` rows store a cause; everything else yields `{}` (the columns
+	* are cleared whenever a row settles to a hard terminal).
+	*/
+	_agentToolInterruptedExtrasFromRow(row) {
+		if (row.status !== "interrupted") return {};
+		return {
+			...row.interrupted_reason !== null ? { reason: row.interrupted_reason } : {},
+			...row.child_still_running !== null ? { childStillRunning: row.child_still_running !== 0 } : {}
+		};
+	}
 	_resultFromAgentToolRow(row) {
 		const output = this._parseAgentToolJson(row.output_json);
 		return {
@@ -4247,7 +4299,8 @@ var Agent = class Agent extends Server {
 			status: row.status,
 			...output !== void 0 ? { output } : {},
 			...row.summary !== null ? { summary: row.summary } : {},
-			...row.error_message !== null ? { error: row.error_message } : {}
+			...row.error_message !== null ? { error: row.error_message } : {},
+			...this._agentToolInterruptedExtrasFromRow(row)
 		};
 	}
 	_agentToolRunInfoFromRow(row, status = row.status, completedAt = row.completed_at ?? void 0) {
@@ -4306,12 +4359,15 @@ var Agent = class Agent extends Server {
 		}
 	}
 	_updateAgentToolTerminal(runId, result, completedAt = Date.now()) {
+		const childStillRunning = result.childStillRunning === void 0 ? null : result.childStillRunning ? 1 : 0;
 		this.sql`
       UPDATE cf_agent_tool_runs
       SET status = ${result.status},
           summary = ${result.summary ?? null},
           output_json = ${this._stringifyAgentToolOutput(result.output)},
           error_message = ${result.error ?? null},
+          interrupted_reason = ${result.reason ?? null},
+          child_still_running = ${childStillRunning},
           completed_at = ${completedAt}
       WHERE run_id = ${runId}
         AND status NOT IN ('completed', 'error', 'aborted')
@@ -4374,9 +4430,13 @@ var Agent = class Agent extends Server {
 		if (!chunks) return sequence;
 		return this._broadcastAgentToolChunks(row.parent_tool_call_id ?? void 0, row.run_id, chunks, sequence, replay, connection);
 	}
-	async _forwardAgentToolStream(stream, parentToolCallId, runId, sequence, signal) {
+	async _forwardAgentToolStream(stream, parentToolCallId, runId, sequence, signal, idleTimeoutMs) {
 		let next = sequence;
-		if (signal?.aborted) return next;
+		if (signal?.aborted) return {
+			next,
+			ended: "aborted"
+		};
+		let ended = "done";
 		const reader = stream.getReader();
 		const decoder = new TextDecoder();
 		let bufferedBytes = "";
@@ -4390,6 +4450,17 @@ var Agent = class Agent extends Server {
 			abortListener = () => resolveAbort?.();
 			signal.addEventListener("abort", abortListener, { once: true });
 		}
+		const idleEnabled = typeof idleTimeoutMs === "number" && idleTimeoutMs > 0 && Number.isFinite(idleTimeoutMs);
+		let resolveIdle;
+		let idleTimer;
+		const idlePromise = new Promise((resolve) => {
+			resolveIdle = resolve;
+		});
+		const armIdle = () => {
+			if (!idleEnabled) return;
+			if (idleTimer !== void 0) clearTimeout(idleTimer);
+			idleTimer = setTimeout(() => resolveIdle?.(), idleTimeoutMs);
+		};
 		let forwardedSinceProgress = false;
 		try {
 			const forwardChunk = (chunk) => {
@@ -4399,6 +4470,7 @@ var Agent = class Agent extends Server {
 					body: chunk.body
 				});
 				forwardedSinceProgress = true;
+				armIdle();
 			};
 			const forwardLine = (line) => {
 				try {
@@ -4419,15 +4491,21 @@ var Agent = class Agent extends Server {
 					bufferedBytes = "";
 				}
 			};
+			armIdle();
 			while (true) {
 				const readPromise = reader.read();
 				readPromise.catch(() => {});
-				const raced = await Promise.race([readPromise.then((result) => ({
-					kind: "read",
-					result
-				})), abortPromise.then(() => ({ kind: "abort" }))]);
-				if (raced.kind === "abort") {
+				const raced = await Promise.race([
+					readPromise.then((result) => ({
+						kind: "read",
+						result
+					})),
+					abortPromise.then(() => ({ kind: "abort" })),
+					idlePromise.then(() => ({ kind: "idle" }))
+				]);
+				if (raced.kind === "abort" || raced.kind === "idle") {
 					aborted = true;
+					ended = raced.kind === "idle" ? "idle" : "aborted";
 					break;
 				}
 				const { done, value } = raced.result;
@@ -4448,12 +4526,16 @@ var Agent = class Agent extends Server {
 				}
 			}
 		} finally {
+			if (idleTimer !== void 0) clearTimeout(idleTimer);
 			if (abortListener && signal) signal.removeEventListener("abort", abortListener);
 			if (!aborted) try {
 				reader.releaseLock();
 			} catch {}
 		}
-		return next;
+		return {
+			next,
+			ended
+		};
 	}
 	/**
 	* Hook invoked by `_forwardAgentToolStream` after a child produces output that
@@ -4490,7 +4572,9 @@ var Agent = class Agent extends Server {
 		else if (result.status === "interrupted") this._broadcastAgentToolEvent(parentToolCallId, sequence, {
 			kind: "interrupted",
 			runId: result.runId,
-			error: result.error ?? "Agent tool run was interrupted"
+			error: result.error ?? "Agent tool run was interrupted",
+			...result.reason !== void 0 ? { reason: result.reason } : {},
+			...result.childStillRunning !== void 0 ? { childStillRunning: result.childStillRunning } : {}
 		}, replay, connection);
 		else this._broadcastAgentToolEvent(parentToolCallId, sequence, {
 			kind: "error",
@@ -4508,7 +4592,7 @@ var Agent = class Agent extends Server {
 		if (!cls) throw new Error(`Agent tool class "${className}" is not exported.`);
 		return cls;
 	}
-	async _replayAndInterruptAgentToolRun(row, message) {
+	async _replayAndInterruptAgentToolRun(row, message, extra) {
 		let sequence = 1;
 		try {
 			sequence = await this._broadcastAgentToolStoredChunks(row, sequence);
@@ -4517,12 +4601,53 @@ var Agent = class Agent extends Server {
 			runId: row.run_id,
 			agentType: row.agent_type,
 			status: "interrupted",
-			error: message
+			error: message,
+			...extra?.reason !== void 0 ? { reason: extra.reason } : {},
+			...extra?.childStillRunning !== void 0 ? { childStillRunning: extra.childStillRunning } : {}
 		};
 		await this._finishAgentToolRun(this._agentToolRunInfoFromRow(row), result, { sequence });
 		return result;
 	}
 	/**
+	* Human-readable prose for an `interrupted` seal. Kept in sync with
+	* {@link AgentToolInterruptedReason}; callers branch on the typed `reason`
+	* field, not this string.
+	*/
+	_interruptedMessageForReason(reason) {
+		switch (reason) {
+			case "no-progress": return "Agent tool run was still running but made no forward progress within the re-attach no-progress budget; the parent gave up.";
+			case "window-exceeded": return "Agent tool run did not reach a terminal result within the maximum re-attach window; the parent gave up.";
+			case "not-tailable": return "Agent tool run was still running, but live-tail reattachment is not supported in this runtime.";
+			case "inspect-timeout": return "Agent tool run inspection timed out during parent recovery.";
+			case "inspect-failed": return "Agent tool run could not be inspected during parent recovery.";
+			case "recovery-deadline": return "Agent tool run recovery deadline exceeded.";
+			default: return "Agent tool run was still running and did not reach a terminal result.";
+		}
+	}
+	/**
+	* Tear down a child agent-tool run the parent has genuinely given up on
+	* (#1630 follow-up). Teardown is scoped to `window-exceeded` ONLY — the hard
+	* ceiling, where the child has had its full recovery window and is therefore
+	* truly exhausted, so cancelling it reclaims its fiber / keep-alive. Every
+	* other give-up is deliberately left repairable: `no-progress` seals stay
+	* SOFT (`interrupted`, `childStillRunning: true`) so a re-issue can still
+	* re-attach and collect the child if it self-heals — tearing those down would
+	* defeat the repair-on-re-issue path and convert a retryable interrupt into a
+	* non-retryable `aborted`. Reasons where the child's state is unknown
+	* (`inspect-*`, `recovery-deadline`, `not-tailable`) are also left alone.
+	* Returns whether the child was torn down (so the caller reports
+	* `childStillRunning: false`).
+	*/
+	async _teardownGivenUpAgentToolChild(adapter, runId, reason) {
+		if (reason !== "window-exceeded") return false;
+		try {
+			await adapter.cancelAgentToolRun(runId, `agent tool run given up by parent recovery: ${reason}`);
+			return true;
+		} catch {
+			return false;
+		}
+	}
+	/**
 	* Re-attach to a still-running child agent-tool run and tail it to its real
 	* terminal result, instead of abandoning it as `interrupted` (#1630). The
 	* child is a separate facet with its own `chatRecovery`, so resolving it via
@@ -4530,54 +4655,98 @@ var Agent = class Agent extends Server {
 	* its live stream (forwarding chunks to the parent's connections) until it
 	* reaches terminal, then inspect for the collected result.
 	*
-	* Bounded by {@link DEFAULT_AGENT_TOOL_REATTACH_TIMEOUT_MS}: a child that keeps
-	* advancing toward terminal within the window is collected; a genuinely hung
-	* child returns `{ result: undefined }` once the budget elapses so the caller
-	* falls back to `interrupted` and recovery can never block forever.
+	* The wait is PROGRESS-KEYED, not a flat wall clock (which previously abandoned
+	* healthy, still-advancing children whose recovery simply outran a fixed
+	* budget). `noProgressTimeoutMs` bounds how long the parent waits with NO
+	* forward progress; it is reset on every forwarded chunk. As long as the child
+	* keeps streaming it is followed through to terminal. The loop also RE-ARMS
+	* across stream-closes (a child re-evicted mid-recovery, or a tail that ends
+	* before terminal) as long as the prior attempt made progress, so a child that
+	* dies and recovers again during deploy churn is still collected. A genuinely
+	* silent/hung child can never block recovery forever: it seals `interrupted`
+	* after one `noProgressTimeoutMs` window. `maxWindowMs` is an OPTIONAL hard
+	* wall-clock ceiling (default `Infinity` — uncapped, mirroring #1672's
+	* `maxRecoveryWork`); set it finite to also bound a child that keeps
+	* progressing, which seals `window-exceeded` and tears the child down.
 	*
 	* Returns the terminal `result` (and `completedAt`) when the child reaches a
-	* terminal status within the budget, plus the advanced broadcast `sequence`.
-	* Returns `{ result: undefined }` when there is no `tailAgentToolRun` adapter,
-	* the budget is exhausted, or the child is still non-terminal.
+	* terminal status, plus the advanced broadcast `sequence`. Returns
+	* `{ result: undefined }` when there is no `tailAgentToolRun` adapter, the
+	* child makes no progress within a full no-progress window, or the ceiling is
+	* reached while the child is still non-terminal — the caller then seals
+	* `interrupted`.
 	*/
-	async _reattachAgentToolRunToTerminal(adapter, row, sequence, budgetMs = DEFAULT_AGENT_TOOL_REATTACH_TIMEOUT_MS) {
-		if (typeof adapter.tailAgentToolRun !== "function") return { sequence };
-		const controller = new AbortController();
-		let timeoutId;
-		if (budgetMs > 0 && Number.isFinite(budgetMs)) timeoutId = setTimeout(() => controller.abort(), budgetMs);
-		else if (budgetMs <= 0) controller.abort();
+	async _reattachAgentToolRunToTerminal(adapter, row, sequence, noProgressTimeoutMs = DEFAULT_AGENT_TOOL_REATTACH_NO_PROGRESS_TIMEOUT_MS, maxWindowMs = DEFAULT_AGENT_TOOL_REATTACH_MAX_WINDOW_MS) {
+		if (typeof adapter.tailAgentToolRun !== "function") return {
+			sequence,
+			reason: "not-tailable"
+		};
 		this._emit("agent_tool:recovery:reattach", {
 			runId: row.run_id,
 			agentType: row.agent_type,
-			budgetMs
+			budgetMs: noProgressTimeoutMs
 		});
-		let nextSequence = sequence;
-		if (!controller.signal.aborted) try {
-			let afterSequence = -1;
+		const collectTerminal = async (seq) => {
+			let inspection = null;
 			try {
-				const existing = await adapter.getAgentToolChunks(row.run_id);
-				const last = existing[existing.length - 1];
-				if (last) afterSequence = last.sequence;
-			} catch {}
-			const stream = await adapter.tailAgentToolRun(row.run_id, { afterSequence });
-			nextSequence = await this._forwardAgentToolStream(stream, row.parent_tool_call_id ?? void 0, row.run_id, nextSequence, controller.signal);
-		} catch {}
-		if (timeoutId !== void 0) clearTimeout(timeoutId);
-		let inspection = null;
+				inspection = await adapter.inspectAgentToolRun(row.run_id);
+			} catch {
+				return null;
+			}
+			if (inspection && inspection.status !== "running" && inspection.status !== "starting") return {
+				sequence: seq,
+				result: this._terminalResultFromInspection(row.agent_type, inspection),
+				completedAt: inspection.completedAt
+			};
+			return null;
+		};
+		let nextSequence = sequence;
+		if (!(noProgressTimeoutMs > 0)) return await collectTerminal(nextSequence) ?? {
+			sequence: nextSequence,
+			reason: "no-progress"
+		};
+		const ceilingController = new AbortController();
+		let ceilingTimer;
+		if (maxWindowMs > 0 && Number.isFinite(maxWindowMs)) ceilingTimer = setTimeout(() => ceilingController.abort(), maxWindowMs);
+		let reason = "no-progress";
 		try {
-			inspection = await adapter.inspectAgentToolRun(row.run_id);
-		} catch {}
-		if (inspection && inspection.status !== "running" && inspection.status !== "starting") return {
+			while (!ceilingController.signal.aborted) {
+				let afterSequence = -1;
+				try {
+					const existing = await adapter.getAgentToolChunks(row.run_id);
+					const last = existing[existing.length - 1];
+					if (last) afterSequence = last.sequence;
+				} catch {}
+				const beforeSequence = nextSequence;
+				let streamEnded = "idle";
+				try {
+					const stream = await adapter.tailAgentToolRun(row.run_id, { afterSequence });
+					const forwarded = await this._forwardAgentToolStream(stream, row.parent_tool_call_id ?? void 0, row.run_id, nextSequence, ceilingController.signal, noProgressTimeoutMs);
+					nextSequence = forwarded.next;
+					streamEnded = forwarded.ended;
+				} catch {}
+				const terminal = await collectTerminal(nextSequence);
+				if (terminal) return terminal;
+				if (ceilingController.signal.aborted) {
+					reason = "window-exceeded";
+					break;
+				}
+				if (streamEnded !== "done") break;
+				if (nextSequence <= beforeSequence) break;
+			}
+		} finally {
+			if (ceilingTimer !== void 0) clearTimeout(ceilingTimer);
+		}
+		return {
 			sequence: nextSequence,
-			result: this._terminalResultFromInspection(row.agent_type, inspection),
-			completedAt: inspection.completedAt
+			reason
 		};
-		return { sequence: nextSequence };
 	}
 	async _replayAgentToolRuns(connection) {
 		const rows = this.sql`
       SELECT run_id, parent_tool_call_id, agent_type, input_preview, status,
-             summary, output_json, error_message, display_metadata, display_order
+             summary, output_json, error_message, interrupted_reason,
+             child_still_running, display_metadata, display_order
       FROM cf_agent_tool_runs
       ORDER BY started_at ASC
     `;
@@ -4601,19 +4770,22 @@ var Agent = class Agent extends Server {
 				status: row.status,
 				output: this._parseAgentToolJson(row.output_json),
 				summary: row.summary ?? void 0,
-				error: row.error_message ?? void 0
+				error: row.error_message ?? void 0,
+				...this._agentToolInterruptedExtrasFromRow(row)
 			}, true, connection);
 		}
 	}
 	async _reconcileAgentToolRuns(options) {
-		const reattachTimeoutMs = options?.reattachTimeoutMs ?? DEFAULT_AGENT_TOOL_REATTACH_TIMEOUT_MS;
+		const reattachTimeoutMs = options?.reattachTimeoutMs ?? this._resolvedOptions.agentToolReattachNoProgressTimeoutMs;
+		const reattachMaxWindowMs = options?.reattachMaxWindowMs ?? this._resolvedOptions.agentToolReattachMaxWindowMs;
 		const startedAt = Date.now();
 		const totalTimeoutMs = options?.totalRecoveryTimeoutMs ?? DEFAULT_AGENT_TOOL_RECOVERY_TOTAL_TIMEOUT_MS;
 		const deadlineAt = totalTimeoutMs > 0 ? startedAt + totalTimeoutMs : Number.POSITIVE_INFINITY;
 		const deferredFinishes = [];
 		const rows = this.sql`
       SELECT run_id, parent_tool_call_id, agent_type, input_preview, status,
-             summary, output_json, error_message, display_metadata, display_order,
+             summary, output_json, error_message, interrupted_reason,
+             child_still_running, display_metadata, display_order,
              started_at, completed_at
       FROM cf_agent_tool_runs
       WHERE status IN ('starting', 'running')
@@ -4654,7 +4826,8 @@ var Agent = class Agent extends Server {
 					runId: row.run_id,
 					agentType: row.agent_type,
 					status: "interrupted",
-					error: "Agent tool run recovery deadline exceeded."
+					reason: "recovery-deadline",
+					error: this._interruptedMessageForReason("recovery-deadline")
 				}, sequence, void 0);
 				continue;
 			}
@@ -4662,12 +4835,16 @@ var Agent = class Agent extends Server {
 			const boundedChildTimeout = childTimeout > 0 ? Math.min(childTimeout, remainingMs) : remainingMs;
 			const recovery = await this._inspectAgentToolRunForRecovery(row, sequence, boundedChildTimeout);
 			if (recovery.status !== "inspected") {
-				await finalizeRow(row, {
-					runId: row.run_id,
-					agentType: row.agent_type,
-					status: "interrupted",
-					error: recovery.status === "timed-out" ? "Agent tool run inspection timed out during parent recovery." : "Agent tool run could not be inspected during parent recovery."
-				}, sequence, void 0);
+				await finalizeRow(row, (() => {
+					const reason = recovery.status === "timed-out" ? "inspect-timeout" : "inspect-failed";
+					return {
+						runId: row.run_id,
+						agentType: row.agent_type,
+						status: "interrupted",
+						reason,
+						error: this._interruptedMessageForReason(reason)
+					};
+				})(), sequence, void 0);
 				continue;
 			}
 			const inspection = recovery.inspection;
@@ -4687,17 +4864,26 @@ var Agent = class Agent extends Server {
 				runId: row.run_id,
 				agentType: row.agent_type,
 				status: "interrupted",
-				error: "Agent tool run was still running, but live-tail reattachment is not supported in this runtime."
+				reason: "not-tailable",
+				childStillRunning: true,
+				error: this._interruptedMessageForReason("not-tailable")
 			}, sequenceAfterReplay, void 0);
 			else await finalizeRow(row, this._terminalResultFromInspection(row.agent_type, inspection), sequenceAfterReplay, inspection.completedAt);
 		}
 		await Promise.all(reattachQueue.map(async ({ row, adapter }) => {
-			const reattach = await this._reattachAgentToolRunToTerminal(adapter, row, 1, reattachTimeoutMs);
-			await finalizeRow(row, reattach.result ?? {
+			const reattach = await this._reattachAgentToolRunToTerminal(adapter, row, 1, reattachTimeoutMs, reattachMaxWindowMs);
+			if (reattach.result) {
+				await finalizeRow(row, reattach.result, reattach.sequence, reattach.completedAt);
+				return;
+			}
+			const tornDown = await this._teardownGivenUpAgentToolChild(adapter, row.run_id, reattach.reason);
+			await finalizeRow(row, {
 				runId: row.run_id,
 				agentType: row.agent_type,
 				status: "interrupted",
-				error: "Agent tool run was still running and did not reach a terminal result within the re-attach budget."
+				reason: reattach.reason,
+				childStillRunning: !tornDown,
+				error: this._interruptedMessageForReason(reattach.reason)
 			}, reattach.sequence, reattach.completedAt);
 		}));
 		this._emit("agent_tool:recovery:complete", {
@@ -4737,6 +4923,7 @@ var Agent = class Agent extends Server {
 				childInspectionTimeoutMs: options?.childInspectionTimeoutMs,
 				totalRecoveryTimeoutMs: options?.totalRecoveryTimeoutMs,
 				reattachTimeoutMs: options?.reattachTimeoutMs,
+				reattachMaxWindowMs: options?.reattachMaxWindowMs,
 				runIds: options?.runIds
 			});
 			await this._runDeferredAgentToolFinishHooks(recoveredAgentToolFinishes);