agents 0.9.0 → 0.10.0

package/dist/experimental/forever.js

@@ -1,338 +0,0 @@
-import { AsyncLocalStorage } from "node:async_hooks";
-import { nanoid } from "nanoid";
-//#region src/experimental/forever.ts
-/**
-* !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
-* !! WARNING: EXPERIMENTAL — DO NOT USE IN PRODUCTION                  !!
-* !!                                                                   !!
-* !! This API is under active development and WILL break between       !!
-* !! releases. Method names, types, behavior, and the mixin signature  !!
-* !! are all subject to change without notice.                         !!
-* !!                                                                   !!
-* !! If you use this, pin your agents version and expect to rewrite    !!
-* !! your code when upgrading.                                         !!
-* !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
-*
-* Experimental fiber mixin for durable long-running execution.
-*
-* Usage:
-*   import { Agent } from "agents";
-*   import { withFibers } from "agents/experimental/forever";
-*
-*   class MyAgent extends withFibers(Agent)<Env, State> {
-*     async doWork(payload, fiberCtx) { ... }
-*   }
-*
-* This mixin adds:
-* - keepAlive() — keep the DO alive via scheduled heartbeats
-* - spawnFiber() — fire-and-forget durable execution
-* - stashFiber() — checkpoint progress that survives eviction
-* - cancelFiber() / getFiber() — manage running fibers
-* - onFiberComplete / onFiberRecovered / onFibersRecovered — lifecycle hooks
-*
-* @experimental This API is not yet stable and may change.
-*/
-const FIBER_CLEANUP_INTERVAL_MS = 600 * 1e3;
-const FIBER_CLEANUP_COMPLETED_MS = 1440 * 60 * 1e3;
-const FIBER_CLEANUP_FAILED_MS = 10080 * 60 * 1e3;
-const fiberContext = new AsyncLocalStorage();
-function withFibers(Base, options) {
-	const debugEnabled = options?.debugFibers ?? false;
-	class FiberAgent extends Base {
-		constructor(...args) {
-			super(...args);
-			this._fiberActiveFibers = /* @__PURE__ */ new Set();
-			this._fiberRecoveryInProgress = false;
-			this._fiberLastCleanupTime = 0;
-			console.warn("[agents/experimental/forever] WARNING: You are using an experimental API that WILL break between releases. Use with caution.");
-			this.sql`
-        CREATE TABLE IF NOT EXISTS cf_agents_fibers (
-          id TEXT PRIMARY KEY NOT NULL,
-          callback TEXT NOT NULL,
-          payload TEXT,
-          snapshot TEXT,
-          status TEXT NOT NULL DEFAULT 'running'
-            CHECK(status IN ('running', 'completed', 'failed', 'interrupted', 'cancelled')),
-          retry_count INTEGER NOT NULL DEFAULT 0,
-          max_retries INTEGER NOT NULL DEFAULT 3,
-          result TEXT,
-          error TEXT,
-          started_at INTEGER,
-          updated_at INTEGER,
-          completed_at INTEGER,
-          created_at INTEGER NOT NULL
-        )
-      `;
-		}
-		/** @internal */ _fiberDebug(msg, ...args) {
-			if (debugEnabled) console.debug(`[fiber] ${msg}`, ...args);
-		}
-		/** @internal */ async _onAlarmHousekeeping() {
-			await this._checkInterruptedFibers();
-		}
-		spawnFiber(methodName, payload, options) {
-			this._maybeCleanupFibers();
-			const name = methodName;
-			if (typeof this[methodName] !== "function") throw new Error(`this.${name} is not a function`);
-			const id = nanoid();
-			const now = Date.now();
-			const maxRetries = options?.maxRetries ?? 3;
-			this.sql`
-        INSERT INTO cf_agents_fibers (id, callback, payload, status, max_retries, retry_count, started_at, updated_at, created_at)
-        VALUES (${id}, ${name}, ${JSON.stringify(payload ?? null)}, 'running', ${maxRetries}, 0, ${now}, ${now}, ${now})
-      `;
-			this._fiberActiveFibers.add(id);
-			this._fiberDebug("spawned fiber=%s method=%s maxRetries=%d", id, name, maxRetries);
-			this._startFiber(id, name, payload, maxRetries).catch((e) => {
-				console.error(`Unhandled error in fiber ${id}:`, e);
-			});
-			return id;
-		}
-		stashFiber(data) {
-			const ctx = fiberContext.getStore();
-			if (!ctx) throw new Error("stashFiber() can only be called within a fiber execution context");
-			const now = Date.now();
-			this.sql`
-        UPDATE cf_agents_fibers
-        SET snapshot = ${JSON.stringify(data)}, updated_at = ${now}
-        WHERE id = ${ctx.fiberId}
-      `;
-			this._fiberDebug("stash fiber=%s", ctx.fiberId);
-		}
-		/**
-		* Note: cancellation is cooperative. The status is set to 'cancelled'
-		* in SQLite, and the _runFiber retry loop checks for this status at
-		* the top of each iteration.
-		*/
-		cancelFiber(fiberId) {
-			const fiber = this._getRawFiber(fiberId);
-			if (!fiber) return false;
-			if (fiber.status === "completed" || fiber.status === "failed" || fiber.status === "cancelled") return false;
-			const now = Date.now();
-			this.sql`
-        UPDATE cf_agents_fibers
-        SET status = 'cancelled', updated_at = ${now}
-        WHERE id = ${fiberId}
-      `;
-			this._fiberActiveFibers.delete(fiberId);
-			this._fiberDebug("cancelled fiber=%s", fiberId);
-			return true;
-		}
-		getFiber(fiberId) {
-			const raw = this._getRawFiber(fiberId);
-			if (!raw) return null;
-			return this._toFiberState(raw);
-		}
-		restartFiber(fiberId) {
-			const fiber = this._getRawFiber(fiberId);
-			if (!fiber) throw new Error(`Fiber ${fiberId} not found`);
-			const now = Date.now();
-			this.sql`
-        UPDATE cf_agents_fibers
-        SET status = 'running', started_at = ${now}, updated_at = ${now}
-        WHERE id = ${fiberId}
-      `;
-			this._fiberActiveFibers.add(fiberId);
-			this._fiberDebug("restarting fiber=%s method=%s retryCount=%d", fiberId, fiber.callback, fiber.retry_count);
-			const parsedPayload = fiber.payload ? JSON.parse(fiber.payload) : void 0;
-			this._startFiber(fiberId, fiber.callback, parsedPayload, fiber.max_retries).catch((e) => {
-				console.error(`Error restarting fiber ${fiberId}:`, e);
-			});
-		}
-		/**
-		* Manually trigger fiber recovery check.
-		* In production, this runs automatically via the heartbeat schedule.
-		* Useful for testing or when you need immediate recovery after
-		* detecting an eviction.
-		*/
-		async checkFibers() {
-			await this._checkInterruptedFibers();
-		}
-		onFiberComplete(_ctx) {}
-		onFiberRecovered(ctx) {
-			this.restartFiber(ctx.id);
-		}
-		async onFibersRecovered(fibers) {
-			for (const fiber of fibers) await this.onFiberRecovered(fiber);
-		}
-		/** @internal */ _getRawFiber(fiberId) {
-			const result = this.sql`
-        SELECT * FROM cf_agents_fibers WHERE id = ${fiberId}
-      `;
-			return result && result.length > 0 ? result[0] : null;
-		}
-		/** @internal */ _safeJsonParse(value) {
-			if (value === null) return null;
-			try {
-				return JSON.parse(value);
-			} catch {
-				return null;
-			}
-		}
-		/** @internal */ _toFiberState(raw) {
-			return {
-				id: raw.id,
-				callback: raw.callback,
-				payload: this._safeJsonParse(raw.payload),
-				snapshot: this._safeJsonParse(raw.snapshot),
-				status: raw.status,
-				retryCount: raw.retry_count,
-				maxRetries: raw.max_retries,
-				result: this._safeJsonParse(raw.result),
-				error: raw.error,
-				startedAt: raw.started_at,
-				updatedAt: raw.updated_at,
-				completedAt: raw.completed_at,
-				createdAt: raw.created_at
-			};
-		}
-		/** @internal */ async _startFiber(id, methodName, payload, maxRetries) {
-			const disposeKeepAlive = await this.keepAlive();
-			await this._runFiber(id, methodName, payload, maxRetries, disposeKeepAlive);
-		}
-		/** @internal */ async _runFiber(id, methodName, payload, maxRetries, disposeKeepAlive) {
-			try {
-				while (true) {
-					const fiber = this._getRawFiber(id);
-					if (!fiber || fiber.status === "cancelled") {
-						this._fiberDebug("fiber=%s exiting: %s", id, !fiber ? "not found" : "cancelled");
-						return;
-					}
-					try {
-						await fiberContext.run({ fiberId: id }, async () => {
-							const snapshot = this._safeJsonParse(fiber.snapshot);
-							const retryCount = fiber.retry_count;
-							const callback = this[methodName];
-							if (typeof callback !== "function") throw new Error(`Fiber method ${methodName} not found`);
-							const result = await callback.call(this, payload, {
-								id,
-								snapshot,
-								retryCount
-							});
-							const now = Date.now();
-							this.sql`
-                UPDATE cf_agents_fibers
-                SET status = 'completed',
-                    result = ${JSON.stringify(result ?? null)},
-                    completed_at = ${now},
-                    updated_at = ${now}
-                WHERE id = ${id}
-              `;
-							this._fiberDebug("fiber=%s completed method=%s", id, methodName);
-							try {
-								await this.onFiberComplete({
-									id,
-									methodName,
-									payload,
-									result
-								});
-							} catch (e) {
-								console.error("Error in onFiberComplete:", e);
-							}
-						});
-						return;
-					} catch (e) {
-						const now = Date.now();
-						const newRetryCount = (this._getRawFiber(id)?.retry_count ?? 0) + 1;
-						if (newRetryCount > maxRetries) {
-							const errorMsg = e instanceof Error ? e.message : String(e);
-							this.sql`
-                UPDATE cf_agents_fibers
-                SET status = 'failed',
-                    error = ${errorMsg},
-                    retry_count = ${newRetryCount},
-                    updated_at = ${now}
-                WHERE id = ${id}
-              `;
-							this._fiberDebug("fiber=%s failed after %d retries: %s", id, newRetryCount, errorMsg);
-							return;
-						}
-						this.sql`
-              UPDATE cf_agents_fibers
-              SET retry_count = ${newRetryCount}, updated_at = ${now}
-              WHERE id = ${id}
-            `;
-						this._fiberDebug("fiber=%s retrying (%d/%d)", id, newRetryCount, maxRetries);
-						continue;
-					}
-				}
-			} finally {
-				this._fiberActiveFibers.delete(id);
-				disposeKeepAlive();
-			}
-		}
-		/** @internal */ async _checkInterruptedFibers() {
-			if (this._fiberRecoveryInProgress) return;
-			this._fiberRecoveryInProgress = true;
-			try {
-				const runningFibers = this.sql`
-          SELECT * FROM cf_agents_fibers
-          WHERE status = 'running'
-          ORDER BY created_at ASC
-        `;
-				if (!runningFibers || runningFibers.length === 0) return;
-				const interrupted = [];
-				for (const fiber of runningFibers) {
-					if (this._fiberActiveFibers.has(fiber.id)) continue;
-					const newRetryCount = fiber.retry_count + 1;
-					const now = Date.now();
-					if (newRetryCount > fiber.max_retries) {
-						this.sql`
-              UPDATE cf_agents_fibers
-              SET status = 'failed',
-                  error = 'max retries exceeded (eviction recovery)',
-                  retry_count = ${newRetryCount},
-                  updated_at = ${now}
-              WHERE id = ${fiber.id}
-            `;
-						this._fiberDebug("fiber=%s max retries exceeded on recovery", fiber.id);
-					} else {
-						this.sql`
-              UPDATE cf_agents_fibers
-              SET status = 'interrupted',
-                  retry_count = ${newRetryCount},
-                  updated_at = ${now}
-              WHERE id = ${fiber.id}
-            `;
-						interrupted.push({
-							id: fiber.id,
-							methodName: fiber.callback,
-							payload: this._safeJsonParse(fiber.payload),
-							snapshot: this._safeJsonParse(fiber.snapshot),
-							retryCount: newRetryCount
-						});
-					}
-				}
-				if (interrupted.length > 0) {
-					this._fiberDebug("recovering %d interrupted fibers", interrupted.length);
-					try {
-						await this.onFibersRecovered(interrupted);
-					} catch (e) {
-						console.error("Error in onFibersRecovered:", e);
-					}
-				}
-			} finally {
-				this._fiberRecoveryInProgress = false;
-			}
-		}
-		/** @internal */ _maybeCleanupFibers() {
-			const now = Date.now();
-			if (now - this._fiberLastCleanupTime < FIBER_CLEANUP_INTERVAL_MS) return;
-			this._fiberLastCleanupTime = now;
-			const completedCutoff = now - FIBER_CLEANUP_COMPLETED_MS;
-			const failedCutoff = now - FIBER_CLEANUP_FAILED_MS;
-			this.sql`
-        DELETE FROM cf_agents_fibers
-        WHERE (status = 'completed' AND completed_at < ${completedCutoff})
-           OR (status = 'failed' AND updated_at < ${failedCutoff})
-           OR (status = 'cancelled' AND updated_at < ${completedCutoff})
-      `;
-			this._fiberDebug("cleanup: checked for old completed/failed/cancelled fibers");
-		}
-	}
-	return FiberAgent;
-}
-//#endregion
-export { withFibers };
-
-//# sourceMappingURL=forever.js.map

package/dist/experimental/forever.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"forever.js","names":[],"sources":["../../src/experimental/forever.ts"],"sourcesContent":["/**\n * !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!\n * !! WARNING: EXPERIMENTAL — DO NOT USE IN PRODUCTION                  !!\n * !!                                                                   !!\n * !! This API is under active development and WILL break between       !!\n * !! releases. Method names, types, behavior, and the mixin signature  !!\n * !! are all subject to change without notice.                         !!\n * !!                                                                   !!\n * !! If you use this, pin your agents version and expect to rewrite    !!\n * !! your code when upgrading.                                         !!\n * !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!\n *\n * Experimental fiber mixin for durable long-running execution.\n *\n * Usage:\n *   import { Agent } from \"agents\";\n *   import { withFibers } from \"agents/experimental/forever\";\n *\n *   class MyAgent extends withFibers(Agent)<Env, State> {\n *     async doWork(payload, fiberCtx) { ... }\n *   }\n *\n * This mixin adds:\n * - keepAlive() — keep the DO alive via scheduled heartbeats\n * - spawnFiber() — fire-and-forget durable execution\n * - stashFiber() — checkpoint progress that survives eviction\n * - cancelFiber() / getFiber() — manage running fibers\n * - onFiberComplete / onFiberRecovered / onFibersRecovered — lifecycle hooks\n *\n * @experimental This API is not yet stable and may change.\n */\nimport { AsyncLocalStorage } from \"node:async_hooks\";\nimport { nanoid } from \"nanoid\";\nimport type { Agent } from \"../index\";\n\n// ── Types ─────────────────────────────────────────────────────────────\n\nexport type FiberState = {\n  id: string;\n  callback: string;\n  payload: unknown;\n  snapshot: unknown | null;\n  status: \"running\" | \"completed\" | \"failed\" | \"interrupted\" | \"cancelled\";\n  retryCount: number;\n  maxRetries: number;\n  result: unknown | null;\n  error: string | null;\n  startedAt: number | null;\n  updatedAt: number | null;\n  completedAt: number | null;\n  createdAt: number;\n};\n\nexport type FiberRecoveryContext = {\n  id: string;\n  methodName: string;\n  payload: unknown;\n  snapshot: unknown | null;\n  retryCount: number;\n};\n\nexport type FiberContext = {\n  id: string;\n  snapshot: unknown | null;\n  retryCount: number;\n};\n\nexport type FiberCompleteContext = {\n  id: string;\n  methodName: string;\n  payload: unknown;\n  result: unknown;\n};\n\n// ── Internal types ────────────────────────────────────────────────────\n\ntype RawFiberRow = {\n  id: string;\n  callback: string;\n  payload: string | null;\n  snapshot: string | null;\n  status: string;\n  retry_count: number;\n  max_retries: number;\n  result: string | null;\n  error: string | null;\n  started_at: number | null;\n  updated_at: number | null;\n  completed_at: number | null;\n  created_at: number;\n};\n\n// ── Constants ─────────────────────────────────────────────────────────\n\nconst FIBER_CLEANUP_INTERVAL_MS = 10 * 60 * 1000;\nconst FIBER_CLEANUP_COMPLETED_MS = 24 * 60 * 60 * 1000;\nconst FIBER_CLEANUP_FAILED_MS = 7 * 24 * 60 * 60 * 1000;\n\nconst fiberContext = new AsyncLocalStorage<{ fiberId: string }>();\n\n// ── Mixin ─────────────────────────────────────────────────────────────\n\n// oxlint-disable-next-line @typescript-eslint/no-explicit-any -- mixin constructor pattern\ntype AgentConstructor = new (...args: any[]) => Agent;\n\nexport function withFibers<TBase extends typeof Agent>(\n  Base: TBase,\n  options?: { debugFibers?: boolean }\n) {\n  const debugEnabled = options?.debugFibers ?? false;\n\n  class FiberAgent extends (Base as AgentConstructor) {\n    // ── Fiber state ───────────────────────────────────────────────\n\n    /** @internal */ _fiberActiveFibers = new Set<string>();\n    /** @internal */ _fiberRecoveryInProgress = false;\n    /** @internal */ _fiberLastCleanupTime = 0;\n\n    // oxlint-disable-next-line @typescript-eslint/no-explicit-any -- mixin constructor\n    constructor(...args: any[]) {\n      super(...args);\n\n      console.warn(\n        \"[agents/experimental/forever] WARNING: You are using an experimental API that WILL break between releases. Use with caution.\"\n      );\n\n      // Create the fibers table\n      this.sql`\n        CREATE TABLE IF NOT EXISTS cf_agents_fibers (\n          id TEXT PRIMARY KEY NOT NULL,\n          callback TEXT NOT NULL,\n          payload TEXT,\n          snapshot TEXT,\n          status TEXT NOT NULL DEFAULT 'running'\n            CHECK(status IN ('running', 'completed', 'failed', 'interrupted', 'cancelled')),\n          retry_count INTEGER NOT NULL DEFAULT 0,\n          max_retries INTEGER NOT NULL DEFAULT 3,\n          result TEXT,\n          error TEXT,\n          started_at INTEGER,\n          updated_at INTEGER,\n          completed_at INTEGER,\n          created_at INTEGER NOT NULL\n        )\n      `;\n    }\n\n    // ── Debug logging ─────────────────────────────────────────────\n\n    /** @internal */ _fiberDebug(msg: string, ...args: unknown[]) {\n      if (debugEnabled) {\n        console.debug(`[fiber] ${msg}`, ...args);\n      }\n    }\n\n    // ── Alarm housekeeping override ─────────────────────────────────\n\n    /** @internal */ async _onAlarmHousekeeping() {\n      await this._checkInterruptedFibers();\n    }\n\n    // ── Public API ────────────────────────────────────────────────\n\n    spawnFiber(\n      methodName: keyof this,\n      payload?: unknown,\n      options?: { maxRetries?: number }\n    ): string {\n      this._maybeCleanupFibers();\n\n      const name = methodName as string;\n      if (typeof this[methodName] !== \"function\") {\n        throw new Error(`this.${name} is not a function`);\n      }\n\n      const id = nanoid();\n      const now = Date.now();\n      const maxRetries = options?.maxRetries ?? 3;\n\n      this.sql`\n        INSERT INTO cf_agents_fibers (id, callback, payload, status, max_retries, retry_count, started_at, updated_at, created_at)\n        VALUES (${id}, ${name}, ${JSON.stringify(payload ?? null)}, 'running', ${maxRetries}, 0, ${now}, ${now}, ${now})\n      `;\n\n      this._fiberActiveFibers.add(id);\n      this._fiberDebug(\n        \"spawned fiber=%s method=%s maxRetries=%d\",\n        id,\n        name,\n        maxRetries\n      );\n\n      void this._startFiber(id, name, payload, maxRetries).catch((e) => {\n        console.error(`Unhandled error in fiber ${id}:`, e);\n      });\n\n      return id;\n    }\n\n    stashFiber(data: unknown): void {\n      const ctx = fiberContext.getStore();\n      if (!ctx) {\n        throw new Error(\n          \"stashFiber() can only be called within a fiber execution context\"\n        );\n      }\n      const now = Date.now();\n      this.sql`\n        UPDATE cf_agents_fibers\n        SET snapshot = ${JSON.stringify(data)}, updated_at = ${now}\n        WHERE id = ${ctx.fiberId}\n      `;\n      this._fiberDebug(\"stash fiber=%s\", ctx.fiberId);\n    }\n\n    /**\n     * Note: cancellation is cooperative. The status is set to 'cancelled'\n     * in SQLite, and the _runFiber retry loop checks for this status at\n     * the top of each iteration.\n     */\n    cancelFiber(fiberId: string): boolean {\n      const fiber = this._getRawFiber(fiberId);\n      if (!fiber) return false;\n      if (\n        fiber.status === \"completed\" ||\n        fiber.status === \"failed\" ||\n        fiber.status === \"cancelled\"\n      ) {\n        return false;\n      }\n\n      const now = Date.now();\n      this.sql`\n        UPDATE cf_agents_fibers\n        SET status = 'cancelled', updated_at = ${now}\n        WHERE id = ${fiberId}\n      `;\n      this._fiberActiveFibers.delete(fiberId);\n      this._fiberDebug(\"cancelled fiber=%s\", fiberId);\n      return true;\n    }\n\n    getFiber(fiberId: string): FiberState | null {\n      const raw = this._getRawFiber(fiberId);\n      if (!raw) return null;\n      return this._toFiberState(raw);\n    }\n\n    restartFiber(fiberId: string): void {\n      const fiber = this._getRawFiber(fiberId);\n      if (!fiber) {\n        throw new Error(`Fiber ${fiberId} not found`);\n      }\n\n      const now = Date.now();\n      this.sql`\n        UPDATE cf_agents_fibers\n        SET status = 'running', started_at = ${now}, updated_at = ${now}\n        WHERE id = ${fiberId}\n      `;\n\n      this._fiberActiveFibers.add(fiberId);\n      this._fiberDebug(\n        \"restarting fiber=%s method=%s retryCount=%d\",\n        fiberId,\n        fiber.callback,\n        fiber.retry_count\n      );\n\n      const parsedPayload = fiber.payload\n        ? JSON.parse(fiber.payload)\n        : undefined;\n\n      void this._startFiber(\n        fiberId,\n        fiber.callback,\n        parsedPayload,\n        fiber.max_retries\n      ).catch((e) => {\n        console.error(`Error restarting fiber ${fiberId}:`, e);\n      });\n    }\n\n    // ── Lifecycle hooks (override in subclass) ────────────────────\n\n    /**\n     * Manually trigger fiber recovery check.\n     * In production, this runs automatically via the heartbeat schedule.\n     * Useful for testing or when you need immediate recovery after\n     * detecting an eviction.\n     */\n    async checkFibers(): Promise<void> {\n      await this._checkInterruptedFibers();\n    }\n\n    // oxlint-disable-next-line @typescript-eslint/no-unused-vars -- overridable hook\n    onFiberComplete(_ctx: FiberCompleteContext): void | Promise<void> {}\n\n    onFiberRecovered(ctx: FiberRecoveryContext): void | Promise<void> {\n      this.restartFiber(ctx.id);\n    }\n\n    async onFibersRecovered(fibers: FiberRecoveryContext[]): Promise<void> {\n      for (const fiber of fibers) {\n        await this.onFiberRecovered(fiber);\n      }\n    }\n\n    // ── Private implementation ────────────────────────────────────\n\n    /** @internal */ _getRawFiber(fiberId: string): RawFiberRow | null {\n      const result = this.sql<RawFiberRow>`\n        SELECT * FROM cf_agents_fibers WHERE id = ${fiberId}\n      `;\n      return result && result.length > 0 ? result[0] : null;\n    }\n\n    /** @internal */ _safeJsonParse(value: string | null): unknown {\n      if (value === null) return null;\n      try {\n        return JSON.parse(value);\n      } catch {\n        return null;\n      }\n    }\n\n    /** @internal */ _toFiberState(raw: RawFiberRow): FiberState {\n      return {\n        id: raw.id,\n        callback: raw.callback,\n        payload: this._safeJsonParse(raw.payload),\n        snapshot: this._safeJsonParse(raw.snapshot),\n        status: raw.status as FiberState[\"status\"],\n        retryCount: raw.retry_count,\n        maxRetries: raw.max_retries,\n        result: this._safeJsonParse(raw.result),\n        error: raw.error,\n        startedAt: raw.started_at,\n        updatedAt: raw.updated_at,\n        completedAt: raw.completed_at,\n        createdAt: raw.created_at\n      };\n    }\n\n    /** @internal */ async _startFiber(\n      id: string,\n      methodName: string,\n      payload: unknown,\n      maxRetries: number\n    ): Promise<void> {\n      const disposeKeepAlive = await this.keepAlive();\n      await this._runFiber(\n        id,\n        methodName,\n        payload,\n        maxRetries,\n        disposeKeepAlive\n      );\n    }\n\n    /** @internal */ async _runFiber(\n      id: string,\n      methodName: string,\n      payload: unknown,\n      maxRetries: number,\n      disposeKeepAlive: () => void\n    ): Promise<void> {\n      try {\n        while (true) {\n          const fiber = this._getRawFiber(id);\n          if (!fiber || fiber.status === \"cancelled\") {\n            this._fiberDebug(\n              \"fiber=%s exiting: %s\",\n              id,\n              !fiber ? \"not found\" : \"cancelled\"\n            );\n            return;\n          }\n\n          try {\n            await fiberContext.run({ fiberId: id }, async () => {\n              const snapshot = this._safeJsonParse(fiber.snapshot);\n              const retryCount = fiber.retry_count;\n\n              const callback = this[methodName as keyof this];\n              if (typeof callback !== \"function\") {\n                throw new Error(`Fiber method ${methodName} not found`);\n              }\n\n              const result = await (\n                callback as (p: unknown, ctx: FiberContext) => Promise<unknown>\n              ).call(this, payload, { id, snapshot, retryCount });\n\n              const now = Date.now();\n              this.sql`\n                UPDATE cf_agents_fibers\n                SET status = 'completed',\n                    result = ${JSON.stringify(result ?? null)},\n                    completed_at = ${now},\n                    updated_at = ${now}\n                WHERE id = ${id}\n              `;\n\n              this._fiberDebug(\"fiber=%s completed method=%s\", id, methodName);\n\n              try {\n                await this.onFiberComplete({\n                  id,\n                  methodName,\n                  payload,\n                  result\n                });\n              } catch (e) {\n                console.error(\"Error in onFiberComplete:\", e);\n              }\n            });\n\n            return;\n          } catch (e) {\n            const now = Date.now();\n            const currentFiber = this._getRawFiber(id);\n            const newRetryCount = (currentFiber?.retry_count ?? 0) + 1;\n\n            if (newRetryCount > maxRetries) {\n              const errorMsg = e instanceof Error ? e.message : String(e);\n              this.sql`\n                UPDATE cf_agents_fibers\n                SET status = 'failed',\n                    error = ${errorMsg},\n                    retry_count = ${newRetryCount},\n                    updated_at = ${now}\n                WHERE id = ${id}\n              `;\n              this._fiberDebug(\n                \"fiber=%s failed after %d retries: %s\",\n                id,\n                newRetryCount,\n                errorMsg\n              );\n              return;\n            }\n\n            this.sql`\n              UPDATE cf_agents_fibers\n              SET retry_count = ${newRetryCount}, updated_at = ${now}\n              WHERE id = ${id}\n            `;\n            this._fiberDebug(\n              \"fiber=%s retrying (%d/%d)\",\n              id,\n              newRetryCount,\n              maxRetries\n            );\n            continue;\n          }\n        }\n      } finally {\n        this._fiberActiveFibers.delete(id);\n        disposeKeepAlive();\n      }\n    }\n\n    /** @internal */ async _checkInterruptedFibers(): Promise<void> {\n      if (this._fiberRecoveryInProgress) return;\n      this._fiberRecoveryInProgress = true;\n\n      try {\n        const runningFibers = this.sql<RawFiberRow>`\n          SELECT * FROM cf_agents_fibers\n          WHERE status = 'running'\n          ORDER BY created_at ASC\n        `;\n\n        if (!runningFibers || runningFibers.length === 0) return;\n\n        const interrupted: FiberRecoveryContext[] = [];\n\n        for (const fiber of runningFibers) {\n          if (this._fiberActiveFibers.has(fiber.id)) continue;\n\n          const newRetryCount = fiber.retry_count + 1;\n          const now = Date.now();\n\n          if (newRetryCount > fiber.max_retries) {\n            this.sql`\n              UPDATE cf_agents_fibers\n              SET status = 'failed',\n                  error = 'max retries exceeded (eviction recovery)',\n                  retry_count = ${newRetryCount},\n                  updated_at = ${now}\n              WHERE id = ${fiber.id}\n            `;\n            this._fiberDebug(\n              \"fiber=%s max retries exceeded on recovery\",\n              fiber.id\n            );\n          } else {\n            this.sql`\n              UPDATE cf_agents_fibers\n              SET status = 'interrupted',\n                  retry_count = ${newRetryCount},\n                  updated_at = ${now}\n              WHERE id = ${fiber.id}\n            `;\n\n            interrupted.push({\n              id: fiber.id,\n              methodName: fiber.callback,\n              payload: this._safeJsonParse(fiber.payload),\n              snapshot: this._safeJsonParse(fiber.snapshot),\n              retryCount: newRetryCount\n            });\n          }\n        }\n\n        if (interrupted.length > 0) {\n          this._fiberDebug(\n            \"recovering %d interrupted fibers\",\n            interrupted.length\n          );\n\n          try {\n            await this.onFibersRecovered(interrupted);\n          } catch (e) {\n            console.error(\"Error in onFibersRecovered:\", e);\n          }\n        }\n      } finally {\n        this._fiberRecoveryInProgress = false;\n      }\n    }\n\n    /** @internal */ _maybeCleanupFibers() {\n      const now = Date.now();\n      if (now - this._fiberLastCleanupTime < FIBER_CLEANUP_INTERVAL_MS) {\n        return;\n      }\n      this._fiberLastCleanupTime = now;\n\n      const completedCutoff = now - FIBER_CLEANUP_COMPLETED_MS;\n      const failedCutoff = now - FIBER_CLEANUP_FAILED_MS;\n\n      this.sql`\n        DELETE FROM cf_agents_fibers\n        WHERE (status = 'completed' AND completed_at < ${completedCutoff})\n           OR (status = 'failed' AND updated_at < ${failedCutoff})\n           OR (status = 'cancelled' AND updated_at < ${completedCutoff})\n      `;\n\n      this._fiberDebug(\n        \"cleanup: checked for old completed/failed/cancelled fibers\"\n      );\n    }\n  }\n\n  return FiberAgent as unknown as FiberAgentClass;\n}\n\n// ── Return type ──────────────────────────────────────────────────────\n//\n// Explicit generic constructor so consumers can write:\n//   const FA = withFibers(Agent);\n//   class MyAgent extends FA<Env> { ... }\n// and still see all FiberMethods on `this`.\n//\n// We define this as a standalone constructor (not intersected with\n// typeof Agent) to avoid overload-resolution issues where TypeScript\n// would pick Agent's constructor and lose FiberMethods.\n\ntype FiberAgentClass = {\n  new <\n    Env extends Cloudflare.Env = Cloudflare.Env,\n    State = unknown,\n    Props extends Record<string, unknown> = Record<string, unknown>\n  >(\n    ctx: DurableObjectState,\n    env: Env\n  ): Agent<Env, State, Props> & FiberMethods;\n};\n\n// ── FiberMethods interface ───────────────────────────────────────────\n//\n// Describes the methods added by the mixin. Exported so users can\n// reference the shape in their own type annotations if needed.\n\nexport interface FiberMethods {\n  spawnFiber(\n    methodName: string,\n    payload?: unknown,\n    options?: { maxRetries?: number }\n  ): string;\n  stashFiber(data: unknown): void;\n  cancelFiber(fiberId: string): boolean;\n  getFiber(fiberId: string): FiberState | null;\n  restartFiber(fiberId: string): void;\n  checkFibers(): Promise<void>;\n  onFiberComplete(ctx: FiberCompleteContext): void | Promise<void>;\n  onFiberRecovered(ctx: FiberRecoveryContext): void | Promise<void>;\n  onFibersRecovered(fibers: FiberRecoveryContext[]): Promise<void>;\n\n  /** @internal */ _fiberActiveFibers: Set<string>;\n  /** @internal */ _fiberRecoveryInProgress: boolean;\n  /** @internal */ _fiberLastCleanupTime: number;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA8FA,MAAM,4BAA4B,MAAU;AAC5C,MAAM,6BAA6B,OAAU,KAAK;AAClD,MAAM,0BAA0B,QAAc,KAAK;AAEnD,MAAM,eAAe,IAAI,mBAAwC;AAOjE,SAAgB,WACd,MACA,SACA;CACA,MAAM,eAAe,SAAS,eAAe;CAE7C,MAAM,mBAAoB,KAA0B;EAQlD,YAAY,GAAG,MAAa;AAC1B,SAAM,GAAG,KAAK;AANC,QAAA,qCAAqB,IAAI,KAAa;AACtC,QAAA,2BAA2B;AAC3B,QAAA,wBAAwB;AAMvC,WAAQ,KACN,+HACD;AAGD,QAAK,GAAG;;;;;;;;;;;;;;;;;;;mBAsBO,YAAY,KAAa,GAAG,MAAiB;AAC5D,OAAI,aACF,SAAQ,MAAM,WAAW,OAAO,GAAG,KAAK;;mBAM3B,MAAM,uBAAuB;AAC5C,SAAM,KAAK,yBAAyB;;EAKtC,WACE,YACA,SACA,SACQ;AACR,QAAK,qBAAqB;GAE1B,MAAM,OAAO;AACb,OAAI,OAAO,KAAK,gBAAgB,WAC9B,OAAM,IAAI,MAAM,QAAQ,KAAK,oBAAoB;GAGnD,MAAM,KAAK,QAAQ;GACnB,MAAM,MAAM,KAAK,KAAK;GACtB,MAAM,aAAa,SAAS,cAAc;AAE1C,QAAK,GAAG;;kBAEI,GAAG,IAAI,KAAK,IAAI,KAAK,UAAU,WAAW,KAAK,CAAC,eAAe,WAAW,OAAO,IAAI,IAAI,IAAI,IAAI,IAAI;;AAGjH,QAAK,mBAAmB,IAAI,GAAG;AAC/B,QAAK,YACH,4CACA,IACA,MACA,WACD;AAEI,QAAK,YAAY,IAAI,MAAM,SAAS,WAAW,CAAC,OAAO,MAAM;AAChE,YAAQ,MAAM,4BAA4B,GAAG,IAAI,EAAE;KACnD;AAEF,UAAO;;EAGT,WAAW,MAAqB;GAC9B,MAAM,MAAM,aAAa,UAAU;AACnC,OAAI,CAAC,IACH,OAAM,IAAI,MACR,mEACD;GAEH,MAAM,MAAM,KAAK,KAAK;AACtB,QAAK,GAAG;;yBAEW,KAAK,UAAU,KAAK,CAAC,iBAAiB,IAAI;qBAC9C,IAAI,QAAQ;;AAE3B,QAAK,YAAY,kBAAkB,IAAI,QAAQ;;;;;;;EAQjD,YAAY,SAA0B;GACpC,MAAM,QAAQ,KAAK,aAAa,QAAQ;AACxC,OAAI,CAAC,MAAO,QAAO;AACnB,OACE,MAAM,WAAW,eACjB,MAAM,WAAW,YACjB,MAAM,WAAW,YAEjB,QAAO;GAGT,MAAM,MAAM,KAAK,KAAK;AACtB,QAAK,GAAG;;iDAEmC,IAAI;qBAChC,QAAQ;;AAEvB,QAAK,mBAAmB,OAAO,QAAQ;AACvC,QAAK,YAAY,sBAAsB,QAAQ;AAC/C,UAAO;;EAGT,SAAS,SAAoC;GAC3C,MAAM,MAAM,KAAK,aAAa,QAAQ;AACtC,OAAI,CAAC,IAAK,QAAO;AACjB,UAAO,KAAK,cAAc,IAAI;;EAGhC,aAAa,SAAuB;GAClC,MAAM,QAAQ,KAAK,aAAa,QAAQ;AACxC,OAAI,CAAC,MACH,OAAM,IAAI,MAAM,SAAS,QAAQ,YAAY;GAG/C,MAAM,MAAM,KAAK,KAAK;AACtB,QAAK,GAAG;;+CAEiC,IAAI,iBAAiB,IAAI;qBACnD,QAAQ;;AAGvB,QAAK,mBAAmB,IAAI,QAAQ;AACpC,QAAK,YACH,+CACA,SACA,MAAM,UACN,MAAM,YACP;GAED,MAAM,gBAAgB,MAAM,UACxB,KAAK,MAAM,MAAM,QAAQ,GACzB,KAAA;AAEC,QAAK,YACR,SACA,MAAM,UACN,eACA,MAAM,YACP,CAAC,OAAO,MAAM;AACb,YAAQ,MAAM,0BAA0B,QAAQ,IAAI,EAAE;KACtD;;;;;;;;EAWJ,MAAM,cAA6B;AACjC,SAAM,KAAK,yBAAyB;;EAItC,gBAAgB,MAAkD;EAElE,iBAAiB,KAAiD;AAChE,QAAK,aAAa,IAAI,GAAG;;EAG3B,MAAM,kBAAkB,QAA+C;AACrE,QAAK,MAAM,SAAS,OAClB,OAAM,KAAK,iBAAiB,MAAM;;mBAMrB,aAAa,SAAqC;GACjE,MAAM,SAAS,KAAK,GAAgB;oDACU,QAAQ;;AAEtD,UAAO,UAAU,OAAO,SAAS,IAAI,OAAO,KAAK;;mBAGlC,eAAe,OAA+B;AAC7D,OAAI,UAAU,KAAM,QAAO;AAC3B,OAAI;AACF,WAAO,KAAK,MAAM,MAAM;WAClB;AACN,WAAO;;;mBAIM,cAAc,KAA8B;AAC3D,UAAO;IACL,IAAI,IAAI;IACR,UAAU,IAAI;IACd,SAAS,KAAK,eAAe,IAAI,QAAQ;IACzC,UAAU,KAAK,eAAe,IAAI,SAAS;IAC3C,QAAQ,IAAI;IACZ,YAAY,IAAI;IAChB,YAAY,IAAI;IAChB,QAAQ,KAAK,eAAe,IAAI,OAAO;IACvC,OAAO,IAAI;IACX,WAAW,IAAI;IACf,WAAW,IAAI;IACf,aAAa,IAAI;IACjB,WAAW,IAAI;IAChB;;mBAGc,MAAM,YACrB,IACA,YACA,SACA,YACe;GACf,MAAM,mBAAmB,MAAM,KAAK,WAAW;AAC/C,SAAM,KAAK,UACT,IACA,YACA,SACA,YACA,iBACD;;mBAGc,MAAM,UACrB,IACA,YACA,SACA,YACA,kBACe;AACf,OAAI;AACF,WAAO,MAAM;KACX,MAAM,QAAQ,KAAK,aAAa,GAAG;AACnC,SAAI,CAAC,SAAS,MAAM,WAAW,aAAa;AAC1C,WAAK,YACH,wBACA,IACA,CAAC,QAAQ,cAAc,YACxB;AACD;;AAGF,SAAI;AACF,YAAM,aAAa,IAAI,EAAE,SAAS,IAAI,EAAE,YAAY;OAClD,MAAM,WAAW,KAAK,eAAe,MAAM,SAAS;OACpD,MAAM,aAAa,MAAM;OAEzB,MAAM,WAAW,KAAK;AACtB,WAAI,OAAO,aAAa,WACtB,OAAM,IAAI,MAAM,gBAAgB,WAAW,YAAY;OAGzD,MAAM,SAAS,MACb,SACA,KAAK,MAAM,SAAS;QAAE;QAAI;QAAU;QAAY,CAAC;OAEnD,MAAM,MAAM,KAAK,KAAK;AACtB,YAAK,GAAG;;;+BAGS,KAAK,UAAU,UAAU,KAAK,CAAC;qCACzB,IAAI;mCACN,IAAI;6BACV,GAAG;;AAGlB,YAAK,YAAY,gCAAgC,IAAI,WAAW;AAEhE,WAAI;AACF,cAAM,KAAK,gBAAgB;SACzB;SACA;SACA;SACA;SACD,CAAC;gBACK,GAAG;AACV,gBAAQ,MAAM,6BAA6B,EAAE;;QAE/C;AAEF;cACO,GAAG;MACV,MAAM,MAAM,KAAK,KAAK;MAEtB,MAAM,iBADe,KAAK,aAAa,GAAG,EACL,eAAe,KAAK;AAEzD,UAAI,gBAAgB,YAAY;OAC9B,MAAM,WAAW,aAAa,QAAQ,EAAE,UAAU,OAAO,EAAE;AAC3D,YAAK,GAAG;;;8BAGQ,SAAS;oCACH,cAAc;mCACf,IAAI;6BACV,GAAG;;AAElB,YAAK,YACH,wCACA,IACA,eACA,SACD;AACD;;AAGF,WAAK,GAAG;;kCAEc,cAAc,iBAAiB,IAAI;2BAC1C,GAAG;;AAElB,WAAK,YACH,6BACA,IACA,eACA,WACD;AACD;;;aAGI;AACR,SAAK,mBAAmB,OAAO,GAAG;AAClC,sBAAkB;;;mBAIL,MAAM,0BAAyC;AAC9D,OAAI,KAAK,yBAA0B;AACnC,QAAK,2BAA2B;AAEhC,OAAI;IACF,MAAM,gBAAgB,KAAK,GAAgB;;;;;AAM3C,QAAI,CAAC,iBAAiB,cAAc,WAAW,EAAG;IAElD,MAAM,cAAsC,EAAE;AAE9C,SAAK,MAAM,SAAS,eAAe;AACjC,SAAI,KAAK,mBAAmB,IAAI,MAAM,GAAG,CAAE;KAE3C,MAAM,gBAAgB,MAAM,cAAc;KAC1C,MAAM,MAAM,KAAK,KAAK;AAEtB,SAAI,gBAAgB,MAAM,aAAa;AACrC,WAAK,GAAG;;;;kCAIc,cAAc;iCACf,IAAI;2BACV,MAAM,GAAG;;AAExB,WAAK,YACH,6CACA,MAAM,GACP;YACI;AACL,WAAK,GAAG;;;kCAGc,cAAc;iCACf,IAAI;2BACV,MAAM,GAAG;;AAGxB,kBAAY,KAAK;OACf,IAAI,MAAM;OACV,YAAY,MAAM;OAClB,SAAS,KAAK,eAAe,MAAM,QAAQ;OAC3C,UAAU,KAAK,eAAe,MAAM,SAAS;OAC7C,YAAY;OACb,CAAC;;;AAIN,QAAI,YAAY,SAAS,GAAG;AAC1B,UAAK,YACH,oCACA,YAAY,OACb;AAED,SAAI;AACF,YAAM,KAAK,kBAAkB,YAAY;cAClC,GAAG;AACV,cAAQ,MAAM,+BAA+B,EAAE;;;aAG3C;AACR,SAAK,2BAA2B;;;mBAInB,sBAAsB;GACrC,MAAM,MAAM,KAAK,KAAK;AACtB,OAAI,MAAM,KAAK,wBAAwB,0BACrC;AAEF,QAAK,wBAAwB;GAE7B,MAAM,kBAAkB,MAAM;GAC9B,MAAM,eAAe,MAAM;AAE3B,QAAK,GAAG;;yDAE2C,gBAAgB;oDACrB,aAAa;uDACV,gBAAgB;;AAGjE,QAAK,YACH,6DACD;;;AAIL,QAAO"}