Messages and abort (#1345)

# Agent Abort Signal and Message Continuation

## Why

Enable users to cancel long-running agent tasks and continue
conversations across multiple `execute()` calls. Also ensures graceful
shutdown when `stagehand.close()` is called by automatically aborting
any running agent tasks.

## What Changed

### New Features (behind `experimental: true`)

#### Abort Signal Support

- Pass `signal` to `agent.execute()` to cancel execution mid-run
- Works with `AbortController` and `AbortSignal.timeout()`
- Throws `AgentAbortError` when aborted

#### Message Continuation

- `execute()` now returns `messages` in the result
- Pass previous messages to continue a conversation across calls

### New Utilities

| File | Purpose |

|---------------------------------|-------------------------------------------------------------------------------------------|
| `combineAbortSignals.ts` | Merges multiple signals (uses native
`AbortSignal.any()` on Node 20+, fallback for older) |
| `errorHandling.ts` | Consolidates abort detection logic—needed because
`close()` may cause indirect errors (e.g., null context) that should
still be treated as abort |
| `validateExperimentalFeatures.ts` | Single place for all
experimental/CUA feature validation |

### CUA Limitations

Abort signal and message continuation are not supported with CUA mode
(throws `StagehandInvalidArgumentError`). This matches existing
streaming limitation.

### Tests Added

- `agent-abort-signal.spec.ts` (7 tests)
- `agent-message-continuation.spec.ts` (4 tests)
- `agent-experimental-validation.spec.ts` (17 tests)

























<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Adds agent abort support and conversation continuation. You can cancel
long runs, auto-abort on close, and carry messages across execute()
calls. Feature is gated behind experimental: true and has clear CUA
limitations.

- **New Features**
- Abort signal for execute() and stream() with AbortController and
AbortSignal.timeout; throws AgentAbortError; stagehand.close()
auto-aborts via an internal controller combined with any user signal.
- Message continuation: execute() returns messages and accepts previous
messages on the next call; tool calls and results are included.

- **Refactors**
- Centralized experimental/CUA validation via
validateExperimentalFeatures: CUA disallows streaming, abort signal, and
message continuation; experimental required for integrations, tools,
streaming, callbacks, signal, and messages.
- Public API updates: re-export ModelMessage; Agent types include
messages and signal; AgentAbortError exported for consistent abort
typing.

<sup>Written for commit 5276e41.
Summary will update automatically on new commits.</sup>

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

---------

Co-authored-by: Nick Sweeting <github@sweeting.me>

Author: tkattkat

.changeset/eleven-apples-yell.md

@@ -0,0 +1,5 @@
+---
+"@browserbasehq/stagehand": patch
+---
+
+Add support for aborting / stopping an agent run & continuing an agent run using messages from prior runs

packages/core/lib/v3/agent/utils/validateExperimentalFeatures.ts

@@ -0,0 +1,92 @@
+import {
+  ExperimentalNotConfiguredError,
+  StagehandInvalidArgumentError,
+} from "../../types/public/sdkErrors";
+import type { AgentConfig, AgentExecuteOptionsBase } from "../../types/public";
+
+export interface AgentValidationOptions {
+  /** Whether experimental mode is enabled */
+  isExperimental: boolean;
+  /** Agent config options (integrations, tools, stream, cua, etc.) */
+  agentConfig?: Partial<AgentConfig>;
+  /** Execute options (callbacks, signal, messages, etc.) */
+  executeOptions?:
+    | (Partial<AgentExecuteOptionsBase> & { callbacks?: unknown })
+    | null;
+  /** Whether this is streaming mode (can be derived from agentConfig.stream) */
+  isStreaming?: boolean;
+}
+
+/**
+ * Validates agent configuration and experimental feature usage.
+ *
+ * This utility consolidates all validation checks for both CUA and non-CUA agent paths:
+ * - Invalid argument errors for CUA (streaming, abort signal, message continuation are not supported)
+ * - Experimental feature checks for integrations and tools (both CUA and non-CUA)
+ * - Experimental feature checks for non-CUA only (callbacks, signal, messages, streaming)
+ *
+ * Throws StagehandInvalidArgumentError for invalid/unsupported configurations.
+ * Throws ExperimentalNotConfiguredError if experimental features are used without experimental mode.
+ */
+export function validateExperimentalFeatures(
+  options: AgentValidationOptions,
+): void {
+  const { isExperimental, agentConfig, executeOptions, isStreaming } = options;
+
+  // CUA-specific validation: certain features are not available at all
+  if (agentConfig?.cua) {
+    const unsupportedFeatures: string[] = [];
+
+    if (agentConfig?.stream) {
+      unsupportedFeatures.push("streaming");
+    }
+    if (executeOptions?.signal) {
+      unsupportedFeatures.push("abort signal");
+    }
+    if (executeOptions?.messages) {
+      unsupportedFeatures.push("message continuation");
+    }
+
+    if (unsupportedFeatures.length > 0) {
+      throw new StagehandInvalidArgumentError(
+        `${unsupportedFeatures.join(", ")} ${unsupportedFeatures.length === 1 ? "is" : "are"} not supported with CUA (Computer Use Agent) mode.`,
+      );
+    }
+  }
+
+  // Skip experimental checks if already in experimental mode
+  if (isExperimental) return;
+
+  const features: string[] = [];
+
+  // Check agent config features (check array length to avoid false positives for empty arrays)
+  const hasIntegrations =
+    agentConfig?.integrations && agentConfig.integrations.length > 0;
+  const hasTools =
+    agentConfig?.tools && Object.keys(agentConfig.tools).length > 0;
+  if (hasIntegrations || hasTools) {
+    features.push("MCP integrations and custom tools");
+  }
+
+  // Check streaming mode (either explicit or derived from config) - only for non-CUA
+  if (!agentConfig?.cua && (isStreaming || agentConfig?.stream)) {
+    features.push("streaming");
+  }
+
+  // Check execute options features - only for non-CUA
+  if (executeOptions && !agentConfig?.cua) {
+    if (executeOptions.callbacks) {
+      features.push("callbacks");
+    }
+    if (executeOptions.signal) {
+      features.push("abort signal");
+    }
+    if (executeOptions.messages) {
+      features.push("message continuation");
+    }
+  }
+
+  if (features.length > 0) {
+    throw new ExperimentalNotConfiguredError(`Agent ${features.join(", ")}`);
+  }
+}

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

@@ -29,8 +29,13 @@ import { mapToolResultToActions } from "../agent/utils/actionMapping";
 import {
   MissingLLMConfigurationError,
   StreamingCallbacksInNonStreamingModeError,
+  AgentAbortError,
 } from "../types/public/sdkErrors";
 
+function getErrorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
 export class V3AgentHandler {
   private v3: V3;
   private logger: (message: LogLine) => void;
@@ -72,9 +77,11 @@ export class V3AgentHandler {
       );
       const tools = this.createTools();
       const allTools: ToolSet = { ...tools, ...this.mcpTools };
-      const messages: ModelMessage[] = [
-        { role: "user", content: options.instruction },
-      ];
+
+      // Use provided messages for continuation, or start fresh with the instruction
+      const messages: ModelMessage[] = options.messages?.length
+        ? [...options.messages, { role: "user", content: options.instruction }]
+        : [{ role: "user", content: options.instruction }];
 
       if (!this.llmClient?.getLanguageModel) {
         throw new MissingLLMConfigurationError();
@@ -176,41 +183,52 @@ export class V3AgentHandler {
     instructionOrOptions: string | AgentExecuteOptions,
   ): Promise<AgentResult> {
     const startTime = Date.now();
-    const {
-      maxSteps,
-      systemPrompt,
-      allTools,
-      messages,
-      wrappedModel,
-      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 signal =
+      typeof instructionOrOptions === "object"
+        ? instructionOrOptions.signal
+        : undefined;
 
     const state: AgentState = {
       collectedReasoning: [],
       actions: [],
       finalMessage: "",
       completed: false,
-      currentPageUrl: initialPageUrl,
+      currentPageUrl: "",
     };
 
+    let messages: ModelMessage[] = [];
+
     try {
+      const {
+        options,
+        maxSteps,
+        systemPrompt,
+        allTools,
+        messages: preparedMessages,
+        wrappedModel,
+        initialPageUrl,
+      } = await this.prepareAgent(instructionOrOptions);
+
+      messages = preparedMessages;
+      state.currentPageUrl = initialPageUrl;
+
+      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 result = await this.llmClient.generateText({
         model: wrappedModel,
         system: systemPrompt,
@@ -221,21 +239,41 @@ export class V3AgentHandler {
         toolChoice: "auto",
         prepareStep: callbacks?.prepareStep,
         onStepFinish: this.createStepHandler(state, callbacks?.onStepFinish),
+        abortSignal: options.signal,
       });
 
-      return this.consolidateMetricsAndResult(startTime, state, result);
+      return this.consolidateMetricsAndResult(
+        startTime,
+        state,
+        messages,
+        result,
+      );
     } catch (error) {
-      const errorMessage = error?.message ?? String(error);
+      // Re-throw validation errors that should propagate to the caller
+      if (error instanceof StreamingCallbacksInNonStreamingModeError) {
+        throw error;
+      }
+
+      // Re-throw abort errors wrapped in AgentAbortError for consistent error typing
+      if (signal?.aborted) {
+        const reason = signal.reason ? String(signal.reason) : "aborted";
+        throw new AgentAbortError(reason);
+      }
+
+      const errorMessage = getErrorMessage(error);
       this.logger({
         category: "agent",
         message: `Error executing agent task: ${errorMessage}`,
         level: 0,
       });
+
+      // For non-abort errors, return a failure result instead of throwing
       return {
         success: false,
         actions: state.actions,
         message: `Failed to execute task: ${errorMessage}`,
         completed: false,
+        messages,
       };
     }
   }
@@ -244,6 +282,7 @@ export class V3AgentHandler {
     instructionOrOptions: string | AgentStreamExecuteOptions,
   ): Promise<AgentStreamResult> {
     const {
+      options,
       maxSteps,
       systemPrompt,
       allTools,
@@ -303,17 +342,25 @@ export class V3AgentHandler {
         if (callbacks?.onFinish) {
           callbacks.onFinish(event);
         }
-        try {
-          const result = this.consolidateMetricsAndResult(
-            startTime,
-            state,
-            event,
-          );
-          resolveResult(result);
-        } catch (error) {
-          handleError(error);
+        const result = this.consolidateMetricsAndResult(
+          startTime,
+          state,
+          messages,
+          event,
+        );
+        resolveResult(result);
+      },
+      onAbort: (event) => {
+        if (callbacks?.onAbort) {
+          callbacks.onAbort(event);
         }
+        // Reject the result promise with AgentAbortError when stream is aborted
+        const reason = options.signal?.reason
+          ? String(options.signal.reason)
+          : "Stream was aborted";
+        rejectResult(new AgentAbortError(reason));
       },
+      abortSignal: options.signal,
     });
 
     const agentStreamResult = streamResult as AgentStreamResult;
@@ -324,7 +371,12 @@ export class V3AgentHandler {
   private consolidateMetricsAndResult(
     startTime: number,
     state: AgentState,
-    result: { text?: string; usage?: LanguageModelUsage },
+    inputMessages: ModelMessage[],
+    result: {
+      text?: string;
+      usage?: LanguageModelUsage;
+      response?: { messages?: ModelMessage[] };
+    },
   ): AgentResult {
     if (!state.finalMessage) {
       const allReasoning = state.collectedReasoning.join(" ").trim();
@@ -344,6 +396,13 @@ export class V3AgentHandler {
       );
     }
 
+    // Combine input messages with response messages for full conversation history
+    const responseMessages = result.response?.messages || [];
+    const fullMessages: ModelMessage[] = [
+      ...inputMessages,
+      ...responseMessages,
+    ];
+
     return {
       success: state.completed,
       message: state.finalMessage || "Task execution completed",
@@ -358,6 +417,7 @@ export class V3AgentHandler {
             inference_time_ms: inferenceTimeMs,
           }
         : undefined,
+      messages: fullMessages,
     };
   }