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

package/dist/esm/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "module"
+}

package/dist/esm/tests/browserbase-session-accessors.test.js

@@ -0,0 +1,101 @@
+import { describe, expect, it, vi, beforeEach, afterEach } from "vitest";
+import { V3 } from "../lib/v3/v3.js";
+const MOCK_SESSION_ID = "session-123";
+const MOCK_SESSION_URL = `https://www.browserbase.com/sessions/${MOCK_SESSION_ID}`;
+const MOCK_DEBUG_URL = `https://debug.browserbase.com/${MOCK_SESSION_ID}`;
+vi.mock("../lib/v3/understudy/context", () => {
+  class MockConnection {
+    onTransportClosed = vi.fn();
+    offTransportClosed = vi.fn();
+    send = vi.fn(async () => {
+    });
+  }
+  class MockV3Context {
+    static async create() {
+      return new MockV3Context();
+    }
+    conn = new MockConnection();
+    pages() {
+      return [];
+    }
+    async close() {
+    }
+  }
+  return { V3Context: MockV3Context };
+});
+vi.mock("../lib/v3/launch/browserbase", () => ({
+  createBrowserbaseSession: vi.fn(async () => ({
+    ws: "wss://mock-browserbase",
+    sessionId: MOCK_SESSION_ID,
+    bb: {
+      sessions: {
+        debug: vi.fn(async () => ({ debuggerUrl: MOCK_DEBUG_URL }))
+      }
+    }
+  }))
+}));
+vi.mock("../lib/v3/launch/local", () => ({
+  launchLocalChrome: vi.fn(async () => ({
+    ws: "ws://local-cdp",
+    chrome: { kill: vi.fn(async () => {
+    }) }
+  }))
+}));
+describe("browserbase accessors", () => {
+  beforeEach(() => {
+    process.env.BROWSERBASE_API_KEY = "fake-key";
+    process.env.BROWSERBASE_PROJECT_ID = "fake-project";
+  });
+  afterEach(() => {
+    delete process.env.BROWSERBASE_API_KEY;
+    delete process.env.BROWSERBASE_PROJECT_ID;
+    vi.clearAllMocks();
+  });
+  it("exposes Browserbase session and debug URLs after init", async () => {
+    const v3 = new V3({
+      env: "BROWSERBASE",
+      disableAPI: true,
+      verbose: 0
+    });
+    try {
+      await v3.init();
+      expect(v3.browserbaseSessionURL).toBe(MOCK_SESSION_URL);
+      expect(v3.browserbaseDebugURL).toBe(MOCK_DEBUG_URL);
+    } finally {
+      await v3.close().catch(() => {
+      });
+    }
+  });
+  it("clears stored URLs after close", async () => {
+    const v3 = new V3({
+      env: "BROWSERBASE",
+      disableAPI: true,
+      verbose: 0
+    });
+    await v3.init();
+    await v3.close();
+    expect(v3.browserbaseSessionURL).toBeUndefined();
+    expect(v3.browserbaseDebugURL).toBeUndefined();
+  });
+});
+describe("local accessors", () => {
+  it("stay empty for LOCAL environments", async () => {
+    const v3 = new V3({
+      env: "LOCAL",
+      disableAPI: true,
+      verbose: 0,
+      localBrowserLaunchOptions: {
+        cdpUrl: "ws://local-existing-session"
+      }
+    });
+    try {
+      await v3.init();
+      expect(v3.browserbaseSessionURL).toBeUndefined();
+      expect(v3.browserbaseDebugURL).toBeUndefined();
+    } finally {
+      await v3.close().catch(() => {
+      });
+    }
+  });
+});
+//# sourceMappingURL=browserbase-session-accessors.test.js.map

package/dist/esm/tests/browserbase-session-accessors.test.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../tests/browserbase-session-accessors.test.ts"],
+  "sourcesContent": ["import { describe, expect, it, vi, beforeEach, afterEach } from \"vitest\";\nimport { V3 } from \"../lib/v3/v3.js\";\n\nconst MOCK_SESSION_ID = \"session-123\";\nconst MOCK_SESSION_URL = `https://www.browserbase.com/sessions/${MOCK_SESSION_ID}`;\nconst MOCK_DEBUG_URL = `https://debug.browserbase.com/${MOCK_SESSION_ID}`;\n\nvi.mock(\"../lib/v3/understudy/context\", () => {\n  class MockConnection {\n    onTransportClosed = vi.fn();\n    offTransportClosed = vi.fn();\n    send = vi.fn(async () => {});\n  }\n\n  class MockV3Context {\n    static async create(): Promise<MockV3Context> {\n      return new MockV3Context();\n    }\n\n    conn = new MockConnection();\n\n    pages(): never[] {\n      return [];\n    }\n\n    async close(): Promise<void> {\n      // noop\n    }\n  }\n\n  return { V3Context: MockV3Context };\n});\n\nvi.mock(\"../lib/v3/launch/browserbase\", () => ({\n  createBrowserbaseSession: vi.fn(async () => ({\n    ws: \"wss://mock-browserbase\",\n    sessionId: MOCK_SESSION_ID,\n    bb: {\n      sessions: {\n        debug: vi.fn(async () => ({ debuggerUrl: MOCK_DEBUG_URL })),\n      },\n    },\n  })),\n}));\n\nvi.mock(\"../lib/v3/launch/local\", () => ({\n  launchLocalChrome: vi.fn(async () => ({\n    ws: \"ws://local-cdp\",\n    chrome: { kill: vi.fn(async () => {}) },\n  })),\n}));\n\ndescribe(\"browserbase accessors\", () => {\n  beforeEach(() => {\n    process.env.BROWSERBASE_API_KEY = \"fake-key\";\n    process.env.BROWSERBASE_PROJECT_ID = \"fake-project\";\n  });\n\n  afterEach(() => {\n    delete process.env.BROWSERBASE_API_KEY;\n    delete process.env.BROWSERBASE_PROJECT_ID;\n    vi.clearAllMocks();\n  });\n\n  it(\"exposes Browserbase session and debug URLs after init\", async () => {\n    const v3 = new V3({\n      env: \"BROWSERBASE\",\n      disableAPI: true,\n      verbose: 0,\n    });\n\n    try {\n      await v3.init();\n\n      expect(v3.browserbaseSessionURL).toBe(MOCK_SESSION_URL);\n      expect(v3.browserbaseDebugURL).toBe(MOCK_DEBUG_URL);\n    } finally {\n      await v3.close().catch(() => {});\n    }\n  });\n\n  it(\"clears stored URLs after close\", async () => {\n    const v3 = new V3({\n      env: \"BROWSERBASE\",\n      disableAPI: true,\n      verbose: 0,\n    });\n\n    await v3.init();\n    await v3.close();\n\n    expect(v3.browserbaseSessionURL).toBeUndefined();\n    expect(v3.browserbaseDebugURL).toBeUndefined();\n  });\n});\n\ndescribe(\"local accessors\", () => {\n  it(\"stay empty for LOCAL environments\", async () => {\n    const v3 = new V3({\n      env: \"LOCAL\",\n      disableAPI: true,\n      verbose: 0,\n      localBrowserLaunchOptions: {\n        cdpUrl: \"ws://local-existing-session\",\n      },\n    });\n\n    try {\n      await v3.init();\n      expect(v3.browserbaseSessionURL).toBeUndefined();\n      expect(v3.browserbaseDebugURL).toBeUndefined();\n    } finally {\n      await v3.close().catch(() => {});\n    }\n  });\n});\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/esm/tests/cache-llm-resolution.test.js

@@ -0,0 +1,187 @@
+import { describe, expect, it, vi } from "vitest";
+import { ActCache } from "../lib/v3/cache/ActCache.js";
+import { AgentCache } from "../lib/v3/cache/AgentCache.js";
+function createFakeStorage(entry) {
+  return {
+    enabled: true,
+    readJson: vi.fn().mockResolvedValue({ value: entry }),
+    writeJson: vi.fn().mockResolvedValue({}),
+    directory: "/tmp/cache"
+  };
+}
+describe("Cache LLM client selection", () => {
+  it("ActCache uses provided override client during replay", async () => {
+    const action = {
+      selector: "xpath=/html/body/button",
+      description: "click button",
+      method: "click",
+      arguments: []
+    };
+    const entry = {
+      version: 1,
+      instruction: "click button",
+      url: "https://example.com",
+      variableKeys: [],
+      actions: [action],
+      actionDescription: "click button",
+      message: "done"
+    };
+    const storage = createFakeStorage(entry);
+    const handler = {
+      takeDeterministicAction: vi.fn().mockResolvedValue({
+        success: true,
+        message: "ok",
+        actionDescription: "click button",
+        actions: [action]
+      })
+    };
+    const defaultClient = { id: "default" };
+    const overrideClient = { id: "override" };
+    const cache = new ActCache({
+      storage,
+      logger: vi.fn(),
+      getActHandler: () => handler,
+      getDefaultLlmClient: () => defaultClient,
+      domSettleTimeoutMs: void 0
+    });
+    const context = {
+      instruction: "click button",
+      cacheKey: "abc",
+      pageUrl: "https://example.com",
+      variableKeys: [],
+      variables: void 0
+    };
+    const result = await cache.tryReplay(
+      context,
+      {},
+      void 0,
+      overrideClient
+    );
+    expect(result?.success).toBe(true);
+    expect(handler.takeDeterministicAction).toHaveBeenCalledTimes(1);
+    const call = vi.mocked(handler.takeDeterministicAction).mock.calls[0];
+    expect(call?.[3]).toBe(overrideClient);
+  });
+  it("AgentCache uses provided override client during replay", async () => {
+    const action = {
+      selector: "xpath=/html/body/input",
+      description: "type email",
+      method: "type",
+      arguments: ["test@example.com"]
+    };
+    const agentStep = {
+      type: "act",
+      instruction: "type email",
+      actions: [action]
+    };
+    const entry = {
+      version: 1,
+      instruction: "fill form",
+      startUrl: "https://example.com",
+      options: {},
+      configSignature: "sig",
+      steps: [agentStep],
+      result: { success: true, actions: [] },
+      timestamp: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    const storage = {
+      enabled: true,
+      readJson: vi.fn().mockImplementation(async () => ({ value: entry })),
+      writeJson: vi.fn().mockResolvedValue({}),
+      directory: "/tmp/cache"
+    };
+    const handler = {
+      takeDeterministicAction: vi.fn().mockResolvedValue({
+        success: true,
+        message: "ok",
+        actionDescription: "type email",
+        actions: [action]
+      })
+    };
+    const fakePage = {};
+    const ctx = {
+      awaitActivePage: vi.fn().mockResolvedValue(fakePage)
+    };
+    const defaultClient = { id: "default-agent" };
+    const overrideClient = { id: "override-agent" };
+    const cache = new AgentCache({
+      storage,
+      logger: vi.fn(),
+      getActHandler: () => handler,
+      getContext: () => ctx,
+      getDefaultLlmClient: () => defaultClient,
+      getBaseModelName: () => "openai/gpt-4.1-mini",
+      getSystemPrompt: () => void 0,
+      domSettleTimeoutMs: void 0,
+      act: vi.fn()
+    });
+    const context = {
+      instruction: "fill form",
+      startUrl: "https://example.com",
+      options: {},
+      configSignature: "sig",
+      cacheKey: "agent-key"
+    };
+    const result = await cache.tryReplay(context, overrideClient);
+    expect(result?.success).toBe(true);
+    expect(handler.takeDeterministicAction).toHaveBeenCalledTimes(1);
+    const call = vi.mocked(handler.takeDeterministicAction).mock.calls[0];
+    expect(call?.[3]).toBe(overrideClient);
+  });
+  it("AgentCache replays non-act steps without requiring an override client", async () => {
+    const gotoEntry = {
+      version: 1,
+      instruction: "navigate home",
+      startUrl: "https://example.com/source",
+      options: {},
+      configSignature: "sig",
+      steps: [
+        {
+          type: "goto",
+          url: "https://example.com/target",
+          waitUntil: "load"
+        }
+      ],
+      result: { success: true, actions: [] },
+      timestamp: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    const storage = {
+      enabled: true,
+      readJson: vi.fn().mockResolvedValue({ value: gotoEntry }),
+      writeJson: vi.fn().mockResolvedValue({}),
+      directory: "/tmp/cache"
+    };
+    const handler = {
+      takeDeterministicAction: vi.fn()
+    };
+    const fakePage = { goto: vi.fn() };
+    const ctx = {
+      awaitActivePage: vi.fn().mockResolvedValue(fakePage)
+    };
+    const cache = new AgentCache({
+      storage,
+      logger: vi.fn(),
+      getActHandler: () => handler,
+      getContext: () => ctx,
+      getDefaultLlmClient: () => ({ id: "default" }),
+      getBaseModelName: () => "openai/gpt-4.1-mini",
+      getSystemPrompt: () => void 0,
+      domSettleTimeoutMs: void 0,
+      act: vi.fn()
+    });
+    const context = {
+      instruction: "navigate home",
+      startUrl: "https://example.com/source",
+      options: {},
+      configSignature: "sig",
+      cacheKey: "agent-goto"
+    };
+    const result = await cache.tryReplay(context);
+    expect(result?.success).toBe(true);
+    expect(handler.takeDeterministicAction).not.toHaveBeenCalled();
+    expect(fakePage.goto).toHaveBeenCalledWith("https://example.com/target", {
+      waitUntil: "load"
+    });
+  });
+});
+//# sourceMappingURL=cache-llm-resolution.test.js.map

package/dist/esm/tests/cache-llm-resolution.test.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../tests/cache-llm-resolution.test.ts"],
+  "sourcesContent": ["import { describe, expect, it, vi } from \"vitest\";\nimport { ActCache } from \"../lib/v3/cache/ActCache.js\";\nimport { AgentCache } from \"../lib/v3/cache/AgentCache.js\";\nimport type { CacheStorage } from \"../lib/v3/cache/CacheStorage.js\";\nimport type { ActHandler } from \"../lib/v3/handlers/actHandler.js\";\nimport type { LLMClient } from \"../lib/v3/llm/LLMClient.js\";\nimport type { Page } from \"../lib/v3/understudy/page.js\";\nimport type { V3Context } from \"../lib/v3/understudy/context.js\";\nimport type {\n  ActCacheContext,\n  CachedActEntry,\n  CachedAgentEntry,\n  AgentCacheContext,\n  AgentReplayActStep,\n} from \"../lib/v3/types/private/index.js\";\nimport type {\n  Action,\n  AgentResult,\n  AvailableModel,\n} from \"../lib/v3/types/public/index.js\";\n\nfunction createFakeStorage<T>(entry: T): CacheStorage {\n  return {\n    enabled: true,\n    readJson: vi.fn().mockResolvedValue({ value: entry }),\n    writeJson: vi.fn().mockResolvedValue({}),\n    directory: \"/tmp/cache\",\n  } as unknown as CacheStorage;\n}\n\ndescribe(\"Cache LLM client selection\", () => {\n  it(\"ActCache uses provided override client during replay\", async () => {\n    const action: Action = {\n      selector: \"xpath=/html/body/button\",\n      description: \"click button\",\n      method: \"click\",\n      arguments: [],\n    };\n\n    const entry: CachedActEntry = {\n      version: 1,\n      instruction: \"click button\",\n      url: \"https://example.com\",\n      variableKeys: [],\n      actions: [action],\n      actionDescription: \"click button\",\n      message: \"done\",\n    };\n\n    const storage = createFakeStorage(entry);\n    const handler = {\n      takeDeterministicAction: vi.fn().mockResolvedValue({\n        success: true,\n        message: \"ok\",\n        actionDescription: \"click button\",\n        actions: [action],\n      }),\n    } as unknown as ActHandler;\n    const defaultClient = { id: \"default\" } as unknown as LLMClient;\n    const overrideClient = { id: \"override\" } as unknown as LLMClient;\n\n    const cache = new ActCache({\n      storage,\n      logger: vi.fn(),\n      getActHandler: () => handler,\n      getDefaultLlmClient: () => defaultClient,\n      domSettleTimeoutMs: undefined,\n    });\n\n    const context: ActCacheContext = {\n      instruction: \"click button\",\n      cacheKey: \"abc\",\n      pageUrl: \"https://example.com\",\n      variableKeys: [],\n      variables: undefined,\n    };\n\n    const result = await cache.tryReplay(\n      context,\n      {} as Page,\n      undefined,\n      overrideClient,\n    );\n\n    expect(result?.success).toBe(true);\n    expect(handler.takeDeterministicAction).toHaveBeenCalledTimes(1);\n    const call = vi.mocked(handler.takeDeterministicAction).mock.calls[0];\n    expect(call?.[3]).toBe(overrideClient);\n  });\n\n  it(\"AgentCache uses provided override client during replay\", async () => {\n    const action: Action = {\n      selector: \"xpath=/html/body/input\",\n      description: \"type email\",\n      method: \"type\",\n      arguments: [\"test@example.com\"],\n    };\n\n    const agentStep: AgentReplayActStep = {\n      type: \"act\",\n      instruction: \"type email\",\n      actions: [action],\n    };\n\n    const entry: CachedAgentEntry = {\n      version: 1,\n      instruction: \"fill form\",\n      startUrl: \"https://example.com\",\n      options: {},\n      configSignature: \"sig\",\n      steps: [agentStep],\n      result: { success: true, actions: [] } as AgentResult,\n      timestamp: new Date().toISOString(),\n    };\n\n    const storage = {\n      enabled: true,\n      readJson: vi.fn().mockImplementation(async () => ({ value: entry })),\n      writeJson: vi.fn().mockResolvedValue({}),\n      directory: \"/tmp/cache\",\n    } as unknown as CacheStorage;\n\n    const handler = {\n      takeDeterministicAction: vi.fn().mockResolvedValue({\n        success: true,\n        message: \"ok\",\n        actionDescription: \"type email\",\n        actions: [action],\n      }),\n    } as unknown as ActHandler;\n\n    const fakePage = {} as Page;\n    const ctx = {\n      awaitActivePage: vi.fn().mockResolvedValue(fakePage),\n    } as unknown as V3Context;\n\n    const defaultClient = { id: \"default-agent\" } as unknown as LLMClient;\n    const overrideClient = { id: \"override-agent\" } as unknown as LLMClient;\n\n    const cache = new AgentCache({\n      storage,\n      logger: vi.fn(),\n      getActHandler: () => handler,\n      getContext: () => ctx,\n      getDefaultLlmClient: () => defaultClient,\n      getBaseModelName: () => \"openai/gpt-4.1-mini\" as AvailableModel,\n      getSystemPrompt: () => undefined,\n      domSettleTimeoutMs: undefined,\n      act: vi.fn(),\n    });\n\n    const context: AgentCacheContext = {\n      instruction: \"fill form\",\n      startUrl: \"https://example.com\",\n      options: {},\n      configSignature: \"sig\",\n      cacheKey: \"agent-key\",\n    };\n\n    const result = await cache.tryReplay(context, overrideClient);\n\n    expect(result?.success).toBe(true);\n    expect(handler.takeDeterministicAction).toHaveBeenCalledTimes(1);\n    const call = vi.mocked(handler.takeDeterministicAction).mock.calls[0];\n    expect(call?.[3]).toBe(overrideClient);\n  });\n\n  it(\"AgentCache replays non-act steps without requiring an override client\", async () => {\n    const gotoEntry: CachedAgentEntry = {\n      version: 1,\n      instruction: \"navigate home\",\n      startUrl: \"https://example.com/source\",\n      options: {},\n      configSignature: \"sig\",\n      steps: [\n        {\n          type: \"goto\",\n          url: \"https://example.com/target\",\n          waitUntil: \"load\",\n        },\n      ],\n      result: { success: true, actions: [] } as AgentResult,\n      timestamp: new Date().toISOString(),\n    };\n\n    const storage = {\n      enabled: true,\n      readJson: vi.fn().mockResolvedValue({ value: gotoEntry }),\n      writeJson: vi.fn().mockResolvedValue({}),\n      directory: \"/tmp/cache\",\n    } as unknown as CacheStorage;\n\n    const handler = {\n      takeDeterministicAction: vi.fn(),\n    } as unknown as ActHandler;\n\n    const fakePage = { goto: vi.fn() } as unknown as Page;\n    const ctx = {\n      awaitActivePage: vi.fn().mockResolvedValue(fakePage),\n    } as unknown as V3Context;\n\n    const cache = new AgentCache({\n      storage,\n      logger: vi.fn(),\n      getActHandler: () => handler,\n      getContext: () => ctx,\n      getDefaultLlmClient: () => ({ id: \"default\" }) as unknown as LLMClient,\n      getBaseModelName: () => \"openai/gpt-4.1-mini\" as AvailableModel,\n      getSystemPrompt: () => undefined,\n      domSettleTimeoutMs: undefined,\n      act: vi.fn(),\n    });\n\n    const context: AgentCacheContext = {\n      instruction: \"navigate home\",\n      startUrl: \"https://example.com/source\",\n      options: {},\n      configSignature: \"sig\",\n      cacheKey: \"agent-goto\",\n    };\n\n    const result = await cache.tryReplay(context);\n\n    expect(result?.success).toBe(true);\n    expect(handler.takeDeterministicAction).not.toHaveBeenCalled();\n    expect(fakePage.goto).toHaveBeenCalledWith(\"https://example.com/target\", {\n      waitUntil: \"load\",\n    });\n  });\n});\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/esm/tests/helpers/mockCDPSession.js

@@ -0,0 +1,27 @@
+class MockCDPSession {
+  constructor(handlers = {}, sessionId = "mock-session") {
+    this.handlers = handlers;
+    this.id = sessionId;
+  }
+  id;
+  calls = [];
+  async send(method, params = {}) {
+    this.calls.push({ method, params });
+    const handler = this.handlers[method];
+    if (!handler) return {};
+    return await handler(params);
+  }
+  on() {
+  }
+  off() {
+  }
+  async close() {
+  }
+  callsFor(method) {
+    return this.calls.filter((call) => call.method === method).map(({ params }) => ({ params }));
+  }
+}
+export {
+  MockCDPSession
+};
+//# sourceMappingURL=mockCDPSession.js.map

package/dist/esm/tests/helpers/mockCDPSession.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../tests/helpers/mockCDPSession.ts"],
+  "sourcesContent": ["import type { CDPSessionLike } from \"../../lib/v3/understudy/cdp.js\";\n\ntype Handler = (params?: Record<string, unknown>) => Promise<unknown> | unknown;\n\nexport class MockCDPSession implements CDPSessionLike {\n  public readonly id: string;\n  public readonly calls: Array<{\n    method: string;\n    params?: Record<string, unknown>;\n  }> = [];\n\n  constructor(\n    private readonly handlers: Record<string, Handler> = {},\n    sessionId = \"mock-session\",\n  ) {\n    this.id = sessionId;\n  }\n\n  async send<R = unknown>(\n    method: string,\n    params: Record<string, unknown> = {},\n  ): Promise<R> {\n    this.calls.push({ method, params });\n    const handler = this.handlers[method];\n    if (!handler) return {} as R;\n    return (await handler(params)) as R;\n  }\n\n  on(): void {}\n  off(): void {}\n  async close(): Promise<void> {}\n\n  callsFor(method: string): Array<{ params?: Record<string, unknown> }> {\n    return this.calls\n      .filter((call) => call.method === method)\n      .map(({ params }) => ({ params }));\n  }\n}\n"],
+  "mappings": "AAIO,MAAM,eAAyC;AAAA,EAOpD,YACmB,WAAoC,CAAC,GACtD,YAAY,gBACZ;AAFiB;AAGjB,SAAK,KAAK;AAAA,EACZ;AAAA,EAXgB;AAAA,EACA,QAGX,CAAC;AAAA,EASN,MAAM,KACJ,QACA,SAAkC,CAAC,GACvB;AACZ,SAAK,MAAM,KAAK,EAAE,QAAQ,OAAO,CAAC;AAClC,UAAM,UAAU,KAAK,SAAS,MAAM;AACpC,QAAI,CAAC,QAAS,QAAO,CAAC;AACtB,WAAQ,MAAM,QAAQ,MAAM;AAAA,EAC9B;AAAA,EAEA,KAAW;AAAA,EAAC;AAAA,EACZ,MAAY;AAAA,EAAC;AAAA,EACb,MAAM,QAAuB;AAAA,EAAC;AAAA,EAE9B,SAAS,QAA6D;AACpE,WAAO,KAAK,MACT,OAAO,CAAC,SAAS,KAAK,WAAW,MAAM,EACvC,IAAI,CAAC,EAAE,OAAO,OAAO,EAAE,OAAO,EAAE;AAAA,EACrC;AACF;",
+  "names": []
+}

package/dist/esm/tests/llm-provider.test.js

@@ -0,0 +1,57 @@
+import { describe, expect, it } from "vitest";
+import { getAISDKLanguageModel } from "../lib/v3/llm/LLMProvider.js";
+describe("getAISDKLanguageModel", () => {
+  describe("ollama provider", () => {
+    it("works without clientOptions", () => {
+      const model = getAISDKLanguageModel("ollama", "llama3.2");
+      expect(model).toBeDefined();
+    });
+    it("works with empty clientOptions", () => {
+      const model = getAISDKLanguageModel("ollama", "llama3.2", {});
+      expect(model).toBeDefined();
+    });
+    it("works with clientOptions containing only undefined values", () => {
+      const model = getAISDKLanguageModel("ollama", "llama3.2", {
+        apiKey: void 0
+      });
+      expect(model).toBeDefined();
+    });
+    it("works with clientOptions containing only null values", () => {
+      const model = getAISDKLanguageModel("ollama", "llama3.2", {
+        apiKey: null
+      });
+      expect(model).toBeDefined();
+    });
+    it("works with custom baseURL", () => {
+      const model = getAISDKLanguageModel("ollama", "llama3.2", {
+        baseURL: "http://custom-ollama:11434"
+      });
+      expect(model).toBeDefined();
+    });
+    it("works even when apiKey is mistakenly provided", () => {
+      const model = getAISDKLanguageModel("ollama", "llama3.2", {
+        apiKey: "unnecessary-key"
+      });
+      expect(model).toBeDefined();
+    });
+  });
+  describe("providers with API keys", () => {
+    it("openai requires valid clientOptions for custom configuration", () => {
+      const defaultModel = getAISDKLanguageModel("openai", "gpt-4o");
+      expect(defaultModel).toBeDefined();
+      const customModel = getAISDKLanguageModel("openai", "gpt-4o", {
+        apiKey: "test-key"
+      });
+      expect(customModel).toBeDefined();
+    });
+  });
+  describe("hasValidOptions logic", () => {
+    it("treats undefined apiKey as no options", () => {
+      const model = getAISDKLanguageModel("ollama", "llama3.2", {
+        apiKey: void 0
+      });
+      expect(model).toBeDefined();
+    });
+  });
+});
+//# sourceMappingURL=llm-provider.test.js.map

package/dist/esm/tests/llm-provider.test.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../tests/llm-provider.test.ts"],
+  "sourcesContent": ["import { describe, expect, it } from \"vitest\";\nimport { getAISDKLanguageModel } from \"../lib/v3/llm/LLMProvider.js\";\n\ndescribe(\"getAISDKLanguageModel\", () => {\n  describe(\"ollama provider\", () => {\n    it(\"works without clientOptions\", () => {\n      const model = getAISDKLanguageModel(\"ollama\", \"llama3.2\");\n      expect(model).toBeDefined();\n    });\n\n    it(\"works with empty clientOptions\", () => {\n      const model = getAISDKLanguageModel(\"ollama\", \"llama3.2\", {});\n      expect(model).toBeDefined();\n    });\n\n    it(\"works with clientOptions containing only undefined values\", () => {\n      const model = getAISDKLanguageModel(\"ollama\", \"llama3.2\", {\n        apiKey: undefined,\n      });\n      expect(model).toBeDefined();\n    });\n\n    it(\"works with clientOptions containing only null values\", () => {\n      const model = getAISDKLanguageModel(\"ollama\", \"llama3.2\", {\n        apiKey: null as unknown as string,\n      });\n      expect(model).toBeDefined();\n    });\n\n    it(\"works with custom baseURL\", () => {\n      const model = getAISDKLanguageModel(\"ollama\", \"llama3.2\", {\n        baseURL: \"http://custom-ollama:11434\",\n      });\n      expect(model).toBeDefined();\n    });\n\n    it(\"works even when apiKey is mistakenly provided\", () => {\n      // Ollama doesn't need an API key, but users might set one anyway\n      const model = getAISDKLanguageModel(\"ollama\", \"llama3.2\", {\n        apiKey: \"unnecessary-key\",\n      });\n      expect(model).toBeDefined();\n    });\n  });\n\n  describe(\"providers with API keys\", () => {\n    it(\"openai requires valid clientOptions for custom configuration\", () => {\n      // Without clientOptions, uses default provider\n      const defaultModel = getAISDKLanguageModel(\"openai\", \"gpt-4o\");\n      expect(defaultModel).toBeDefined();\n\n      // With valid apiKey, uses custom provider\n      const customModel = getAISDKLanguageModel(\"openai\", \"gpt-4o\", {\n        apiKey: \"test-key\",\n      });\n      expect(customModel).toBeDefined();\n    });\n  });\n\n  describe(\"hasValidOptions logic\", () => {\n    it(\"treats undefined apiKey as no options\", () => {\n      // This should use the default provider path (AISDKProviders)\n      // not the custom provider path (AISDKProvidersWithAPIKey)\n      const model = getAISDKLanguageModel(\"ollama\", \"llama3.2\", {\n        apiKey: undefined,\n      });\n      expect(model).toBeDefined();\n    });\n  });\n});\n"],
+  "mappings": "AAAA,SAAS,UAAU,QAAQ,UAAU;AACrC,SAAS,6BAA6B;AAEtC,SAAS,yBAAyB,MAAM;AACtC,WAAS,mBAAmB,MAAM;AAChC,OAAG,+BAA+B,MAAM;AACtC,YAAM,QAAQ,sBAAsB,UAAU,UAAU;AACxD,aAAO,KAAK,EAAE,YAAY;AAAA,IAC5B,CAAC;AAED,OAAG,kCAAkC,MAAM;AACzC,YAAM,QAAQ,sBAAsB,UAAU,YAAY,CAAC,CAAC;AAC5D,aAAO,KAAK,EAAE,YAAY;AAAA,IAC5B,CAAC;AAED,OAAG,6DAA6D,MAAM;AACpE,YAAM,QAAQ,sBAAsB,UAAU,YAAY;AAAA,QACxD,QAAQ;AAAA,MACV,CAAC;AACD,aAAO,KAAK,EAAE,YAAY;AAAA,IAC5B,CAAC;AAED,OAAG,wDAAwD,MAAM;AAC/D,YAAM,QAAQ,sBAAsB,UAAU,YAAY;AAAA,QACxD,QAAQ;AAAA,MACV,CAAC;AACD,aAAO,KAAK,EAAE,YAAY;AAAA,IAC5B,CAAC;AAED,OAAG,6BAA6B,MAAM;AACpC,YAAM,QAAQ,sBAAsB,UAAU,YAAY;AAAA,QACxD,SAAS;AAAA,MACX,CAAC;AACD,aAAO,KAAK,EAAE,YAAY;AAAA,IAC5B,CAAC;AAED,OAAG,iDAAiD,MAAM;AAExD,YAAM,QAAQ,sBAAsB,UAAU,YAAY;AAAA,QACxD,QAAQ;AAAA,MACV,CAAC;AACD,aAAO,KAAK,EAAE,YAAY;AAAA,IAC5B,CAAC;AAAA,EACH,CAAC;AAED,WAAS,2BAA2B,MAAM;AACxC,OAAG,gEAAgE,MAAM;AAEvE,YAAM,eAAe,sBAAsB,UAAU,QAAQ;AAC7D,aAAO,YAAY,EAAE,YAAY;AAGjC,YAAM,cAAc,sBAAsB,UAAU,UAAU;AAAA,QAC5D,QAAQ;AAAA,MACV,CAAC;AACD,aAAO,WAAW,EAAE,YAAY;AAAA,IAClC,CAAC;AAAA,EACH,CAAC;AAED,WAAS,yBAAyB,MAAM;AACtC,OAAG,yCAAyC,MAAM;AAGhD,YAAM,QAAQ,sBAAsB,UAAU,YAAY;AAAA,QACxD,QAAQ;AAAA,MACV,CAAC;AACD,aAAO,KAAK,EAAE,YAAY;AAAA,IAC5B,CAAC;AAAA,EACH,CAAC;AACH,CAAC;",
+  "names": []
+}

package/dist/esm/tests/model-deprecation.test.js

@@ -0,0 +1,135 @@
+import { describe, expect, it } from "vitest";
+import { LLMProvider } from "../lib/v3/llm/LLMProvider.js";
+import {
+  UnsupportedModelError,
+  UnsupportedAISDKModelProviderError
+} from "../lib/v3/types/public/sdkErrors.js";
+const mockClientOptions = { apiKey: "test-api-key-for-testing" };
+describe("Model format deprecation", () => {
+  describe("UnsupportedModelError", () => {
+    it("includes guidance to use provider/model format for unknown model names", () => {
+      const error = new UnsupportedModelError([
+        "gpt-4o",
+        "claude-3-5-sonnet-latest"
+      ]);
+      expect(error.message).toContain("provider/model");
+      expect(error.message).toContain(
+        "https://docs.stagehand.dev/v3/configuration/models"
+      );
+    });
+    it("includes example of provider/model format", () => {
+      const error = new UnsupportedModelError(["gpt-4o"]);
+      expect(error.message).toContain("openai/gpt-4o");
+      expect(error.message).toContain("anthropic/claude-sonnet-4");
+    });
+    it("works with feature parameter", () => {
+      const error = new UnsupportedModelError(["gpt-4o"], "extract");
+      expect(error.message).toContain("extract");
+      expect(error.message).toContain("provider/model");
+      expect(error.message).toContain(
+        "https://docs.stagehand.dev/v3/configuration/models"
+      );
+    });
+  });
+  describe("LLMProvider.getClient deprecation warning", () => {
+    it("logs deprecation warning for legacy model names", () => {
+      const logs = [];
+      const logger = (line) => logs.push(line);
+      const provider = new LLMProvider(logger);
+      const client = provider.getClient("gpt-4o", mockClientOptions);
+      expect(client).toBeDefined();
+      const deprecationWarning = logs.find(
+        (log) => log.message.toLowerCase().includes("deprecated") || log.message.toLowerCase().includes("deprecation")
+      );
+      expect(deprecationWarning).toBeDefined();
+      expect(deprecationWarning.level).toBe(0);
+    });
+    it("deprecation warning mentions provider/model format", () => {
+      const logs = [];
+      const logger = (line) => logs.push(line);
+      const provider = new LLMProvider(logger);
+      provider.getClient("gpt-4o", mockClientOptions);
+      const deprecationWarning = logs.find(
+        (log) => log.message.toLowerCase().includes("deprecated") || log.message.toLowerCase().includes("deprecation")
+      );
+      expect(deprecationWarning).toBeDefined();
+      const message = deprecationWarning.message;
+      expect(message).toContain("provider/model");
+      expect(message).toContain("openai/gpt-5");
+    });
+    it("returns OpenAIClient for legacy OpenAI model names", () => {
+      const logs = [];
+      const logger = (line) => logs.push(line);
+      const provider = new LLMProvider(logger);
+      const client = provider.getClient("gpt-4o", mockClientOptions);
+      expect(client).toBeDefined();
+      expect(client.constructor.name).toBe("OpenAIClient");
+    });
+    it("returns AnthropicClient for legacy Anthropic model names", () => {
+      const logs = [];
+      const logger = (line) => logs.push(line);
+      const provider = new LLMProvider(logger);
+      const client = provider.getClient(
+        "claude-3-5-sonnet-latest",
+        mockClientOptions
+      );
+      expect(client).toBeDefined();
+      expect(client.constructor.name).toBe("AnthropicClient");
+    });
+  });
+  describe("LLMProvider.getClient error handling", () => {
+    it("throws UnsupportedModelError for unknown model without slash", () => {
+      const logs = [];
+      const logger = (line) => logs.push(line);
+      const provider = new LLMProvider(logger);
+      expect(() => {
+        provider.getClient("some-unknown-model", mockClientOptions);
+      }).toThrow(UnsupportedModelError);
+    });
+    it("UnsupportedModelError includes provider/model format guidance", () => {
+      const logs = [];
+      const logger = (line) => logs.push(line);
+      const provider = new LLMProvider(logger);
+      try {
+        provider.getClient("some-unknown-model", mockClientOptions);
+      } catch (error) {
+        expect(error.message).toContain("provider/model");
+      }
+    });
+    it("throws UnsupportedAISDKModelProviderError for invalid provider in provider/model format", () => {
+      const logs = [];
+      const logger = (line) => logs.push(line);
+      const provider = new LLMProvider(logger);
+      expect(() => {
+        provider.getClient("invalid-provider/some-model", mockClientOptions);
+      }).toThrow(UnsupportedAISDKModelProviderError);
+    });
+    it("UnsupportedAISDKModelProviderError lists valid providers", () => {
+      const logs = [];
+      const logger = (line) => logs.push(line);
+      const provider = new LLMProvider(logger);
+      try {
+        provider.getClient("invalid-provider/some-model", mockClientOptions);
+      } catch (error) {
+        const message = error.message;
+        expect(message).toContain("openai");
+        expect(message).toContain("anthropic");
+        expect(message).toContain("google");
+      }
+    });
+  });
+  describe("new provider/model format", () => {
+    it("does not log deprecation warning for provider/model format", () => {
+      const logs = [];
+      const logger = (line) => logs.push(line);
+      const provider = new LLMProvider(logger);
+      const client = provider.getClient("openai/gpt-4o", mockClientOptions);
+      expect(client).toBeDefined();
+      const deprecationWarning = logs.find(
+        (log) => log.message.toLowerCase().includes("deprecated") || log.message.toLowerCase().includes("deprecation")
+      );
+      expect(deprecationWarning).toBeUndefined();
+    });
+  });
+});
+//# sourceMappingURL=model-deprecation.test.js.map

package/dist/esm/tests/model-deprecation.test.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../tests/model-deprecation.test.ts"],
+  "sourcesContent": ["import { describe, expect, it } from \"vitest\";\nimport { LLMProvider } from \"../lib/v3/llm/LLMProvider.js\";\nimport {\n  UnsupportedModelError,\n  UnsupportedAISDKModelProviderError,\n} from \"../lib/v3/types/public/sdkErrors.js\";\nimport type { LogLine } from \"../lib/v3/types/public/logs.js\";\n\n// Mock client options with fake API keys for testing\nconst mockClientOptions = { apiKey: \"test-api-key-for-testing\" };\n\ndescribe(\"Model format deprecation\", () => {\n  describe(\"UnsupportedModelError\", () => {\n    it(\"includes guidance to use provider/model format for unknown model names\", () => {\n      const error = new UnsupportedModelError([\n        \"gpt-4o\",\n        \"claude-3-5-sonnet-latest\",\n      ]);\n\n      // Should mention the new format\n      expect(error.message).toContain(\"provider/model\");\n      // Should include link to docs\n      expect(error.message).toContain(\n        \"https://docs.stagehand.dev/v3/configuration/models\",\n      );\n    });\n\n    it(\"includes example of provider/model format\", () => {\n      const error = new UnsupportedModelError([\"gpt-4o\"]);\n\n      // Should provide examples like openai/gpt-4o\n      expect(error.message).toContain(\"openai/gpt-4o\");\n      expect(error.message).toContain(\"anthropic/claude-sonnet-4\");\n    });\n\n    it(\"works with feature parameter\", () => {\n      const error = new UnsupportedModelError([\"gpt-4o\"], \"extract\");\n\n      expect(error.message).toContain(\"extract\");\n      expect(error.message).toContain(\"provider/model\");\n      expect(error.message).toContain(\n        \"https://docs.stagehand.dev/v3/configuration/models\",\n      );\n    });\n  });\n\n  describe(\"LLMProvider.getClient deprecation warning\", () => {\n    it(\"logs deprecation warning for legacy model names\", () => {\n      const logs: LogLine[] = [];\n      const logger = (line: LogLine) => logs.push(line);\n      const provider = new LLMProvider(logger);\n\n      // Using a legacy model name like \"gpt-4o\" instead of \"openai/gpt-4o\"\n      // Should not throw, but should log a deprecation warning\n      const client = provider.getClient(\"gpt-4o\", mockClientOptions);\n\n      // Should return a client (not throw)\n      expect(client).toBeDefined();\n\n      // Should have logged a deprecation warning at level 0\n      const deprecationWarning = logs.find(\n        (log) =>\n          log.message.toLowerCase().includes(\"deprecated\") ||\n          log.message.toLowerCase().includes(\"deprecation\"),\n      );\n      expect(deprecationWarning).toBeDefined();\n      expect(deprecationWarning!.level).toBe(0);\n    });\n\n    it(\"deprecation warning mentions provider/model format\", () => {\n      const logs: LogLine[] = [];\n      const logger = (line: LogLine) => logs.push(line);\n      const provider = new LLMProvider(logger);\n\n      provider.getClient(\"gpt-4o\", mockClientOptions);\n\n      const deprecationWarning = logs.find(\n        (log) =>\n          log.message.toLowerCase().includes(\"deprecated\") ||\n          log.message.toLowerCase().includes(\"deprecation\"),\n      );\n\n      expect(deprecationWarning).toBeDefined();\n      const message = deprecationWarning!.message;\n      // Should mention the provider/model format\n      expect(message).toContain(\"provider/model\");\n      // Should give an example\n      expect(message).toContain(\"openai/gpt-5\");\n    });\n\n    it(\"returns OpenAIClient for legacy OpenAI model names\", () => {\n      const logs: LogLine[] = [];\n      const logger = (line: LogLine) => logs.push(line);\n      const provider = new LLMProvider(logger);\n\n      const client = provider.getClient(\"gpt-4o\", mockClientOptions);\n\n      // Should return a client\n      expect(client).toBeDefined();\n      // The client should be an OpenAIClient (check constructor name)\n      expect(client.constructor.name).toBe(\"OpenAIClient\");\n    });\n\n    it(\"returns AnthropicClient for legacy Anthropic model names\", () => {\n      const logs: LogLine[] = [];\n      const logger = (line: LogLine) => logs.push(line);\n      const provider = new LLMProvider(logger);\n\n      const client = provider.getClient(\n        \"claude-3-5-sonnet-latest\",\n        mockClientOptions,\n      );\n\n      // Should return a client\n      expect(client).toBeDefined();\n      // The client should be an AnthropicClient\n      expect(client.constructor.name).toBe(\"AnthropicClient\");\n    });\n  });\n\n  describe(\"LLMProvider.getClient error handling\", () => {\n    it(\"throws UnsupportedModelError for unknown model without slash\", () => {\n      const logs: LogLine[] = [];\n      const logger = (line: LogLine) => logs.push(line);\n      const provider = new LLMProvider(logger);\n\n      // Unknown model without slash should throw UnsupportedModelError\n      expect(() => {\n        provider.getClient(\"some-unknown-model\", mockClientOptions);\n      }).toThrow(UnsupportedModelError);\n    });\n\n    it(\"UnsupportedModelError includes provider/model format guidance\", () => {\n      const logs: LogLine[] = [];\n      const logger = (line: LogLine) => logs.push(line);\n      const provider = new LLMProvider(logger);\n\n      try {\n        provider.getClient(\"some-unknown-model\", mockClientOptions);\n      } catch (error) {\n        expect((error as Error).message).toContain(\"provider/model\");\n      }\n    });\n\n    it(\"throws UnsupportedAISDKModelProviderError for invalid provider in provider/model format\", () => {\n      const logs: LogLine[] = [];\n      const logger = (line: LogLine) => logs.push(line);\n      const provider = new LLMProvider(logger);\n\n      // Invalid provider but correct format\n      expect(() => {\n        provider.getClient(\"invalid-provider/some-model\", mockClientOptions);\n      }).toThrow(UnsupportedAISDKModelProviderError);\n    });\n\n    it(\"UnsupportedAISDKModelProviderError lists valid providers\", () => {\n      const logs: LogLine[] = [];\n      const logger = (line: LogLine) => logs.push(line);\n      const provider = new LLMProvider(logger);\n\n      try {\n        provider.getClient(\"invalid-provider/some-model\", mockClientOptions);\n      } catch (error) {\n        const message = (error as Error).message;\n        // Should list valid providers\n        expect(message).toContain(\"openai\");\n        expect(message).toContain(\"anthropic\");\n        expect(message).toContain(\"google\");\n      }\n    });\n  });\n\n  describe(\"new provider/model format\", () => {\n    it(\"does not log deprecation warning for provider/model format\", () => {\n      const logs: LogLine[] = [];\n      const logger = (line: LogLine) => logs.push(line);\n      const provider = new LLMProvider(logger);\n\n      // Using the new format\n      const client = provider.getClient(\"openai/gpt-4o\", mockClientOptions);\n\n      expect(client).toBeDefined();\n\n      // Should NOT have a deprecation warning\n      const deprecationWarning = logs.find(\n        (log) =>\n          log.message.toLowerCase().includes(\"deprecated\") ||\n          log.message.toLowerCase().includes(\"deprecation\"),\n      );\n      expect(deprecationWarning).toBeUndefined();\n    });\n  });\n});\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/esm/tests/page-snapshot.test.js

@@ -0,0 +1,36 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { promises as fs } from "fs";
+import { Page } from "../lib/v3/understudy/page.js";
+import * as snapshotModule from "../lib/v3/understudy/a11y/snapshot/index.js";
+const baseSnapshot = {
+  combinedTree: "tree",
+  combinedXpathMap: {},
+  combinedUrlMap: {},
+  perFrame: []
+};
+describe("Page.snapshot", () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+  it("forwards the includeIframes flag to captureHybridSnapshot", async () => {
+    vi.spyOn(fs, "writeFile").mockResolvedValue();
+    const captureSpy = vi.spyOn(snapshotModule, "captureHybridSnapshot").mockResolvedValue(baseSnapshot);
+    const fakePage = {};
+    await Page.prototype.snapshot.call(fakePage, { includeIframes: false });
+    expect(captureSpy).toHaveBeenCalledWith(fakePage, {
+      pierceShadow: true,
+      includeIframes: false
+    });
+  });
+  it("falls back to default iframe inclusion when option is omitted", async () => {
+    vi.spyOn(fs, "writeFile").mockResolvedValue();
+    const captureSpy = vi.spyOn(snapshotModule, "captureHybridSnapshot").mockResolvedValue(baseSnapshot);
+    const fakePage = {};
+    await Page.prototype.snapshot.call(fakePage);
+    expect(captureSpy).toHaveBeenCalledWith(fakePage, {
+      pierceShadow: true,
+      includeIframes: void 0
+    });
+  });
+});
+//# sourceMappingURL=page-snapshot.test.js.map