agents 0.12.4 → 0.13.1

package/dist/index.js

@@ -1,8 +1,8 @@
 import { __DO_NOT_USE_WILL_BREAK__agentContext } from "./internal_context.js";
 import { MessageType } from "./types.js";
-import { camelCaseToKebabCase } from "./utils.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-CS51BNGR.js";
+import { i as _classPrivateFieldInitSpec, n as _classPrivateFieldSet2, t as _classPrivateFieldGet2 } from "./classPrivateFieldGet2-Evpt0SEr.js";
 import { SUB_PREFIX, getSubAgentByName, parseSubAgentPath, routeSubAgentRequest } from "./sub-routing.js";
 import { isErrorRetryable, tryN, validateRetryOptions } from "./retries.js";
 import { o as RPC_DO_PREFIX, r as MCPConnectionState, s as DisposableStore, t as MCPClientManager } from "./client-D1kFXo80.js";
@@ -12,7 +12,7 @@ import { AsyncLocalStorage } from "node:async_hooks";
 import { parseCronExpression } from "cron-schedule";
 import { nanoid } from "nanoid";
 import { EmailMessage } from "cloudflare:email";
-import { RpcTarget } from "cloudflare:workers";
+import { RpcTarget, exports } from "cloudflare:workers";
 import { Server, getServerByName, routePartykitRequest } from "partyserver";
 //#region src/index.ts
 let _Symbol$dispose;
@@ -120,7 +120,7 @@ const DEFAULT_KEEP_ALIVE_INTERVAL_MS = 3e4;
 * 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 = 7;
+const CURRENT_SCHEMA_VERSION = 8;
 const SCHEMA_VERSION_ROW_ID = "cf_schema_version";
 const STATE_ROW_ID = "cf_state_row_id";
 const STATE_WAS_CHANGED = "cf_state_was_changed";
@@ -549,6 +549,32 @@ var Agent = class Agent extends Server {
 			this.sql`
         CREATE INDEX IF NOT EXISTS idx_facet_runs_owner_path_key
         ON cf_agents_facet_runs(owner_path_key)
+      `;
+			this.sql`
+        CREATE TABLE IF NOT EXISTS cf_agents_fibers (
+          fiber_id TEXT PRIMARY KEY,
+          idempotency_key TEXT UNIQUE,
+          name TEXT NOT NULL,
+          status TEXT NOT NULL,
+          snapshot TEXT,
+          metadata_json TEXT,
+          error_message TEXT,
+          created_at INTEGER NOT NULL,
+          started_at INTEGER,
+          completed_at INTEGER
+        )
+      `;
+			this.sql`
+        CREATE INDEX IF NOT EXISTS idx_fibers_status_created
+        ON cf_agents_fibers(status, created_at, fiber_id)
+      `;
+			this.sql`
+        CREATE INDEX IF NOT EXISTS idx_fibers_name_status_created
+        ON cf_agents_fibers(name, status, created_at, fiber_id)
+      `;
+			this.sql`
+        CREATE INDEX IF NOT EXISTS idx_fibers_status_completed
+        ON cf_agents_fibers(status, completed_at, created_at)
       `;
 			this.sql`
         CREATE TABLE IF NOT EXISTS cf_agent_tool_runs (
@@ -595,6 +621,9 @@ var Agent = class Agent extends Server {
 		this._keepAliveRefs = 0;
 		this._facetKeepAliveTokens = /* @__PURE__ */ new Set();
 		this._runFiberActiveFibers = /* @__PURE__ */ new Set();
+		this._managedFiberAbortControllers = /* @__PURE__ */ new Map();
+		this._managedFiberExecutions = /* @__PURE__ */ new Map();
+		this._managedFiberTerminalWaiters = /* @__PURE__ */ new Map();
 		this._runFiberRecoveryInProgress = false;
 		this._ParentClass = Object.getPrototypeOf(this).constructor;
 		this.initialState = DEFAULT_STATE;
@@ -2211,6 +2240,295 @@ var Agent = class Agent extends Server {
 			dispose();
 		}
 	}
+	_isTerminalFiberStatus(status) {
+		return status === "completed" || status === "aborted" || status === "interrupted" || status === "error";
+	}
+	_notifyManagedFiberTerminal(fiberId) {
+		const row = this._readFiber(fiberId);
+		if (row && !this._isTerminalFiberStatus(row.status)) return;
+		const waiters = this._managedFiberTerminalWaiters.get(fiberId);
+		if (!waiters) return;
+		this._managedFiberTerminalWaiters.delete(fiberId);
+		for (const resolve of waiters) resolve();
+	}
+	_waitForManagedFiberTerminal(fiberId) {
+		const row = this._readFiber(fiberId);
+		if (!row || this._isTerminalFiberStatus(row.status)) return Promise.resolve();
+		return new Promise((resolve) => {
+			let waiters = this._managedFiberTerminalWaiters.get(fiberId);
+			if (!waiters) {
+				waiters = /* @__PURE__ */ new Set();
+				this._managedFiberTerminalWaiters.set(fiberId, waiters);
+			}
+			waiters.add(resolve);
+		});
+	}
+	_normalizeFiberStatusFilter(status) {
+		if (!status) return null;
+		return new Set(Array.isArray(status) ? status : [status]);
+	}
+	_parseFiberJsonObject(value) {
+		if (value === null) return null;
+		try {
+			const parsed = JSON.parse(value);
+			if (parsed !== null && typeof parsed === "object" && !Array.isArray(parsed)) return parsed;
+		} catch {}
+		return null;
+	}
+	_parseFiberSnapshot(value) {
+		if (value === null) return void 0;
+		try {
+			return JSON.parse(value);
+		} catch {
+			return;
+		}
+	}
+	_fiberErrorMessage(error) {
+		return error instanceof Error ? error.message : String(error);
+	}
+	_stringifyFiberSnapshot(snapshot) {
+		return snapshot === void 0 ? null : JSON.stringify(snapshot);
+	}
+	_fiberRecoveryErrorMessage(result) {
+		if (result.status === "error") return result.error === void 0 ? null : this._fiberErrorMessage(result.error);
+		if (result.status === "aborted" || result.status === "interrupted") return result.reason ?? null;
+		return null;
+	}
+	_applyManagedFiberRecoveryResult(fiberId, result) {
+		const completedAt = Date.now();
+		const snapshot = this._stringifyFiberSnapshot(result.snapshot);
+		const errorMessage = this._fiberRecoveryErrorMessage(result);
+		const metadata = result.status === "completed" && result.metadata !== void 0 ? JSON.stringify(result.metadata) : void 0;
+		if (metadata !== void 0) {
+			this.sql`
+        UPDATE cf_agents_fibers
+        SET status = ${result.status},
+            snapshot = COALESCE(${snapshot}, snapshot),
+            metadata_json = ${metadata},
+            error_message = ${errorMessage},
+            completed_at = ${completedAt}
+        WHERE fiber_id = ${fiberId}
+          AND status = 'interrupted'
+      `;
+			this._notifyManagedFiberTerminal(fiberId);
+			return;
+		}
+		this.sql`
+      UPDATE cf_agents_fibers
+      SET status = ${result.status},
+          snapshot = COALESCE(${snapshot}, snapshot),
+          error_message = ${errorMessage},
+          completed_at = ${completedAt}
+      WHERE fiber_id = ${fiberId}
+        AND status = 'interrupted'
+    `;
+		this._notifyManagedFiberTerminal(fiberId);
+	}
+	_settleManagedFiberExecution(fiberId, outcome, signal) {
+		const completedAt = Date.now();
+		if (outcome.ok) {
+			this.sql`
+        UPDATE cf_agents_fibers
+        SET status = 'completed', completed_at = ${completedAt}
+        WHERE fiber_id = ${fiberId} AND status = 'running'
+      `;
+			this._notifyManagedFiberTerminal(fiberId);
+			return;
+		}
+		const message = this._fiberErrorMessage(outcome.error);
+		const status = signal.aborted ? "aborted" : "error";
+		this.sql`
+      UPDATE cf_agents_fibers
+      SET status = ${status},
+          error_message = ${message},
+          completed_at = ${completedAt}
+      WHERE fiber_id = ${fiberId} AND status = 'running'
+    `;
+		this._notifyManagedFiberTerminal(fiberId);
+	}
+	_parseFiberRecoverySnapshot(fiberId, snapshotText) {
+		if (!snapshotText) return null;
+		try {
+			return JSON.parse(snapshotText);
+		} catch {
+			console.warn(`[Agent] Corrupted snapshot for fiber ${fiberId}, treating as null`);
+			return null;
+		}
+	}
+	async _runFiberRecoveryHook(ctx, managedRow) {
+		try {
+			if (!await this._handleInternalFiberRecovery(ctx)) {
+				const recoveryResult = await this.onFiberRecovered(ctx);
+				if (managedRow && recoveryResult) this._applyManagedFiberRecoveryResult(ctx.id, recoveryResult);
+			}
+		} catch (e) {
+			if (managedRow) this.sql`
+          UPDATE cf_agents_fibers
+          SET error_message = ${this._fiberErrorMessage(e)}
+          WHERE fiber_id = ${ctx.id}
+            AND status = 'interrupted'
+        `;
+			console.error(`[Agent] Fiber recovery failed for "${ctx.name}" (${ctx.id}):`, e);
+		}
+	}
+	_fiberInspectionFromRow(row) {
+		const snapshot = this._parseFiberSnapshot(row.snapshot);
+		const inspection = {
+			fiberId: row.fiber_id,
+			name: row.name,
+			status: row.status,
+			createdAt: row.created_at
+		};
+		if (row.idempotency_key !== null) inspection.idempotencyKey = row.idempotency_key;
+		if (snapshot !== void 0) inspection.snapshot = snapshot;
+		if (row.error_message !== null) inspection.error = row.error_message;
+		const metadata = this._parseFiberJsonObject(row.metadata_json);
+		if (metadata !== null) inspection.metadata = metadata;
+		if (row.started_at !== null) inspection.startedAt = row.started_at;
+		if (row.completed_at !== null) inspection.settledAt = row.completed_at;
+		return inspection;
+	}
+	async _waitForManagedFiber(fiberId) {
+		const row = this._readFiber(fiberId);
+		if (!row || this._isTerminalFiberStatus(row.status)) return row ? this._fiberInspectionFromRow(row) : null;
+		if (this._managedFiberExecutions.has(fiberId)) {
+			await this._waitForManagedFiberTerminal(fiberId);
+			return this.inspectFiber(fiberId);
+		}
+		await this._checkRunFibers();
+		await this._waitForManagedFiberTerminal(fiberId);
+		return this.inspectFiber(fiberId);
+	}
+	_readFiber(fiberId) {
+		return this.sql`
+      SELECT fiber_id, idempotency_key, name, status, snapshot, metadata_json,
+             error_message, created_at, started_at, completed_at
+      FROM cf_agents_fibers
+      WHERE fiber_id = ${fiberId}
+      LIMIT 1
+    `[0] ?? null;
+	}
+	_readFiberByKey(idempotencyKey) {
+		return this.sql`
+      SELECT fiber_id, idempotency_key, name, status, snapshot, metadata_json,
+             error_message, created_at, started_at, completed_at
+      FROM cf_agents_fibers
+      WHERE idempotency_key = ${idempotencyKey}
+      LIMIT 1
+    `[0] ?? null;
+	}
+	_listFiberRows(options) {
+		const limit = Math.min(Math.max(options?.limit ?? 50, 1), 100);
+		const statuses = this._normalizeFiberStatusFilter(options?.status);
+		if (statuses) return [...statuses].flatMap((status) => this._listFiberRowsByStatus(status, limit, options?.name)).sort((a, b) => b.created_at === a.created_at ? b.fiber_id.localeCompare(a.fiber_id) : b.created_at - a.created_at).slice(0, limit);
+		if (options?.name) return this.sql`
+        SELECT fiber_id, idempotency_key, name, status, snapshot, metadata_json,
+               error_message, created_at, started_at, completed_at
+        FROM cf_agents_fibers
+        WHERE name = ${options.name}
+        ORDER BY created_at DESC, fiber_id DESC
+        LIMIT ${limit}
+      `;
+		return this.sql`
+      SELECT fiber_id, idempotency_key, name, status, snapshot, metadata_json,
+             error_message, created_at, started_at, completed_at
+      FROM cf_agents_fibers
+      ORDER BY created_at DESC, fiber_id DESC
+      LIMIT ${limit}
+    `;
+	}
+	_listFiberRowsByStatus(status, limit, name) {
+		if (name) return this.sql`
+        SELECT fiber_id, idempotency_key, name, status, snapshot, metadata_json,
+               error_message, created_at, started_at, completed_at
+        FROM cf_agents_fibers
+        WHERE status = ${status} AND name = ${name}
+        ORDER BY created_at DESC, fiber_id DESC
+        LIMIT ${limit}
+      `;
+		return this.sql`
+      SELECT fiber_id, idempotency_key, name, status, snapshot, metadata_json,
+             error_message, created_at, started_at, completed_at
+      FROM cf_agents_fibers
+      WHERE status = ${status}
+      ORDER BY created_at DESC, fiber_id DESC
+      LIMIT ${limit}
+    `;
+	}
+	async inspectFiber(fiberId) {
+		const row = this._readFiber(fiberId);
+		return row ? this._fiberInspectionFromRow(row) : null;
+	}
+	async inspectFiberByKey(idempotencyKey) {
+		const row = this._readFiberByKey(idempotencyKey);
+		return row ? this._fiberInspectionFromRow(row) : null;
+	}
+	async listFibers(options) {
+		return this._listFiberRows(options).map((row) => this._fiberInspectionFromRow(row));
+	}
+	async cancelFiber(fiberId, reason) {
+		const row = this._readFiber(fiberId);
+		if (!row || this._isTerminalFiberStatus(row.status)) return false;
+		const now = Date.now();
+		this.sql`
+      UPDATE cf_agents_fibers
+      SET status = 'aborted',
+          error_message = ${reason ?? null},
+          completed_at = ${now}
+      WHERE fiber_id = ${fiberId}
+        AND status IN ('pending', 'running')
+    `;
+		this._managedFiberAbortControllers.get(fiberId)?.abort(reason);
+		this._notifyManagedFiberTerminal(fiberId);
+		return true;
+	}
+	async cancelFiberByKey(idempotencyKey, reason) {
+		const row = this._readFiberByKey(idempotencyKey);
+		return row ? this.cancelFiber(row.fiber_id, reason) : false;
+	}
+	async resolveFiber(fiberId, result) {
+		const row = this._readFiber(fiberId);
+		if (!row || row.status !== "interrupted") return false;
+		this._applyManagedFiberRecoveryResult(fiberId, result);
+		return true;
+	}
+	async deleteFibers(options) {
+		const terminalStatuses = [...this._normalizeFiberStatusFilter(options?.status) ?? new Set([
+			"completed",
+			"aborted",
+			"error"
+		])].filter((status) => this._isTerminalFiberStatus(status));
+		if (terminalStatuses.length === 0) return 0;
+		const limit = Math.min(Math.max(options?.limit ?? 100, 1), 500);
+		const settledBefore = options?.settledBefore?.getTime();
+		const rows = terminalStatuses.flatMap((status) => this._listTerminalFiberRowsForDelete(status, limit, settledBefore)).sort((a, b) => a.completed_at === b.completed_at ? a.created_at - b.created_at : (a.completed_at ?? 0) - (b.completed_at ?? 0)).slice(0, limit);
+		for (const row of rows) this.sql`
+        DELETE FROM cf_agents_fibers
+        WHERE fiber_id = ${row.fiber_id}
+          AND status IN ('completed', 'aborted', 'interrupted', 'error')
+      `;
+		return rows.length;
+	}
+	_listTerminalFiberRowsForDelete(status, limit, settledBefore) {
+		if (settledBefore !== void 0) return this.sql`
+        SELECT fiber_id, idempotency_key, name, status, snapshot, metadata_json,
+               error_message, created_at, started_at, completed_at
+        FROM cf_agents_fibers
+        WHERE status = ${status}
+          AND completed_at IS NOT NULL
+          AND completed_at < ${settledBefore}
+        ORDER BY completed_at ASC, created_at ASC
+        LIMIT ${limit}
+      `;
+		return this.sql`
+      SELECT fiber_id, idempotency_key, name, status, snapshot, metadata_json,
+             error_message, created_at, started_at, completed_at
+      FROM cf_agents_fibers
+      WHERE status = ${status}
+      ORDER BY completed_at ASC, created_at ASC
+      LIMIT ${limit}
+    `;
+	}
 	/**
 	* Run a function as a durable fiber. The fiber is registered in SQLite
 	* before execution, checkpointable during execution via `ctx.stash()`,
@@ -2225,7 +2543,100 @@ var Agent = class Agent extends Server {
 	* @returns The return value of fn
 	*/
 	async runFiber(name, fn) {
-		const id = nanoid();
+		return this._runFiberInternal(nanoid(), name, fn);
+	}
+	async startFiber(name, fn, options) {
+		const fiberId = options?.fiberId ?? nanoid();
+		const idempotencyKey = options?.idempotencyKey;
+		if (options?.fiberId !== void 0 && options.fiberId.trim() === "") throw new Error("fiberId must not be blank");
+		if (options?.idempotencyKey !== void 0 && options.idempotencyKey.trim() === "") throw new Error("idempotencyKey must not be blank");
+		const existingById = this._readFiber(fiberId);
+		const existingByKey = idempotencyKey ? this._readFiberByKey(idempotencyKey) : null;
+		if (existingById && existingByKey && existingById.fiber_id !== existingByKey.fiber_id) throw new Error("fiberId and idempotencyKey refer to different fibers");
+		if (existingByKey && options?.fiberId && existingByKey.fiber_id !== fiberId) throw new Error("fiberId and idempotencyKey refer to different fibers");
+		const existing = existingById ?? existingByKey;
+		if (existing) {
+			if (options?.waitForCompletion && !this._isTerminalFiberStatus(existing.status)) {
+				const waited = await this._waitForManagedFiber(existing.fiber_id);
+				if (waited) return {
+					...waited,
+					accepted: false
+				};
+				throw new Error(`Fiber ${existing.fiber_id} no longer exists`);
+			}
+			return {
+				...this._fiberInspectionFromRow(existing),
+				accepted: false
+			};
+		}
+		const now = Date.now();
+		this.sql`
+      INSERT INTO cf_agents_fibers
+        (fiber_id, idempotency_key, name, status, snapshot, metadata_json,
+         error_message, created_at, started_at, completed_at)
+      VALUES
+        (${fiberId}, ${idempotencyKey ?? null}, ${name}, 'pending', NULL,
+         ${options?.metadata ? JSON.stringify(options.metadata) : null}, NULL,
+         ${now}, NULL, NULL)
+    `;
+		const row = this._readFiber(fiberId);
+		if (!row) throw new Error(`Failed to create fiber ${fiberId}`);
+		const execution = this._executeManagedFiber(fiberId, name, fn).catch((error) => {
+			console.error(`[Agent] Managed fiber "${name}" (${fiberId}) failed:`, error);
+		}).finally(() => {
+			if (this._managedFiberExecutions.get(fiberId) === execution) this._managedFiberExecutions.delete(fiberId);
+		});
+		this._managedFiberExecutions.set(fiberId, execution);
+		if (options?.waitForCompletion) {
+			const completed = await this._waitForManagedFiber(fiberId);
+			if (!completed) throw new Error(`Fiber ${fiberId} no longer exists`);
+			return {
+				...completed,
+				accepted: true
+			};
+		}
+		return {
+			...this._fiberInspectionFromRow(row),
+			accepted: true
+		};
+	}
+	async _executeManagedFiber(fiberId, name, fn) {
+		const row = this._readFiber(fiberId);
+		if (!row || row.status !== "pending") return;
+		const controller = new AbortController();
+		this._managedFiberAbortControllers.set(fiberId, controller);
+		const now = Date.now();
+		this.sql`
+      UPDATE cf_agents_fibers
+      SET status = 'running', started_at = ${now}
+      WHERE fiber_id = ${fiberId} AND status = 'pending'
+    `;
+		const updated = this._readFiber(fiberId);
+		if (!updated || updated.status !== "running") {
+			this._managedFiberAbortControllers.delete(fiberId);
+			return;
+		}
+		let settled = false;
+		try {
+			await this._runFiberInternal(fiberId, name, fn, {
+				signal: controller.signal,
+				managed: true,
+				beforeRunCleanup: (outcome) => {
+					settled = true;
+					this._settleManagedFiberExecution(fiberId, outcome, controller.signal);
+				}
+			});
+		} catch (error) {
+			if (!settled) this._settleManagedFiberExecution(fiberId, {
+				ok: false,
+				error
+			}, controller.signal);
+		} finally {
+			this._managedFiberAbortControllers.delete(fiberId);
+		}
+	}
+	async _runFiberInternal(id, name, fn, options) {
+		const signal = options?.signal ?? new AbortController().signal;
 		this.sql`
       INSERT INTO cf_agents_runs (id, name, snapshot, created_at)
       VALUES (${id}, ${name}, NULL, ${Date.now()})
@@ -2242,19 +2653,36 @@ var Agent = class Agent extends Server {
 			}
 			dispose = await this.keepAlive();
 			const stash = (data) => {
+				const snapshot = JSON.stringify(data);
 				this.sql`
-          UPDATE cf_agents_runs SET snapshot = ${JSON.stringify(data)}
+          UPDATE cf_agents_runs SET snapshot = ${snapshot}
           WHERE id = ${id}
         `;
+				if (options?.managed) this.sql`
+            UPDATE cf_agents_fibers SET snapshot = ${snapshot}
+            WHERE fiber_id = ${id}
+          `;
 			};
-			return await _fiberALS.run({
-				id,
-				stash
-			}, () => fn({
-				id,
-				stash,
-				snapshot: null
-			}));
+			try {
+				const result = await _fiberALS.run({
+					id,
+					signal,
+					stash
+				}, () => fn({
+					id,
+					signal,
+					stash,
+					snapshot: null
+				}));
+				options?.beforeRunCleanup?.({ ok: true });
+				return result;
+			} catch (error) {
+				options?.beforeRunCleanup?.({
+					ok: false,
+					error
+				});
+				throw error;
+			}
 		} finally {
 			this._runFiberActiveFibers.delete(id);
 			this.sql`DELETE FROM cf_agents_runs WHERE id = ${id}`;
@@ -2306,24 +2734,67 @@ var Agent = class Agent extends Server {
 			const rows = this.sql`SELECT id, name, snapshot, created_at FROM cf_agents_runs`;
 			for (const row of rows) {
 				if (this._runFiberActiveFibers.has(row.id)) continue;
-				let snapshot = null;
-				if (row.snapshot) try {
-					snapshot = JSON.parse(row.snapshot);
-				} catch {
-					console.warn(`[Agent] Corrupted snapshot for fiber ${row.id}, treating as null`);
-				}
+				const snapshot = this._parseFiberRecoverySnapshot(row.id, row.snapshot);
 				const ctx = {
 					id: row.id,
 					name: row.name,
 					snapshot,
 					createdAt: row.created_at
 				};
-				try {
-					if (!await this._handleInternalFiberRecovery(ctx)) await this.onFiberRecovered(ctx);
-				} catch (e) {
-					console.error(`[Agent] Fiber recovery failed for "${ctx.name}" (${ctx.id}):`, e);
+				const managedRow = this._readFiber(row.id);
+				if (managedRow) {
+					if (this._isTerminalFiberStatus(managedRow.status)) {
+						this.sql`DELETE FROM cf_agents_runs WHERE id = ${row.id}`;
+						this._notifyManagedFiberTerminal(row.id);
+						continue;
+					}
+					const completedAt = Date.now();
+					this.sql`
+            UPDATE cf_agents_fibers
+            SET status = 'interrupted',
+                snapshot = ${row.snapshot},
+                completed_at = ${completedAt}
+            WHERE fiber_id = ${row.id}
+              AND status IN ('pending', 'running')
+          `;
+					ctx.idempotencyKey = managedRow.idempotency_key ?? void 0;
+					ctx.metadata = this._parseFiberJsonObject(managedRow.metadata_json);
+					ctx.status = "interrupted";
 				}
+				await this._runFiberRecoveryHook(ctx, managedRow);
 				this.sql`DELETE FROM cf_agents_runs WHERE id = ${row.id}`;
+				if (managedRow) this._notifyManagedFiberTerminal(row.id);
+			}
+			const ledgerOnlyRows = this.sql`
+        SELECT f.fiber_id, f.idempotency_key, f.name, f.status, f.snapshot,
+               f.metadata_json, f.error_message, f.created_at, f.started_at,
+               f.completed_at
+        FROM cf_agents_fibers f
+        LEFT JOIN cf_agents_runs r ON r.id = f.fiber_id
+        WHERE f.status IN ('pending', 'running')
+          AND r.id IS NULL
+      `;
+			for (const row of ledgerOnlyRows) {
+				if (this._runFiberActiveFibers.has(row.fiber_id)) continue;
+				const snapshot = this._parseFiberRecoverySnapshot(row.fiber_id, row.snapshot);
+				const completedAt = Date.now();
+				this.sql`
+          UPDATE cf_agents_fibers
+          SET status = 'interrupted',
+              completed_at = ${completedAt}
+          WHERE fiber_id = ${row.fiber_id}
+            AND status IN ('pending', 'running')
+        `;
+				await this._runFiberRecoveryHook({
+					id: row.fiber_id,
+					name: row.name,
+					snapshot,
+					createdAt: row.created_at,
+					idempotencyKey: row.idempotency_key ?? void 0,
+					metadata: this._parseFiberJsonObject(row.metadata_json),
+					status: "interrupted"
+				}, row);
+				this._notifyManagedFiberTerminal(row.fiber_id);
 			}
 		} finally {
 			this._runFiberRecoveryInProgress = false;
@@ -3092,7 +3563,29 @@ var Agent = class Agent extends Server {
 	* @internal
 	*/
 	async _cf_invokeSubAgent(className, name, method, args) {
-		const handle = await this._cf_resolveSubAgent(className, name);
+		const stub = await this._cf_resolveSubAgent(className, name);
+		return await this._cf_invokeStubMethod(stub, className, method, args);
+	}
+	/**
+	* Bridge method used by `parentAgent()` when the requested parent is
+	* itself a facet (and therefore has no top-level env namespace).
+	* The root receives the full root-first target path, then each hop
+	* delegates to the next facet using that facet's own `ctx.facets`.
+	*
+	* @internal
+	*/
+	async _cf_invokeSubAgentPath(path, method, args) {
+		const [self, next, ...rest] = path;
+		if (!self) throw new Error(`Sub-agent path invocation requires a non-empty path.`);
+		const ownClassName = this.constructor.name;
+		if (self.className !== ownClassName || self.name !== this.name) throw new Error(`Sub-agent path invocation reached ${ownClassName}("${this.name}") but expected ${self.className}("${self.name}").`);
+		if (!next) return await this._cf_invokeStubMethod(this, this.constructor.name, method, args);
+		const child = await this._cf_resolveSubAgent(next.className, next.name);
+		if (rest.length === 0) return await this._cf_invokeStubMethod(child, next.className, method, args);
+		return await child._cf_invokeSubAgentPath([next, ...rest], method, args);
+	}
+	async _cf_invokeStubMethod(stub, className, method, args) {
+		const handle = stub;
 		if (typeof handle[method] !== "function") throw new Error(`Method "${method}" not found on ${className}.`);
 		return await handle[method](...args);
 	}
@@ -3116,11 +3609,11 @@ var Agent = class Agent extends Server {
 	*
 	* The facet's name (and `this.name` getter) is handled entirely by
 	* partyserver via `ctx.id.name`, which is populated because the
-	* parent passed an explicit `id: parentNs.idFromName(name)` to
+	* parent passed an explicit named Durable Object id to
 	* `ctx.facets.get()` — see {@link _cf_resolveSubAgent}. No
 	* `setName()` call or `__ps_name` storage write is needed; the
-	* facet's name survives cold wake automatically because the
-	* factory re-runs and `idFromName` is deterministic.
+	* facet's name survives cold wake automatically because the factory
+	* re-runs and `idFromName` is deterministic.
 	*
 	* @internal Called by {@link subAgent}.
 	*/
@@ -3167,26 +3660,33 @@ var Agent = class Agent extends Server {
 		}];
 	}
 	/**
-	* Resolve a typed RPC stub for this facet's **immediate** parent
+	* Resolve a typed parent stub for this facet's **immediate** parent
 	* agent.
 	*
 	* Symmetric with `subAgent(Cls, name)`: while `subAgent` opens a
 	* stub from parent to child, `parentAgent` opens one from child
 	* to parent. Pass the direct parent's class reference — the
 	* framework verifies it matches the last entry of
-	* `this.parentPath` at runtime, then looks up `env[Cls.name]` to
-	* find the namespace binding.
+	* `this.parentPath` at runtime. If the parent is a top-level
+	* Durable Object, the framework returns the normal namespace stub.
+	* If the parent is itself a facet, the framework returns a bridge
+	* proxy that routes method calls through the root/supervisor and
+	* then down the recorded facet path.
 	*
 	* `this.parentPath` is root-first, so the direct parent is the
 	* **last** entry: `this.parentPath.at(-1)`. For grandparents and
 	* further ancestors, iterate `this.parentPath` and use
 	* `getAgentByName(env.X, this.parentPath[i].name)` directly.
 	*
-	* Assumes the standard "binding name matches class name" convention.
-	* If your `wrangler.jsonc` binds the parent under a different name
-	* (e.g. `{ class_name: "Inbox", name: "MY_INBOX" }`), call
-	* `getAgentByName(env.MY_INBOX, this.parentPath.at(-1)!.name)`
-	* directly instead.
+	* For top-level parents, the framework first checks `env[Cls.name]`,
+	* then falls back to the Worker `exports` object. This supports
+	* custom binding names as long as the parent class is exported under
+	* its class name.
+	*
+	* Facet-parent stubs route normal HTTP `.fetch()` calls through the
+	* same root bridge as RPC methods. WebSocket upgrade requests are
+	* not supported yet because WebSocket handles cannot be serialized
+	* over RPC.
 	*
 	* @experimental The API surface may change before stabilizing.
 	*
@@ -3194,7 +3694,8 @@ var Agent = class Agent extends Server {
 	* @throws If `Cls.name` doesn't match the recorded direct-parent
 	*         class (guards against accidentally reaching the wrong
 	*         DO, especially in nested Root → Mid → Leaf chains).
-	* @throws If no env binding named `Cls.name` is found.
+	* @throws If no namespace is found for a top-level parent, or no
+	*         root namespace is available for a facet parent bridge.
 	*
 	* @example
 	* ```ts
@@ -3211,10 +3712,46 @@ var Agent = class Agent extends Server {
 		const parent = this._parentPath[this._parentPath.length - 1];
 		if (!parent) throw new Error(`parentAgent(): ${this.constructor.name} is not a facet — only sub-agents (spawned via \`subAgent()\`) have a parent.`);
 		if (cls.name !== parent.className) throw new Error(`parentAgent(${cls.name}): this facet's recorded parent class is "${parent.className}", not "${cls.name}". Pass the class whose constructor actually spawned this facet.`);
-		const binding = this.env[cls.name];
-		if (!binding) throw new Error(`parentAgent(${cls.name}): no top-level binding "${cls.name}" found in env. If the parent is bound under a different name (e.g. "MY_${cls.name.toUpperCase()}"), use \`getAgentByName(env.MY_${cls.name.toUpperCase()}, this.parentPath.at(-1)!.name)\` directly.`);
+		if (this._parentPath.length > 1) return await this._cf_parentAgentFacetProxy(cls.name, this._parentPath);
+		const binding = this._cf_getTopLevelNamespaceByClassName(cls.name);
+		if (!binding) throw new Error(`parentAgent(${cls.name}): no top-level namespace for "${cls.name}" was found in env or worker exports. Make sure the parent class is exported under that class name and registered as a Durable Object binding.`);
 		return await getServerByName(binding, parent.name);
 	}
+	_cf_getTopLevelNamespaceByClassName(className) {
+		return this._cf_asDurableObjectNamespace(this.env[className]) ?? this._cf_asDurableObjectNamespace(exports[className]);
+	}
+	_cf_asDurableObjectNamespace(candidate) {
+		const binding = candidate;
+		return binding?.idFromName ? binding : void 0;
+	}
+	async _cf_parentAgentFacetProxy(className, parentPath) {
+		const [root] = parentPath;
+		if (!root) throw new Error(`parentAgent(${className}): parent path is empty.`);
+		const rootBinding = this._cf_getTopLevelNamespaceByClassName(root.className);
+		if (!rootBinding) throw new Error(`parentAgent(${className}): direct parent is a facet, but no top-level root namespace "${root.className}" was found in env or worker exports to bridge the call.`);
+		const rootStubPromise = getServerByName(rootBinding, root.name);
+		const targetPath = parentPath.map((step) => ({ ...step }));
+		const invokeBridge = async (method, args) => {
+			return await (await rootStubPromise)._cf_invokeSubAgentPath(targetPath, method, args);
+		};
+		const owner = this;
+		return new Proxy({}, { get(_target, prop) {
+			if (isInternalJsStubProp(prop)) return void 0;
+			if (typeof prop !== "string") return void 0;
+			if (prop === "fetch") return async (input, init) => {
+				if (owner._cf_isWebSocketUpgradeRequest(input, init)) throw new Error(`parentAgent(${className}).fetch() does not support WebSocket upgrade requests yet. Use externally routed sub-agent URLs for WebSocket connections.`);
+				return await invokeBridge(prop, [input, init]);
+			};
+			return async (...args) => {
+				return await invokeBridge(prop, args);
+			};
+		} });
+	}
+	_cf_isWebSocketUpgradeRequest(input, init) {
+		const initHeaders = init?.headers ? new Headers(init.headers) : void 0;
+		const requestHeaders = input instanceof Request ? new Headers(input.headers) : void 0;
+		return initHeaders?.get("Upgrade")?.toLowerCase() === "websocket" || requestHeaders?.get("Upgrade")?.toLowerCase() === "websocket";
+	}
 	/**
 	* Get or create a named sub-agent — a child Durable Object (facet)
 	* with its own isolated SQLite storage running on the same machine.
@@ -3796,13 +4333,13 @@ var Agent = class Agent extends Server {
 		if (!Cls) throw new Error(`Sub-agent class "${className}" not found in worker exports. Make sure the class is exported from your worker entry point and that the export name matches the class name.`);
 		if (name.includes("\0")) throw new Error(`Sub-agent name contains null character (\\0), which is reserved.`);
 		const facetKey = `${className}\0${name}`;
-		const parentClassName = this.constructor.name;
-		const parentNs = ctx.exports[parentClassName];
-		if (!parentNs?.idFromName) {
-			const minificationHint = /^_*[a-z][a-z0-9]{0,2}$/.test(parentClassName) ? ` The class name "${parentClassName}" looks minified — make sure your bundler preserves class names (e.g. esbuild's \`keepNames: true\`).` : "";
-			throw new Error(`Sub-agent bootstrap requires the parent class "${parentClassName}" to be bound as a Durable Object namespace, but ctx.exports["${parentClassName}"] is missing or doesn't expose idFromName.${minificationHint} Make sure the parent agent class is registered in your wrangler.jsonc durable_objects.bindings under its class name.`);
+		const rootClassName = this._parentPath[0]?.className ?? this.constructor.name;
+		const rootNs = ctx.exports[rootClassName];
+		if (!rootNs?.idFromName) {
+			const minificationHint = /^_*[a-z][a-z0-9]{0,2}$/.test(rootClassName) ? ` The class name "${rootClassName}" looks minified — make sure your bundler preserves class names (e.g. esbuild's \`keepNames: true\`).` : "";
+			throw new Error(`Sub-agent bootstrap requires the root agent class "${rootClassName}" to be available as a Durable Object namespace, but ctx.exports["${rootClassName}"] is missing or doesn't expose idFromName.${minificationHint} Make sure the root agent class is exported under that class name and registered in your wrangler.jsonc durable_objects.bindings.`);
 		}
-		const facetId = parentNs.idFromName(name);
+		const facetId = rootNs.idFromName(name);
 		const stub = ctx.facets.get(facetKey, () => ({
 			class: Cls,
 			id: facetId
@@ -3955,6 +4492,7 @@ var Agent = class Agent extends Server {
 		this.sql`DROP TABLE IF EXISTS cf_agents_workflows`;
 		this.sql`DROP TABLE IF EXISTS cf_agents_sub_agents`;
 		this.sql`DROP TABLE IF EXISTS cf_agents_runs`;
+		this.sql`DROP TABLE IF EXISTS cf_agents_fibers`;
 		this.sql`DROP TABLE IF EXISTS cf_agents_facet_runs`;
 		this.sql`DROP TABLE IF EXISTS cf_agent_tool_runs`;
 	}