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

package/dist/cjs/lib/v3/shutdown/supervisorClient.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Parent-side helper for spawning the shutdown supervisor process.
+ *
+ * The supervisor runs out-of-process and watches a lifeline pipe. If the parent
+ * dies, the supervisor performs best-effort cleanup (Chrome kill or Browserbase
+ * session release) when keepAlive is false.
+ */
+import type { ShutdownSupervisorConfig, ShutdownSupervisorHandle } from "../types/private/shutdown.js";
+/**
+ * Start a supervisor process for crash cleanup. Returns a handle that can
+ * stop the supervisor during a normal shutdown.
+ */
+export declare function startShutdownSupervisor(config: ShutdownSupervisorConfig, opts?: {
+    onError?: (error: Error, context: string) => void;
+}): ShutdownSupervisorHandle | null;

package/dist/cjs/lib/v3/tests/agent-abort-signal.spec.js

@@ -0,0 +1,113 @@
+var import_test = require("@playwright/test");
+var import_v3 = require("../v3.js");
+var import_v3_config = require("./v3.config.js");
+var import_sdkErrors = require("../types/public/sdkErrors.js");
+import_test.test.describe("Stagehand agent abort signal", () => {
+  let v3;
+  import_test.test.beforeEach(async () => {
+    v3 = new import_v3.V3({
+      ...import_v3_config.v3TestConfig,
+      experimental: true
+    });
+    await v3.init();
+  });
+  import_test.test.afterEach(async () => {
+    await v3?.close?.().catch(() => {
+    });
+  });
+  (0, import_test.test)("non-streaming: abort signal stops execution and throws AgentAbortError", async () => {
+    import_test.test.setTimeout(6e4);
+    const agent = v3.agent({
+      model: "anthropic/claude-haiku-4-5-20251001"
+    });
+    const page = v3.context.pages()[0];
+    await page.goto("https://example.com");
+    const controller = new AbortController();
+    setTimeout(() => controller.abort(), 500);
+    await (0, import_test.expect)(
+      agent.execute({
+        instruction: "Describe every visual element on this page in extreme detail. Describe at least 100 different elements.",
+        maxSteps: 50,
+        signal: controller.signal
+      })
+    ).rejects.toThrow(import_sdkErrors.AgentAbortError);
+  });
+  (0, import_test.test)("streaming: abort signal stops stream and rejects result with AgentAbortError", async () => {
+    import_test.test.setTimeout(6e4);
+    const agent = v3.agent({
+      stream: true,
+      model: "anthropic/claude-haiku-4-5-20251001"
+    });
+    const page = v3.context.pages()[0];
+    await page.goto("https://example.com");
+    const controller = new AbortController();
+    setTimeout(() => controller.abort(), 500);
+    const streamResult = await agent.execute({
+      instruction: "Describe every visual element on this page in extreme detail. Describe at least 100 different elements.",
+      maxSteps: 50,
+      signal: controller.signal
+    });
+    const consumeStream = async () => {
+      for await (const _ of streamResult.textStream) {
+      }
+    };
+    const [, resultError] = await Promise.allSettled([
+      consumeStream(),
+      streamResult.result
+    ]);
+    (0, import_test.expect)(resultError.status).toBe("rejected");
+    (0, import_test.expect)(resultError.reason).toBeInstanceOf(
+      import_sdkErrors.AgentAbortError
+    );
+  });
+  (0, import_test.test)("non-streaming: already aborted signal throws AgentAbortError immediately", async () => {
+    import_test.test.setTimeout(2e4);
+    const agent = v3.agent({
+      model: "anthropic/claude-haiku-4-5-20251001"
+    });
+    const page = v3.context.pages()[0];
+    await page.goto("https://example.com");
+    const controller = new AbortController();
+    controller.abort();
+    await (0, import_test.expect)(
+      agent.execute({
+        instruction: "This should not run.",
+        maxSteps: 3,
+        signal: controller.signal
+      })
+    ).rejects.toThrow(import_sdkErrors.AgentAbortError);
+  });
+  (0, import_test.test)("non-streaming: execution completes normally without abort signal", async () => {
+    import_test.test.setTimeout(6e4);
+    const agent = v3.agent({
+      model: "anthropic/claude-haiku-4-5-20251001"
+    });
+    const page = v3.context.pages()[0];
+    await page.goto("https://example.com");
+    const result = await agent.execute({
+      instruction: "Describe this page briefly.",
+      maxSteps: 3
+    });
+    (0, import_test.expect)(result.success).toBe(true);
+    (0, import_test.expect)(result.completed).toBe(true);
+  });
+  (0, import_test.test)("streaming: execution completes normally without abort signal", async () => {
+    import_test.test.setTimeout(6e4);
+    const agent = v3.agent({
+      stream: true,
+      model: "anthropic/claude-haiku-4-5-20251001"
+    });
+    const page = v3.context.pages()[0];
+    await page.goto("https://example.com");
+    const streamResult = await agent.execute({
+      instruction: "Describe this page briefly.",
+      maxSteps: 3
+    });
+    for await (const _ of streamResult.textStream) {
+    }
+    const result = await streamResult.result;
+    (0, import_test.expect)(result.success).toBe(true);
+    (0, import_test.expect)(result.completed).toBe(true);
+  });
+});
+//# sourceMappingURL=agent-abort-signal.spec.js.map

package/dist/cjs/lib/v3/tests/agent-abort-signal.spec.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../../lib/v3/tests/agent-abort-signal.spec.ts"],
+  "sourcesContent": ["import { test, expect } from \"@playwright/test\";\nimport { V3 } from \"../v3.js\";\nimport { v3TestConfig } from \"./v3.config.js\";\nimport { AgentAbortError } from \"../types/public/sdkErrors.js\";\n\ntest.describe(\"Stagehand agent abort signal\", () => {\n  let v3: V3;\n\n  test.beforeEach(async () => {\n    v3 = new V3({\n      ...v3TestConfig,\n      experimental: true,\n    });\n    await v3.init();\n  });\n\n  test.afterEach(async () => {\n    await v3?.close?.().catch(() => {});\n  });\n\n  test(\"non-streaming: abort signal stops execution and throws AgentAbortError\", async () => {\n    test.setTimeout(60000);\n\n    const agent = v3.agent({\n      model: \"anthropic/claude-haiku-4-5-20251001\",\n    });\n\n    const page = v3.context.pages()[0];\n    await page.goto(\"https://example.com\");\n\n    const controller = new AbortController();\n\n    // Abort after 500ms - should be enough for the LLM to start but not finish\n    setTimeout(() => controller.abort(), 500);\n\n    await expect(\n      agent.execute({\n        instruction:\n          \"Describe every visual element on this page in extreme detail. Describe at least 100 different elements.\",\n        maxSteps: 50,\n        signal: controller.signal,\n      }),\n    ).rejects.toThrow(AgentAbortError);\n  });\n\n  test(\"streaming: abort signal stops stream and rejects result with AgentAbortError\", async () => {\n    test.setTimeout(60000);\n\n    const agent = v3.agent({\n      stream: true,\n      model: \"anthropic/claude-haiku-4-5-20251001\",\n    });\n\n    const page = v3.context.pages()[0];\n    await page.goto(\"https://example.com\");\n\n    const controller = new AbortController();\n\n    // Abort after 500ms\n    setTimeout(() => controller.abort(), 500);\n\n    const streamResult = await agent.execute({\n      instruction:\n        \"Describe every visual element on this page in extreme detail. Describe at least 100 different elements.\",\n      maxSteps: 50,\n      signal: controller.signal,\n    });\n\n    // Handle both stream consumption and result promise together\n    // The result promise will reject with AgentAbortError when aborted\n    const consumeStream = async () => {\n      // eslint-disable-next-line @typescript-eslint/no-unused-vars\n      for await (const _ of streamResult.textStream) {\n        // Just consume chunks until stream ends\n      }\n    };\n\n    // Both should complete - stream ends and result rejects\n    const [, resultError] = await Promise.allSettled([\n      consumeStream(),\n      streamResult.result,\n    ]);\n\n    // The result should have rejected with AgentAbortError\n    expect(resultError.status).toBe(\"rejected\");\n    expect((resultError as PromiseRejectedResult).reason).toBeInstanceOf(\n      AgentAbortError,\n    );\n  });\n\n  test(\"non-streaming: already aborted signal throws AgentAbortError immediately\", async () => {\n    test.setTimeout(20000);\n\n    const agent = v3.agent({\n      model: \"anthropic/claude-haiku-4-5-20251001\",\n    });\n\n    const page = v3.context.pages()[0];\n    await page.goto(\"https://example.com\");\n\n    // Create an already aborted controller\n    const controller = new AbortController();\n    controller.abort();\n\n    await expect(\n      agent.execute({\n        instruction: \"This should not run.\",\n        maxSteps: 3,\n        signal: controller.signal,\n      }),\n    ).rejects.toThrow(AgentAbortError);\n  });\n\n  test(\"non-streaming: execution completes normally without abort signal\", async () => {\n    test.setTimeout(60000);\n\n    const agent = v3.agent({\n      model: \"anthropic/claude-haiku-4-5-20251001\",\n    });\n\n    const page = v3.context.pages()[0];\n    await page.goto(\"https://example.com\");\n\n    // No signal provided - should complete normally\n    const result = await agent.execute({\n      instruction: \"Describe this page briefly.\",\n      maxSteps: 3,\n    });\n\n    expect(result.success).toBe(true);\n    expect(result.completed).toBe(true);\n  });\n\n  test(\"streaming: execution completes normally without abort signal\", async () => {\n    test.setTimeout(60000);\n\n    const agent = v3.agent({\n      stream: true,\n      model: \"anthropic/claude-haiku-4-5-20251001\",\n    });\n\n    const page = v3.context.pages()[0];\n    await page.goto(\"https://example.com\");\n\n    // No signal provided - should complete normally\n    const streamResult = await agent.execute({\n      instruction: \"Describe this page briefly.\",\n      maxSteps: 3,\n    });\n\n    // Consume the stream first\n    // eslint-disable-next-line @typescript-eslint/no-unused-vars\n    for await (const _ of streamResult.textStream) {\n      // Just consume\n    }\n\n    // Now get the final result\n    const result = await streamResult.result;\n\n    expect(result.success).toBe(true);\n    expect(result.completed).toBe(true);\n  });\n});\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/cjs/lib/v3/tests/agent-cache-self-heal.spec.js

@@ -0,0 +1,102 @@
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var import_test = require("@playwright/test");
+var import_promises = __toESM(require("fs/promises"), 1);
+var import_path = __toESM(require("path"), 1);
+var import_v3 = require("../v3.js");
+var import_v3_config = require("./v3.config.js");
+import_test.test.describe("Agent cache self-heal (e2e)", () => {
+  let v3;
+  let cacheDir;
+  import_test.test.beforeEach(async ({}, testInfo) => {
+    await import_promises.default.mkdir(testInfo.outputDir, { recursive: true });
+    cacheDir = await import_promises.default.mkdtemp(import_path.default.join(testInfo.outputDir, "agent-cache-"));
+    v3 = new import_v3.V3({
+      ...import_v3_config.v3TestConfig,
+      cacheDir,
+      selfHeal: true
+    });
+    await v3.init();
+  });
+  import_test.test.afterEach(async () => {
+    await v3?.close?.().catch(() => {
+    });
+  });
+  (0, import_test.test)("replays heal corrupted selectors", async () => {
+    import_test.test.setTimeout(12e4);
+    const agent = v3.agent({
+      model: "anthropic/claude-haiku-4-5-20251001"
+    });
+    const page = v3.context.pages()[0];
+    const url = "https://browserbase.github.io/stagehand-eval-sites/sites/shadow-dom/";
+    const instruction = "click the button";
+    await page.goto(url, { waitUntil: "networkidle" });
+    const firstResult = await agent.execute({ instruction, maxSteps: 20 });
+    (0, import_test.expect)(firstResult.success).toBe(true);
+    const cachePath = await locateAgentCacheFile(cacheDir);
+    const originalEntry = await readCacheEntry(cachePath);
+    const originalActionStep = findFirstActionStep(originalEntry);
+    (0, import_test.expect)(originalActionStep).toBeDefined();
+    const originalSelector = originalActionStep?.actions?.[0]?.selector;
+    (0, import_test.expect)(typeof originalSelector).toBe("string");
+    if (originalActionStep?.actions?.[0]) {
+      originalActionStep.actions[0].selector = "xpath=/yeee";
+    }
+    await import_promises.default.writeFile(
+      cachePath,
+      JSON.stringify(originalEntry, null, 2),
+      "utf8"
+    );
+    await page.goto(url, { waitUntil: "networkidle" });
+    const replayResult = await agent.execute({ instruction, maxSteps: 20 });
+    (0, import_test.expect)(replayResult.success).toBe(true);
+    const healedEntry = await readCacheEntry(cachePath);
+    const healedActionStep = findFirstActionStep(healedEntry);
+    (0, import_test.expect)(healedActionStep?.actions?.[0]?.selector).toBe(originalSelector);
+    (0, import_test.expect)(healedActionStep?.actions?.[0]?.selector).not.toBe("xpath=/yeee");
+    (0, import_test.expect)(healedEntry.timestamp).not.toBe(originalEntry.timestamp);
+  });
+});
+async function locateAgentCacheFile(cacheDir) {
+  const deadline = Date.now() + 1e4;
+  while (Date.now() < deadline) {
+    const entries = await import_promises.default.readdir(cacheDir);
+    const agentFiles = entries.filter((file) => file.startsWith("agent-"));
+    if (agentFiles.length > 0) {
+      return import_path.default.join(cacheDir, agentFiles[0]);
+    }
+    await new Promise((resolve) => setTimeout(resolve, 200));
+  }
+  throw new Error("Timed out waiting for agent cache entry to be written");
+}
+async function readCacheEntry(cachePath) {
+  const raw = await import_promises.default.readFile(cachePath, "utf8");
+  return JSON.parse(raw);
+}
+function findFirstActionStep(entry) {
+  return entry.steps.find((step) => {
+    const actions = step.actions;
+    return Array.isArray(actions) && actions.length > 0;
+  });
+}
+//# sourceMappingURL=agent-cache-self-heal.spec.js.map

package/dist/cjs/lib/v3/tests/agent-cache-self-heal.spec.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../../lib/v3/tests/agent-cache-self-heal.spec.ts"],
+  "sourcesContent": ["import { test, expect } from \"@playwright/test\";\nimport fs from \"fs/promises\";\nimport path from \"path\";\nimport { V3 } from \"../v3.js\";\nimport { v3TestConfig } from \"./v3.config.js\";\nimport type {\n  AgentReplayActStep,\n  AgentReplayFillFormStep,\n  CachedAgentEntry,\n} from \"../types/private/cache.js\";\n\ntest.describe(\"Agent cache self-heal (e2e)\", () => {\n  let v3: V3;\n  let cacheDir: string;\n\n  // eslint-disable-next-line no-empty-pattern\n  test.beforeEach(async ({}, testInfo) => {\n    await fs.mkdir(testInfo.outputDir, { recursive: true });\n    cacheDir = await fs.mkdtemp(path.join(testInfo.outputDir, \"agent-cache-\"));\n    v3 = new V3({\n      ...v3TestConfig,\n      cacheDir,\n      selfHeal: true,\n    });\n    await v3.init();\n  });\n\n  test.afterEach(async () => {\n    await v3?.close?.().catch(() => {});\n  });\n\n  test(\"replays heal corrupted selectors\", async () => {\n    test.setTimeout(120_000);\n\n    const agent = v3.agent({\n      model: \"anthropic/claude-haiku-4-5-20251001\",\n    });\n    const page = v3.context.pages()[0];\n    const url =\n      \"https://browserbase.github.io/stagehand-eval-sites/sites/shadow-dom/\";\n    const instruction = \"click the button\";\n\n    await page.goto(url, { waitUntil: \"networkidle\" });\n    const firstResult = await agent.execute({ instruction, maxSteps: 20 });\n    expect(firstResult.success).toBe(true);\n\n    const cachePath = await locateAgentCacheFile(cacheDir);\n    const originalEntry = await readCacheEntry(cachePath);\n    const originalActionStep = findFirstActionStep(originalEntry);\n    expect(originalActionStep).toBeDefined();\n    const originalSelector = originalActionStep?.actions?.[0]?.selector;\n    expect(typeof originalSelector).toBe(\"string\");\n\n    // Corrupt the cached selector so the replay needs to self-heal.\n    if (originalActionStep?.actions?.[0]) {\n      originalActionStep.actions[0].selector = \"xpath=/yeee\";\n    }\n    await fs.writeFile(\n      cachePath,\n      JSON.stringify(originalEntry, null, 2),\n      \"utf8\",\n    );\n\n    // Second run should replay from cache, self-heal, and update the file.\n    await page.goto(url, { waitUntil: \"networkidle\" });\n    const replayResult = await agent.execute({ instruction, maxSteps: 20 });\n    expect(replayResult.success).toBe(true);\n\n    const healedEntry = await readCacheEntry(cachePath);\n    const healedActionStep = findFirstActionStep(healedEntry);\n    expect(healedActionStep?.actions?.[0]?.selector).toBe(originalSelector);\n    expect(healedActionStep?.actions?.[0]?.selector).not.toBe(\"xpath=/yeee\");\n    expect(healedEntry.timestamp).not.toBe(originalEntry.timestamp);\n  });\n});\n\nasync function locateAgentCacheFile(cacheDir: string): Promise<string> {\n  const deadline = Date.now() + 10_000;\n  while (Date.now() < deadline) {\n    const entries = await fs.readdir(cacheDir);\n    const agentFiles = entries.filter((file) => file.startsWith(\"agent-\"));\n    if (agentFiles.length > 0) {\n      return path.join(cacheDir, agentFiles[0]!);\n    }\n    await new Promise((resolve) => setTimeout(resolve, 200));\n  }\n  throw new Error(\"Timed out waiting for agent cache entry to be written\");\n}\n\nasync function readCacheEntry(cachePath: string): Promise<CachedAgentEntry> {\n  const raw = await fs.readFile(cachePath, \"utf8\");\n  return JSON.parse(raw) as CachedAgentEntry;\n}\n\ntype StepWithActions = AgentReplayActStep | AgentReplayFillFormStep;\n\nfunction findFirstActionStep(\n  entry: CachedAgentEntry,\n): StepWithActions | undefined {\n  return entry.steps.find((step) => {\n    const actions = (step as StepWithActions).actions;\n    return Array.isArray(actions) && actions.length > 0;\n  }) as StepWithActions | undefined;\n}\n"],
+  "mappings": "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",
+  "names": ["fs", "path"]
+}

package/dist/cjs/lib/v3/tests/agent-callbacks.spec.js

@@ -0,0 +1,374 @@
+var import_test = require("@playwright/test");
+var import_v3 = require("../v3.js");
+var import_v3_config = require("./v3.config.js");
+var import_sdkErrors = require("../types/public/sdkErrors.js");
+import_test.test.describe("Stagehand agent callbacks behavior", () => {
+  let v3;
+  import_test.test.beforeEach(async () => {
+    v3 = new import_v3.V3({
+      ...import_v3_config.v3TestConfig,
+      experimental: true
+      // Required for callbacks and streaming
+    });
+    await v3.init();
+  });
+  import_test.test.afterEach(async () => {
+    await v3?.close?.().catch(() => {
+    });
+  });
+  import_test.test.describe("Non-streaming callbacks (stream: false)", () => {
+    (0, import_test.test)("onStepFinish callback is called for each step", async () => {
+      import_test.test.setTimeout(6e4);
+      const stepFinishEvents = [];
+      const agent = v3.agent({
+        model: "anthropic/claude-haiku-4-5-20251001"
+      });
+      const page = v3.context.pages()[0];
+      await page.goto("https://example.com");
+      await agent.execute({
+        instruction: "What is the title of this page? Mark the task as complete after answering.",
+        maxSteps: 5,
+        callbacks: {
+          onStepFinish: async (event) => {
+            stepFinishEvents.push(event);
+          }
+        }
+      });
+      (0, import_test.expect)(stepFinishEvents.length).toBeGreaterThan(0);
+      for (const event of stepFinishEvents) {
+        (0, import_test.expect)(event).toHaveProperty("finishReason");
+        (0, import_test.expect)(event).toHaveProperty("text");
+      }
+    });
+    (0, import_test.test)("prepareStep callback is called before each step", async () => {
+      import_test.test.setTimeout(6e4);
+      let prepareStepCallCount = 0;
+      const agent = v3.agent({
+        model: "anthropic/claude-haiku-4-5-20251001"
+      });
+      const page = v3.context.pages()[0];
+      await page.goto("https://example.com");
+      await agent.execute({
+        instruction: "Simply describe the page briefly.",
+        maxSteps: 3,
+        callbacks: {
+          prepareStep: async (stepContext) => {
+            prepareStepCallCount++;
+            return stepContext;
+          }
+        }
+      });
+      (0, import_test.expect)(prepareStepCallCount).toBeGreaterThan(0);
+    });
+    (0, import_test.test)("callbacks receive tool call information", async () => {
+      import_test.test.setTimeout(6e4);
+      const toolCalls = [];
+      const agent = v3.agent({
+        model: "anthropic/claude-haiku-4-5-20251001"
+      });
+      const page = v3.context.pages()[0];
+      await page.goto("https://example.com");
+      await agent.execute({
+        instruction: "Take a screenshot and describe what you see briefly. Then mark the task as complete.",
+        maxSteps: 3,
+        callbacks: {
+          onStepFinish: async (event) => {
+            if (event.toolCalls) {
+              for (const tc of event.toolCalls) {
+                toolCalls.push({
+                  toolName: tc.toolName,
+                  input: tc.input
+                });
+              }
+            }
+          }
+        }
+      });
+      (0, import_test.expect)(toolCalls.length).toBeGreaterThan(0);
+      (0, import_test.expect)(
+        toolCalls.some(
+          (tc) => tc.toolName === "screenshot" || tc.toolName === "ariaTree"
+        )
+      ).toBe(true);
+    });
+  });
+  import_test.test.describe("Streaming callbacks (stream: true)", () => {
+    (0, import_test.test)("onStepFinish callback is called for each step in stream mode", async () => {
+      import_test.test.setTimeout(6e4);
+      const stepFinishEvents = [];
+      const agent = v3.agent({
+        stream: true,
+        model: "anthropic/claude-haiku-4-5-20251001"
+      });
+      const page = v3.context.pages()[0];
+      await page.goto("https://example.com");
+      const streamResult = await agent.execute({
+        instruction: "What is this page? Describe it briefly.",
+        maxSteps: 5,
+        callbacks: {
+          onStepFinish: async (event) => {
+            stepFinishEvents.push(event);
+          }
+        }
+      });
+      for await (const _ of streamResult.textStream) {
+      }
+      await streamResult.result;
+      (0, import_test.expect)(stepFinishEvents.length).toBeGreaterThan(0);
+    });
+    (0, import_test.test)("onChunk callback is called for each chunk", async () => {
+      import_test.test.setTimeout(6e4);
+      let chunkCount = 0;
+      const agent = v3.agent({
+        stream: true,
+        model: "anthropic/claude-haiku-4-5-20251001"
+      });
+      const page = v3.context.pages()[0];
+      await page.goto("https://example.com");
+      const streamResult = await agent.execute({
+        instruction: "Say hello briefly and describe the page.",
+        maxSteps: 3,
+        callbacks: {
+          onChunk: async () => {
+            chunkCount++;
+          }
+        }
+      });
+      for await (const _ of streamResult.textStream) {
+      }
+      await streamResult.result;
+      (0, import_test.expect)(chunkCount).toBeGreaterThan(0);
+    });
+    (0, import_test.test)("onFinish callback is called when stream completes", async () => {
+      import_test.test.setTimeout(6e4);
+      let finishCalled = false;
+      let finishEvent = null;
+      const agent = v3.agent({
+        stream: true,
+        model: "anthropic/claude-haiku-4-5-20251001"
+      });
+      const page = v3.context.pages()[0];
+      await page.goto("https://example.com");
+      const streamResult = await agent.execute({
+        instruction: "Simply describe the page briefly.",
+        maxSteps: 3,
+        callbacks: {
+          onFinish: (event) => {
+            finishCalled = true;
+            finishEvent = event;
+          }
+        }
+      });
+      for await (const _ of streamResult.textStream) {
+      }
+      await streamResult.result;
+      (0, import_test.expect)(finishCalled).toBe(true);
+      (0, import_test.expect)(finishEvent).not.toBeNull();
+    });
+    (0, import_test.test)("prepareStep callback works in stream mode", async () => {
+      import_test.test.setTimeout(6e4);
+      let prepareStepCallCount = 0;
+      const agent = v3.agent({
+        stream: true,
+        model: "anthropic/claude-haiku-4-5-20251001"
+      });
+      const page = v3.context.pages()[0];
+      await page.goto("https://example.com");
+      const streamResult = await agent.execute({
+        instruction: "Simply describe the page briefly.",
+        maxSteps: 3,
+        callbacks: {
+          prepareStep: async (stepContext) => {
+            prepareStepCallCount++;
+            return stepContext;
+          }
+        }
+      });
+      for await (const _ of streamResult.textStream) {
+      }
+      await streamResult.result;
+      (0, import_test.expect)(prepareStepCallCount).toBeGreaterThan(0);
+    });
+  });
+  import_test.test.describe("Streaming-only callbacks runtime validation", () => {
+    (0, import_test.test)("throws StreamingCallbacksInNonStreamingModeError when onChunk is used", async () => {
+      const agent = v3.agent({
+        model: "anthropic/claude-haiku-4-5-20251001"
+      });
+      const page = v3.context.pages()[0];
+      await page.goto("https://example.com");
+      try {
+        await agent.execute({
+          instruction: "test",
+          callbacks: {
+            onChunk: () => {
+            }
+          }
+        });
+        throw new Error("Expected error to be thrown");
+      } catch (error) {
+        (0, import_test.expect)(error).toBeInstanceOf(import_sdkErrors.StreamingCallbacksInNonStreamingModeError);
+        (0, import_test.expect)(
+          error.invalidCallbacks
+        ).toEqual(["onChunk"]);
+      }
+    });
+    (0, import_test.test)("throws StreamingCallbacksInNonStreamingModeError when onFinish is used", async () => {
+      const agent = v3.agent({
+        model: "anthropic/claude-haiku-4-5-20251001"
+      });
+      const page = v3.context.pages()[0];
+      await page.goto("https://example.com");
+      try {
+        await agent.execute({
+          instruction: "test",
+          callbacks: {
+            onFinish: () => {
+            }
+          }
+        });
+        throw new Error("Expected error to be thrown");
+      } catch (error) {
+        (0, import_test.expect)(error).toBeInstanceOf(import_sdkErrors.StreamingCallbacksInNonStreamingModeError);
+        (0, import_test.expect)(
+          error.invalidCallbacks
+        ).toEqual(["onFinish"]);
+      }
+    });
+    (0, import_test.test)("throws StreamingCallbacksInNonStreamingModeError when onError is used", async () => {
+      const agent = v3.agent({
+        model: "anthropic/claude-haiku-4-5-20251001"
+      });
+      const page = v3.context.pages()[0];
+      await page.goto("https://example.com");
+      try {
+        await agent.execute({
+          instruction: "test",
+          callbacks: {
+            onError: () => {
+            }
+          }
+        });
+        throw new Error("Expected error to be thrown");
+      } catch (error) {
+        (0, import_test.expect)(error).toBeInstanceOf(import_sdkErrors.StreamingCallbacksInNonStreamingModeError);
+        (0, import_test.expect)(
+          error.invalidCallbacks
+        ).toEqual(["onError"]);
+      }
+    });
+    (0, import_test.test)("throws StreamingCallbacksInNonStreamingModeError when onAbort is used", async () => {
+      const agent = v3.agent({
+        model: "anthropic/claude-haiku-4-5-20251001"
+      });
+      const page = v3.context.pages()[0];
+      await page.goto("https://example.com");
+      try {
+        await agent.execute({
+          instruction: "test",
+          callbacks: {
+            onAbort: () => {
+            }
+          }
+        });
+        throw new Error("Expected error to be thrown");
+      } catch (error) {
+        (0, import_test.expect)(error).toBeInstanceOf(import_sdkErrors.StreamingCallbacksInNonStreamingModeError);
+        (0, import_test.expect)(
+          error.invalidCallbacks
+        ).toEqual(["onAbort"]);
+      }
+    });
+    (0, import_test.test)("error includes all invalid callbacks when multiple are used", async () => {
+      const agent = v3.agent({
+        model: "anthropic/claude-haiku-4-5-20251001"
+      });
+      const page = v3.context.pages()[0];
+      await page.goto("https://example.com");
+      try {
+        await agent.execute({
+          instruction: "test",
+          callbacks: {
+            onChunk: () => {
+            },
+            onFinish: () => {
+            }
+          }
+        });
+        throw new Error("Expected error to be thrown");
+      } catch (error) {
+        (0, import_test.expect)(error).toBeInstanceOf(import_sdkErrors.StreamingCallbacksInNonStreamingModeError);
+        (0, import_test.expect)(
+          error.invalidCallbacks
+        ).toEqual(["onChunk", "onFinish"]);
+      }
+    });
+  });
+  import_test.test.describe("Combined callbacks", () => {
+    (0, import_test.test)("multiple callbacks can be used together", async () => {
+      import_test.test.setTimeout(6e4);
+      let prepareStepCount = 0;
+      let stepFinishCount = 0;
+      const agent = v3.agent({
+        model: "anthropic/claude-haiku-4-5-20251001"
+      });
+      const page = v3.context.pages()[0];
+      await page.goto("https://example.com");
+      await agent.execute({
+        instruction: "Simply describe the page briefly.",
+        maxSteps: 3,
+        callbacks: {
+          prepareStep: async (stepContext) => {
+            prepareStepCount++;
+            return stepContext;
+          },
+          onStepFinish: async () => {
+            stepFinishCount++;
+          }
+        }
+      });
+      (0, import_test.expect)(prepareStepCount).toBeGreaterThan(0);
+      (0, import_test.expect)(stepFinishCount).toBeGreaterThan(0);
+    });
+    (0, import_test.test)("streaming with multiple callbacks", async () => {
+      import_test.test.setTimeout(6e4);
+      let prepareStepCount = 0;
+      let stepFinishCount = 0;
+      let chunkCount = 0;
+      let finishCalled = false;
+      const agent = v3.agent({
+        stream: true,
+        model: "anthropic/claude-haiku-4-5-20251001"
+      });
+      const page = v3.context.pages()[0];
+      await page.goto("https://example.com");
+      const streamResult = await agent.execute({
+        instruction: "Say hello briefly and describe the page.",
+        maxSteps: 3,
+        callbacks: {
+          prepareStep: async (stepContext) => {
+            prepareStepCount++;
+            return stepContext;
+          },
+          onStepFinish: async () => {
+            stepFinishCount++;
+          },
+          onChunk: async () => {
+            chunkCount++;
+          },
+          onFinish: () => {
+            finishCalled = true;
+          }
+        }
+      });
+      for await (const _ of streamResult.textStream) {
+      }
+      await streamResult.result;
+      (0, import_test.expect)(prepareStepCount).toBeGreaterThan(0);
+      (0, import_test.expect)(stepFinishCount).toBeGreaterThan(0);
+      (0, import_test.expect)(chunkCount).toBeGreaterThan(0);
+      (0, import_test.expect)(finishCalled).toBe(true);
+    });
+  });
+});
+//# sourceMappingURL=agent-callbacks.spec.js.map