Agent callbacks (#1316)

## Summary

Adds callback support to the Stagehand agent for both streaming and
non-streaming execution modes, allowing users to hook into various
stages of agent execution.

## Changes

### New Types (`lib/v3/types/public/agent.ts`)

Added callback interfaces for agent execution:

- **`AgentCallbacks`** - Base callbacks shared between modes:
  - `prepareStep` - Modify settings before each LLM step
  - `onStepFinish` - Called after each step completes

- **`AgentExecuteCallbacks`** - Non-streaming mode callbacks (extends
`AgentCallbacks`)

- **`AgentStreamCallbacks`** - Streaming mode callbacks (extends
`AgentCallbacks`):
  - `onChunk` - Called for each streamed chunk
  - `onFinish` - Called when stream completes
  - `onError` - Called on stream errors
  - `onAbort` - Called when stream is aborted

- **`AgentExecuteOptionsBase`** - Base options without callbacks
- **`AgentExecuteOptions`** - Non-streaming options with
`AgentExecuteCallbacks`
- **`AgentStreamExecuteOptions`** - Streaming options with
`AgentStreamCallbacks`

### Handler Updates (`lib/v3/handlers/v3AgentHandler.ts`)

- Modified `createStepHandler` to accept optional user callback
- Updated `execute()` to pass callbacks to `generateText`
- Updated `stream()` to pass callbacks to `streamText`

### Type Safety

Added compile-time enforcement that streaming-only callbacks (`onChunk`,
`onFinish`, `onError`, `onAbort`) can only be used with `stream: true`:

```typescript
// Works - streaming callbacks with stream: true
const agent = stagehand.agent({ stream: true });
await agent.execute({
  instruction: "...",
  callbacks: { onChunk: async (chunk) => console.log(chunk) }
});

// Compile error - streaming callbacks without stream: true
const agent = stagehand.agent({ stream: false });
await agent.execute({
  instruction: "...",
  callbacks: { onChunk: async (chunk) => console.log(chunk) }
  // Error: "This callback requires 'stream: true' in AgentConfig..."
});
```

## Type Castings Explained

Several type assertions were necessary due to TypeScript's limitations
with conditional types:

### 1. Callback extraction in handlers

```typescript
const callbacks = (instructionOrOptions as AgentExecuteOptions).callbacks as
  | AgentExecuteCallbacks
  | undefined;
```

**Why:** `instructionOrOptions` can be `string | AgentExecuteOptions`.
When it's a string, there are no callbacks. We cast after the
`prepareAgent` call because at that point we know it's been resolved to
options.

### 2. Streaming vs non-streaming branch in v3.ts

```typescript
result = await handler.execute(
  instructionOrOptions as string | AgentExecuteOptions,
);
```

**Why:** The implementation signature accepts `string |
AgentExecuteOptions | AgentStreamExecuteOptions` to satisfy both
overloads, but within the non-streaming branch we know it's the
non-streaming type. TypeScript can't narrow based on the `isStreaming`
runtime check.

### 3. Error fallback in stream()

```typescript
return {
  textStream: (async function* () {})(),
  result: resultPromise,
} as unknown as AgentStreamResult;
```

**Why:** When `prepareAgent` fails in streaming mode, we return a
minimal object with just `textStream` and `result`. This doesn't satisfy
all properties of `StreamTextResult`, but the `result` promise will
reject with the actual error. The double cast (`as unknown as`) is
needed because TypeScript knows this partial object doesn't match the
full type.

## Usage Example

```typescript
const agent = stagehand.agent({
  stream: true,
  model: "anthropic/claude-sonnet-4-20250514",
});

const result = await agent.execute({
  instruction: "Search for something",
  maxSteps: 20,
  callbacks: {
    prepareStep: async (ctx) => {
      console.log("Preparing step...");
      return ctx;
    },
    onStepFinish: async (event) => {
      console.log(`Step finished: ${event.finishReason}`);
      if (event.toolCalls) {
        for (const tc of event.toolCalls) {
          console.log(`Tool used: ${tc.toolName}`);
        }
      }
    },
    onChunk: async (chunk) => {
      // Process each chunk
    },
    onFinish: (event) => {
      console.log(`Completed in ${event.steps.length} steps`);
    },
  },
});

for await (const chunk of result.textStream) {
  process.stdout.write(chunk);
}

const finalResult = await result.result;
console.log(finalResult.message);
```

## Testing

- Added `agent-callbacks.spec.ts` with tests for:
  - Non-streaming callbacks (`onStepFinish`, `prepareStep`)
- Streaming callbacks (`onChunk`, `onFinish`, `prepareStep`,
`onStepFinish`)
  - Combined callback usage
  - Tool call information in callbacks






















<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Adds lifecycle callbacks to the Stagehand agent for both non-streaming
and streaming modes, letting users hook into steps, chunks, finish, and
errors. Strong type safety and runtime validation prevent using
streaming-only callbacks without stream: true; callbacks remain behind
experimental.

- **New Features**
- Added runtime errors in non-streaming mode when
onChunk/onFinish/onError/onAbort are provided, with clear messages
instructing to set stream: true.

<sup>Written for commit 15c08d1.
Summary will update automatically on new commits.</sup>

<!-- End of auto-generated description by cubic. -->

---------

Co-authored-by: greptile-apps[bot] <165735046+greptile-apps[bot]@users.noreply.github.com>

Author: tkattkat

.changeset/shiny-wings-reply.md

@@ -0,0 +1,5 @@
+---
+"@browserbasehq/stagehand": patch
+---
+
+Add support for callbacks in stagehand agent

packages/core/lib/v3/cache/AgentCache.ts

@@ -20,7 +20,7 @@ import type {
   AgentResult,
   AgentStreamResult,
   AgentConfig,
-  AgentExecuteOptions,
+  AgentExecuteOptionsBase,
   Logger,
 } from "../types/public";
 import type { Page } from "../understudy/page";
@@ -74,7 +74,7 @@ export class AgentCache {
   }
 
   sanitizeExecuteOptions(
-    options?: AgentExecuteOptions,
+    options?: AgentExecuteOptionsBase,
   ): SanitizedAgentExecuteOptions {
     if (!options) return {};
     const sanitized: SanitizedAgentExecuteOptions = {};

packages/core/lib/v3/handlers/v3AgentHandler.ts

@@ -8,19 +8,27 @@ import {
   stepCountIs,
   type LanguageModelUsage,
   type StepResult,
+  type GenerateTextOnStepFinishCallback,
+  type StreamTextOnStepFinishCallback,
 } from "ai";
 import { processMessages } from "../agent/utils/messageProcessing";
 import { LLMClient } from "../llm/LLMClient";
 import {
   AgentExecuteOptions,
+  AgentStreamExecuteOptions,
+  AgentExecuteOptionsBase,
   AgentResult,
   AgentContext,
   AgentState,
   AgentStreamResult,
+  AgentStreamCallbacks,
 } from "../types/public/agent";
 import { V3FunctionName } from "../types/public/methods";
 import { mapToolResultToActions } from "../agent/utils/actionMapping";
-import { MissingLLMConfigurationError } from "../types/public/sdkErrors";
+import {
+  MissingLLMConfigurationError,
+  StreamingCallbacksInNonStreamingModeError,
+} from "../types/public/sdkErrors";
 
 export class V3AgentHandler {
   private v3: V3;
@@ -47,7 +55,7 @@ export class V3AgentHandler {
   }
 
   private async prepareAgent(
-    instructionOrOptions: string | AgentExecuteOptions,
+    instructionOrOptions: string | AgentExecuteOptionsBase,
   ): Promise<AgentContext> {
     try {
       const options =
@@ -102,7 +110,12 @@ export class V3AgentHandler {
     }
   }
 
-  private createStepHandler(state: AgentState) {
+  private createStepHandler(
+    state: AgentState,
+    userCallback?:
+      | GenerateTextOnStepFinishCallback<ToolSet>
+      | StreamTextOnStepFinishCallback<ToolSet>,
+  ) {
     return async (event: StepResult<ToolSet>) => {
       this.logger({
         category: "agent",
@@ -150,6 +163,10 @@ export class V3AgentHandler {
         }
         state.currentPageUrl = (await this.v3.context.awaitActivePage()).url();
       }
+
+      if (userCallback) {
+        await userCallback(event);
+      }
     };
   }
 
@@ -166,6 +183,23 @@ export class V3AgentHandler {
       initialPageUrl,
     } = await this.prepareAgent(instructionOrOptions);
 
+    const callbacks = (instructionOrOptions as AgentExecuteOptions).callbacks;
+
+    if (callbacks) {
+      const streamingOnlyCallbacks = [
+        "onChunk",
+        "onFinish",
+        "onError",
+        "onAbort",
+      ];
+      const invalidCallbacks = streamingOnlyCallbacks.filter(
+        (name) => callbacks[name as keyof typeof callbacks] != null,
+      );
+      if (invalidCallbacks.length > 0) {
+        throw new StreamingCallbacksInNonStreamingModeError(invalidCallbacks);
+      }
+    }
+
     const state: AgentState = {
       collectedReasoning: [],
       actions: [],
@@ -183,7 +217,8 @@ export class V3AgentHandler {
         stopWhen: (result) => this.handleStop(result, maxSteps),
         temperature: 1,
         toolChoice: "auto",
-        onStepFinish: this.createStepHandler(state),
+        prepareStep: callbacks?.prepareStep,
+        onStepFinish: this.createStepHandler(state, callbacks?.onStepFinish),
       });
 
       return this.consolidateMetricsAndResult(startTime, state, result);
@@ -204,7 +239,7 @@ export class V3AgentHandler {
   }
 
   public async stream(
-    instructionOrOptions: string | AgentExecuteOptions,
+    instructionOrOptions: string | AgentStreamExecuteOptions,
   ): Promise<AgentStreamResult> {
     const {
       maxSteps,
@@ -215,6 +250,9 @@ export class V3AgentHandler {
       initialPageUrl,
     } = await this.prepareAgent(instructionOrOptions);
 
+    const callbacks = (instructionOrOptions as AgentStreamExecuteOptions)
+      .callbacks as AgentStreamCallbacks | undefined;
+
     const state: AgentState = {
       collectedReasoning: [],
       actions: [],
@@ -250,11 +288,19 @@ export class V3AgentHandler {
       stopWhen: (result) => this.handleStop(result, maxSteps),
       temperature: 1,
       toolChoice: "auto",
-      onStepFinish: this.createStepHandler(state),
-      onError: ({ error }) => {
-        handleError(error);
+      prepareStep: callbacks?.prepareStep,
+      onStepFinish: this.createStepHandler(state, callbacks?.onStepFinish),
+      onError: (event) => {
+        if (callbacks?.onError) {
+          callbacks.onError(event);
+        }
+        handleError(event.error);
       },
+      onChunk: callbacks?.onChunk,
       onFinish: (event) => {
+        if (callbacks?.onFinish) {
+          callbacks.onFinish(event);
+        }
         try {
           const result = this.consolidateMetricsAndResult(
             startTime,