add logging of full control flow

Author: pirate

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

@@ -22,6 +22,7 @@ import {
   performUnderstudyMethod,
   waitForDomNetworkQuiet,
 } from "./handlerUtils/actHandlerUtils";
+import { logStepStart, logStepEnd } from "../hierarchicalLogger";
 
 export class ActHandler {
   private readonly llmClient: LLMClient;
@@ -73,6 +74,8 @@ export class ActHandler {
   async act(params: ActHandlerParams): Promise<ActResult> {
     const { instruction, page, variables, timeout, model } = params;
 
+    logStepStart("act", instruction, { timeout, hasVariables: !!variables });
+
     const llmClient = this.resolveLlmClient(model);
 
     const doObserveAndAct = async (): Promise<ActResult> => {
@@ -313,19 +316,23 @@ export class ActHandler {
     };
 
     // Hard timeout for entire act() call → reject on timeout (align with extract/observe)
+    let result: ActResult;
     if (!timeout) {
-      return doObserveAndAct();
+      result = await doObserveAndAct();
+    } else {
+      result = await Promise.race([
+        doObserveAndAct(),
+        new Promise<ActResult>((_, reject) => {
+          setTimeout(
+            () => reject(new Error(`act() timed out after ${timeout}ms`)),
+            timeout,
+          );
+        }),
+      ]);
     }
 
-    return await Promise.race([
-      doObserveAndAct(),
-      new Promise<ActResult>((_, reject) => {
-        setTimeout(
-          () => reject(new Error(`act() timed out after ${timeout}ms`)),
-          timeout,
-        );
-      }),
-    ]);
+    logStepEnd("act", result.success, result.message);
+    return result;
   }
 
   async actFromObserveResult(

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

@@ -15,6 +15,7 @@ import {
   ModelConfiguration,
 } from "../types/public/model";
 import { StagehandInvalidArgumentError } from "../types/public/sdkErrors";
+import { logStepStart, logStepEnd } from "../hierarchicalLogger";
 
 /**
  * Scans the provided Zod schema for any `z.string().url()` fields and
@@ -94,6 +95,12 @@ export class ExtractHandler {
   ): Promise<z.infer<T> | { pageText: string }> {
     const { instruction, schema, page, selector, timeout, model } = params;
 
+    logStepStart("extract", instruction ?? "(no instruction - page text)", {
+      hasSchema: !!schema,
+      selector,
+      timeout,
+    });
+
     const llmClient = this.resolveLlmClient(model);
 
     const doExtract = async (): Promise<z.infer<T> | { pageText: string }> => {
@@ -220,16 +227,23 @@ export class ExtractHandler {
 
       return output as z.infer<T>;
     };
-    if (!timeout) return doExtract();
-
-    return await Promise.race([
-      doExtract(),
-      new Promise<z.infer<T> | { pageText: string }>((_, reject) => {
-        setTimeout(
-          () => reject(new Error(`extract() timed out after ${timeout}ms`)),
-          timeout,
-        );
-      }),
-    ]);
+
+    let result: z.infer<T> | { pageText: string };
+    if (!timeout) {
+      result = await doExtract();
+    } else {
+      result = await Promise.race([
+        doExtract(),
+        new Promise<z.infer<T> | { pageText: string }>((_, reject) => {
+          setTimeout(
+            () => reject(new Error(`extract() timed out after ${timeout}ms`)),
+            timeout,
+          );
+        }),
+      ]);
+    }
+
+    logStepEnd("extract", true, "extraction completed");
+    return result;
   }
 }

packages/core/lib/v3/handlers/handlerUtils/actHandlerUtils.ts

@@ -6,6 +6,10 @@ import { resolveLocatorWithHops } from "../../understudy/deepLocator";
 import type { Page } from "../../understudy/page";
 import { v3Logger } from "../../logger";
 import { StagehandClickError } from "../../types/public/sdkErrors";
+import {
+  logActionStart,
+  logActionEnd,
+} from "../../hierarchicalLogger";
 
 export class UnderstudyCommandException extends Error {
   constructor(message: string) {
@@ -42,6 +46,9 @@ export async function performUnderstudyMethod(
   domSettleTimeoutMs?: number,
 ): Promise<void> {
   const selectorRaw = normalizeRootXPath(rawXPath);
+
+  logActionStart(method, selectorRaw, args);
+
   // Unified resolver: supports '>>' hops and XPath across iframes
   const locator: Locator = await resolveLocatorWithHops(
     page,
@@ -97,13 +104,16 @@ export async function performUnderstudyMethod(
             level: 1,
             auxiliary: { method: { value: method, type: "string" } },
           });
+          logActionEnd(method, false, `Method ${method} not supported`);
           throw new UnderstudyCommandException(
             `Method ${method} not supported`,
           );
       }
     }
 
     await handlePossibleNavigation("action", selectorRaw, initialUrl, frame);
+
+    logActionEnd(method, true);
   } catch (e) {
     const msg = e instanceof Error ? e.message : String(e);
     const stack = e instanceof Error ? e.stack : undefined;
@@ -119,6 +129,7 @@ export async function performUnderstudyMethod(
         args: { value: JSON.stringify(args), type: "object" },
       },
     });
+    logActionEnd(method, false, msg);
     throw new UnderstudyCommandException(msg);
   }
 }

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

@@ -13,6 +13,7 @@ import {
   ClientOptions,
   ModelConfiguration,
 } from "../types/public/model";
+import { logStepStart, logStepEnd } from "../hierarchicalLogger";
 
 export class ObserveHandler {
   private readonly llmClient: LLMClient;
@@ -67,6 +68,8 @@ export class ObserveHandler {
       instruction ??
       "Find elements that can be used for any future actions in the page. These may be navigation links, related pages, section/subsection links, buttons, or other interactive elements. Be comprehensive: if there are multiple elements that may be relevant for future actions, return all of them.";
 
+    logStepStart("observe", effectiveInstruction, { timeout, selector });
+
     const doObserve = async (): Promise<Action[]> => {
       v3Logger({
         category: "observation",
@@ -171,16 +174,22 @@ export class ObserveHandler {
       return elementsWithSelectors;
     };
 
-    if (!timeout) return doObserve();
-
-    return await Promise.race([
-      doObserve(),
-      new Promise<Action[]>((_, reject) => {
-        setTimeout(
-          () => reject(new Error(`observe() timed out after ${timeout}ms`)),
-          timeout,
-        );
-      }),
-    ]);
+    let result: Action[];
+    if (!timeout) {
+      result = await doObserve();
+    } else {
+      result = await Promise.race([
+        doObserve(),
+        new Promise<Action[]>((_, reject) => {
+          setTimeout(
+            () => reject(new Error(`observe() timed out after ${timeout}ms`)),
+            timeout,
+          );
+        }),
+      ]);
+    }
+
+    logStepEnd("observe", true, `observed ${result.length} actions`);
+    return result;
   }
 }

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

@@ -12,6 +12,7 @@ import {
 import { V3FunctionName } from "../types/public/methods";
 import { mapToolResultToActions } from "../agent/utils/actionMapping";
 import { MissingLLMConfigurationError } from "../types/public/sdkErrors";
+import { logTaskStart, logTaskEnd } from "../hierarchicalLogger";
 
 export class V3AgentHandler {
   private v3: V3;
@@ -46,6 +47,10 @@ export class V3AgentHandler {
         ? { instruction: instructionOrOptions }
         : instructionOrOptions;
 
+    logTaskStart(options.instruction, {
+      maxSteps: options.maxSteps,
+    });
+
     const maxSteps = options.maxSteps || 10;
     const actions: AgentAction[] = [];
     let finalMessage = "";
@@ -155,7 +160,7 @@ export class V3AgentHandler {
         );
       }
 
-      return {
+      const agentResult = {
         success: completed,
         message: finalMessage || "Task execution completed",
         actions,
@@ -170,19 +175,26 @@ export class V3AgentHandler {
             }
           : undefined,
       };
+
+      logTaskEnd(agentResult.success, agentResult.message);
+      return agentResult;
     } catch (error) {
       const errorMessage = error?.message ?? String(error);
       this.logger({
         category: "agent",
         message: `Error executing agent task: ${errorMessage}`,
         level: 0,
       });
-      return {
+
+      const errorResult = {
         success: false,
         actions,
         message: `Failed to execute task: ${errorMessage}`,
         completed: false,
       };
+
+      logTaskEnd(false, errorResult.message);
+      return errorResult;
     }
   }