Issue#186

[cp90-pixel]

Summary

• expose the Playwright command metadata in ActResult so callers can inspect what Stagehand executed
• capture the executed command details throughout the act handler, including self-heal retries
• document the new response shape for page.act

Testing

• pnpm lint

fixes issue #186

[changeset-bot]

⚠️ No Changeset found

Latest commit: b5d17db

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.

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 Overview

Summary

Exposes executed Playwright command details in ActResult to help developers understand what actions Stagehand generated.

Key changes:

• Added PlaywrightCommandResult interface with method, selector, and arguments fields
• Added optional playwrightCommand field to ActResult interface
• Implemented buildPlaywrightCommand() and normalizeSelector() helper methods
• Updated all ActResult returns to include playwrightCommand metadata
• Updated documentation with example response

Issues found:

• Critical logic error in self-heal fallback path (lines 204-215): uses original failed method/args instead of newly observed element's method/args, causing self-heal to potentially retry with the same failing command

Confidence Score: 1/5

• This PR contains a critical bug in the self-heal logic that will cause failures
• The self-heal fallback incorrectly uses the original failed observe.method and observe.arguments instead of the newly discovered element.method and element.arguments, defeating the purpose of the self-heal retry. This will cause the retry to fail with the same error. The PR also lacks a changeset as required by custom instructions.
• lib/handlers/actHandler.ts lines 204-215 must be fixed before merge

Important Files Changed

File Analysis

Filename	Score	Overview
types/stagehand.ts	5/5	Added new PlaywrightCommandResult interface and playwrightCommand field to ActResult
docs/references/act.mdx	5/5	Updated documentation to include playwrightCommand field with example
lib/handlers/actHandler.ts	1/5	Added playwrightCommand tracking throughout act handler, but self-heal logic uses wrong method/args

Sequence Diagram

sequenceDiagram
    participant User
    participant StagehandPage
    participant ActHandler
    participant ObserveHandler
    participant PlaywrightPage

    User->>StagehandPage: page.act(action)
    StagehandPage->>ActHandler: observeAct(action)
    ActHandler->>ObserveHandler: observe(instruction)
    ObserveHandler-->>ActHandler: ObserveResult[]
    ActHandler->>ActHandler: actFromObserveResult(element)
    ActHandler->>ActHandler: buildPlaywrightCommand(method, args, selector)
    Note over ActHandler: Creates PlaywrightCommandResult
    ActHandler->>PlaywrightPage: _performPlaywrightMethod(method, args, selector)
    alt Success
        PlaywrightPage-->>ActHandler: success
        ActHandler-->>User: ActResult with playwrightCommand
    else Failure (selfHeal enabled)
        PlaywrightPage-->>ActHandler: error
        ActHandler->>ObserveHandler: observe(instruction) [retry]
        ObserveHandler-->>ActHandler: ObserveResult[] [new element]
        ActHandler->>ActHandler: buildPlaywrightCommand(method, args, fallbackSelector)
        Note over ActHandler: Updates playwrightCommand with fallback selector
        ActHandler->>PlaywrightPage: _performPlaywrightMethod(method, args, fallbackSelector)
        PlaywrightPage-->>ActHandler: success/failure
        ActHandler-->>User: ActResult with playwrightCommand
    end

Loading

Additional Comments (1)

1. lib/handlers/actHandler.ts, line 1 (link)

   style: missing changeset - check that one is added before merge

   Context Used: Rule from dashboard - All PRs that make code changes must include a changeset to document the version bump and changes. (source)

_{3 files reviewed, 3 comments}

_{Edit Code Review Agent Settings | Greptile}

[greptile-apps]

logic: self-heal fallback uses wrong method/args

uses observe.method and observe.arguments (from original failed attempt) instead of element.method and element.arguments from the newly observed element

Suggested change

	attemptedPlaywrightCommand = this.buildPlaywrightCommand(
	observe.method,
	observe.arguments,
	fallbackSelector,
	);
	attemptedPlaywrightCommand = this.buildPlaywrightCommand(
	element.method,
	element.arguments,
	fallbackSelector,
	);

Prompt To Fix With AI

This is a comment left during a code review.
Path: lib/handlers/actHandler.ts
Line: 204:208

Comment:
**logic:** self-heal fallback uses wrong method/args

uses `observe.method` and `observe.arguments` (from original failed attempt) instead of `element.method` and `element.arguments` from the newly observed element

```suggestion
        attemptedPlaywrightCommand = this.buildPlaywrightCommand(
          element.method,
          element.arguments,
          fallbackSelector,
        );
```

How can I resolve this? If you propose a fix, please make it concise.

[greptile-apps]

logic: self-heal uses original method/args instead of new element's

the comment says "override previously provided method and arguments" but the code does the opposite - it uses the original observe.method and observe.arguments instead of using the new element.method and element.arguments from the fresh observation

Suggested change

	await this._performPlaywrightMethod(
	// override previously provided method and arguments
	observe.method,
	observe.arguments,
	// only update selector
	element.selector,
	fallbackSelector,
	domSettleTimeoutMs,
	await this._performPlaywrightMethod(
	element.method,
	element.arguments,
	fallbackSelector,
	domSettleTimeoutMs,
	);

Prompt To Fix With AI

This is a comment left during a code review.
Path: lib/handlers/actHandler.ts
Line: 209:215

Comment:
**logic:** self-heal uses original method/args instead of new element's

the comment says "override previously provided method and arguments" but the code does the opposite - it uses the original `observe.method` and `observe.arguments` instead of using the new `element.method` and `element.arguments` from the fresh observation

```suggestion
        await this._performPlaywrightMethod(
          element.method,
          element.arguments,
          fallbackSelector,
          domSettleTimeoutMs,
        );
```

How can I resolve this? If you propose a fix, please make it concise.