Repository: browserbase/stagehand
File: packages/core/lib/v3/v3.ts (TypeScript)

Code before:

  /**
   * Prepares shared context for agent execution (both execute and stream).
   * Extracts duplicated setup logic into a single helper.
   */
  private async prepareAgentExecution(
    options: AgentConfig | undefined,
    instructionOrOptions:
      | string
      | AgentExecuteOptions
      | AgentStreamExecuteOptions,
    agentConfigSignature: string,
  ): Promise<{
    handler: V3AgentHandler;
    resolvedOptions: AgentExecuteOptions | AgentStreamExecuteOptions;
    instruction: string;
    cacheContext: AgentCacheContext | null;
    llmClient: LLMClient;
  }> {
    // Note: experimental validation is done at the call site before this method
    // Warn if mode is not explicitly set (defaults to "dom")
    if (options?.mode === undefined) {
      this.logger({
        category: "agent",
        message:
          "Using DOM mode (legacy). Consider using mode: 'hybrid' for improved performance.\n  → https://docs.stagehand.dev/v3/basics/agent\n",
        level: 0,
      });
    }

    const tools = options?.integrations
      ? await resolveTools(options.integrations, options.tools)
      : (options?.tools ?? {});

    const agentLlmClient = options?.model
      ? this.resolveLlmClient(options.model)
      : this.llmClient;

    const handler = new V3AgentHandler(
      this,
      this.logger,
      agentLlmClient,
      typeof options?.executionModel === "string"
        ? options.executionModel
        : options?.executionModel?.modelName,
      options?.systemPrompt,
      tools,
      options?.mode,
    );

    const resolvedOptions: AgentExecuteOptions | AgentStreamExecuteOptions =

Review comment (performance):
```suggestion
          "Using agent in default DOM mode (legacy). Agent will default to 'hybrid' on an upcoming release for improved performance.\n  → https://docs.stagehand.dev/v3/basics/agent\n",
```

Code after:

  /**
   * Prepares shared context for agent execution (both execute and stream).
   * Extracts duplicated setup logic into a single helper.
   */
  private async prepareAgentExecution(
    options: AgentConfig | undefined,
    instructionOrOptions:
      | string
      | AgentExecuteOptions
      | AgentStreamExecuteOptions,
    agentConfigSignature: string,
  ): Promise<{
    handler: V3AgentHandler;
    resolvedOptions: AgentExecuteOptions | AgentStreamExecuteOptions;
    instruction: string;
    cacheContext: AgentCacheContext | null;
    llmClient: LLMClient;
  }> {
    // Note: experimental validation is done at the call site before this method
    // Warn if mode is not explicitly set (defaults to "dom")
    if (options?.mode === undefined) {
      this.logger({
        category: "agent",
        message:
          "Using agent in default DOM mode (legacy). Agent will default to 'hybrid' on an upcoming release for improved performance.\n  → https://docs.stagehand.dev/v3/basics/agent\n",
        level: 0,
      });
    }

    const tools = options?.integrations
      ? await resolveTools(options.integrations, options.tools)
      : (options?.tools ?? {});

    const agentLlmClient = options?.model
      ? this.resolveLlmClient(options.model)
      : this.llmClient;

    const handler = new V3AgentHandler(
      this,
      this.logger,
      agentLlmClient,
      typeof options?.executionModel === "string"
        ? options.executionModel
        : options?.executionModel?.modelName,
      options?.systemPrompt,
      tools,
      options?.mode,
    );

    const resolvedOptions: AgentExecuteOptions | AgentStreamExecuteOptions =