Issue#186

docs/references/act.mdx

@@ -118,11 +118,25 @@ await page.act(observe_result: ObserveResult) -> ActResult
   The action that was performed.
 </ParamField>
 
+<ParamField
+  path="playwrightCommand"
+  type="PlaywrightCommandResult"
+  optional
+>
+  Details about the underlying Playwright method that Stagehand executed,
+  including the selector and arguments that were used.
+</ParamField>
+
 ```Example Response
 {
   success: true,
   message: 'Action [scrollTo] performed successfully on selector: /html[1]',
-  action: 'Scrollable area of the page where user can navigate to the pricing section or other parts of the page'
+  action: 'Scrollable area of the page where user can navigate to the pricing section or other parts of the page',
+  playwrightCommand: {
+    method: 'scrollTo',
+    selector: '/html[1]',
+    arguments: []
+  }
 }
 ```
 

lib/handlers/actHandler.ts

@@ -71,6 +71,36 @@ export class StagehandActHandler {
     });
 
     const method = observe.method;
+    const args = Array.isArray(observe.arguments) ? [...observe.arguments] : [];
+    const selector =
+      this.normalizeSelector(observe.selector) ?? observe.selector;
+    let attemptedPlaywrightCommand = this.buildPlaywrightCommand(
+      method,
+      args,
+      selector,
+    );
+
+    if (!method) {
+      this.logger({
+        category: "action",
+        message: "ObserveResult did not include a Playwright method",
+        level: 1,
+        auxiliary: {
+          observeResult: {
+            value: JSON.stringify(observe),
+            type: "object",
+          },
+        },
+      });
+      return {
+        success: false,
+        message:
+          "Unable to perform action: The ObserveResult did not include a Playwright method.",
+        action: observe.description || "ObserveResult action",
+        playwrightCommand: attemptedPlaywrightCommand,
+      };
+    }
+
     if (method === "not-supported") {
       this.logger({
         category: "action",
@@ -92,11 +122,9 @@ export class StagehandActHandler {
         success: false,
         message: `Unable to perform action: The method '${method}' is not supported in ObserveResult. Please use a supported Playwright locator method.`,
         action: observe.description || `ObserveResult action (${method})`,
+        playwrightCommand: attemptedPlaywrightCommand,
       };
     }
-    const args = observe.arguments ?? [];
-    // remove the xpath prefix on the selector
-    const selector = observe.selector.replace("xpath=", "");
 
     try {
       await this._performPlaywrightMethod(
@@ -110,6 +138,7 @@ export class StagehandActHandler {
         success: true,
         message: `Action [${method}] performed successfully on selector: ${selector}`,
         action: observe.description || `ObserveResult action (${method})`,
+        playwrightCommand: attemptedPlaywrightCommand,
       };
     } catch (err) {
       if (
@@ -129,6 +158,7 @@ export class StagehandActHandler {
           success: false,
           message: `Failed to perform act: ${err.message}`,
           action: observe.description || `ObserveResult action (${method})`,
+          playwrightCommand: attemptedPlaywrightCommand,
         };
       }
       // We will try to use observeAct on a failed ObserveResult-act if selfHeal is true
@@ -165,21 +195,30 @@ export class StagehandActHandler {
             success: false,
             message: `Failed to self heal act: Element not found.`,
             action: actCommand,
+            playwrightCommand: attemptedPlaywrightCommand,
           };
         }
         const element: ObserveResult = observeResults[0];
+        const fallbackSelector =
+          this.normalizeSelector(element.selector) ?? element.selector;
+        attemptedPlaywrightCommand = this.buildPlaywrightCommand(
+          observe.method,
+          observe.arguments,
+          fallbackSelector,
+        );
         await this._performPlaywrightMethod(
           // override previously provided method and arguments
           observe.method,
           observe.arguments,
           // only update selector
-          element.selector,
+          fallbackSelector,
           domSettleTimeoutMs,
         );
         return {
           success: true,
           message: `Action [${element.method}] performed successfully on selector: ${element.selector}`,
           action: observe.description || `ObserveResult action (${method})`,
+          playwrightCommand: attemptedPlaywrightCommand,
         };
       } catch (err) {
         this.logger({
@@ -195,11 +234,38 @@ export class StagehandActHandler {
           success: false,
           message: `Failed to perform act: ${err.message}`,
           action: observe.description || `ObserveResult action (${method})`,
+          playwrightCommand: attemptedPlaywrightCommand,
         };
       }
     }
   }
 
+  private normalizeSelector(selector?: string): string | undefined {
+    if (!selector) {
+      return undefined;
+    }
+
+    return selector.replace(/^xpath=/i, "").trim();
+  }
+
+  private buildPlaywrightCommand(
+    method: string | undefined,
+    args: unknown[] | undefined,
+    selector: string | undefined,
+  ): ActResult["playwrightCommand"] {
+    if (!method || !selector) {
+      return undefined;
+    }
+
+    const commandArguments = Array.isArray(args) ? args : [];
+
+    return {
+      method,
+      selector,
+      arguments: commandArguments,
+    };
+  }
+
   /**
    * Perform an act based on an instruction.
    * This method will observe the page and then perform the act on the first element returned.

types/stagehand.ts

@@ -125,10 +125,17 @@ export interface ActOptions {
   frameId?: string;
 }
 
+export interface PlaywrightCommandResult {
+  method: string;
+  selector: string;
+  arguments: unknown[];
+}
+
 export interface ActResult {
   success: boolean;
   message: string;
   action: string;
+  playwrightCommand?: PlaywrightCommandResult;
 }
 
 export interface ExtractOptions<T extends z.AnyZodObject> {