@browserbasehq/orca 3.0.9-alpha-4 → 3.1.0-patch.0

package/dist/esm/lib/v3/cache/ActCache.js

@@ -0,0 +1,292 @@
+import { createHash } from "crypto";
+import { safeGetPageUrl, waitForCachedSelector } from "./utils.js";
+import { StagehandNotInitializedError } from "../types/public/sdkErrors.js";
+export class ActCache {
+    storage;
+    logger;
+    getActHandler;
+    getDefaultLlmClient;
+    domSettleTimeoutMs;
+    constructor({ storage, logger, getActHandler, getDefaultLlmClient, domSettleTimeoutMs, }) {
+        this.storage = storage;
+        this.logger = logger;
+        this.getActHandler = getActHandler;
+        this.getDefaultLlmClient = getDefaultLlmClient;
+        this.domSettleTimeoutMs = domSettleTimeoutMs;
+    }
+    get enabled() {
+        return this.storage.enabled;
+    }
+    async prepareContext(instruction, page, variables) {
+        if (!this.enabled)
+            return null;
+        const sanitizedInstruction = instruction.trim();
+        const sanitizedVariables = variables ? { ...variables } : undefined;
+        const variableKeys = sanitizedVariables
+            ? Object.keys(sanitizedVariables).sort()
+            : [];
+        const pageUrl = await safeGetPageUrl(page);
+        const cacheKey = this.buildActCacheKey(sanitizedInstruction, pageUrl, variableKeys);
+        return {
+            instruction: sanitizedInstruction,
+            cacheKey,
+            pageUrl,
+            variableKeys,
+            variables: sanitizedVariables,
+        };
+    }
+    async tryReplay(context, page, timeout, llmClientOverride) {
+        if (!this.enabled)
+            return null;
+        const { value: entry, error, path, } = await this.storage.readJson(`${context.cacheKey}.json`);
+        if (error && path) {
+            this.logger({
+                category: "cache",
+                message: `failed to read act cache entry: ${path}`,
+                level: 2,
+                auxiliary: {
+                    error: { value: String(error), type: "string" },
+                },
+            });
+            return null;
+        }
+        if (!entry)
+            return null;
+        if (entry.version !== 1)
+            return null;
+        if (!Array.isArray(entry.actions) || entry.actions.length === 0) {
+            return null;
+        }
+        const entryVariableKeys = Array.isArray(entry.variableKeys)
+            ? [...entry.variableKeys].sort()
+            : [];
+        const contextVariableKeys = [...context.variableKeys];
+        if (!this.doVariableKeysMatch(entryVariableKeys, contextVariableKeys)) {
+            return null;
+        }
+        if (contextVariableKeys.length > 0 &&
+            (!context.variables ||
+                !this.hasAllVariableValues(contextVariableKeys, context.variables))) {
+            this.logger({
+                category: "cache",
+                message: "act cache miss: missing variables for replay",
+                level: 2,
+                auxiliary: {
+                    instruction: { value: context.instruction, type: "string" },
+                },
+            });
+            return null;
+        }
+        this.logger({
+            category: "cache",
+            message: "act cache hit",
+            level: 1,
+            auxiliary: {
+                instruction: { value: context.instruction, type: "string" },
+                url: {
+                    value: entry.url ?? context.pageUrl,
+                    type: "string",
+                },
+            },
+        });
+        return await this.replayCachedActions(context, entry, page, timeout, llmClientOverride);
+    }
+    async store(context, result) {
+        if (!this.enabled)
+            return;
+        const entry = {
+            version: 1,
+            instruction: context.instruction,
+            url: context.pageUrl,
+            variableKeys: context.variableKeys,
+            actions: result.actions ?? [],
+            actionDescription: result.actionDescription,
+            message: result.message,
+        };
+        const { error, path } = await this.storage.writeJson(`${context.cacheKey}.json`, entry);
+        if (error && path) {
+            this.logger({
+                category: "cache",
+                message: "failed to write act cache entry",
+                level: 1,
+                auxiliary: {
+                    error: { value: String(error), type: "string" },
+                },
+            });
+            return;
+        }
+        this.logger({
+            category: "cache",
+            message: "act cache stored",
+            level: 2,
+            auxiliary: {
+                instruction: { value: context.instruction, type: "string" },
+                url: { value: context.pageUrl, type: "string" },
+            },
+        });
+    }
+    buildActCacheKey(instruction, url, variableKeys) {
+        const payload = JSON.stringify({
+            instruction,
+            url,
+            variableKeys,
+        });
+        return createHash("sha256").update(payload).digest("hex");
+    }
+    async replayCachedActions(context, entry, page, timeout, llmClientOverride) {
+        const handler = this.getActHandler();
+        if (!handler) {
+            throw new StagehandNotInitializedError("act()");
+        }
+        const effectiveClient = llmClientOverride ?? this.getDefaultLlmClient();
+        const execute = async () => {
+            const actionResults = [];
+            for (const action of entry.actions) {
+                await waitForCachedSelector({
+                    page,
+                    selector: action.selector,
+                    timeout: this.domSettleTimeoutMs,
+                    logger: this.logger,
+                    context: "act",
+                });
+                const result = await handler.takeDeterministicAction(action, page, this.domSettleTimeoutMs, effectiveClient, undefined, context.variables);
+                actionResults.push(result);
+                if (!result.success) {
+                    break;
+                }
+            }
+            if (actionResults.length === 0) {
+                return {
+                    success: false,
+                    message: "Failed to perform act: cached entry has no actions",
+                    actionDescription: entry.actionDescription ?? entry.instruction,
+                    actions: [],
+                };
+            }
+            const success = actionResults.every((r) => r.success);
+            const actions = actionResults.flatMap((r) => r.actions ?? []);
+            const message = actionResults
+                .map((r) => r.message)
+                .filter((m) => m && m.trim().length > 0)
+                .join(" → ") ||
+                entry.message ||
+                `Replayed ${entry.actions.length} cached action${entry.actions.length === 1 ? "" : "s"}.`;
+            const actionDescription = entry.actionDescription ||
+                actionResults[actionResults.length - 1]?.actionDescription ||
+                entry.actions[entry.actions.length - 1]?.description ||
+                entry.instruction;
+            if (success &&
+                actions.length > 0 &&
+                this.haveActionsChanged(entry.actions, actions)) {
+                await this.refreshCacheEntry(context, {
+                    ...entry,
+                    actions,
+                    message,
+                    actionDescription,
+                });
+            }
+            return {
+                success,
+                message,
+                actionDescription,
+                actions,
+            };
+        };
+        return await this.runWithTimeout(execute, timeout);
+    }
+    haveActionsChanged(original, updated) {
+        if (original.length !== updated.length) {
+            return true;
+        }
+        for (let i = 0; i < original.length; i += 1) {
+            const orig = original[i];
+            const next = updated[i];
+            if (!next) {
+                return true;
+            }
+            if (orig.selector !== next.selector) {
+                return true;
+            }
+            if (orig.description !== next.description) {
+                return true;
+            }
+            if ((orig.method ?? "") !== (next.method ?? "")) {
+                return true;
+            }
+            const origArgs = orig.arguments ?? [];
+            const nextArgs = next.arguments ?? [];
+            if (origArgs.length !== nextArgs.length) {
+                return true;
+            }
+            for (let j = 0; j < origArgs.length; j += 1) {
+                if (origArgs[j] !== nextArgs[j]) {
+                    return true;
+                }
+            }
+        }
+        return false;
+    }
+    async refreshCacheEntry(context, entry) {
+        const { error, path } = await this.storage.writeJson(`${context.cacheKey}.json`, {
+            ...entry,
+            variableKeys: context.variableKeys,
+        });
+        if (error && path) {
+            this.logger({
+                category: "cache",
+                message: "failed to update act cache entry after self-heal",
+                level: 0,
+                auxiliary: {
+                    error: { value: String(error), type: "string" },
+                },
+            });
+            return;
+        }
+        this.logger({
+            category: "cache",
+            message: "act cache entry updated after self-heal",
+            level: 2,
+            auxiliary: {
+                instruction: { value: context.instruction, type: "string" },
+                url: { value: context.pageUrl, type: "string" },
+            },
+        });
+    }
+    doVariableKeysMatch(entryKeys, contextKeys) {
+        if (entryKeys.length !== contextKeys.length) {
+            return false;
+        }
+        for (let i = 0; i < entryKeys.length; i += 1) {
+            if (entryKeys[i] !== contextKeys[i]) {
+                return false;
+            }
+        }
+        return true;
+    }
+    hasAllVariableValues(variableKeys, variables) {
+        for (const key of variableKeys) {
+            if (!(key in variables)) {
+                return false;
+            }
+        }
+        return true;
+    }
+    async runWithTimeout(run, timeout) {
+        if (!timeout) {
+            return await run();
+        }
+        return await new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                reject(new Error(`act() timed out after ${timeout}ms`));
+            }, timeout);
+            void run().then((value) => {
+                clearTimeout(timer);
+                resolve(value);
+            }, (err) => {
+                clearTimeout(timer);
+                reject(err);
+            });
+        });
+    }
+}
+//# sourceMappingURL=ActCache.js.map

package/dist/esm/lib/v3/cache/ActCache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ActCache.js","sourceRoot":"","sources":["../../../../../lib/v3/cache/ActCache.ts"],"names":[],"mappings":"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","sourcesContent":["import { createHash } from \"crypto\";\nimport type { ActHandler } from \"../handlers/actHandler.js\";\nimport type { LLMClient } from \"../llm/LLMClient.js\";\nimport type { Action, ActResult, Logger } from \"../types/public/index.js\";\nimport type { Page } from \"../understudy/page.js\";\nimport { CacheStorage } from \"./CacheStorage.js\";\nimport { safeGetPageUrl, waitForCachedSelector } from \"./utils.js\";\nimport {\n  ActCacheContext,\n  ActCacheDeps,\n  CachedActEntry,\n} from \"../types/private/index.js\";\nimport { StagehandNotInitializedError } from \"../types/public/sdkErrors.js\";\n\nexport class ActCache {\n  private readonly storage: CacheStorage;\n  private readonly logger: Logger;\n  private readonly getActHandler: () => ActHandler | null;\n  private readonly getDefaultLlmClient: () => LLMClient;\n  private readonly domSettleTimeoutMs?: number;\n\n  constructor({\n    storage,\n    logger,\n    getActHandler,\n    getDefaultLlmClient,\n    domSettleTimeoutMs,\n  }: ActCacheDeps) {\n    this.storage = storage;\n    this.logger = logger;\n    this.getActHandler = getActHandler;\n    this.getDefaultLlmClient = getDefaultLlmClient;\n    this.domSettleTimeoutMs = domSettleTimeoutMs;\n  }\n\n  get enabled(): boolean {\n    return this.storage.enabled;\n  }\n\n  async prepareContext(\n    instruction: string,\n    page: Page,\n    variables?: Record<string, string>,\n  ): Promise<ActCacheContext | null> {\n    if (!this.enabled) return null;\n    const sanitizedInstruction = instruction.trim();\n    const sanitizedVariables = variables ? { ...variables } : undefined;\n    const variableKeys = sanitizedVariables\n      ? Object.keys(sanitizedVariables).sort()\n      : [];\n    const pageUrl = await safeGetPageUrl(page);\n    const cacheKey = this.buildActCacheKey(\n      sanitizedInstruction,\n      pageUrl,\n      variableKeys,\n    );\n    return {\n      instruction: sanitizedInstruction,\n      cacheKey,\n      pageUrl,\n      variableKeys,\n      variables: sanitizedVariables,\n    };\n  }\n\n  async tryReplay(\n    context: ActCacheContext,\n    page: Page,\n    timeout?: number,\n    llmClientOverride?: LLMClient,\n  ): Promise<ActResult | null> {\n    if (!this.enabled) return null;\n\n    const {\n      value: entry,\n      error,\n      path,\n    } = await this.storage.readJson<CachedActEntry>(`${context.cacheKey}.json`);\n    if (error && path) {\n      this.logger({\n        category: \"cache\",\n        message: `failed to read act cache entry: ${path}`,\n        level: 2,\n        auxiliary: {\n          error: { value: String(error), type: \"string\" },\n        },\n      });\n      return null;\n    }\n    if (!entry) return null;\n    if (entry.version !== 1) return null;\n    if (!Array.isArray(entry.actions) || entry.actions.length === 0) {\n      return null;\n    }\n\n    const entryVariableKeys = Array.isArray(entry.variableKeys)\n      ? [...entry.variableKeys].sort()\n      : [];\n    const contextVariableKeys = [...context.variableKeys];\n\n    if (!this.doVariableKeysMatch(entryVariableKeys, contextVariableKeys)) {\n      return null;\n    }\n\n    if (\n      contextVariableKeys.length > 0 &&\n      (!context.variables ||\n        !this.hasAllVariableValues(contextVariableKeys, context.variables))\n    ) {\n      this.logger({\n        category: \"cache\",\n        message: \"act cache miss: missing variables for replay\",\n        level: 2,\n        auxiliary: {\n          instruction: { value: context.instruction, type: \"string\" },\n        },\n      });\n      return null;\n    }\n\n    this.logger({\n      category: \"cache\",\n      message: \"act cache hit\",\n      level: 1,\n      auxiliary: {\n        instruction: { value: context.instruction, type: \"string\" },\n        url: {\n          value: entry.url ?? context.pageUrl,\n          type: \"string\",\n        },\n      },\n    });\n\n    return await this.replayCachedActions(\n      context,\n      entry,\n      page,\n      timeout,\n      llmClientOverride,\n    );\n  }\n\n  async store(context: ActCacheContext, result: ActResult): Promise<void> {\n    if (!this.enabled) return;\n\n    const entry: CachedActEntry = {\n      version: 1,\n      instruction: context.instruction,\n      url: context.pageUrl,\n      variableKeys: context.variableKeys,\n      actions: result.actions ?? [],\n      actionDescription: result.actionDescription,\n      message: result.message,\n    };\n\n    const { error, path } = await this.storage.writeJson(\n      `${context.cacheKey}.json`,\n      entry,\n    );\n    if (error && path) {\n      this.logger({\n        category: \"cache\",\n        message: \"failed to write act cache entry\",\n        level: 1,\n        auxiliary: {\n          error: { value: String(error), type: \"string\" },\n        },\n      });\n      return;\n    }\n\n    this.logger({\n      category: \"cache\",\n      message: \"act cache stored\",\n      level: 2,\n      auxiliary: {\n        instruction: { value: context.instruction, type: \"string\" },\n        url: { value: context.pageUrl, type: \"string\" },\n      },\n    });\n  }\n\n  private buildActCacheKey(\n    instruction: string,\n    url: string,\n    variableKeys: string[],\n  ): string {\n    const payload = JSON.stringify({\n      instruction,\n      url,\n      variableKeys,\n    });\n    return createHash(\"sha256\").update(payload).digest(\"hex\");\n  }\n\n  private async replayCachedActions(\n    context: ActCacheContext,\n    entry: CachedActEntry,\n    page: Page,\n    timeout?: number,\n    llmClientOverride?: LLMClient,\n  ): Promise<ActResult> {\n    const handler = this.getActHandler();\n    if (!handler) {\n      throw new StagehandNotInitializedError(\"act()\");\n    }\n    const effectiveClient = llmClientOverride ?? this.getDefaultLlmClient();\n\n    const execute = async (): Promise<ActResult> => {\n      const actionResults: ActResult[] = [];\n      for (const action of entry.actions) {\n        await waitForCachedSelector({\n          page,\n          selector: action.selector,\n          timeout: this.domSettleTimeoutMs,\n          logger: this.logger,\n          context: \"act\",\n        });\n        const result = await handler.takeDeterministicAction(\n          action,\n          page,\n          this.domSettleTimeoutMs,\n          effectiveClient,\n          undefined,\n          context.variables,\n        );\n        actionResults.push(result);\n        if (!result.success) {\n          break;\n        }\n      }\n\n      if (actionResults.length === 0) {\n        return {\n          success: false,\n          message: \"Failed to perform act: cached entry has no actions\",\n          actionDescription: entry.actionDescription ?? entry.instruction,\n          actions: [],\n        };\n      }\n\n      const success = actionResults.every((r) => r.success);\n      const actions = actionResults.flatMap((r) => r.actions ?? []);\n      const message =\n        actionResults\n          .map((r) => r.message)\n          .filter((m) => m && m.trim().length > 0)\n          .join(\" → \") ||\n        entry.message ||\n        `Replayed ${entry.actions.length} cached action${\n          entry.actions.length === 1 ? \"\" : \"s\"\n        }.`;\n      const actionDescription =\n        entry.actionDescription ||\n        actionResults[actionResults.length - 1]?.actionDescription ||\n        entry.actions[entry.actions.length - 1]?.description ||\n        entry.instruction;\n\n      if (\n        success &&\n        actions.length > 0 &&\n        this.haveActionsChanged(entry.actions, actions)\n      ) {\n        await this.refreshCacheEntry(context, {\n          ...entry,\n          actions,\n          message,\n          actionDescription,\n        });\n      }\n      return {\n        success,\n        message,\n        actionDescription,\n        actions,\n      };\n    };\n\n    return await this.runWithTimeout(execute, timeout);\n  }\n\n  private haveActionsChanged(original: Action[], updated: Action[]): boolean {\n    if (original.length !== updated.length) {\n      return true;\n    }\n\n    for (let i = 0; i < original.length; i += 1) {\n      const orig = original[i];\n      const next = updated[i];\n      if (!next) {\n        return true;\n      }\n\n      if (orig.selector !== next.selector) {\n        return true;\n      }\n\n      if (orig.description !== next.description) {\n        return true;\n      }\n\n      if ((orig.method ?? \"\") !== (next.method ?? \"\")) {\n        return true;\n      }\n\n      const origArgs = orig.arguments ?? [];\n      const nextArgs = next.arguments ?? [];\n      if (origArgs.length !== nextArgs.length) {\n        return true;\n      }\n\n      for (let j = 0; j < origArgs.length; j += 1) {\n        if (origArgs[j] !== nextArgs[j]) {\n          return true;\n        }\n      }\n    }\n\n    return false;\n  }\n\n  private async refreshCacheEntry(\n    context: ActCacheContext,\n    entry: CachedActEntry,\n  ): Promise<void> {\n    const { error, path } = await this.storage.writeJson(\n      `${context.cacheKey}.json`,\n      {\n        ...entry,\n        variableKeys: context.variableKeys,\n      },\n    );\n\n    if (error && path) {\n      this.logger({\n        category: \"cache\",\n        message: \"failed to update act cache entry after self-heal\",\n        level: 0,\n        auxiliary: {\n          error: { value: String(error), type: \"string\" },\n        },\n      });\n      return;\n    }\n\n    this.logger({\n      category: \"cache\",\n      message: \"act cache entry updated after self-heal\",\n      level: 2,\n      auxiliary: {\n        instruction: { value: context.instruction, type: \"string\" },\n        url: { value: context.pageUrl, type: \"string\" },\n      },\n    });\n  }\n\n  private doVariableKeysMatch(\n    entryKeys: string[],\n    contextKeys: string[],\n  ): boolean {\n    if (entryKeys.length !== contextKeys.length) {\n      return false;\n    }\n\n    for (let i = 0; i < entryKeys.length; i += 1) {\n      if (entryKeys[i] !== contextKeys[i]) {\n        return false;\n      }\n    }\n\n    return true;\n  }\n\n  private hasAllVariableValues(\n    variableKeys: string[],\n    variables: Record<string, string>,\n  ): boolean {\n    for (const key of variableKeys) {\n      if (!(key in variables)) {\n        return false;\n      }\n    }\n    return true;\n  }\n\n  private async runWithTimeout<T>(\n    run: () => Promise<T>,\n    timeout?: number,\n  ): Promise<T> {\n    if (!timeout) {\n      return await run();\n    }\n\n    return await new Promise<T>((resolve, reject) => {\n      const timer = setTimeout(() => {\n        reject(new Error(`act() timed out after ${timeout}ms`));\n      }, timeout);\n\n      void run().then(\n        (value) => {\n          clearTimeout(timer);\n          resolve(value);\n        },\n        (err) => {\n          clearTimeout(timer);\n          reject(err);\n        },\n      );\n    });\n  }\n}\n"]}

package/dist/esm/lib/v3/cache/AgentCache.d.ts

@@ -0,0 +1,109 @@
+import type { LLMClient } from "../llm/LLMClient.js";
+import type { AgentReplayStep, SanitizedAgentExecuteOptions, AgentCacheContext, AgentCacheDeps, AgentCacheTransferPayload } from "../types/private/index.js";
+import type { AgentResult, AgentStreamResult, AgentConfig, AgentExecuteOptionsBase } from "../types/public/index.js";
+import type { Page } from "../understudy/page.js";
+export declare class AgentCache {
+    private readonly storage;
+    private readonly logger;
+    private readonly getActHandler;
+    private readonly getContext;
+    private readonly getDefaultLlmClient;
+    private readonly getBaseModelName;
+    private readonly getSystemPrompt;
+    private readonly domSettleTimeoutMs?;
+    private readonly act;
+    private readonly bufferLatestEntry;
+    private recording;
+    private latestEntry;
+    constructor({ storage, logger, getActHandler, getContext, getDefaultLlmClient, getBaseModelName, getSystemPrompt, domSettleTimeoutMs, act, bufferLatestEntry, }: AgentCacheDeps);
+    get enabled(): boolean;
+    shouldAttemptCache(instruction: string): boolean;
+    sanitizeExecuteOptions(options?: AgentExecuteOptionsBase): SanitizedAgentExecuteOptions;
+    buildConfigSignature(agentOptions?: AgentConfig): string;
+    prepareContext(params: {
+        instruction: string;
+        options: SanitizedAgentExecuteOptions;
+        configSignature: string;
+        page: Page;
+    }): Promise<AgentCacheContext | null>;
+    tryReplay(context: AgentCacheContext, llmClientOverride?: LLMClient): Promise<AgentResult | null>;
+    /**
+     * Attempts to replay a cached agent execution and returns it as a stream result.
+     *
+     * This method exists because the agent API exposes two execution modes:
+     * - `execute()` - Returns a Promise<AgentResult> directly
+     * - `stream()` - Returns an AgentStreamResult with async iterables for real-time output
+     *
+     * When a cache hit occurs, we need to return the appropriate type for each mode:
+     * - For `execute()`, we use `tryReplay()` which returns AgentResult
+     * - For `stream()`, we use `tryReplayAsStream()` which wraps the result in a
+     *   stream-compatible interface
+     *
+     * This ensures consumers using `stream()` can still iterate over `textStream`
+     * and await `result` even when the response comes from cache, maintaining
+     * API consistency regardless of whether the result was cached or live.
+     */
+    tryReplayAsStream(context: AgentCacheContext, llmClientOverride?: LLMClient): Promise<AgentStreamResult | null>;
+    /**
+     * Creates a mock AgentStreamResult that wraps a cached AgentResult.
+     *
+     * AgentStreamResult (from the AI SDK) is a complex type with multiple async
+     * iterables and promises. When serving from cache, we don't have an actual
+     * LLM stream to consume - we just have the final result. This method creates
+     * a "fake" stream
+  
+     * This approach lets cached responses be transparent to the consumer -
+     * they can use the same iteration patterns whether the result is live or cached.
+     */
+    private createCachedStreamResult;
+    /**
+     * Wraps an AgentStreamResult with caching logic.
+     *
+     * This method handles the complexity of caching for streaming responses:
+     * 1. Begins recording agent replay steps
+     * 2. Wraps the stream's result promise to capture completion
+     * 3. On success: ends recording and stores the cache entry
+     * 4. On error: discards the recording
+     *
+     * This keeps the caching orchestration in AgentCache rather than
+     * spreading it across the V3 class.
+     *
+     * @param context - The cache context for this execution
+     * @param streamResult - The stream result from the agent handler
+     * @param beginRecording - Callback to start recording (from V3)
+     * @param endRecording - Callback to end recording and get steps (from V3)
+     * @param discardRecording - Callback to discard recording on error (from V3)
+     * @returns The wrapped stream result with caching enabled
+     */
+    wrapStreamForCaching(context: AgentCacheContext, streamResult: AgentStreamResult, beginRecording: () => void, endRecording: () => AgentReplayStep[], discardRecording: () => void): AgentStreamResult;
+    store(context: AgentCacheContext, steps: AgentReplayStep[], result: AgentResult): Promise<void>;
+    consumeBufferedEntry(): AgentCacheTransferPayload | null;
+    storeTransferredEntry(payload: AgentCacheTransferPayload | null): Promise<void>;
+    /**
+     * Clone the agent result and prune bulky fields (e.g. screenshot base64 blobs)
+     * before persisting it to disk. This keeps cache entries compact without
+     * mutating the live AgentResult returned to callers.
+     */
+    private pruneAgentResult;
+    beginRecording(): void;
+    endRecording(): AgentReplayStep[];
+    discardRecording(): void;
+    isRecording(): boolean;
+    recordStep(step: AgentReplayStep): void;
+    isReplayActive(): boolean;
+    private serializeAgentModelForCache;
+    private buildAgentCacheKey;
+    private sanitizeModelOptionsForCache;
+    private sanitizeModelValueForCache;
+    private replayAgentCacheEntry;
+    private executeAgentReplayStep;
+    private replayAgentActStep;
+    private replayAgentFillFormStep;
+    private replayAgentGotoStep;
+    private replayAgentScrollStep;
+    private replayAgentWaitStep;
+    private replayAgentNavBackStep;
+    private replayAgentKeysStep;
+    private haveActionsChanged;
+    private refreshAgentCacheEntry;
+}