Ashwin/fix strict ts errors

lib/StagehandPage.ts

@@ -47,7 +47,7 @@ export class StagehandPage {
   private observeHandler: StagehandObserveHandler;
   private llmClient: LLMClient;
   private cdpClient: CDPSession | null = null;
-  private api: StagehandAPI;
+  private api?: StagehandAPI;
   private userProvidedInstructions?: string;
   private waitForCaptchaSolves: boolean;
   private initialized: boolean = false;
@@ -101,7 +101,8 @@ export class StagehandPage {
         const value = target[prop];
         // If the property is a function, wrap it to update active page before execution
         if (typeof value === "function" && prop !== "on") {
-          return (...args: unknown[]) => value.apply(target, args);
+          return (...args: unknown[]) =>
+            (value as (...a: unknown[]) => unknown).apply(target, args);
         }
         return value;
       },
@@ -114,25 +115,23 @@ export class StagehandPage {
     this.userProvidedInstructions = userProvidedInstructions;
     this.waitForCaptchaSolves = waitForCaptchaSolves ?? false;
 
-    if (this.llmClient) {
-      this.actHandler = new StagehandActHandler({
-        logger: this.stagehand.logger,
-        stagehandPage: this,
-        selfHeal: this.stagehand.selfHeal,
-      });
-      this.extractHandler = new StagehandExtractHandler({
-        stagehand: this.stagehand,
-        logger: this.stagehand.logger,
-        stagehandPage: this,
-        userProvidedInstructions,
-      });
-      this.observeHandler = new StagehandObserveHandler({
-        stagehand: this.stagehand,
-        logger: this.stagehand.logger,
-        stagehandPage: this,
-        userProvidedInstructions,
-      });
-    }
+    this.actHandler = new StagehandActHandler({
+      logger: this.stagehand.logger,
+      stagehandPage: this,
+      selfHeal: this.stagehand.selfHeal,
+    });
+    this.extractHandler = new StagehandExtractHandler({
+      stagehand: this.stagehand,
+      logger: this.stagehand.logger,
+      stagehandPage: this,
+      userProvidedInstructions,
+    });
+    this.observeHandler = new StagehandObserveHandler({
+      stagehand: this.stagehand,
+      logger: this.stagehand.logger,
+      stagehandPage: this,
+      userProvidedInstructions,
+    });
   }
 
   public ordinalForFrameId(fid: string | undefined): number {
@@ -180,7 +179,10 @@ ${scriptContent} \
           level: 1,
           auxiliary: {
             error: { value: (err as Error).message, type: "string" },
-            trace: { value: (err as Error).stack, type: "string" },
+            trace: {
+              value: (err as Error).stack ?? "No stack trace available",
+              type: "string",
+            },
           },
         });
         throw err;
@@ -280,17 +282,18 @@ ${scriptContent} \
             }
 
             // Use type assertion to safely call the method with proper typing
+            type EnhancedOptions =
+              | ActOptions
+              | ExtractOptions<z.AnyZodObject>
+              | ObserveOptions;
             type EnhancedMethod = (
-              options:
-                | ActOptions
-                | ExtractOptions<z.AnyZodObject>
-                | ObserveOptions,
+              options: EnhancedOptions,
             ) => Promise<
               ActResult | ExtractResult<z.AnyZodObject> | ObserveResult[]
             >;
 
             const method = this[prop as keyof StagehandPage] as EnhancedMethod;
-            return (options: unknown) => method.call(this, options);
+            return (options: EnhancedOptions) => method.call(this, options);
           }
 
           // Handle screenshots with CDP
@@ -395,7 +398,8 @@ ${scriptContent} \
 
           // For all other method calls, update active page
           if (typeof value === "function") {
-            return (...args: unknown[]) => value.apply(target, args);
+            return (...args: unknown[]) =>
+              (value as (...a: unknown[]) => unknown).apply(target, args);
           }
 
           return value;
@@ -702,34 +706,42 @@ ${scriptContent} \
 
       await clearOverlays(this.page);
 
-      // check if user called extract() with no arguments
-      if (!instructionOrOptions) {
+      // check if user called extract() with no arguments or empty string
+      // NOTE: This explicitly matches the old behavior of early exiting on empty string,
+      //       but it might make more sense to only early exit on undefined.
+      if (instructionOrOptions === undefined || instructionOrOptions === "") {
         let result: ExtractResult<T>;
         if (this.api) {
           result = await this.api.extract<T>({ frameId: this.rootFrameId });
         } else {
           result = await this.extractHandler.extract();
         }
-        this.stagehand.addToHistory("extract", instructionOrOptions, result);
+        // NOTE: This always pushes empty string into the history because of `addToHistory`'s
+        //       type signature, feel free to change this to something else.
+        this.stagehand.addToHistory("extract", "", result);
         return result;
       }
 
       const options: ExtractOptions<T> =
         typeof instructionOrOptions === "string"
           ? {
               instruction: instructionOrOptions,
-              schema: defaultExtractSchema as T,
+              schema: defaultExtractSchema as unknown as T,
             }
           : instructionOrOptions.schema
             ? instructionOrOptions
             : {
                 ...instructionOrOptions,
-                schema: defaultExtractSchema as T,
+                schema: defaultExtractSchema as unknown as T,
               };
 
+      // NOTE: The current code early exits on empty string, but proceeds with { instruction: "" }
+      //       This is a bit confusing, but it's consistent with the old behavior.
+      // NOTE: instruction and schema should be defined at this point as per the docs, see ExtractOptions interface definition
+      //       The below default values should be removed in the future
       const {
-        instruction,
-        schema,
+        instruction = "",
+        schema = defaultExtractSchema,
         modelName,
         modelClientOptions,
         domSettleTimeoutMs,
@@ -832,7 +844,7 @@ ${scriptContent} \
           : instructionOrOptions || {};
 
       const {
-        instruction,
+        instruction = "",
         modelName,
         modelClientOptions,
         domSettleTimeoutMs,
@@ -845,7 +857,11 @@ ${scriptContent} \
       if (this.api) {
         const opts = { ...options, frameId: this.rootFrameId };
         const result = await this.api.observe(opts);
-        this.stagehand.addToHistory("observe", instructionOrOptions, result);
+        this.stagehand.addToHistory(
+          "observe",
+          instructionOrOptions ?? "",
+          result,
+        );
         return result;
       }
 
@@ -923,7 +939,11 @@ ${scriptContent} \
           throw e;
         });
 
-      this.stagehand.addToHistory("observe", instructionOrOptions, result);
+      this.stagehand.addToHistory(
+        "observe",
+        instructionOrOptions ?? "",
+        result,
+      );
 
       return result;
     } catch (err: unknown) {

lib/a11y/utils.ts

@@ -206,7 +206,11 @@ export async function buildBackendIdMaps(
       xpathMap[enc] = path;
 
       // recurse into sub-document if <iframe>
-      if (lc(node.nodeName) === "iframe" && node.contentDocument) {
+      if (
+        node.nodeName &&
+        lc(node.nodeName) === "iframe" &&
+        node.contentDocument
+      ) {
         const childFid = node.contentDocument.frameId ?? fid;
         stack.push({ node: node.contentDocument, path: "", fid: childFid });
       }
@@ -263,7 +267,8 @@ async function cleanStructuralNodes(
   logger?: (l: LogLine) => void,
 ): Promise<AccessibilityNode | null> {
   // 0. ignore negative pseudo-nodes
-  if (+node.nodeId < 0) return null;
+  // NOTE: Nodes with non-numeric node.nodeId won't be ignored: Number(node.nodeId) returns NaN, and NaN < 0 is false
+  if (!node.nodeId || Number(node.nodeId) < 0) return null;
 
   // 1. leaf check
   if (!node.children?.length) {

lib/api.ts

@@ -34,7 +34,7 @@ export class StagehandAPI {
   private apiKey: string;
   private projectId: string;
   private sessionId?: string;
-  private modelApiKey: string;
+  private modelApiKey?: string;
   private logger: (message: LogLine) => void;
   private fetchWithCookies;
 
@@ -65,8 +65,11 @@ export class StagehandAPI {
     this.modelApiKey = modelApiKey;
 
     const region = browserbaseSessionCreateParams?.region;
+    // NOTE: Looks like there was some discussion here -- I personally agree that this should throw
+    //       Thread: https://github.com/browserbase/stagehand/pull/801#discussion_r2138856174
+    //       I'm changing the fallback value to "" to make TS happy for now, but this probably shouldn't be the case
     if (region && region !== "us-west-2") {
-      return { sessionId: browserbaseSessionID ?? null, available: false };
+      return { sessionId: browserbaseSessionID ?? "", available: false };
     }
     const sessionResponse = await this.request("/sessions/start", {
       method: "POST",
@@ -165,6 +168,8 @@ export class StagehandAPI {
     return response;
   }
 
+  // NOTE: This is a strange way to process SSE, and also doesn't guarantee that it returns T (actually explicitly returns null in one case)
+  //       I feel pretty confused by this, so I'll leave this here to refactor later
   private async execute<T>({
     method,
     args,
@@ -197,8 +202,9 @@ export class StagehandAPI {
     while (true) {
       const { value, done } = await reader.read();
 
+      // NOTE: This is a tempfix to make TS happy, but needing this is a code smell
       if (done && !buffer) {
-        return null;
+        return null as T;
       }
 
       buffer += decoder.decode(value, { stream: true });
@@ -231,12 +237,23 @@ export class StagehandAPI {
 
       if (done) break;
     }
+
+    // NOTE: This is a tempfix to make TS happy, but needing this is a code smell
+    return null as T;
   }
 
   private async request(
     path: string,
     options: RequestInit = {},
   ): Promise<Response> {
+    // These must be set for a request to be made successfully
+    if (!this.modelApiKey) {
+      throw new StagehandAPIError("modelApiKey is required");
+    }
+    if (!this.sessionId) {
+      throw new StagehandAPIError("sessionId is required");
+    }
+
     const defaultHeaders: Record<string, string> = {
       "x-bb-api-key": this.apiKey,
       "x-bb-project-id": this.projectId,

lib/cache/LLMCache.ts

@@ -1,12 +1,9 @@
+import { LogLine } from "../../types/log";
 import { BaseCache, CacheEntry } from "./BaseCache";
 
 export class LLMCache extends BaseCache<CacheEntry> {
   constructor(
-    logger: (message: {
-      category?: string;
-      message: string;
-      level?: number;
-    }) => void,
+    logger: (message: LogLine) => void,
     cacheDir?: string,
     cacheFile?: string,
   ) {