@browserbasehq/orca 3.2.0-preview.3 → 3.2.0-preview.5

package/dist/esm/lib/v3/agent/utils/captchaSolver.js

@@ -0,0 +1,171 @@
+const SOLVING_STARTED = "browserbase-solving-started";
+const SOLVING_FINISHED = "browserbase-solving-finished";
+const SOLVING_ERRORED = "browserbase-solving-errored";
+/** Maximum time (ms) to wait for the captcha solver before giving up. */
+const SOLVE_TIMEOUT_MS = 90_000;
+// ---------------------------------------------------------------------------
+// Shared captcha notification strings
+// ---------------------------------------------------------------------------
+/** Injected into the agent message stream after a successful captcha solve. */
+export const CAPTCHA_SOLVED_MSG = "A captcha was automatically detected and solved — no further interaction with the captcha is needed, even if it does not visually appear solved. Do not click the captcha checkbox, widget, or challenge again. Continue with your task.";
+/** Injected into the agent message stream when the captcha solver fails. */
+export const CAPTCHA_ERRORED_MSG = "A captcha was detected but the automatic captcha solver failed to solve it. You may need to try a different approach or navigate around the captcha.";
+/** Appended to the system prompt (DOM/hybrid agents) when captchas auto-solve. */
+export const CAPTCHA_SYSTEM_PROMPT_NOTE = "Captchas on this page are automatically detected and solved by the browser environment. Do not interact with or attempt to solve any captchas yourself — they will be handled for you. Do not click the captcha checkbox, widget, or challenge again after it has been solved, even if it still looks unresolved. Continue with your task as if the captcha does not exist.";
+/** Appended to the CUA system prompt when captchas auto-solve. */
+export const CAPTCHA_CUA_SYSTEM_PROMPT_NOTE = "\n\nCaptchas on this page are automatically detected and solved by the browser environment. Do not interact with or attempt to solve any captchas yourself — they will be handled for you. Continue with your task as if the captcha does not exist.";
+/**
+ * Tracks Browserbase captcha solver state via console messages and provides
+ * a blocking `waitIfSolving()` that agents call before each step/action.
+ *
+ * Accepts a page-provider callback so the listener is automatically
+ * re-attached when the active page changes (e.g. popup / new tab).
+ *
+ * All concurrent callers of `waitIfSolving()` share the same underlying
+ * promise, so multiple waiters are safely resolved together.
+ */
+export class CaptchaSolver {
+    solving = false;
+    _solvedSinceLastConsume = false;
+    _erroredSinceLastConsume = false;
+    listener = null;
+    attachedPage = null;
+    pageProvider = null;
+    /** Shared promise that all concurrent waitIfSolving() callers await. */
+    waitPromise = null;
+    /** Resolves the shared waitPromise. */
+    resolveWait = null;
+    /** Timeout handle for the 90s deadline. */
+    waitTimer = null;
+    /**
+     * Initialise with a callback that returns the current active page.
+     * The listener is lazily (re-)attached whenever the active page changes.
+     */
+    init(pageProvider) {
+        this.pageProvider = pageProvider;
+    }
+    /** Whether a captcha solve is currently in progress. */
+    isSolving() {
+        return this.solving;
+    }
+    /**
+     * Ensure the console listener is attached to the current active page.
+     * If the active page has changed since the last call, the old listener
+     * is removed and a new one is installed.
+     */
+    async ensureAttached() {
+        if (!this.pageProvider)
+            return;
+        const page = await this.pageProvider();
+        if (page === this.attachedPage)
+            return;
+        // Detach from the old page
+        this.detachListener();
+        this.attachedPage = page;
+        this.listener = (msg) => {
+            const text = msg.text();
+            if (text === SOLVING_STARTED) {
+                this.solving = true;
+            }
+            else if (text === SOLVING_FINISHED) {
+                this.solving = false;
+                this._solvedSinceLastConsume = true;
+                this.settle();
+            }
+            else if (text === SOLVING_ERRORED) {
+                this.solving = false;
+                this._erroredSinceLastConsume = true;
+                this.settle();
+            }
+        };
+        page.on("console", this.listener);
+    }
+    /**
+     * Returns a promise that resolves immediately if no captcha is being
+     * solved, or blocks until the solver finishes, errors, or the 90s
+     * timeout is reached.
+     *
+     * Also re-attaches the listener to the current active page if it has
+     * changed since the last call.
+     *
+     * All concurrent callers share the same promise, so no waiter is
+     * orphaned.
+     */
+    async waitIfSolving() {
+        await this.ensureAttached();
+        if (!this.solving)
+            return;
+        // Return the existing shared promise if one is already pending
+        if (this.waitPromise)
+            return this.waitPromise;
+        this.waitPromise = new Promise((resolve) => {
+            this.resolveWait = resolve;
+            this.waitTimer = setTimeout(() => {
+                this.solving = false;
+                this._erroredSinceLastConsume = true;
+                this.settle();
+            }, SOLVE_TIMEOUT_MS);
+        });
+        return this.waitPromise;
+    }
+    /**
+     * Returns and resets the solve event flags.
+     * Call after `waitIfSolving()` to check whether a captcha was solved
+     * (or errored) since the last consume.  This captures events even if
+     * the solve completed between two `waitIfSolving()` calls.
+     */
+    consumeSolveResult() {
+        const result = {
+            solved: this._solvedSinceLastConsume,
+            errored: this._erroredSinceLastConsume,
+        };
+        this._solvedSinceLastConsume = false;
+        this._erroredSinceLastConsume = false;
+        return result;
+    }
+    /**
+     * Remove the console listener and reset all state.
+     */
+    dispose() {
+        this.detachListener();
+        this.attachedPage = null;
+        this.pageProvider = null;
+        this.solving = false;
+        this._solvedSinceLastConsume = false;
+        this._erroredSinceLastConsume = false;
+        this.settle();
+    }
+    // ------------------------------------------------------------------
+    // Internal helpers
+    // ------------------------------------------------------------------
+    /** Remove the console listener from the currently attached page. */
+    detachListener() {
+        if (this.attachedPage && this.listener) {
+            this.attachedPage.off("console", this.listener);
+        }
+        this.listener = null;
+        // If a solve was in progress, mark it as errored so consumers
+        // know it was interrupted (consistent with the timeout path).
+        if (this.solving) {
+            this._erroredSinceLastConsume = true;
+        }
+        // Reset solving state so waiters aren't stuck waiting for events
+        // that can never arrive from the detached page.
+        this.solving = false;
+        this.settle();
+    }
+    /** Resolve the shared wait promise and clear the timeout. */
+    settle() {
+        if (this.waitTimer) {
+            clearTimeout(this.waitTimer);
+            this.waitTimer = null;
+        }
+        if (this.resolveWait) {
+            const resolve = this.resolveWait;
+            this.resolveWait = null;
+            this.waitPromise = null;
+            resolve();
+        }
+    }
+}
+//# sourceMappingURL=captchaSolver.js.map

package/dist/esm/lib/v3/agent/utils/captchaSolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"captchaSolver.js","sourceRoot":"","sources":["../../../../../../lib/v3/agent/utils/captchaSolver.ts"],"names":[],"mappings":"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","sourcesContent":["import type { Page } from \"../../understudy/page.js\";\nimport type { ConsoleMessage } from \"../../understudy/consoleMessage.js\";\n\nconst SOLVING_STARTED = \"browserbase-solving-started\";\nconst SOLVING_FINISHED = \"browserbase-solving-finished\";\nconst SOLVING_ERRORED = \"browserbase-solving-errored\";\n\n/** Maximum time (ms) to wait for the captcha solver before giving up. */\nconst SOLVE_TIMEOUT_MS = 90_000;\n\n// ---------------------------------------------------------------------------\n// Shared captcha notification strings\n// ---------------------------------------------------------------------------\n\n/** Injected into the agent message stream after a successful captcha solve. */\nexport const CAPTCHA_SOLVED_MSG =\n  \"A captcha was automatically detected and solved — no further interaction with the captcha is needed, even if it does not visually appear solved. Do not click the captcha checkbox, widget, or challenge again. Continue with your task.\";\n\n/** Injected into the agent message stream when the captcha solver fails. */\nexport const CAPTCHA_ERRORED_MSG =\n  \"A captcha was detected but the automatic captcha solver failed to solve it. You may need to try a different approach or navigate around the captcha.\";\n\n/** Appended to the system prompt (DOM/hybrid agents) when captchas auto-solve. */\nexport const CAPTCHA_SYSTEM_PROMPT_NOTE =\n  \"Captchas on this page are automatically detected and solved by the browser environment. Do not interact with or attempt to solve any captchas yourself — they will be handled for you. Do not click the captcha checkbox, widget, or challenge again after it has been solved, even if it still looks unresolved. Continue with your task as if the captcha does not exist.\";\n\n/** Appended to the CUA system prompt when captchas auto-solve. */\nexport const CAPTCHA_CUA_SYSTEM_PROMPT_NOTE =\n  \"\\n\\nCaptchas on this page are automatically detected and solved by the browser environment. Do not interact with or attempt to solve any captchas yourself — they will be handled for you. Continue with your task as if the captcha does not exist.\";\n\n/**\n * Tracks Browserbase captcha solver state via console messages and provides\n * a blocking `waitIfSolving()` that agents call before each step/action.\n *\n * Accepts a page-provider callback so the listener is automatically\n * re-attached when the active page changes (e.g. popup / new tab).\n *\n * All concurrent callers of `waitIfSolving()` share the same underlying\n * promise, so multiple waiters are safely resolved together.\n */\nexport class CaptchaSolver {\n  private solving = false;\n  private _solvedSinceLastConsume = false;\n  private _erroredSinceLastConsume = false;\n  private listener: ((msg: ConsoleMessage) => void) | null = null;\n  private attachedPage: Page | null = null;\n  private pageProvider: (() => Promise<Page>) | null = null;\n\n  /** Shared promise that all concurrent waitIfSolving() callers await. */\n  private waitPromise: Promise<void> | null = null;\n  /** Resolves the shared waitPromise. */\n  private resolveWait: (() => void) | null = null;\n  /** Timeout handle for the 90s deadline. */\n  private waitTimer: ReturnType<typeof setTimeout> | null = null;\n\n  /**\n   * Initialise with a callback that returns the current active page.\n   * The listener is lazily (re-)attached whenever the active page changes.\n   */\n  init(pageProvider: () => Promise<Page>): void {\n    this.pageProvider = pageProvider;\n  }\n\n  /** Whether a captcha solve is currently in progress. */\n  isSolving(): boolean {\n    return this.solving;\n  }\n\n  /**\n   * Ensure the console listener is attached to the current active page.\n   * If the active page has changed since the last call, the old listener\n   * is removed and a new one is installed.\n   */\n  async ensureAttached(): Promise<void> {\n    if (!this.pageProvider) return;\n    const page = await this.pageProvider();\n    if (page === this.attachedPage) return;\n\n    // Detach from the old page\n    this.detachListener();\n\n    this.attachedPage = page;\n    this.listener = (msg: ConsoleMessage) => {\n      const text = msg.text();\n      if (text === SOLVING_STARTED) {\n        this.solving = true;\n      } else if (text === SOLVING_FINISHED) {\n        this.solving = false;\n        this._solvedSinceLastConsume = true;\n        this.settle();\n      } else if (text === SOLVING_ERRORED) {\n        this.solving = false;\n        this._erroredSinceLastConsume = true;\n        this.settle();\n      }\n    };\n    page.on(\"console\", this.listener);\n  }\n\n  /**\n   * Returns a promise that resolves immediately if no captcha is being\n   * solved, or blocks until the solver finishes, errors, or the 90s\n   * timeout is reached.\n   *\n   * Also re-attaches the listener to the current active page if it has\n   * changed since the last call.\n   *\n   * All concurrent callers share the same promise, so no waiter is\n   * orphaned.\n   */\n  async waitIfSolving(): Promise<void> {\n    await this.ensureAttached();\n\n    if (!this.solving) return;\n\n    // Return the existing shared promise if one is already pending\n    if (this.waitPromise) return this.waitPromise;\n\n    this.waitPromise = new Promise<void>((resolve) => {\n      this.resolveWait = resolve;\n      this.waitTimer = setTimeout(() => {\n        this.solving = false;\n        this._erroredSinceLastConsume = true;\n        this.settle();\n      }, SOLVE_TIMEOUT_MS);\n    });\n\n    return this.waitPromise;\n  }\n\n  /**\n   * Returns and resets the solve event flags.\n   * Call after `waitIfSolving()` to check whether a captcha was solved\n   * (or errored) since the last consume.  This captures events even if\n   * the solve completed between two `waitIfSolving()` calls.\n   */\n  consumeSolveResult(): { solved: boolean; errored: boolean } {\n    const result = {\n      solved: this._solvedSinceLastConsume,\n      errored: this._erroredSinceLastConsume,\n    };\n    this._solvedSinceLastConsume = false;\n    this._erroredSinceLastConsume = false;\n    return result;\n  }\n\n  /**\n   * Remove the console listener and reset all state.\n   */\n  dispose(): void {\n    this.detachListener();\n    this.attachedPage = null;\n    this.pageProvider = null;\n    this.solving = false;\n    this._solvedSinceLastConsume = false;\n    this._erroredSinceLastConsume = false;\n    this.settle();\n  }\n\n  // ------------------------------------------------------------------\n  // Internal helpers\n  // ------------------------------------------------------------------\n\n  /** Remove the console listener from the currently attached page. */\n  private detachListener(): void {\n    if (this.attachedPage && this.listener) {\n      this.attachedPage.off(\"console\", this.listener);\n    }\n    this.listener = null;\n    // If a solve was in progress, mark it as errored so consumers\n    // know it was interrupted (consistent with the timeout path).\n    if (this.solving) {\n      this._erroredSinceLastConsume = true;\n    }\n    // Reset solving state so waiters aren't stuck waiting for events\n    // that can never arrive from the detached page.\n    this.solving = false;\n    this.settle();\n  }\n\n  /** Resolve the shared wait promise and clear the timeout. */\n  private settle(): void {\n    if (this.waitTimer) {\n      clearTimeout(this.waitTimer);\n      this.waitTimer = null;\n    }\n    if (this.resolveWait) {\n      const resolve = this.resolveWait;\n      this.resolveWait = null;\n      this.waitPromise = null;\n      resolve();\n    }\n  }\n}\n"]}

package/dist/esm/lib/v3/agent/utils/variables.d.ts

@@ -9,6 +9,11 @@ export declare function resolveVariableValue(v: VariableValue): string;
  * Returns undefined for simple primitive values.
  */
 export declare function getVariableDescription(v: VariableValue): string | undefined;
+export interface VariablePromptEntry {
+    name: string;
+    description?: string;
+}
+export declare function getVariablePromptEntries(variables?: Variables): VariablePromptEntry[];
 /**
  * Substitutes %variableName% tokens in text with resolved variable values.
  * Works with both simple and rich variable formats.

package/dist/esm/lib/v3/agent/utils/variables.js

@@ -18,6 +18,14 @@ export function getVariableDescription(v) {
     }
     return undefined;
 }
+export function getVariablePromptEntries(variables) {
+    if (!variables)
+        return [];
+    return Object.entries(variables).map(([name, value]) => ({
+        name,
+        description: getVariableDescription(value),
+    }));
+}
 /**
  * Substitutes %variableName% tokens in text with resolved variable values.
  * Works with both simple and rich variable formats.

package/dist/esm/lib/v3/agent/utils/variables.js.map

@@ -1 +1 @@
-{"version":3,"file":"variables.js","sourceRoot":"","sources":["../../../../../../lib/v3/agent/utils/variables.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,MAAM,UAAU,oBAAoB,CAAC,CAAgB;IACnD,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,IAAI,IAAI,OAAO,IAAI,CAAC,EAAE,CAAC;QACxD,OAAO,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;IACzB,CAAC;IACD,OAAO,MAAM,CAAC,CAAC,CAAC,CAAC;AACnB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,sBAAsB,CAAC,CAAgB;IACrD,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,IAAI,IAAI,OAAO,IAAI,CAAC,EAAE,CAAC;QACxD,OAAO,CAAC,CAAC,WAAW,CAAC;IACvB,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,mBAAmB,CACjC,IAAY,EACZ,SAAqB;IAErB,IAAI,CAAC,SAAS;QAAE,OAAO,IAAI,CAAC;IAC5B,IAAI,MAAM,GAAG,IAAI,CAAC;IAClB,KAAK,MAAM,CAAC,GAAG,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC;QACjD,MAAM,KAAK,GAAG,IAAI,GAAG,GAAG,CAAC;QACzB,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,oBAAoB,CAAC,CAAC,CAAC,CAAC,CAAC;IAC7D,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAC9B,SAAqB;IAErB,IAAI,CAAC,SAAS,IAAI,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,SAAS,CAAC;IACxE,MAAM,MAAM,GAA2B,EAAE,CAAC;IAC1C,KAAK,MAAM,CAAC,GAAG,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC;QACjD,MAAM,CAAC,GAAG,CAAC,GAAG,oBAAoB,CAAC,CAAC,CAAC,CAAC;IACxC,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC","sourcesContent":["import type { Variables, VariableValue } from \"../../types/public/agent.js\";\n\n/**\n * Resolves a VariableValue to its primitive string value.\n * Handles both simple primitives (\"secret\") and rich objects ({ value: \"secret\", description: \"...\" }).\n */\nexport function resolveVariableValue(v: VariableValue): string {\n  if (typeof v === \"object\" && v !== null && \"value\" in v) {\n    return String(v.value);\n  }\n  return String(v);\n}\n\n/**\n * Extracts the optional description from a VariableValue.\n * Returns undefined for simple primitive values.\n */\nexport function getVariableDescription(v: VariableValue): string | undefined {\n  if (typeof v === \"object\" && v !== null && \"value\" in v) {\n    return v.description;\n  }\n  return undefined;\n}\n\n/**\n * Substitutes %variableName% tokens in text with resolved variable values.\n * Works with both simple and rich variable formats.\n */\nexport function substituteVariables(\n  text: string,\n  variables?: Variables,\n): string {\n  if (!variables) return text;\n  let result = text;\n  for (const [key, v] of Object.entries(variables)) {\n    const token = `%${key}%`;\n    result = result.split(token).join(resolveVariableValue(v));\n  }\n  return result;\n}\n\n/**\n * Flattens Variables to Record<string, string> for internal consumers\n * that only need key→value mappings (e.g., actHandler, cache replay).\n */\nexport function flattenVariables(\n  variables?: Variables,\n): Record<string, string> | undefined {\n  if (!variables || Object.keys(variables).length === 0) return undefined;\n  const result: Record<string, string> = {};\n  for (const [key, v] of Object.entries(variables)) {\n    result[key] = resolveVariableValue(v);\n  }\n  return result;\n}\n"]}
+{"version":3,"file":"variables.js","sourceRoot":"","sources":["../../../../../../lib/v3/agent/utils/variables.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,MAAM,UAAU,oBAAoB,CAAC,CAAgB;IACnD,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,IAAI,IAAI,OAAO,IAAI,CAAC,EAAE,CAAC;QACxD,OAAO,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;IACzB,CAAC;IACD,OAAO,MAAM,CAAC,CAAC,CAAC,CAAC;AACnB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,sBAAsB,CAAC,CAAgB;IACrD,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,IAAI,IAAI,OAAO,IAAI,CAAC,EAAE,CAAC;QACxD,OAAO,CAAC,CAAC,WAAW,CAAC;IACvB,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAOD,MAAM,UAAU,wBAAwB,CACtC,SAAqB;IAErB,IAAI,CAAC,SAAS;QAAE,OAAO,EAAE,CAAC;IAC1B,OAAO,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,CAAC;QACvD,IAAI;QACJ,WAAW,EAAE,sBAAsB,CAAC,KAAK,CAAC;KAC3C,CAAC,CAAC,CAAC;AACN,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,mBAAmB,CACjC,IAAY,EACZ,SAAqB;IAErB,IAAI,CAAC,SAAS;QAAE,OAAO,IAAI,CAAC;IAC5B,IAAI,MAAM,GAAG,IAAI,CAAC;IAClB,KAAK,MAAM,CAAC,GAAG,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC;QACjD,MAAM,KAAK,GAAG,IAAI,GAAG,GAAG,CAAC;QACzB,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,oBAAoB,CAAC,CAAC,CAAC,CAAC,CAAC;IAC7D,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAC9B,SAAqB;IAErB,IAAI,CAAC,SAAS,IAAI,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,SAAS,CAAC;IACxE,MAAM,MAAM,GAA2B,EAAE,CAAC;IAC1C,KAAK,MAAM,CAAC,GAAG,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC;QACjD,MAAM,CAAC,GAAG,CAAC,GAAG,oBAAoB,CAAC,CAAC,CAAC,CAAC;IACxC,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC","sourcesContent":["import type { Variables, VariableValue } from \"../../types/public/agent.js\";\n\n/**\n * Resolves a VariableValue to its primitive string value.\n * Handles both simple primitives (\"secret\") and rich objects ({ value: \"secret\", description: \"...\" }).\n */\nexport function resolveVariableValue(v: VariableValue): string {\n  if (typeof v === \"object\" && v !== null && \"value\" in v) {\n    return String(v.value);\n  }\n  return String(v);\n}\n\n/**\n * Extracts the optional description from a VariableValue.\n * Returns undefined for simple primitive values.\n */\nexport function getVariableDescription(v: VariableValue): string | undefined {\n  if (typeof v === \"object\" && v !== null && \"value\" in v) {\n    return v.description;\n  }\n  return undefined;\n}\n\nexport interface VariablePromptEntry {\n  name: string;\n  description?: string;\n}\n\nexport function getVariablePromptEntries(\n  variables?: Variables,\n): VariablePromptEntry[] {\n  if (!variables) return [];\n  return Object.entries(variables).map(([name, value]) => ({\n    name,\n    description: getVariableDescription(value),\n  }));\n}\n\n/**\n * Substitutes %variableName% tokens in text with resolved variable values.\n * Works with both simple and rich variable formats.\n */\nexport function substituteVariables(\n  text: string,\n  variables?: Variables,\n): string {\n  if (!variables) return text;\n  let result = text;\n  for (const [key, v] of Object.entries(variables)) {\n    const token = `%${key}%`;\n    result = result.split(token).join(resolveVariableValue(v));\n  }\n  return result;\n}\n\n/**\n * Flattens Variables to Record<string, string> for internal consumers\n * that only need key→value mappings (e.g., actHandler, cache replay).\n */\nexport function flattenVariables(\n  variables?: Variables,\n): Record<string, string> | undefined {\n  if (!variables || Object.keys(variables).length === 0) return undefined;\n  const result: Record<string, string> = {};\n  for (const [key, v] of Object.entries(variables)) {\n    result[key] = resolveVariableValue(v);\n  }\n  return result;\n}\n"]}

package/dist/esm/lib/v3/flowlogger/EventEmitter.d.ts

@@ -0,0 +1,7 @@
+import { EventEmitter } from "node:events";
+export declare class EventEmitterWithWildcardSupport extends EventEmitter {
+    private readonly wildcardListeners;
+    on(eventName: string | symbol, listener: (...args: unknown[]) => void): this;
+    off(eventName: string | symbol, listener: (...args: unknown[]) => void): this;
+    emit(eventName: string | symbol, ...args: unknown[]): boolean;
+}

package/dist/esm/lib/v3/flowlogger/EventEmitter.js

@@ -0,0 +1,26 @@
+import { EventEmitter } from "node:events";
+export class EventEmitterWithWildcardSupport extends EventEmitter {
+    wildcardListeners = new Set();
+    on(eventName, listener) {
+        if (eventName === "*") {
+            this.wildcardListeners.add(listener);
+            return this;
+        }
+        return super.on(eventName, listener);
+    }
+    off(eventName, listener) {
+        if (eventName === "*") {
+            this.wildcardListeners.delete(listener);
+            return this;
+        }
+        return super.off(eventName, listener);
+    }
+    emit(eventName, ...args) {
+        const handled = super.emit(eventName, ...args);
+        for (const listener of this.wildcardListeners) {
+            listener(...args);
+        }
+        return handled || this.wildcardListeners.size > 0;
+    }
+}
+//# sourceMappingURL=EventEmitter.js.map

package/dist/esm/lib/v3/flowlogger/EventEmitter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"EventEmitter.js","sourceRoot":"","sources":["../../../../../lib/v3/flowlogger/EventEmitter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAI3C,MAAM,OAAO,+BAAgC,SAAQ,YAAY;IAC9C,iBAAiB,GAAG,IAAI,GAAG,EAAyB,CAAC;IAE7D,EAAE,CACT,SAA0B,EAC1B,QAAsC;QAEtC,IAAI,SAAS,KAAK,GAAG,EAAE,CAAC;YACtB,IAAI,CAAC,iBAAiB,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;YACrC,OAAO,IAAI,CAAC;QACd,CAAC;QAED,OAAO,KAAK,CAAC,EAAE,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;IACvC,CAAC;IAEQ,GAAG,CACV,SAA0B,EAC1B,QAAsC;QAEtC,IAAI,SAAS,KAAK,GAAG,EAAE,CAAC;YACtB,IAAI,CAAC,iBAAiB,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;YACxC,OAAO,IAAI,CAAC;QACd,CAAC;QAED,OAAO,KAAK,CAAC,GAAG,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;IACxC,CAAC;IAEQ,IAAI,CAAC,SAA0B,EAAE,GAAG,IAAe;QAC1D,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,CAAC,SAAS,EAAE,GAAG,IAAI,CAAC,CAAC;QAE/C,KAAK,MAAM,QAAQ,IAAI,IAAI,CAAC,iBAAiB,EAAE,CAAC;YAC9C,QAAQ,CAAC,GAAG,IAAI,CAAC,CAAC;QACpB,CAAC;QAED,OAAO,OAAO,IAAI,IAAI,CAAC,iBAAiB,CAAC,IAAI,GAAG,CAAC,CAAC;IACpD,CAAC;CACF","sourcesContent":["import { EventEmitter } from \"node:events\";\n\ntype WildcardEventListener = (...args: unknown[]) => void;\n\nexport class EventEmitterWithWildcardSupport extends EventEmitter {\n  private readonly wildcardListeners = new Set<WildcardEventListener>();\n\n  override on(\n    eventName: string | symbol,\n    listener: (...args: unknown[]) => void,\n  ): this {\n    if (eventName === \"*\") {\n      this.wildcardListeners.add(listener);\n      return this;\n    }\n\n    return super.on(eventName, listener);\n  }\n\n  override off(\n    eventName: string | symbol,\n    listener: (...args: unknown[]) => void,\n  ): this {\n    if (eventName === \"*\") {\n      this.wildcardListeners.delete(listener);\n      return this;\n    }\n\n    return super.off(eventName, listener);\n  }\n\n  override emit(eventName: string | symbol, ...args: unknown[]): boolean {\n    const handled = super.emit(eventName, ...args);\n\n    for (const listener of this.wildcardListeners) {\n      listener(...args);\n    }\n\n    return handled || this.wildcardListeners.size > 0;\n  }\n}\n"]}

package/dist/esm/lib/v3/flowlogger/EventSink.d.ts

@@ -0,0 +1,44 @@
+import { FlowEvent } from "./FlowLogger.js";
+import type { EventStoreApi, EventStoreQuery } from "./EventStore.js";
+export interface EventSink {
+    emit(event: FlowEvent): Promise<void>;
+    query(query: EventStoreQuery): Promise<FlowEvent[]>;
+    destroy(): Promise<void>;
+}
+declare abstract class FileEventSink implements EventSink {
+    private readonly streamPromise;
+    constructor(sessionDirPromise: Promise<string | null>, fileName: string);
+    protected abstract serialize(event: FlowEvent): Promise<string | null>;
+    emit(event: FlowEvent): Promise<void>;
+    query(): Promise<FlowEvent[]>;
+    destroy(): Promise<void>;
+}
+export declare class JsonlFileEventSink extends FileEventSink {
+    constructor(sessionDirPromise: Promise<string | null>);
+    protected serialize(event: FlowEvent): Promise<string>;
+}
+export declare class PrettyLogFileEventSink extends FileEventSink {
+    private readonly store;
+    constructor(sessionDirPromise: Promise<string | null>, store: Pick<EventStoreApi, "query">);
+    protected serialize(event: FlowEvent): Promise<string | null>;
+}
+export declare class PrettyStderrEventSink implements EventSink {
+    private readonly store;
+    constructor(store: Pick<EventStoreApi, "query">);
+    emit(event: FlowEvent): Promise<void>;
+    query(): Promise<FlowEvent[]>;
+    destroy(): Promise<void>;
+}
+export declare class InMemoryEventSink implements EventSink {
+    protected readonly limit: number;
+    constructor(limit?: number);
+    protected readonly events: FlowEvent[];
+    protected storeEvent(event: FlowEvent): FlowEvent;
+    emit(event: FlowEvent): Promise<void>;
+    query(query: EventStoreQuery): Promise<FlowEvent[]>;
+    destroy(): Promise<void>;
+}
+export declare class ShallowInMemoryEventSink extends InMemoryEventSink {
+    protected storeEvent(event: FlowEvent): FlowEvent;
+}
+export {};

package/dist/esm/lib/v3/flowlogger/EventSink.js

@@ -0,0 +1,206 @@
+import fs from "node:fs";
+import path from "node:path";
+import { FlowEvent } from "./FlowLogger.js";
+import { prettifyColorStderrLine, prettifyEvent, prettifyIsCdpEvent, prettifySanitizeEvent, } from "./prettify.js";
+// Checks whether an event matches a query used by queryable sinks. `eventId` matches both the event itself and descendants of that event.
+function matchesEventStoreQuery(event, query) {
+    if (query.sessionId && event.sessionId !== query.sessionId)
+        return false;
+    if (query.eventId) {
+        const matchesEvent = event.eventId === query.eventId ||
+            event.eventParentIds.includes(query.eventId);
+        if (!matchesEvent) {
+            return false;
+        }
+    }
+    if (query.eventType) {
+        const pattern = new RegExp(`^${query.eventType
+            .replace(/[.*+?^${}()|[\]\\]/g, "\\$&")
+            .replace(/\\\*/g, ".*")}$`);
+        if (!pattern.test(event.eventType)) {
+            return false;
+        }
+    }
+    return true;
+}
+// =============================================================================
+// File Sink Helpers
+// =============================================================================
+// Returns true when a file sink's stream is still open and writable.
+function isWritable(stream) {
+    return !!(stream && !stream.destroyed && stream.writable);
+}
+// Writes a serialized event to a file sink and converts callback-style stream completion into a promise.
+function writeToStream(stream, value) {
+    return new Promise((resolve, reject) => {
+        try {
+            stream.write(value, (error) => {
+                if (error) {
+                    reject(error);
+                    return;
+                }
+                resolve();
+            });
+        }
+        catch (error) {
+            reject(error);
+        }
+    });
+}
+// =============================================================================
+// Event Sink Implementations
+// =============================================================================
+class FileEventSink {
+    streamPromise; // Lazily opens the one file stream owned by this sink when the session directory resolves.
+    // Creates a best-effort file sink bound to a single session directory.
+    constructor(sessionDirPromise, fileName) {
+        this.streamPromise = sessionDirPromise.then((sessionDir) => sessionDir
+            ? fs.createWriteStream(path.join(sessionDir, fileName), { flags: "a" })
+            : null);
+    }
+    // Serializes and appends a single event. File sinks are intentionally best-effort and never allowed to affect library execution flow.
+    async emit(event) {
+        try {
+            const stream = await this.streamPromise;
+            if (!isWritable(stream)) {
+                return;
+            }
+            const serialized = await this.serialize(event);
+            if (!serialized) {
+                return;
+            }
+            await writeToStream(stream, serialized);
+        }
+        catch {
+            // best effort only
+        }
+    }
+    // File sinks are write-only and do not support query reads.
+    async query() {
+        return [];
+    }
+    // Closes the underlying file stream when the owning store shuts down.
+    async destroy() {
+        const stream = await this.streamPromise.catch(() => null);
+        if (!isWritable(stream)) {
+            return;
+        }
+        await new Promise((resolve) => {
+            stream.end(resolve);
+        });
+    }
+}
+export class JsonlFileEventSink extends FileEventSink {
+    // Writes full verbatim events to `session_events.jsonl`.
+    constructor(sessionDirPromise) {
+        super(sessionDirPromise, "session_events.jsonl");
+    }
+    // Serializes the full event for lossless machine-readable storage.
+    async serialize(event) {
+        return `${JSON.stringify(event)}\n`;
+    }
+}
+export class PrettyLogFileEventSink extends FileEventSink {
+    store;
+    // Writes human-readable pretty lines to `session_events.log`.
+    constructor(sessionDirPromise, store) {
+        super(sessionDirPromise, "session_events.log");
+        this.store = store;
+    }
+    // Pretty-prints the event using recent in-memory ancestry.
+    async serialize(event) {
+        const line = await prettifyEvent(this.store, prettifySanitizeEvent(event));
+        return line ? `${line}\n` : null;
+    }
+}
+export class PrettyStderrEventSink {
+    store;
+    // Writes pretty lines to stderr for verbose local debugging. CDP events are intentionally omitted here to keep stderr high-signal.
+    constructor(store) {
+        this.store = store;
+    } // Queried during prettification so stderr lines can include recent ancestry tags.
+    // Best-effort stderr writer used only for interactive debugging output.
+    async emit(event) {
+        try {
+            if (prettifyIsCdpEvent(event)) {
+                return;
+            }
+            const line = await prettifyEvent(this.store, prettifySanitizeEvent(event));
+            if (!line) {
+                return;
+            }
+            await new Promise((resolve, reject) => {
+                try {
+                    process.stderr.write(`${prettifyColorStderrLine(line)}\n`, (error) => {
+                        if (error) {
+                            reject(error);
+                            return;
+                        }
+                        resolve();
+                    });
+                }
+                catch (error) {
+                    reject(error);
+                }
+            });
+        }
+        catch {
+            // best effort only
+        }
+    }
+    // Stderr sink is write-only and does not support query reads.
+    async query() {
+        return [];
+    }
+    // No teardown is required for stderr.
+    async destroy() { }
+}
+export class InMemoryEventSink {
+    limit;
+    // Retains recent events for query lookups. Tests usually attach this sink explicitly when they need full historical payloads.
+    constructor(limit = Infinity) {
+        this.limit = limit;
+    }
+    events = []; // Retained history; `emit()` appends to it and trims old entries when `limit` is exceeded.
+    // Gives subclasses a hook to transform events before they are retained.
+    storeEvent(event) {
+        return event;
+    }
+    // Stores a new event and trims the oldest retained entries once the sink exceeds its configured limit.
+    async emit(event) {
+        this.events.push(this.storeEvent(event));
+        if (this.events.length > this.limit) {
+            this.events.splice(0, this.events.length - this.limit);
+        }
+    }
+    // Returns retained events that match the query, ordered by creation time.
+    async query(query) {
+        const filtered = this.events.filter((event) => matchesEventStoreQuery(event, query));
+        filtered.sort((left, right) => {
+            const createdAtOrder = left.eventCreatedAt.localeCompare(right.eventCreatedAt);
+            if (createdAtOrder !== 0) {
+                return createdAtOrder;
+            }
+            return left.eventId.localeCompare(right.eventId);
+        });
+        return query.limit ? filtered.slice(-query.limit) : filtered;
+    }
+    // Clears retained history when the owning store shuts down.
+    async destroy() {
+        this.events.length = 0;
+    }
+}
+export class ShallowInMemoryEventSink extends InMemoryEventSink {
+    // Retains only ancestry metadata for the default query sink so verbose or long-running sessions do not hold onto large payloads such as screenshots.
+    storeEvent(event) {
+        return new FlowEvent({
+            eventType: event.eventType,
+            eventId: event.eventId,
+            eventCreatedAt: event.eventCreatedAt,
+            sessionId: event.sessionId,
+            eventParentIds: [...event.eventParentIds],
+            data: {},
+        });
+    }
+}
+//# sourceMappingURL=EventSink.js.map

package/dist/esm/lib/v3/flowlogger/EventSink.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"EventSink.js","sourceRoot":"","sources":["../../../../../lib/v3/flowlogger/EventSink.ts"],"names":[],"mappings":"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","sourcesContent":["import fs from \"node:fs\";\nimport path from \"node:path\";\nimport { FlowEvent } from \"./FlowLogger.js\";\nimport type { EventStoreApi, EventStoreQuery } from \"./EventStore.js\";\nimport {\n  prettifyColorStderrLine,\n  prettifyEvent,\n  prettifyIsCdpEvent,\n  prettifySanitizeEvent,\n} from \"./prettify.js\";\n\n// =============================================================================\n// Event Sink Contracts\n// =============================================================================\n\nexport interface EventSink {\n  emit(event: FlowEvent): Promise<void>;\n  query(query: EventStoreQuery): Promise<FlowEvent[]>;\n  destroy(): Promise<void>;\n}\n\n// Checks whether an event matches a query used by queryable sinks. `eventId` matches both the event itself and descendants of that event.\nfunction matchesEventStoreQuery(\n  event: FlowEvent,\n  query: EventStoreQuery,\n): boolean {\n  if (query.sessionId && event.sessionId !== query.sessionId) return false;\n\n  if (query.eventId) {\n    const matchesEvent =\n      event.eventId === query.eventId ||\n      event.eventParentIds.includes(query.eventId);\n    if (!matchesEvent) {\n      return false;\n    }\n  }\n\n  if (query.eventType) {\n    const pattern = new RegExp(\n      `^${query.eventType\n        .replace(/[.*+?^${}()|[\\]\\\\]/g, \"\\\\$&\")\n        .replace(/\\\\\\*/g, \".*\")}$`,\n    );\n    if (!pattern.test(event.eventType)) {\n      return false;\n    }\n  }\n\n  return true;\n}\n\n// =============================================================================\n// File Sink Helpers\n// =============================================================================\n\n// Returns true when a file sink's stream is still open and writable.\nfunction isWritable(stream: fs.WriteStream | null): stream is fs.WriteStream {\n  return !!(stream && !stream.destroyed && stream.writable);\n}\n\n// Writes a serialized event to a file sink and converts callback-style stream completion into a promise.\nfunction writeToStream(stream: fs.WriteStream, value: string): Promise<void> {\n  return new Promise<void>((resolve, reject) => {\n    try {\n      stream.write(value, (error?: Error | null) => {\n        if (error) {\n          reject(error);\n          return;\n        }\n        resolve();\n      });\n    } catch (error) {\n      reject(error);\n    }\n  });\n}\n\n// =============================================================================\n// Event Sink Implementations\n// =============================================================================\n\nabstract class FileEventSink implements EventSink {\n  private readonly streamPromise: Promise<fs.WriteStream | null>; // Lazily opens the one file stream owned by this sink when the session directory resolves.\n\n  // Creates a best-effort file sink bound to a single session directory.\n  constructor(sessionDirPromise: Promise<string | null>, fileName: string) {\n    this.streamPromise = sessionDirPromise.then((sessionDir) =>\n      sessionDir\n        ? fs.createWriteStream(path.join(sessionDir, fileName), { flags: \"a\" })\n        : null,\n    );\n  }\n\n  protected abstract serialize(event: FlowEvent): Promise<string | null>;\n\n  // Serializes and appends a single event. File sinks are intentionally best-effort and never allowed to affect library execution flow.\n  async emit(event: FlowEvent): Promise<void> {\n    try {\n      const stream = await this.streamPromise;\n      if (!isWritable(stream)) {\n        return;\n      }\n\n      const serialized = await this.serialize(event);\n      if (!serialized) {\n        return;\n      }\n\n      await writeToStream(stream, serialized);\n    } catch {\n      // best effort only\n    }\n  }\n\n  // File sinks are write-only and do not support query reads.\n  async query(): Promise<FlowEvent[]> {\n    return [];\n  }\n\n  // Closes the underlying file stream when the owning store shuts down.\n  async destroy(): Promise<void> {\n    const stream = await this.streamPromise.catch((): null => null);\n    if (!isWritable(stream)) {\n      return;\n    }\n\n    await new Promise<void>((resolve) => {\n      stream.end(resolve);\n    });\n  }\n}\n\nexport class JsonlFileEventSink extends FileEventSink {\n  // Writes full verbatim events to `session_events.jsonl`.\n  constructor(sessionDirPromise: Promise<string | null>) {\n    super(sessionDirPromise, \"session_events.jsonl\");\n  }\n\n  // Serializes the full event for lossless machine-readable storage.\n  protected async serialize(event: FlowEvent): Promise<string> {\n    return `${JSON.stringify(event)}\\n`;\n  }\n}\n\nexport class PrettyLogFileEventSink extends FileEventSink {\n  // Writes human-readable pretty lines to `session_events.log`.\n  constructor(\n    sessionDirPromise: Promise<string | null>,\n    private readonly store: Pick<EventStoreApi, \"query\">, // Queried during prettification so each line can recover recent ancestry tags.\n  ) {\n    super(sessionDirPromise, \"session_events.log\");\n  }\n\n  // Pretty-prints the event using recent in-memory ancestry.\n  protected async serialize(event: FlowEvent): Promise<string | null> {\n    const line = await prettifyEvent(this.store, prettifySanitizeEvent(event));\n    return line ? `${line}\\n` : null;\n  }\n}\n\nexport class PrettyStderrEventSink implements EventSink {\n  // Writes pretty lines to stderr for verbose local debugging. CDP events are intentionally omitted here to keep stderr high-signal.\n  constructor(private readonly store: Pick<EventStoreApi, \"query\">) {} // Queried during prettification so stderr lines can include recent ancestry tags.\n\n  // Best-effort stderr writer used only for interactive debugging output.\n  async emit(event: FlowEvent): Promise<void> {\n    try {\n      if (prettifyIsCdpEvent(event)) {\n        return;\n      }\n\n      const line = await prettifyEvent(\n        this.store,\n        prettifySanitizeEvent(event),\n      );\n      if (!line) {\n        return;\n      }\n\n      await new Promise<void>((resolve, reject) => {\n        try {\n          process.stderr.write(\n            `${prettifyColorStderrLine(line)}\\n`,\n            (error?: Error | null) => {\n              if (error) {\n                reject(error);\n                return;\n              }\n              resolve();\n            },\n          );\n        } catch (error) {\n          reject(error);\n        }\n      });\n    } catch {\n      // best effort only\n    }\n  }\n\n  // Stderr sink is write-only and does not support query reads.\n  async query(): Promise<FlowEvent[]> {\n    return [];\n  }\n\n  // No teardown is required for stderr.\n  async destroy(): Promise<void> {}\n}\n\nexport class InMemoryEventSink implements EventSink {\n  // Retains recent events for query lookups. Tests usually attach this sink explicitly when they need full historical payloads.\n  constructor(protected readonly limit = Infinity) {}\n\n  protected readonly events: FlowEvent[] = []; // Retained history; `emit()` appends to it and trims old entries when `limit` is exceeded.\n\n  // Gives subclasses a hook to transform events before they are retained.\n  protected storeEvent(event: FlowEvent): FlowEvent {\n    return event;\n  }\n\n  // Stores a new event and trims the oldest retained entries once the sink exceeds its configured limit.\n  async emit(event: FlowEvent): Promise<void> {\n    this.events.push(this.storeEvent(event));\n    if (this.events.length > this.limit) {\n      this.events.splice(0, this.events.length - this.limit);\n    }\n  }\n\n  // Returns retained events that match the query, ordered by creation time.\n  async query(query: EventStoreQuery): Promise<FlowEvent[]> {\n    const filtered = this.events.filter((event) =>\n      matchesEventStoreQuery(event, query),\n    );\n    filtered.sort((left, right) => {\n      const createdAtOrder = left.eventCreatedAt.localeCompare(\n        right.eventCreatedAt,\n      );\n      if (createdAtOrder !== 0) {\n        return createdAtOrder;\n      }\n\n      return left.eventId.localeCompare(right.eventId);\n    });\n    return query.limit ? filtered.slice(-query.limit) : filtered;\n  }\n\n  // Clears retained history when the owning store shuts down.\n  async destroy(): Promise<void> {\n    this.events.length = 0;\n  }\n}\n\nexport class ShallowInMemoryEventSink extends InMemoryEventSink {\n  // Retains only ancestry metadata for the default query sink so verbose or long-running sessions do not hold onto large payloads such as screenshots.\n  protected override storeEvent(event: FlowEvent): FlowEvent {\n    return new FlowEvent({\n      eventType: event.eventType,\n      eventId: event.eventId,\n      eventCreatedAt: event.eventCreatedAt,\n      sessionId: event.sessionId,\n      eventParentIds: [...event.eventParentIds],\n      data: {},\n    });\n  }\n}\n"]}

package/dist/esm/lib/v3/flowlogger/EventStore.d.ts

@@ -0,0 +1,26 @@
+import type { V3Options } from "../types/public/index.js";
+import { EventSink } from "./EventSink.js";
+import { FlowEvent } from "./FlowLogger.js";
+export interface EventStoreQuery {
+    sessionId?: string;
+    eventId?: string;
+    eventType?: string;
+    limit?: number;
+}
+export interface EventStoreApi {
+    readonly sessionId: string;
+    emit(event: FlowEvent): Promise<void>;
+    query(query: EventStoreQuery): Promise<FlowEvent[]>;
+    destroy(): Promise<void>;
+}
+export declare function getConfigDir(): string;
+export declare class EventStore implements EventStoreApi {
+    readonly sessionId: string;
+    private readonly sinks;
+    private destroyed;
+    query: (query: EventStoreQuery) => Promise<FlowEvent[]>;
+    constructor(sessionId: string, options?: V3Options, querySink?: EventSink);
+    private registerSink;
+    emit: (event: FlowEvent) => Promise<void>;
+    destroy(): Promise<void>;
+}