Fix executionModel propagation on agent

[miguelg719]

why

When passing an executionModel to agent (for LLM-powered tools -- act, extract...) from a different provider than the one for the model provided in the Stagehand constructor, or in the AgentConfig, API keys are not propagating properly and causing errors in non-local environments

The root cause is the execution model was being passed as a string, and its respective API key doesn't propagate if explicitly defined. Unnoticeable if the API key for each provider is exported or in .env, since we automatically pull when none is specified. This issue doesn't express itself if the different models share the same provider.

what changed

test plan

---

Summary by cubic

Fix executionModel propagation by accepting either a string or AgentModelConfig across agent tools and the handler, and normalizing model names for correct resolution, API key usage, and telemetry.

• Refactors
  • Added extractModelName; used in resolveModel and telemetry model logging.
  • Updated act, extract, fillForm tools, tool options, and V3AgentHandler to accept executionModel: string | AgentModelConfig.
  • In V3, pass executionModel (or fallback to model) directly to the handler and use extractModelName for the logged model.
  • Added tests covering tool propagation, fallback logic, and model utils (extractModelName, resolveModel).

^{Written for commit 0417e07. Summary will update on new commits. Review in cubic}

[changeset-bot]

⚠️ No Changeset found

Latest commit: 0417e07

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[greptile-apps]

Greptile Summary

Fixed executionModel propagation to properly pass API keys when using different LLM providers for agent tools versus agent orchestration.

Key Changes:

• Changed executionModel type from string to string | AgentModelConfig across agent tools (act, extract, fillForm) and handler
• Added extractModelName helper utility to normalize model name extraction from both string and object formats
• Simplified agent setup by passing full executionModel configuration object instead of extracting just the modelName string
• Updated telemetry logging to use extractModelName for consistent model name resolution

Impact:
This fix resolves API key propagation issues in non-local environments where different providers (e.g., OpenAI for agent orchestration, Anthropic for tool execution) require distinct API keys. Previously, only the model name string was passed, causing API authentication failures when explicit API keys were defined in the model configuration.

Confidence Score: 5/5

• This PR is safe to merge with minimal risk
• The changes are well-scoped, type-safe, and address a clear bug in API key propagation. All modifications maintain backward compatibility (string still accepted), improve type safety by allowing full configuration objects, and use a consistent pattern across all affected files.
• No files require special attention

Important Files Changed

Filename	Overview
packages/core/lib/modelUtils.ts	Added extractModelName helper to normalize model name extraction from string or object formats, used in resolveModel and telemetry
packages/core/lib/v3/agent/tools/act.ts	Updated executionModel parameter to accept `string
packages/core/lib/v3/agent/tools/extract.ts	Updated executionModel parameter to accept `string
packages/core/lib/v3/agent/tools/fillform.ts	Updated executionModel parameter to accept `string
packages/core/lib/v3/agent/tools/index.ts	Updated V3AgentToolOptions.executionModel to accept `string
packages/core/lib/v3/handlers/v3AgentHandler.ts	Updated constructor and class property to accept executionModel as `string
packages/core/lib/v3/v3.ts	Simplified agent setup by passing through full executionModel object and using extractModelName helper for telemetry logging

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[Agent Config with executionModel] --> B{executionModel type?}
    B -->|string| C[Model name only]
    B -->|AgentModelConfig| D[Full config with API keys]
    
    C --> E[V3AgentHandler constructor]
    D --> E
    
    E --> F[createTools method]
    F --> G[Pass executionModel to tools]
    
    G --> H[act tool]
    G --> I[extract tool]
    G --> J[fillForm tool]
    
    H --> K{Has executionModel?}
    I --> K
    J --> K
    
    K -->|Yes| L[v3.act/extract/fillForm with model option]
    K -->|No| M[Use default model]
    
    L --> N[resolveLlmClient with full config]
    N --> O[API key properly propagated]
    
    style D fill:#90EE90
    style O fill:#90EE90
    style C fill:#FFB6C1

Loading

_{Last reviewed commit: 9557735}

[greptile-apps]

_{7 files reviewed, no comments}

_{Edit Code Review Agent Settings | Greptile}

[cubic-dev-ai]

No issues found across 7 files

Confidence score: 5/5

• Automated review surfaced no issues in the provided summaries.
• No files require special attention.

Architecture diagram

sequenceDiagram
    participant User
    participant V3 as V3 Orchestrator
    participant Handler as V3AgentHandler
    participant Tools as Agent Tools (Act/Extract/Fill)
    participant Utils as ModelUtils
    participant LLM as LLM Provider / Client

    Note over User,LLM: Execution Model Propagation Flow

    User->>V3: agent(options)
    Note right of User: options include model and <br/>NEW: executionModel as AgentModelConfig

    V3->>V3: resolveLlmClient(options.model)
    
    V3->>Handler: NEW: Create Handler with executionModel (string | AgentModelConfig)
    
    Handler->>Tools: NEW: Initialize Tools with executionModel config
    
    Note over Tools,Utils: During Tool Execution (e.g., act, extract)

    Tools->>Utils: extractModelName(executionModel)
    Utils-->>Tools: Normalized model name string

    Tools->>Utils: resolveModel(executionModel)
    
    alt executionModel is AgentModelConfig
        Utils->>Utils: Extract modelName
        Utils->>Utils: CHANGED: Extract clientOptions (API Keys, Base URL)
    else executionModel is string
        Utils->>Utils: Use modelName
        Utils->>Utils: Use default clientOptions (from ENV)
    end

    Utils-->>Tools: { clientOptions, modelName, isCua }

    Tools->>LLM: Request completion
    Note right of Tools: Uses specific clientOptions (API Keys)<br/>resolved for the executionModel provider

    LLM-->>Tools: Tool Result
    Tools-->>Handler: Action / Data
    Handler-->>V3: Result
    V3-->>User: Final Response

Loading