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

package/dist/esm/tests/unit/flowlogger-eventstore.test.js

@@ -0,0 +1,248 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { EventStore } from "../../lib/v3/flowlogger/EventStore.js";
+import { EventEmitterWithWildcardSupport } from "../../lib/v3/flowlogger/EventEmitter.js";
+import { FlowEvent } from "../../lib/v3/flowlogger/FlowLogger.js";
+function attachEventStoreToBus(store, bus) {
+    const onFlowEvent = (event) => {
+        if (event instanceof FlowEvent) {
+            void store.emit(event);
+        }
+    };
+    bus.on("*", onFlowEvent);
+    return () => {
+        bus.off("*", onFlowEvent);
+    };
+}
+function createVerboseStoreHarness() {
+    const writes = [];
+    process.stderr.write = ((chunk, cb) => {
+        writes.push(String(chunk));
+        cb?.(null);
+        return true;
+    });
+    const store = new EventStore("session-test");
+    const bus = new EventEmitterWithWildcardSupport();
+    const detachBus = attachEventStoreToBus(store, bus);
+    return { writes, store, bus, detachBus };
+}
+describe("flow logger event store", () => {
+    const stderrWrite = process.stderr.write.bind(process.stderr);
+    afterEach(() => {
+        process.stderr.write = stderrWrite;
+    });
+    it("queries recent events from the default in-memory sink", async () => {
+        const store = new EventStore("session-test");
+        await store.emit(new FlowEvent({
+            eventType: "StagehandExtractEvent",
+            sessionId: "session-test",
+            eventId: "stagehand-1234",
+            eventCreatedAt: "2026-03-16T21:45:00.000Z",
+            data: { params: ["grab title"] },
+        }));
+        const events = await store.query({});
+        expect(events).toHaveLength(1);
+        expect(events[0].eventType).toBe("StagehandExtractEvent");
+        await store.destroy();
+    });
+    it("drops payloads from the default in-memory sink", async () => {
+        const store = new EventStore("session-test");
+        await store.emit(new FlowEvent({
+            eventType: "LlmRequestEvent",
+            sessionId: "session-test",
+            eventId: "llm-1234",
+            eventCreatedAt: "2026-03-16T21:45:00.000Z",
+            data: {
+                prompt: [{ type: "image_url", image_url: { url: "huge" } }],
+                output: "huge",
+            },
+        }));
+        const [event] = await store.query({});
+        expect(event.eventType).toBe("LlmRequestEvent");
+        expect(event.eventId).toBe("llm-1234");
+        expect(event.data).toEqual({});
+        await store.destroy();
+    });
+    it("renders semantic hierarchy tags for non-cdp stderr events only", async () => {
+        // Intercept stderr so the pretty sink can be asserted without polluting the
+        // real test runner output.
+        const { writes, store, bus, detachBus } = createVerboseStoreHarness();
+        const stepEvent = new FlowEvent({
+            eventType: "StagehandExtractEvent",
+            sessionId: "session-test",
+            eventId: "stagehand-1234",
+            eventCreatedAt: "2026-03-16T21:45:00.000Z",
+            data: { params: ["grab title"] },
+        });
+        const cdpEvent = new FlowEvent({
+            eventType: "CdpCallEvent",
+            sessionId: "session-test",
+            eventId: "cdp-call-5678",
+            eventCreatedAt: "2026-03-16T21:45:00.100Z",
+            eventParentIds: [stepEvent.eventId],
+            data: {
+                method: "Runtime.evaluate",
+                params: { expression: "2 + 2" },
+                targetId: "1234567890ABCDEF1234567890ABCDEF",
+            },
+        });
+        // The stderr sink intentionally suppresses CDP noise even though the event
+        // still exists for in-memory and file-backed sinks.
+        bus.emit(stepEvent.eventType, stepEvent);
+        bus.emit(cdpEvent.eventType, cdpEvent);
+        await new Promise((resolve) => setTimeout(resolve, 0));
+        expect(writes).toHaveLength(1);
+        expect(writes[0]).toContain("[🆂 #1234 EXTRACT]");
+        expect(writes[0]).toContain("Stagehand.extract");
+        expect(writes[0]).not.toContain("Runtime.evaluate");
+        detachBus();
+        await store.destroy();
+    });
+    it("renders generic stagehand events without crashing the stderr sink", async () => {
+        const { writes, store, bus, detachBus } = createVerboseStoreHarness();
+        // `StagehandEvent` has no action suffix, so this guards the formatter path
+        // that cannot assume a method name exists.
+        bus.emit("StagehandEvent", new FlowEvent({
+            eventType: "StagehandEvent",
+            sessionId: "session-test",
+            eventId: "stagehand-0001",
+            eventCreatedAt: "2026-03-16T21:45:00.000Z",
+            data: { params: ["noop"] },
+        }));
+        await new Promise((resolve) => setTimeout(resolve, 0));
+        expect(writes).toHaveLength(1);
+        expect(writes[0]).toContain("[🆂 #0001");
+        expect(writes[0]).toContain("Stagehand(");
+        detachBus();
+        await store.destroy();
+    });
+    it("colorizes pretty stderr output with ansi escapes when enabled", async () => {
+        const previousForceColor = process.env.FORCE_COLOR;
+        const previousNoColor = process.env.NO_COLOR;
+        delete process.env.NO_COLOR;
+        process.env.FORCE_COLOR = "1";
+        const { writes, store, bus, detachBus } = createVerboseStoreHarness();
+        try {
+            bus.emit("StagehandActEvent", new FlowEvent({
+                eventType: "StagehandActEvent",
+                sessionId: "session-test",
+                eventId: "stagehand-0002",
+                eventCreatedAt: "2026-03-16T21:45:00.000Z",
+                data: { params: ["click submit"] },
+            }));
+            await new Promise((resolve) => setTimeout(resolve, 0));
+            expect(writes).toHaveLength(1);
+            expect(writes[0]).toContain("\u001B[");
+        }
+        finally {
+            if (previousNoColor === undefined) {
+                delete process.env.NO_COLOR;
+            }
+            else {
+                process.env.NO_COLOR = previousNoColor;
+            }
+            if (previousForceColor === undefined) {
+                delete process.env.FORCE_COLOR;
+            }
+            else {
+                process.env.FORCE_COLOR = previousForceColor;
+            }
+            detachBus();
+            await store.destroy();
+        }
+    });
+    it("keeps agent ancestry and start ids for completion events after many child events", async () => {
+        const { writes, store, bus, detachBus } = createVerboseStoreHarness();
+        const agentEvent = new FlowEvent({
+            eventType: "AgentExecuteEvent",
+            sessionId: "session-test",
+            eventId: "agent-1234",
+            eventCreatedAt: "2026-03-16T21:45:00.000Z",
+            data: { params: [{ instruction: "click the button" }] },
+        });
+        const actEvent = new FlowEvent({
+            eventType: "StagehandActEvent",
+            sessionId: "session-test",
+            eventId: "stagehand-2222",
+            eventCreatedAt: "2026-03-16T21:45:00.001Z",
+            eventParentIds: [agentEvent.eventId],
+            data: { params: ["click the button"] },
+        });
+        const clickEvent = new FlowEvent({
+            eventType: "UnderstudyClickEvent",
+            sessionId: "session-test",
+            eventId: "action-3333",
+            eventCreatedAt: "2026-03-16T21:45:00.002Z",
+            eventParentIds: [agentEvent.eventId, actEvent.eventId],
+            data: { target: "xpath=/button[1]" },
+        });
+        bus.emit(agentEvent.eventType, agentEvent);
+        bus.emit(actEvent.eventType, actEvent);
+        bus.emit(clickEvent.eventType, clickEvent);
+        // Flood the retained history with child events so the completion lines have
+        // to recover their displayed ancestry from the queryable sink.
+        for (let index = 0; index < 150; index += 1) {
+            bus.emit("CdpCallEvent", new FlowEvent({
+                eventType: "CdpCallEvent",
+                sessionId: "session-test",
+                eventId: `cdp-${String(index).padStart(4, "0")}`,
+                eventCreatedAt: `2026-03-16T21:45:00.${String(index + 10).padStart(3, "0")}Z`,
+                eventParentIds: [
+                    agentEvent.eventId,
+                    actEvent.eventId,
+                    clickEvent.eventId,
+                ],
+                data: {
+                    method: "Runtime.evaluate",
+                    params: { expression: `${index}` },
+                    targetId: "1234567890ABCDEF1234567890ABCDEF",
+                },
+            }));
+        }
+        bus.emit("UnderstudyClickCompletedEvent", new FlowEvent({
+            eventType: "UnderstudyClickCompletedEvent",
+            sessionId: "session-test",
+            eventId: "done-4444",
+            eventCreatedAt: "2026-03-16T21:45:01.000Z",
+            eventParentIds: [
+                agentEvent.eventId,
+                actEvent.eventId,
+                clickEvent.eventId,
+            ],
+            data: { durationMs: 250 },
+        }));
+        bus.emit("StagehandActCompletedEvent", new FlowEvent({
+            eventType: "StagehandActCompletedEvent",
+            sessionId: "session-test",
+            eventId: "done-5555",
+            eventCreatedAt: "2026-03-16T21:45:01.001Z",
+            eventParentIds: [agentEvent.eventId, actEvent.eventId],
+            data: { durationMs: 500 },
+        }));
+        bus.emit("AgentExecuteCompletedEvent", new FlowEvent({
+            eventType: "AgentExecuteCompletedEvent",
+            sessionId: "session-test",
+            eventId: "done-6666",
+            eventCreatedAt: "2026-03-16T21:45:01.002Z",
+            eventParentIds: [agentEvent.eventId],
+            data: { durationMs: 750 },
+        }));
+        await new Promise((resolve) => setTimeout(resolve, 0));
+        // Completion lines should reference the original started-event ids, not the
+        // synthetic completed-event ids emitted at the end of the lifecycle.
+        const clickCompletedLine = writes.find((line) => line.includes("CLICK completed"));
+        const actCompletedLine = writes.find((line) => line.includes("ACT completed"));
+        const agentCompletedLine = writes.find((line) => line.includes("Agent.execute() completed"));
+        expect(clickCompletedLine).toContain("[🅰 #1234]");
+        expect(clickCompletedLine).toContain("[🆂 #2222 ACT]");
+        expect(clickCompletedLine).toContain("[🆄 #3333 CLICK]");
+        expect(clickCompletedLine).not.toContain("#4444");
+        expect(actCompletedLine).toContain("[🅰 #1234]");
+        expect(actCompletedLine).toContain("[🆂 #2222 ACT]");
+        expect(actCompletedLine).not.toContain("#5555");
+        expect(agentCompletedLine).toContain("[🅰 #1234]");
+        expect(agentCompletedLine).not.toContain("#6666");
+        detachBus();
+        await store.destroy();
+    });
+});
+//# sourceMappingURL=flowlogger-eventstore.test.js.map

package/dist/esm/tests/unit/flowlogger-eventstore.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"flowlogger-eventstore.test.js","sourceRoot":"","sources":["../../../../tests/unit/flowlogger-eventstore.test.ts"],"names":[],"mappings":"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","sourcesContent":["import { afterEach, describe, expect, it } from \"vitest\";\nimport { EventStore } from \"../../lib/v3/flowlogger/EventStore.js\";\nimport { EventEmitterWithWildcardSupport } from \"../../lib/v3/flowlogger/EventEmitter.js\";\nimport { FlowEvent } from \"../../lib/v3/flowlogger/FlowLogger.js\";\n\nfunction attachEventStoreToBus(\n  store: EventStore,\n  bus: EventEmitterWithWildcardSupport,\n): () => void {\n  const onFlowEvent = (event: unknown) => {\n    if (event instanceof FlowEvent) {\n      void store.emit(event);\n    }\n  };\n\n  bus.on(\"*\", onFlowEvent);\n  return () => {\n    bus.off(\"*\", onFlowEvent);\n  };\n}\n\nfunction createVerboseStoreHarness(): {\n  writes: string[];\n  store: EventStore;\n  bus: EventEmitterWithWildcardSupport;\n  detachBus: () => void;\n} {\n  const writes: string[] = [];\n  process.stderr.write = ((\n    chunk: string,\n    cb?: (error?: Error | null) => void,\n  ) => {\n    writes.push(String(chunk));\n    cb?.(null);\n    return true;\n  }) as typeof process.stderr.write;\n\n  const store = new EventStore(\"session-test\");\n  const bus = new EventEmitterWithWildcardSupport();\n  const detachBus = attachEventStoreToBus(store, bus);\n\n  return { writes, store, bus, detachBus };\n}\n\ndescribe(\"flow logger event store\", () => {\n  const stderrWrite = process.stderr.write.bind(process.stderr);\n\n  afterEach(() => {\n    process.stderr.write = stderrWrite;\n  });\n\n  it(\"queries recent events from the default in-memory sink\", async () => {\n    const store = new EventStore(\"session-test\");\n\n    await store.emit(\n      new FlowEvent({\n        eventType: \"StagehandExtractEvent\",\n        sessionId: \"session-test\",\n        eventId: \"stagehand-1234\",\n        eventCreatedAt: \"2026-03-16T21:45:00.000Z\",\n        data: { params: [\"grab title\"] },\n      }),\n    );\n\n    const events = await store.query({});\n    expect(events).toHaveLength(1);\n    expect(events[0].eventType).toBe(\"StagehandExtractEvent\");\n\n    await store.destroy();\n  });\n\n  it(\"drops payloads from the default in-memory sink\", async () => {\n    const store = new EventStore(\"session-test\");\n\n    await store.emit(\n      new FlowEvent({\n        eventType: \"LlmRequestEvent\",\n        sessionId: \"session-test\",\n        eventId: \"llm-1234\",\n        eventCreatedAt: \"2026-03-16T21:45:00.000Z\",\n        data: {\n          prompt: [{ type: \"image_url\", image_url: { url: \"huge\" } }],\n          output: \"huge\",\n        },\n      }),\n    );\n\n    const [event] = await store.query({});\n    expect(event.eventType).toBe(\"LlmRequestEvent\");\n    expect(event.eventId).toBe(\"llm-1234\");\n    expect(event.data).toEqual({});\n\n    await store.destroy();\n  });\n\n  it(\"renders semantic hierarchy tags for non-cdp stderr events only\", async () => {\n    // Intercept stderr so the pretty sink can be asserted without polluting the\n    // real test runner output.\n    const { writes, store, bus, detachBus } = createVerboseStoreHarness();\n\n    const stepEvent = new FlowEvent({\n      eventType: \"StagehandExtractEvent\",\n      sessionId: \"session-test\",\n      eventId: \"stagehand-1234\",\n      eventCreatedAt: \"2026-03-16T21:45:00.000Z\",\n      data: { params: [\"grab title\"] },\n    });\n    const cdpEvent = new FlowEvent({\n      eventType: \"CdpCallEvent\",\n      sessionId: \"session-test\",\n      eventId: \"cdp-call-5678\",\n      eventCreatedAt: \"2026-03-16T21:45:00.100Z\",\n      eventParentIds: [stepEvent.eventId],\n      data: {\n        method: \"Runtime.evaluate\",\n        params: { expression: \"2 + 2\" },\n        targetId: \"1234567890ABCDEF1234567890ABCDEF\",\n      },\n    });\n\n    // The stderr sink intentionally suppresses CDP noise even though the event\n    // still exists for in-memory and file-backed sinks.\n    bus.emit(stepEvent.eventType, stepEvent);\n    bus.emit(cdpEvent.eventType, cdpEvent);\n    await new Promise((resolve) => setTimeout(resolve, 0));\n\n    expect(writes).toHaveLength(1);\n    expect(writes[0]).toContain(\"[🆂 #1234 EXTRACT]\");\n    expect(writes[0]).toContain(\"Stagehand.extract\");\n    expect(writes[0]).not.toContain(\"Runtime.evaluate\");\n\n    detachBus();\n    await store.destroy();\n  });\n\n  it(\"renders generic stagehand events without crashing the stderr sink\", async () => {\n    const { writes, store, bus, detachBus } = createVerboseStoreHarness();\n\n    // `StagehandEvent` has no action suffix, so this guards the formatter path\n    // that cannot assume a method name exists.\n    bus.emit(\n      \"StagehandEvent\",\n      new FlowEvent({\n        eventType: \"StagehandEvent\",\n        sessionId: \"session-test\",\n        eventId: \"stagehand-0001\",\n        eventCreatedAt: \"2026-03-16T21:45:00.000Z\",\n        data: { params: [\"noop\"] },\n      }),\n    );\n    await new Promise((resolve) => setTimeout(resolve, 0));\n\n    expect(writes).toHaveLength(1);\n    expect(writes[0]).toContain(\"[🆂 #0001\");\n    expect(writes[0]).toContain(\"Stagehand(\");\n\n    detachBus();\n    await store.destroy();\n  });\n\n  it(\"colorizes pretty stderr output with ansi escapes when enabled\", async () => {\n    const previousForceColor = process.env.FORCE_COLOR;\n    const previousNoColor = process.env.NO_COLOR;\n    delete process.env.NO_COLOR;\n    process.env.FORCE_COLOR = \"1\";\n\n    const { writes, store, bus, detachBus } = createVerboseStoreHarness();\n\n    try {\n      bus.emit(\n        \"StagehandActEvent\",\n        new FlowEvent({\n          eventType: \"StagehandActEvent\",\n          sessionId: \"session-test\",\n          eventId: \"stagehand-0002\",\n          eventCreatedAt: \"2026-03-16T21:45:00.000Z\",\n          data: { params: [\"click submit\"] },\n        }),\n      );\n      await new Promise((resolve) => setTimeout(resolve, 0));\n\n      expect(writes).toHaveLength(1);\n      expect(writes[0]).toContain(\"\\u001B[\");\n    } finally {\n      if (previousNoColor === undefined) {\n        delete process.env.NO_COLOR;\n      } else {\n        process.env.NO_COLOR = previousNoColor;\n      }\n\n      if (previousForceColor === undefined) {\n        delete process.env.FORCE_COLOR;\n      } else {\n        process.env.FORCE_COLOR = previousForceColor;\n      }\n\n      detachBus();\n      await store.destroy();\n    }\n  });\n\n  it(\"keeps agent ancestry and start ids for completion events after many child events\", async () => {\n    const { writes, store, bus, detachBus } = createVerboseStoreHarness();\n\n    const agentEvent = new FlowEvent({\n      eventType: \"AgentExecuteEvent\",\n      sessionId: \"session-test\",\n      eventId: \"agent-1234\",\n      eventCreatedAt: \"2026-03-16T21:45:00.000Z\",\n      data: { params: [{ instruction: \"click the button\" }] },\n    });\n    const actEvent = new FlowEvent({\n      eventType: \"StagehandActEvent\",\n      sessionId: \"session-test\",\n      eventId: \"stagehand-2222\",\n      eventCreatedAt: \"2026-03-16T21:45:00.001Z\",\n      eventParentIds: [agentEvent.eventId],\n      data: { params: [\"click the button\"] },\n    });\n    const clickEvent = new FlowEvent({\n      eventType: \"UnderstudyClickEvent\",\n      sessionId: \"session-test\",\n      eventId: \"action-3333\",\n      eventCreatedAt: \"2026-03-16T21:45:00.002Z\",\n      eventParentIds: [agentEvent.eventId, actEvent.eventId],\n      data: { target: \"xpath=/button[1]\" },\n    });\n\n    bus.emit(agentEvent.eventType, agentEvent);\n    bus.emit(actEvent.eventType, actEvent);\n    bus.emit(clickEvent.eventType, clickEvent);\n\n    // Flood the retained history with child events so the completion lines have\n    // to recover their displayed ancestry from the queryable sink.\n    for (let index = 0; index < 150; index += 1) {\n      bus.emit(\n        \"CdpCallEvent\",\n        new FlowEvent({\n          eventType: \"CdpCallEvent\",\n          sessionId: \"session-test\",\n          eventId: `cdp-${String(index).padStart(4, \"0\")}`,\n          eventCreatedAt: `2026-03-16T21:45:00.${String(index + 10).padStart(3, \"0\")}Z`,\n          eventParentIds: [\n            agentEvent.eventId,\n            actEvent.eventId,\n            clickEvent.eventId,\n          ],\n          data: {\n            method: \"Runtime.evaluate\",\n            params: { expression: `${index}` },\n            targetId: \"1234567890ABCDEF1234567890ABCDEF\",\n          },\n        }),\n      );\n    }\n\n    bus.emit(\n      \"UnderstudyClickCompletedEvent\",\n      new FlowEvent({\n        eventType: \"UnderstudyClickCompletedEvent\",\n        sessionId: \"session-test\",\n        eventId: \"done-4444\",\n        eventCreatedAt: \"2026-03-16T21:45:01.000Z\",\n        eventParentIds: [\n          agentEvent.eventId,\n          actEvent.eventId,\n          clickEvent.eventId,\n        ],\n        data: { durationMs: 250 },\n      }),\n    );\n    bus.emit(\n      \"StagehandActCompletedEvent\",\n      new FlowEvent({\n        eventType: \"StagehandActCompletedEvent\",\n        sessionId: \"session-test\",\n        eventId: \"done-5555\",\n        eventCreatedAt: \"2026-03-16T21:45:01.001Z\",\n        eventParentIds: [agentEvent.eventId, actEvent.eventId],\n        data: { durationMs: 500 },\n      }),\n    );\n    bus.emit(\n      \"AgentExecuteCompletedEvent\",\n      new FlowEvent({\n        eventType: \"AgentExecuteCompletedEvent\",\n        sessionId: \"session-test\",\n        eventId: \"done-6666\",\n        eventCreatedAt: \"2026-03-16T21:45:01.002Z\",\n        eventParentIds: [agentEvent.eventId],\n        data: { durationMs: 750 },\n      }),\n    );\n    await new Promise((resolve) => setTimeout(resolve, 0));\n\n    // Completion lines should reference the original started-event ids, not the\n    // synthetic completed-event ids emitted at the end of the lifecycle.\n    const clickCompletedLine = writes.find((line) =>\n      line.includes(\"CLICK completed\"),\n    );\n    const actCompletedLine = writes.find((line) =>\n      line.includes(\"ACT completed\"),\n    );\n    const agentCompletedLine = writes.find((line) =>\n      line.includes(\"Agent.execute() completed\"),\n    );\n\n    expect(clickCompletedLine).toContain(\"[🅰 #1234]\");\n    expect(clickCompletedLine).toContain(\"[🆂 #2222 ACT]\");\n    expect(clickCompletedLine).toContain(\"[🆄 #3333 CLICK]\");\n    expect(clickCompletedLine).not.toContain(\"#4444\");\n\n    expect(actCompletedLine).toContain(\"[🅰 #1234]\");\n    expect(actCompletedLine).toContain(\"[🆂 #2222 ACT]\");\n    expect(actCompletedLine).not.toContain(\"#5555\");\n\n    expect(agentCompletedLine).toContain(\"[🅰 #1234]\");\n    expect(agentCompletedLine).not.toContain(\"#6666\");\n\n    detachBus();\n    await store.destroy();\n  });\n});\n"]}

package/dist/esm/tests/unit/openai-cua-client.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/esm/tests/unit/openai-cua-client.test.js

@@ -0,0 +1,69 @@
+import { describe, expect, it, vi } from "vitest";
+import { OpenAICUAClient } from "../../lib/v3/agent/OpenAICUAClient.js";
+function createClient() {
+    return new OpenAICUAClient("openai", "computer-use-preview-2025-03-11", undefined, { apiKey: "test-key" });
+}
+describe("OpenAICUAClient", () => {
+    it("exposes captchaSolvedProceed tool after a captcha context note", () => {
+        const client = createClient();
+        // Before captcha note — tool should not be active
+        expect(client
+            .captchaSolvedToolActive).toBe(false);
+        // Simulate a captcha context note being added (as the CUA handler does)
+        client.addContextNote("A captcha was automatically detected and solved — no further interaction needed.");
+        expect(client
+            .captchaSolvedToolActive).toBe(true);
+    });
+    it("does NOT activate captcha tool for non-captcha context notes", () => {
+        const client = createClient();
+        client.addContextNote("The page has finished loading.");
+        expect(client
+            .captchaSolvedToolActive).toBe(false);
+    });
+    it("deactivates captcha tool after takeAction handles the function call", async () => {
+        const client = createClient();
+        client.addContextNote("A captcha was solved.");
+        expect(client
+            .captchaSolvedToolActive).toBe(true);
+        // Simulate the model calling the captchaSolvedProceed tool
+        const result = await client.takeAction([
+            {
+                type: "function_call",
+                name: "captchaSolvedProceed",
+                call_id: "call-1",
+                arguments: "{}",
+            },
+        ], vi.fn());
+        // Tool should be deactivated
+        expect(client
+            .captchaSolvedToolActive).toBe(false);
+        // Result should contain a function_call_output confirming proceed
+        expect(result).toEqual([
+            {
+                type: "function_call_output",
+                call_id: "call-1",
+                output: expect.stringContaining("Continue completing"),
+            },
+        ]);
+    });
+    it("does NOT auto-continue follow-up questions without a captcha context", async () => {
+        const client = createClient();
+        const executeStepSpy = vi.spyOn(client, "executeStep");
+        executeStepSpy.mockResolvedValueOnce({
+            actions: [],
+            message: "I've located the Submit button. Should I go ahead and submit it?",
+            completed: true,
+            nextInputItems: [],
+            responseId: "response-1",
+            usage: { input_tokens: 1, output_tokens: 1, inference_time_ms: 1 },
+        });
+        const result = await client.execute({
+            options: { instruction: "Submit the form.", maxSteps: 10 },
+            logger: vi.fn(),
+        });
+        // Should NOT have continued — the model's follow-up is treated as completion
+        expect(executeStepSpy).toHaveBeenCalledTimes(1);
+        expect(result.completed).toBe(true);
+    });
+});
+//# sourceMappingURL=openai-cua-client.test.js.map

package/dist/esm/tests/unit/openai-cua-client.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"openai-cua-client.test.js","sourceRoot":"","sources":["../../../../tests/unit/openai-cua-client.test.ts"],"names":[],"mappings":"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","sourcesContent":["import { describe, expect, it, vi } from \"vitest\";\nimport { OpenAICUAClient } from \"../../lib/v3/agent/OpenAICUAClient.js\";\n\nfunction createClient() {\n  return new OpenAICUAClient(\n    \"openai\",\n    \"computer-use-preview-2025-03-11\",\n    undefined,\n    { apiKey: \"test-key\" },\n  );\n}\n\ndescribe(\"OpenAICUAClient\", () => {\n  it(\"exposes captchaSolvedProceed tool after a captcha context note\", () => {\n    const client = createClient();\n\n    // Before captcha note — tool should not be active\n    expect(\n      (client as unknown as { captchaSolvedToolActive: boolean })\n        .captchaSolvedToolActive,\n    ).toBe(false);\n\n    // Simulate a captcha context note being added (as the CUA handler does)\n    client.addContextNote(\n      \"A captcha was automatically detected and solved — no further interaction needed.\",\n    );\n\n    expect(\n      (client as unknown as { captchaSolvedToolActive: boolean })\n        .captchaSolvedToolActive,\n    ).toBe(true);\n  });\n\n  it(\"does NOT activate captcha tool for non-captcha context notes\", () => {\n    const client = createClient();\n\n    client.addContextNote(\"The page has finished loading.\");\n\n    expect(\n      (client as unknown as { captchaSolvedToolActive: boolean })\n        .captchaSolvedToolActive,\n    ).toBe(false);\n  });\n\n  it(\"deactivates captcha tool after takeAction handles the function call\", async () => {\n    const client = createClient();\n    client.addContextNote(\"A captcha was solved.\");\n\n    expect(\n      (client as unknown as { captchaSolvedToolActive: boolean })\n        .captchaSolvedToolActive,\n    ).toBe(true);\n\n    // Simulate the model calling the captchaSolvedProceed tool\n    const result = await (\n      client as unknown as {\n        takeAction: (\n          output: unknown[],\n          logger: (msg: unknown) => void,\n        ) => Promise<unknown[]>;\n      }\n    ).takeAction(\n      [\n        {\n          type: \"function_call\",\n          name: \"captchaSolvedProceed\",\n          call_id: \"call-1\",\n          arguments: \"{}\",\n        },\n      ],\n      vi.fn(),\n    );\n\n    // Tool should be deactivated\n    expect(\n      (client as unknown as { captchaSolvedToolActive: boolean })\n        .captchaSolvedToolActive,\n    ).toBe(false);\n\n    // Result should contain a function_call_output confirming proceed\n    expect(result).toEqual([\n      {\n        type: \"function_call_output\",\n        call_id: \"call-1\",\n        output: expect.stringContaining(\"Continue completing\"),\n      },\n    ]);\n  });\n\n  it(\"does NOT auto-continue follow-up questions without a captcha context\", async () => {\n    const client = createClient();\n    // No captcha context note — no tool should be exposed\n\n    type ExecuteStepResult = {\n      actions: Array<{ type: string }>;\n      message: string;\n      completed: boolean;\n      nextInputItems: unknown[];\n      responseId: string;\n      usage: {\n        input_tokens: number;\n        output_tokens: number;\n        inference_time_ms: number;\n      };\n    };\n\n    const executeStepSpy = vi.spyOn(\n      client as unknown as {\n        executeStep: (\n          inputItems: unknown[],\n          previousResponseId: string | undefined,\n          logger: (message: { message: string }) => void,\n        ) => Promise<ExecuteStepResult>;\n      },\n      \"executeStep\",\n    );\n\n    executeStepSpy.mockResolvedValueOnce({\n      actions: [],\n      message:\n        \"I've located the Submit button. Should I go ahead and submit it?\",\n      completed: true,\n      nextInputItems: [],\n      responseId: \"response-1\",\n      usage: { input_tokens: 1, output_tokens: 1, inference_time_ms: 1 },\n    });\n\n    const result = await client.execute({\n      options: { instruction: \"Submit the form.\", maxSteps: 10 } as never,\n      logger: vi.fn(),\n    });\n\n    // Should NOT have continued — the model's follow-up is treated as completion\n    expect(executeStepSpy).toHaveBeenCalledTimes(1);\n    expect(result.completed).toBe(true);\n  });\n});\n"]}

package/dist/esm/tests/unit/prompt-observe-variables.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/esm/tests/unit/prompt-observe-variables.test.js

@@ -0,0 +1,17 @@
+import { describe, expect, it } from "vitest";
+import { buildObserveSystemPrompt } from "../../lib/prompt.js";
+describe("buildObserveSystemPrompt", () => {
+    it("includes variable descriptions when present", () => {
+        const prompt = buildObserveSystemPrompt(undefined, ["click", "fill"], {
+            username: {
+                value: "john@example.com",
+                description: "The login email",
+            },
+            password: "secret123",
+        });
+        expect(prompt.content).toContain("Supported actions: click, fill");
+        expect(prompt.content).toContain("Available variables: %username% (The login email), %password%");
+        expect(prompt.content).toContain("return the matching %variableName% placeholder");
+    });
+});
+//# sourceMappingURL=prompt-observe-variables.test.js.map

package/dist/esm/tests/unit/prompt-observe-variables.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt-observe-variables.test.js","sourceRoot":"","sources":["../../../../tests/unit/prompt-observe-variables.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,QAAQ,CAAC;AAC9C,OAAO,EAAE,wBAAwB,EAAE,MAAM,qBAAqB,CAAC;AAE/D,QAAQ,CAAC,0BAA0B,EAAE,GAAG,EAAE;IACxC,EAAE,CAAC,6CAA6C,EAAE,GAAG,EAAE;QACrD,MAAM,MAAM,GAAG,wBAAwB,CAAC,SAAS,EAAE,CAAC,OAAO,EAAE,MAAM,CAAC,EAAE;YACpE,QAAQ,EAAE;gBACR,KAAK,EAAE,kBAAkB;gBACzB,WAAW,EAAE,iBAAiB;aAC/B;YACD,QAAQ,EAAE,WAAW;SACtB,CAAC,CAAC;QAEH,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,SAAS,CAAC,gCAAgC,CAAC,CAAC;QACnE,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,SAAS,CAC9B,+DAA+D,CAChE,CAAC;QACF,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,SAAS,CAC9B,gDAAgD,CACjD,CAAC;IACJ,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC","sourcesContent":["import { describe, expect, it } from \"vitest\";\nimport { buildObserveSystemPrompt } from \"../../lib/prompt.js\";\n\ndescribe(\"buildObserveSystemPrompt\", () => {\n  it(\"includes variable descriptions when present\", () => {\n    const prompt = buildObserveSystemPrompt(undefined, [\"click\", \"fill\"], {\n      username: {\n        value: \"john@example.com\",\n        description: \"The login email\",\n      },\n      password: \"secret123\",\n    });\n\n    expect(prompt.content).toContain(\"Supported actions: click, fill\");\n    expect(prompt.content).toContain(\n      \"Available variables: %username% (The login email), %password%\",\n    );\n    expect(prompt.content).toContain(\n      \"return the matching %variableName% placeholder\",\n    );\n  });\n});\n"]}

package/dist/esm/tests/unit/public-api/public-types.test.js.map

@@ -1 +1 @@
-{"version":3,"file":"public-types.test.js","sourceRoot":"","sources":["../../../../../tests/unit/public-api/public-types.test.ts"],"names":[],"mappings":"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","sourcesContent":["import { describe, expectTypeOf, it } from \"vitest\";\nimport * as Stagehand from \"@browserbasehq/stagehand\";\n\n// Type-level manifest of all expected exported types\n// Since these types don't exist at runtime, we currently need to manually add new publicly exported types\n// to this list ourselves - it's not automatically going to catch changes like our export-surface.test.ts does.\n\n// eslint-disable-next-line @typescript-eslint/no-unused-vars\ntype ExpectedExportedTypes = {\n  // Types from model.ts\n  AvailableModel: Stagehand.AvailableModel;\n  AvailableCuaModel: Stagehand.AvailableCuaModel;\n  ModelProvider: Stagehand.ModelProvider;\n  ClientOptions: Stagehand.ClientOptions;\n  ModelConfiguration: Stagehand.ModelConfiguration;\n  AnthropicJsonSchemaObject: Stagehand.AnthropicJsonSchemaObject;\n  AISDKProvider: Stagehand.AISDKProvider;\n  AISDKCustomProvider: Stagehand.AISDKCustomProvider;\n  LLMTool: Stagehand.LLMTool;\n  // Types from methods.ts\n  ActOptions: Stagehand.ActOptions;\n  ActResult: Stagehand.ActResult;\n  ExtractResult: Stagehand.ExtractResult<Stagehand.StagehandZodSchema>;\n  Action: Stagehand.Action;\n  HistoryEntry: Stagehand.HistoryEntry;\n  ExtractOptions: Stagehand.ExtractOptions;\n  ObserveOptions: Stagehand.ObserveOptions;\n  ObserveResult: Stagehand.ObserveResult;\n  V3FunctionName: Stagehand.V3FunctionName;\n  // Types from agent.ts\n  Tool: Stagehand.Tool;\n  AgentAction: Stagehand.AgentAction;\n  AgentResult: Stagehand.AgentResult;\n  AgentExecuteOptions: Stagehand.AgentExecuteOptions;\n  AgentType: Stagehand.AgentType;\n  AgentExecutionOptions: Stagehand.AgentExecutionOptions<Stagehand.AgentExecuteOptions>;\n  AgentHandlerOptions: Stagehand.AgentHandlerOptions;\n  ActionExecutionResult: Stagehand.ActionExecutionResult;\n  ToolUseItem: Stagehand.ToolUseItem;\n  AnthropicMessage: Stagehand.AnthropicMessage;\n  AnthropicContentBlock: Stagehand.AnthropicContentBlock;\n  AnthropicTextBlock: Stagehand.AnthropicTextBlock;\n  AnthropicToolResult: Stagehand.AnthropicToolResult;\n  ResponseItem: Stagehand.ResponseItem;\n  ComputerCallItem: Stagehand.ComputerCallItem;\n  FunctionCallItem: Stagehand.FunctionCallItem;\n  ResponseInputItem: Stagehand.ResponseInputItem;\n  AgentInstance: Stagehand.AgentInstance;\n  AgentProviderType: Stagehand.AgentProviderType;\n  AgentModelConfig: Stagehand.AgentModelConfig;\n  AgentConfig: Stagehand.AgentConfig;\n  AgentToolMode: Stagehand.AgentToolMode;\n  VariableValue: Stagehand.VariableValue;\n  Variables: Stagehand.Variables;\n  AgentCallbacks: Stagehand.AgentCallbacks;\n  AgentExecuteCallbacks: Stagehand.AgentExecuteCallbacks;\n  AgentStreamCallbacks: Stagehand.AgentStreamCallbacks;\n  AgentExecuteOptionsBase: Stagehand.AgentExecuteOptionsBase;\n  AgentStreamExecuteOptions: Stagehand.AgentStreamExecuteOptions;\n  ModelMessage: Stagehand.ModelMessage;\n  // Types from agent/tools\n  AgentTools: Stagehand.AgentTools;\n  AgentToolTypesMap: Stagehand.AgentToolTypesMap;\n  AgentUITools: Stagehand.AgentUITools;\n  AgentToolCall: Stagehand.AgentToolCall;\n  AgentToolResult: Stagehand.AgentToolResult;\n  // Types from logs.ts\n  LogLevel: Stagehand.LogLevel;\n  LogLine: Stagehand.LogLine;\n  Logger: Stagehand.Logger;\n  // Types from metrics.ts\n  StagehandMetrics: Stagehand.StagehandMetrics;\n  // Types from options.ts\n  V3Env: Stagehand.V3Env;\n  LocalBrowserLaunchOptions: Stagehand.LocalBrowserLaunchOptions;\n  V3Options: Stagehand.V3Options;\n  // Types from page.ts\n  AnyPage: Stagehand.AnyPage;\n  Page: Stagehand.Page;\n  PlaywrightPage: Stagehand.PlaywrightPage;\n  PatchrightPage: Stagehand.PatchrightPage;\n  PuppeteerPage: Stagehand.PuppeteerPage;\n  ConsoleListener: Stagehand.ConsoleListener;\n  LoadState: Stagehand.LoadState;\n  // Types from LLMClient.ts\n  ChatMessage: Stagehand.ChatMessage;\n  ChatMessageContent: Stagehand.ChatMessageContent;\n  ChatMessageImageContent: Stagehand.ChatMessageImageContent;\n  ChatMessageTextContent: Stagehand.ChatMessageTextContent;\n  ChatCompletionOptions: Stagehand.ChatCompletionOptions;\n  LLMResponse: Stagehand.LLMResponse;\n  CreateChatCompletionOptions: Stagehand.CreateChatCompletionOptions;\n  LLMUsage: Stagehand.LLMUsage;\n  LLMParsedResponse: Stagehand.LLMParsedResponse<Record<string, unknown>>;\n  // Types from zodCompat.ts\n  StagehandZodSchema: Stagehand.StagehandZodSchema;\n  StagehandZodObject: Stagehand.StagehandZodObject;\n  InferStagehandSchema: Stagehand.InferStagehandSchema<Stagehand.StagehandZodSchema>;\n  JsonSchemaDocument: Stagehand.JsonSchemaDocument;\n  // Types from utils.ts\n  JsonSchema: Stagehand.JsonSchema;\n  JsonSchemaProperty: Stagehand.JsonSchemaProperty;\n  // Types from cookies.ts\n  Cookie: Stagehand.Cookie;\n  CookieParam: Stagehand.CookieParam;\n  ClearCookieOptions: Stagehand.ClearCookieOptions;\n};\n\ndescribe(\"Stagehand public API types\", () => {\n  describe(\"AnyPage\", () => {\n    type ExpectedAnyPage =\n      | Stagehand.PlaywrightPage\n      | Stagehand.PuppeteerPage\n      | Stagehand.PatchrightPage\n      | Stagehand.Page;\n\n    it(\"matches expected type shape\", () => {\n      expectTypeOf<Stagehand.AnyPage>().toEqualTypeOf<ExpectedAnyPage>();\n    });\n  });\n\n  describe(\"ActOptions\", () => {\n    type ExpectedActOptions = {\n      model?: Stagehand.ModelConfiguration;\n      variables?: Stagehand.Variables;\n      timeout?: number;\n      page?: Stagehand.AnyPage;\n      serverCache?: boolean;\n    };\n\n    it(\"matches expected type shape\", () => {\n      expectTypeOf<Stagehand.ActOptions>().toEqualTypeOf<ExpectedActOptions>();\n    });\n  });\n\n  describe(\"ActResult\", () => {\n    type ExpectedActResult = {\n      success: boolean;\n      message: string;\n      actionDescription: string;\n      actions: Stagehand.Action[];\n      cacheStatus?: \"HIT\" | \"MISS\";\n    };\n\n    it(\"matches expected type shape\", () => {\n      expectTypeOf<Stagehand.ActResult>().toEqualTypeOf<ExpectedActResult>();\n    });\n  });\n\n  describe(\"ExtractOptions\", () => {\n    type ExpectedExtractOptions = {\n      model?: Stagehand.ModelConfiguration;\n      timeout?: number;\n      selector?: string;\n      page?: Stagehand.AnyPage;\n      serverCache?: boolean;\n    };\n\n    it(\"matches expected type shape\", () => {\n      expectTypeOf<Stagehand.ExtractOptions>().toEqualTypeOf<ExpectedExtractOptions>();\n    });\n  });\n\n  describe(\"ObserveOptions\", () => {\n    type ExpectedObserveOptions = {\n      model?: Stagehand.ModelConfiguration;\n      timeout?: number;\n      selector?: string;\n      page?: Stagehand.AnyPage;\n      serverCache?: boolean;\n    };\n\n    it(\"matches expected type shape\", () => {\n      expectTypeOf<Stagehand.ObserveOptions>().toEqualTypeOf<ExpectedObserveOptions>();\n    });\n  });\n\n  describe(\"ObserveResult\", () => {\n    it(\"is an Action array with optional cacheStatus\", () => {\n      expectTypeOf<Stagehand.ObserveResult>().toExtend<Stagehand.Action[]>();\n      expectTypeOf<Stagehand.ObserveResult[\"cacheStatus\"]>().toEqualTypeOf<\n        \"HIT\" | \"MISS\" | undefined\n      >();\n    });\n  });\n\n  describe(\"Action\", () => {\n    type ExpectedAction = {\n      selector: string;\n      description: string;\n      method?: string;\n      arguments?: string[];\n    };\n\n    it(\"matches expected type shape\", () => {\n      expectTypeOf<Stagehand.Action>().toEqualTypeOf<ExpectedAction>();\n    });\n  });\n\n  describe(\"AgentAction\", () => {\n    // AgentAction is a separate type from Action, not an extension\n    // It has additional fields like type, reasoning, taskCompleted, etc.\n    it(\"has type field\", () => {\n      type TestAction = { type: string } & Stagehand.AgentAction;\n      expectTypeOf<TestAction[\"type\"]>().toEqualTypeOf<string>();\n    });\n  });\n\n  describe(\"AgentExecuteOptions\", () => {\n    type ExpectedAgentExecuteOptions = {\n      instruction: string;\n      maxSteps?: number;\n      page?: Stagehand.AnyPage;\n      highlightCursor?: boolean;\n      messages?: Stagehand.ModelMessage[];\n      signal?: AbortSignal;\n      excludeTools?: string[];\n      output?: Stagehand.StagehandZodObject;\n      callbacks?: Stagehand.AgentExecuteCallbacks;\n      variables?: Stagehand.Variables;\n      toolTimeout?: number;\n      useSearch?: boolean;\n    };\n\n    it(\"matches expected type shape\", () => {\n      expectTypeOf<Stagehand.AgentExecuteOptions>().toEqualTypeOf<ExpectedAgentExecuteOptions>();\n    });\n  });\n\n  describe(\"AgentStreamExecuteOptions\", () => {\n    type ExpectedAgentStreamExecuteOptions = {\n      instruction: string;\n      maxSteps?: number;\n      page?: Stagehand.AnyPage;\n      highlightCursor?: boolean;\n      messages?: Stagehand.ModelMessage[];\n      signal?: AbortSignal;\n      excludeTools?: string[];\n      output?: Stagehand.StagehandZodObject;\n      callbacks?: Stagehand.AgentStreamCallbacks;\n      variables?: Stagehand.Variables;\n      toolTimeout?: number;\n      useSearch?: boolean;\n    };\n\n    it(\"matches expected type shape\", () => {\n      expectTypeOf<Stagehand.AgentStreamExecuteOptions>().toEqualTypeOf<ExpectedAgentStreamExecuteOptions>();\n    });\n  });\n\n  describe(\"AgentExecutionOptions\", () => {\n    type ExpectedAgentExecutionOptions<T = Stagehand.AgentExecuteOptions> = {\n      options: T;\n      logger: (message: Stagehand.LogLine) => void;\n      retries?: number;\n    };\n\n    it(\"matches expected type shape\", () => {\n      expectTypeOf<\n        Stagehand.AgentExecutionOptions<Stagehand.AgentExecuteOptions>\n      >().toEqualTypeOf<\n        ExpectedAgentExecutionOptions<Stagehand.AgentExecuteOptions>\n      >();\n    });\n  });\n\n  describe(\"AgentResult\", () => {\n    type ExpectedAgentResult = {\n      success: boolean;\n      message: string;\n      actions: Stagehand.AgentAction[];\n      completed: boolean;\n      metadata?: Record<string, unknown>;\n      usage?: {\n        input_tokens: number;\n        output_tokens: number;\n        reasoning_tokens?: number;\n        cached_input_tokens?: number;\n        inference_time_ms: number;\n      };\n      messages?: Stagehand.ModelMessage[];\n      output?: Record<string, unknown>;\n    };\n\n    it(\"matches expected type shape\", () => {\n      expectTypeOf<Stagehand.AgentResult>().toEqualTypeOf<ExpectedAgentResult>();\n    });\n  });\n\n  describe(\"AgentConfig\", () => {\n    type ExpectedAgentConfig = {\n      systemPrompt?: string;\n      integrations?: (unknown | string)[];\n      tools?: unknown;\n      cua?: boolean;\n      model?: string | Stagehand.AgentModelConfig<string>;\n      executionModel?: string | Stagehand.AgentModelConfig<string>;\n      stream?: boolean;\n      mode?: Stagehand.AgentToolMode;\n    };\n\n    it(\"matches expected type shape\", () => {\n      expectTypeOf<Stagehand.AgentConfig>().toExtend<ExpectedAgentConfig>();\n    });\n  });\n\n  describe(\"AgentToolMode\", () => {\n    type ExpectedAgentToolMode = \"dom\" | \"hybrid\" | \"cua\";\n\n    it(\"matches expected type shape\", () => {\n      expectTypeOf<Stagehand.AgentToolMode>().toEqualTypeOf<ExpectedAgentToolMode>();\n    });\n  });\n\n  describe(\"HistoryEntry\", () => {\n    type ExpectedHistoryEntry = {\n      method: \"act\" | \"extract\" | \"observe\" | \"navigate\" | \"agent\";\n      parameters: unknown;\n      result: unknown;\n      timestamp: string;\n    };\n\n    it(\"matches expected type shape\", () => {\n      expectTypeOf<Stagehand.HistoryEntry>().toEqualTypeOf<ExpectedHistoryEntry>();\n    });\n  });\n\n  describe(\"Cookie\", () => {\n    type ExpectedCookie = {\n      name: string;\n      value: string;\n      domain: string;\n      path: string;\n      expires: number;\n      httpOnly: boolean;\n      secure: boolean;\n      sameSite: \"Strict\" | \"Lax\" | \"None\";\n    };\n\n    it(\"matches expected type shape\", () => {\n      expectTypeOf<Stagehand.Cookie>().toEqualTypeOf<ExpectedCookie>();\n    });\n  });\n\n  describe(\"CookieParam\", () => {\n    type ExpectedCookieParam = {\n      name: string;\n      value: string;\n      url?: string;\n      domain?: string;\n      path?: string;\n      expires?: number;\n      httpOnly?: boolean;\n      secure?: boolean;\n      sameSite?: \"Strict\" | \"Lax\" | \"None\";\n    };\n\n    it(\"matches expected type shape\", () => {\n      expectTypeOf<Stagehand.CookieParam>().toEqualTypeOf<ExpectedCookieParam>();\n    });\n  });\n\n  describe(\"ClearCookieOptions\", () => {\n    type ExpectedClearCookieOptions = {\n      name?: string | RegExp;\n      domain?: string | RegExp;\n      path?: string | RegExp;\n    };\n\n    it(\"matches expected type shape\", () => {\n      expectTypeOf<Stagehand.ClearCookieOptions>().toEqualTypeOf<ExpectedClearCookieOptions>();\n    });\n  });\n});\n"]}
+{"version":3,"file":"public-types.test.js","sourceRoot":"","sources":["../../../../../tests/unit/public-api/public-types.test.ts"],"names":[],"mappings":"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","sourcesContent":["import { describe, expectTypeOf, it } from \"vitest\";\nimport * as Stagehand from \"@browserbasehq/stagehand\";\n\n// Type-level manifest of all expected exported types\n// Since these types don't exist at runtime, we currently need to manually add new publicly exported types\n// to this list ourselves - it's not automatically going to catch changes like our export-surface.test.ts does.\n\n// eslint-disable-next-line @typescript-eslint/no-unused-vars\ntype ExpectedExportedTypes = {\n  // Types from model.ts\n  AvailableModel: Stagehand.AvailableModel;\n  AvailableCuaModel: Stagehand.AvailableCuaModel;\n  ModelProvider: Stagehand.ModelProvider;\n  ClientOptions: Stagehand.ClientOptions;\n  ModelConfiguration: Stagehand.ModelConfiguration;\n  AnthropicJsonSchemaObject: Stagehand.AnthropicJsonSchemaObject;\n  AISDKProvider: Stagehand.AISDKProvider;\n  AISDKCustomProvider: Stagehand.AISDKCustomProvider;\n  LLMTool: Stagehand.LLMTool;\n  // Types from methods.ts\n  ActOptions: Stagehand.ActOptions;\n  ActResult: Stagehand.ActResult;\n  ExtractResult: Stagehand.ExtractResult<Stagehand.StagehandZodSchema>;\n  Action: Stagehand.Action;\n  HistoryEntry: Stagehand.HistoryEntry;\n  ExtractOptions: Stagehand.ExtractOptions;\n  ObserveOptions: Stagehand.ObserveOptions;\n  ObserveResult: Stagehand.ObserveResult;\n  V3FunctionName: Stagehand.V3FunctionName;\n  // Types from agent.ts\n  Tool: Stagehand.Tool;\n  AgentAction: Stagehand.AgentAction;\n  AgentResult: Stagehand.AgentResult;\n  AgentExecuteOptions: Stagehand.AgentExecuteOptions;\n  AgentType: Stagehand.AgentType;\n  AgentExecutionOptions: Stagehand.AgentExecutionOptions<Stagehand.AgentExecuteOptions>;\n  AgentHandlerOptions: Stagehand.AgentHandlerOptions;\n  ActionExecutionResult: Stagehand.ActionExecutionResult;\n  ToolUseItem: Stagehand.ToolUseItem;\n  AnthropicMessage: Stagehand.AnthropicMessage;\n  AnthropicContentBlock: Stagehand.AnthropicContentBlock;\n  AnthropicTextBlock: Stagehand.AnthropicTextBlock;\n  AnthropicToolResult: Stagehand.AnthropicToolResult;\n  ResponseItem: Stagehand.ResponseItem;\n  ComputerCallItem: Stagehand.ComputerCallItem;\n  FunctionCallItem: Stagehand.FunctionCallItem;\n  ResponseInputItem: Stagehand.ResponseInputItem;\n  AgentInstance: Stagehand.AgentInstance;\n  AgentProviderType: Stagehand.AgentProviderType;\n  AgentModelConfig: Stagehand.AgentModelConfig;\n  AgentConfig: Stagehand.AgentConfig;\n  AgentToolMode: Stagehand.AgentToolMode;\n  VariableValue: Stagehand.VariableValue;\n  Variables: Stagehand.Variables;\n  AgentCallbacks: Stagehand.AgentCallbacks;\n  AgentExecuteCallbacks: Stagehand.AgentExecuteCallbacks;\n  AgentStreamCallbacks: Stagehand.AgentStreamCallbacks;\n  AgentExecuteOptionsBase: Stagehand.AgentExecuteOptionsBase;\n  AgentStreamExecuteOptions: Stagehand.AgentStreamExecuteOptions;\n  ModelMessage: Stagehand.ModelMessage;\n  // Types from agent/tools\n  AgentTools: Stagehand.AgentTools;\n  AgentToolTypesMap: Stagehand.AgentToolTypesMap;\n  AgentUITools: Stagehand.AgentUITools;\n  AgentToolCall: Stagehand.AgentToolCall;\n  AgentToolResult: Stagehand.AgentToolResult;\n  // Types from logs.ts\n  LogLevel: Stagehand.LogLevel;\n  LogLine: Stagehand.LogLine;\n  Logger: Stagehand.Logger;\n  // Types from metrics.ts\n  StagehandMetrics: Stagehand.StagehandMetrics;\n  // Types from options.ts\n  V3Env: Stagehand.V3Env;\n  LocalBrowserLaunchOptions: Stagehand.LocalBrowserLaunchOptions;\n  V3Options: Stagehand.V3Options;\n  // Types from page.ts\n  AnyPage: Stagehand.AnyPage;\n  Page: Stagehand.Page;\n  PlaywrightPage: Stagehand.PlaywrightPage;\n  PatchrightPage: Stagehand.PatchrightPage;\n  PuppeteerPage: Stagehand.PuppeteerPage;\n  ConsoleListener: Stagehand.ConsoleListener;\n  LoadState: Stagehand.LoadState;\n  // Types from LLMClient.ts\n  ChatMessage: Stagehand.ChatMessage;\n  ChatMessageContent: Stagehand.ChatMessageContent;\n  ChatMessageImageContent: Stagehand.ChatMessageImageContent;\n  ChatMessageTextContent: Stagehand.ChatMessageTextContent;\n  ChatCompletionOptions: Stagehand.ChatCompletionOptions;\n  LLMResponse: Stagehand.LLMResponse;\n  CreateChatCompletionOptions: Stagehand.CreateChatCompletionOptions;\n  LLMUsage: Stagehand.LLMUsage;\n  LLMParsedResponse: Stagehand.LLMParsedResponse<Record<string, unknown>>;\n  // Types from zodCompat.ts\n  StagehandZodSchema: Stagehand.StagehandZodSchema;\n  StagehandZodObject: Stagehand.StagehandZodObject;\n  InferStagehandSchema: Stagehand.InferStagehandSchema<Stagehand.StagehandZodSchema>;\n  JsonSchemaDocument: Stagehand.JsonSchemaDocument;\n  // Types from utils.ts\n  JsonSchema: Stagehand.JsonSchema;\n  JsonSchemaProperty: Stagehand.JsonSchemaProperty;\n  // Types from cookies.ts\n  Cookie: Stagehand.Cookie;\n  CookieParam: Stagehand.CookieParam;\n  ClearCookieOptions: Stagehand.ClearCookieOptions;\n};\n\ndescribe(\"Stagehand public API types\", () => {\n  describe(\"AnyPage\", () => {\n    type ExpectedAnyPage =\n      | Stagehand.PlaywrightPage\n      | Stagehand.PuppeteerPage\n      | Stagehand.PatchrightPage\n      | Stagehand.Page;\n\n    it(\"matches expected type shape\", () => {\n      expectTypeOf<Stagehand.AnyPage>().toEqualTypeOf<ExpectedAnyPage>();\n    });\n  });\n\n  describe(\"ActOptions\", () => {\n    type ExpectedActOptions = {\n      model?: Stagehand.ModelConfiguration;\n      variables?: Stagehand.Variables;\n      timeout?: number;\n      page?: Stagehand.AnyPage;\n      serverCache?: boolean;\n    };\n\n    it(\"matches expected type shape\", () => {\n      expectTypeOf<Stagehand.ActOptions>().toEqualTypeOf<ExpectedActOptions>();\n    });\n  });\n\n  describe(\"ActResult\", () => {\n    type ExpectedActResult = {\n      success: boolean;\n      message: string;\n      actionDescription: string;\n      actions: Stagehand.Action[];\n      cacheStatus?: \"HIT\" | \"MISS\";\n    };\n\n    it(\"matches expected type shape\", () => {\n      expectTypeOf<Stagehand.ActResult>().toEqualTypeOf<ExpectedActResult>();\n    });\n  });\n\n  describe(\"ExtractOptions\", () => {\n    type ExpectedExtractOptions = {\n      model?: Stagehand.ModelConfiguration;\n      timeout?: number;\n      selector?: string;\n      page?: Stagehand.AnyPage;\n      serverCache?: boolean;\n    };\n\n    it(\"matches expected type shape\", () => {\n      expectTypeOf<Stagehand.ExtractOptions>().toEqualTypeOf<ExpectedExtractOptions>();\n    });\n  });\n\n  describe(\"ObserveOptions\", () => {\n    type ExpectedObserveOptions = {\n      model?: Stagehand.ModelConfiguration;\n      variables?: Stagehand.Variables;\n      timeout?: number;\n      selector?: string;\n      page?: Stagehand.AnyPage;\n      serverCache?: boolean;\n    };\n\n    it(\"matches expected type shape\", () => {\n      expectTypeOf<Stagehand.ObserveOptions>().toEqualTypeOf<ExpectedObserveOptions>();\n    });\n  });\n\n  describe(\"ObserveResult\", () => {\n    it(\"is an Action array with optional cacheStatus\", () => {\n      expectTypeOf<Stagehand.ObserveResult>().toExtend<Stagehand.Action[]>();\n      expectTypeOf<Stagehand.ObserveResult[\"cacheStatus\"]>().toEqualTypeOf<\n        \"HIT\" | \"MISS\" | undefined\n      >();\n    });\n  });\n\n  describe(\"Action\", () => {\n    type ExpectedAction = {\n      selector: string;\n      description: string;\n      method?: string;\n      arguments?: string[];\n    };\n\n    it(\"matches expected type shape\", () => {\n      expectTypeOf<Stagehand.Action>().toEqualTypeOf<ExpectedAction>();\n    });\n  });\n\n  describe(\"AgentAction\", () => {\n    // AgentAction is a separate type from Action, not an extension\n    // It has additional fields like type, reasoning, taskCompleted, etc.\n    it(\"has type field\", () => {\n      type TestAction = { type: string } & Stagehand.AgentAction;\n      expectTypeOf<TestAction[\"type\"]>().toEqualTypeOf<string>();\n    });\n  });\n\n  describe(\"AgentExecuteOptions\", () => {\n    type ExpectedAgentExecuteOptions = {\n      instruction: string;\n      maxSteps?: number;\n      page?: Stagehand.AnyPage;\n      highlightCursor?: boolean;\n      messages?: Stagehand.ModelMessage[];\n      signal?: AbortSignal;\n      excludeTools?: string[];\n      output?: Stagehand.StagehandZodObject;\n      callbacks?: Stagehand.AgentExecuteCallbacks;\n      variables?: Stagehand.Variables;\n      toolTimeout?: number;\n      useSearch?: boolean;\n    };\n\n    it(\"matches expected type shape\", () => {\n      expectTypeOf<Stagehand.AgentExecuteOptions>().toEqualTypeOf<ExpectedAgentExecuteOptions>();\n    });\n  });\n\n  describe(\"AgentStreamExecuteOptions\", () => {\n    type ExpectedAgentStreamExecuteOptions = {\n      instruction: string;\n      maxSteps?: number;\n      page?: Stagehand.AnyPage;\n      highlightCursor?: boolean;\n      messages?: Stagehand.ModelMessage[];\n      signal?: AbortSignal;\n      excludeTools?: string[];\n      output?: Stagehand.StagehandZodObject;\n      callbacks?: Stagehand.AgentStreamCallbacks;\n      variables?: Stagehand.Variables;\n      toolTimeout?: number;\n      useSearch?: boolean;\n    };\n\n    it(\"matches expected type shape\", () => {\n      expectTypeOf<Stagehand.AgentStreamExecuteOptions>().toEqualTypeOf<ExpectedAgentStreamExecuteOptions>();\n    });\n  });\n\n  describe(\"AgentExecutionOptions\", () => {\n    type ExpectedAgentExecutionOptions<T = Stagehand.AgentExecuteOptions> = {\n      options: T;\n      logger: (message: Stagehand.LogLine) => void;\n      retries?: number;\n    };\n\n    it(\"matches expected type shape\", () => {\n      expectTypeOf<\n        Stagehand.AgentExecutionOptions<Stagehand.AgentExecuteOptions>\n      >().toEqualTypeOf<\n        ExpectedAgentExecutionOptions<Stagehand.AgentExecuteOptions>\n      >();\n    });\n  });\n\n  describe(\"AgentResult\", () => {\n    type ExpectedAgentResult = {\n      success: boolean;\n      message: string;\n      actions: Stagehand.AgentAction[];\n      completed: boolean;\n      metadata?: Record<string, unknown>;\n      usage?: {\n        input_tokens: number;\n        output_tokens: number;\n        reasoning_tokens?: number;\n        cached_input_tokens?: number;\n        inference_time_ms: number;\n      };\n      messages?: Stagehand.ModelMessage[];\n      output?: Record<string, unknown>;\n    };\n\n    it(\"matches expected type shape\", () => {\n      expectTypeOf<Stagehand.AgentResult>().toEqualTypeOf<ExpectedAgentResult>();\n    });\n  });\n\n  describe(\"AgentConfig\", () => {\n    type ExpectedAgentConfig = {\n      systemPrompt?: string;\n      integrations?: (unknown | string)[];\n      tools?: unknown;\n      cua?: boolean;\n      model?: string | Stagehand.AgentModelConfig<string>;\n      executionModel?: string | Stagehand.AgentModelConfig<string>;\n      stream?: boolean;\n      mode?: Stagehand.AgentToolMode;\n    };\n\n    it(\"matches expected type shape\", () => {\n      expectTypeOf<Stagehand.AgentConfig>().toExtend<ExpectedAgentConfig>();\n    });\n  });\n\n  describe(\"AgentToolMode\", () => {\n    type ExpectedAgentToolMode = \"dom\" | \"hybrid\" | \"cua\";\n\n    it(\"matches expected type shape\", () => {\n      expectTypeOf<Stagehand.AgentToolMode>().toEqualTypeOf<ExpectedAgentToolMode>();\n    });\n  });\n\n  describe(\"HistoryEntry\", () => {\n    type ExpectedHistoryEntry = {\n      method: \"act\" | \"extract\" | \"observe\" | \"navigate\" | \"agent\";\n      parameters: unknown;\n      result: unknown;\n      timestamp: string;\n    };\n\n    it(\"matches expected type shape\", () => {\n      expectTypeOf<Stagehand.HistoryEntry>().toEqualTypeOf<ExpectedHistoryEntry>();\n    });\n  });\n\n  describe(\"Cookie\", () => {\n    type ExpectedCookie = {\n      name: string;\n      value: string;\n      domain: string;\n      path: string;\n      expires: number;\n      httpOnly: boolean;\n      secure: boolean;\n      sameSite: \"Strict\" | \"Lax\" | \"None\";\n    };\n\n    it(\"matches expected type shape\", () => {\n      expectTypeOf<Stagehand.Cookie>().toEqualTypeOf<ExpectedCookie>();\n    });\n  });\n\n  describe(\"CookieParam\", () => {\n    type ExpectedCookieParam = {\n      name: string;\n      value: string;\n      url?: string;\n      domain?: string;\n      path?: string;\n      expires?: number;\n      httpOnly?: boolean;\n      secure?: boolean;\n      sameSite?: \"Strict\" | \"Lax\" | \"None\";\n    };\n\n    it(\"matches expected type shape\", () => {\n      expectTypeOf<Stagehand.CookieParam>().toEqualTypeOf<ExpectedCookieParam>();\n    });\n  });\n\n  describe(\"ClearCookieOptions\", () => {\n    type ExpectedClearCookieOptions = {\n      name?: string | RegExp;\n      domain?: string | RegExp;\n      path?: string | RegExp;\n    };\n\n    it(\"matches expected type shape\", () => {\n      expectTypeOf<Stagehand.ClearCookieOptions>().toEqualTypeOf<ExpectedClearCookieOptions>();\n    });\n  });\n});\n"]}

package/dist/esm/tests/unit/timeout-handlers.test.js

@@ -685,6 +685,56 @@ describe("No-timeout success paths", () => {
         expect(result[0]).toHaveProperty("description", "Submit button");
         expect(metricsCallback).toHaveBeenCalledWith(V3FunctionName.OBSERVE, 150, 75, 15, 8, 600);
     });
+    it("observe() forwards variables to inference and preserves placeholders", async () => {
+        const captureHybridSnapshotMock = vi.mocked(captureHybridSnapshot);
+        captureHybridSnapshotMock.mockResolvedValue({
+            combinedTree: "tree content",
+            combinedXpathMap: { "1-0": "/html/body/input" },
+            combinedUrlMap: {},
+        });
+        const observeInferenceMock = vi.mocked(observeInference);
+        observeInferenceMock.mockResolvedValue({
+            elements: [
+                {
+                    elementId: "1-0",
+                    description: "Email field",
+                    method: "fill",
+                    arguments: ["%username%"],
+                },
+            ],
+            prompt_tokens: 150,
+            completion_tokens: 75,
+            reasoning_tokens: 15,
+            cached_input_tokens: 8,
+            inference_time_ms: 600,
+        });
+        vi.mocked(createTimeoutGuard).mockImplementation(() => {
+            return vi.fn(() => {
+                // No-op - never throws
+            });
+        });
+        const handler = buildObserveHandler();
+        const fakePage = {
+            mainFrame: vi.fn().mockReturnValue({}),
+        };
+        const variables = {
+            username: {
+                value: "john@example.com",
+                description: "The login email",
+            },
+        };
+        const result = await handler.observe({
+            instruction: "find the field where %username% should be entered",
+            variables,
+            page: fakePage,
+        });
+        expect(observeInferenceMock).toHaveBeenCalledWith(expect.objectContaining({
+            variables,
+        }));
+        expect(result).toHaveLength(1);
+        expect(result[0]).toHaveProperty("arguments");
+        expect(result[0]?.arguments).toEqual(["%username%"]);
+    });
     it("act() with zero timeout behaves as no timeout", async () => {
         const waitForDomNetworkQuietMock = vi.mocked(waitForDomNetworkQuiet);
         waitForDomNetworkQuietMock.mockResolvedValue(undefined);