@mastra/stagehand 0.2.1 → 0.2.2

package/dist/index.d.cts

@@ -69,6 +69,13 @@ declare const tabsInputSchema: z.ZodObject<{
     url: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 type TabsInput = z.output<typeof tabsInputSchema>;
+/**
+ * stagehand_screenshot - Capture a screenshot of the current page
+ */
+declare const screenshotInputSchema: z.ZodObject<{
+    fullPage: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+type ScreenshotInput = z.output<typeof screenshotInputSchema>;
 declare const stagehandSchemas: {
     readonly act: z.ZodObject<{
         instruction: z.ZodString;
@@ -105,6 +112,9 @@ declare const stagehandSchemas: {
         url: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>;
     readonly close: z.ZodObject<{}, z.core.$strip>;
+    readonly screenshot: z.ZodObject<{
+        fullPage: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>;
 };
 
 /**
@@ -179,6 +189,20 @@ declare class StagehandThreadManager extends ThreadManager<V3> {
     destroyAllSessions(): Promise<void>;
 }
 
+/**
+ * Stagehand Tool Constants
+ */
+declare const STAGEHAND_TOOLS: {
+    readonly ACT: "stagehand_act";
+    readonly EXTRACT: "stagehand_extract";
+    readonly OBSERVE: "stagehand_observe";
+    readonly NAVIGATE: "stagehand_navigate";
+    readonly TABS: "stagehand_tabs";
+    readonly CLOSE: "stagehand_close";
+    readonly SCREENSHOT: "stagehand_screenshot";
+};
+type StagehandToolName = (typeof STAGEHAND_TOOLS)[keyof typeof STAGEHAND_TOOLS];
+
 /**
  * Stagehand Browser Types
  */
@@ -248,6 +272,17 @@ interface StagehandConfigExtensions {
      * @default false
      */
     preserveUserDataDir?: boolean;
+    /**
+     * Tool names to exclude from the browser toolset.
+     * Use this to disable specific tools, e.g. `['stagehand_screenshot']`
+     * to skip the screenshot tool for models that don't support vision.
+     *
+     * @example
+     * ```ts
+     * new StagehandBrowser({ excludeTools: ['stagehand_screenshot'] })
+     * ```
+     */
+    excludeTools?: StagehandToolName[];
 }
 /**
  * Configuration for StagehandBrowser.
@@ -446,6 +481,16 @@ declare class StagehandBrowser extends MastraBrowser {
         title: string;
         hint: string;
     } | BrowserToolError>;
+    /**
+     * Capture a screenshot of the current page
+     * @param input - Screenshot input
+     * @param threadId - Optional thread ID for thread-safe operation
+     */
+    screenshot(input: ScreenshotInput, threadId?: string): Promise<{
+        base64: string;
+        url: string;
+        title: string;
+    } | BrowserToolError>;
     /**
      * Manage browser tabs - list, create, switch, close
      * @param input - Tabs input
@@ -515,19 +560,6 @@ declare class StagehandBrowser extends MastraBrowser {
  */
 declare function getStagehandChromePid(stagehand: Stagehand): number | undefined;
 
-/**
- * Stagehand Tool Constants
- */
-declare const STAGEHAND_TOOLS: {
-    readonly ACT: "stagehand_act";
-    readonly EXTRACT: "stagehand_extract";
-    readonly OBSERVE: "stagehand_observe";
-    readonly NAVIGATE: "stagehand_navigate";
-    readonly TABS: "stagehand_tabs";
-    readonly CLOSE: "stagehand_close";
-};
-type StagehandToolName = (typeof STAGEHAND_TOOLS)[keyof typeof STAGEHAND_TOOLS];
-
 /**
  * Stagehand Tools
  *

package/dist/index.d.ts

@@ -69,6 +69,13 @@ declare const tabsInputSchema: z.ZodObject<{
     url: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 type TabsInput = z.output<typeof tabsInputSchema>;
+/**
+ * stagehand_screenshot - Capture a screenshot of the current page
+ */
+declare const screenshotInputSchema: z.ZodObject<{
+    fullPage: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+type ScreenshotInput = z.output<typeof screenshotInputSchema>;
 declare const stagehandSchemas: {
     readonly act: z.ZodObject<{
         instruction: z.ZodString;
@@ -105,6 +112,9 @@ declare const stagehandSchemas: {
         url: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>;
     readonly close: z.ZodObject<{}, z.core.$strip>;
+    readonly screenshot: z.ZodObject<{
+        fullPage: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>;
 };
 
 /**
@@ -179,6 +189,20 @@ declare class StagehandThreadManager extends ThreadManager<V3> {
     destroyAllSessions(): Promise<void>;
 }
 
+/**
+ * Stagehand Tool Constants
+ */
+declare const STAGEHAND_TOOLS: {
+    readonly ACT: "stagehand_act";
+    readonly EXTRACT: "stagehand_extract";
+    readonly OBSERVE: "stagehand_observe";
+    readonly NAVIGATE: "stagehand_navigate";
+    readonly TABS: "stagehand_tabs";
+    readonly CLOSE: "stagehand_close";
+    readonly SCREENSHOT: "stagehand_screenshot";
+};
+type StagehandToolName = (typeof STAGEHAND_TOOLS)[keyof typeof STAGEHAND_TOOLS];
+
 /**
  * Stagehand Browser Types
  */
@@ -248,6 +272,17 @@ interface StagehandConfigExtensions {
      * @default false
      */
     preserveUserDataDir?: boolean;
+    /**
+     * Tool names to exclude from the browser toolset.
+     * Use this to disable specific tools, e.g. `['stagehand_screenshot']`
+     * to skip the screenshot tool for models that don't support vision.
+     *
+     * @example
+     * ```ts
+     * new StagehandBrowser({ excludeTools: ['stagehand_screenshot'] })
+     * ```
+     */
+    excludeTools?: StagehandToolName[];
 }
 /**
  * Configuration for StagehandBrowser.
@@ -446,6 +481,16 @@ declare class StagehandBrowser extends MastraBrowser {
         title: string;
         hint: string;
     } | BrowserToolError>;
+    /**
+     * Capture a screenshot of the current page
+     * @param input - Screenshot input
+     * @param threadId - Optional thread ID for thread-safe operation
+     */
+    screenshot(input: ScreenshotInput, threadId?: string): Promise<{
+        base64: string;
+        url: string;
+        title: string;
+    } | BrowserToolError>;
     /**
      * Manage browser tabs - list, create, switch, close
      * @param input - Tabs input
@@ -515,19 +560,6 @@ declare class StagehandBrowser extends MastraBrowser {
  */
 declare function getStagehandChromePid(stagehand: Stagehand): number | undefined;
 
-/**
- * Stagehand Tool Constants
- */
-declare const STAGEHAND_TOOLS: {
-    readonly ACT: "stagehand_act";
-    readonly EXTRACT: "stagehand_extract";
-    readonly OBSERVE: "stagehand_observe";
-    readonly NAVIGATE: "stagehand_navigate";
-    readonly TABS: "stagehand_tabs";
-    readonly CLOSE: "stagehand_close";
-};
-type StagehandToolName = (typeof STAGEHAND_TOOLS)[keyof typeof STAGEHAND_TOOLS];
-
 /**
  * Stagehand Tools
  *

package/dist/index.js

@@ -152,6 +152,9 @@ var tabsInputSchema = z.object({
     });
   }
 });
+var screenshotInputSchema = z.object({
+  fullPage: z.boolean().optional().describe("Capture the full scrollable page instead of just the viewport (default: false)")
+});
 var stagehandSchemas = {
   // Core AI
   act: actInputSchema,
@@ -160,7 +163,9 @@ var stagehandSchemas = {
   // Navigation & State
   navigate: navigateInputSchema,
   tabs: tabsInputSchema,
-  close: closeInputSchema
+  close: closeInputSchema,
+  // Utility
+  screenshot: screenshotInputSchema
 };
 
 // src/tools/constants.ts
@@ -172,7 +177,9 @@ var STAGEHAND_TOOLS = {
   // Navigation & State
   NAVIGATE: "stagehand_navigate",
   TABS: "stagehand_tabs",
-  CLOSE: "stagehand_close"
+  CLOSE: "stagehand_close",
+  // Utility
+  SCREENSHOT: "stagehand_screenshot"
 };
 
 // src/tools/act.ts
@@ -253,6 +260,38 @@ function createObserveTool(browser) {
     }
   });
 }
+function createScreenshotTool(browser) {
+  return createTool({
+    id: STAGEHAND_TOOLS.SCREENSHOT,
+    description: "Capture a screenshot of the current viewport as a visible PNG (set fullPage: true for full-page capture). Use observe or extract when you only need text or interactive elements \u2014 screenshots are expensive. Use this when you need to visually inspect the page, e.g. evaluating images, product photos, layout, design, or colors.",
+    inputSchema: screenshotInputSchema,
+    execute: async (input, { agent }) => {
+      const threadId = agent?.threadId;
+      browser.setCurrentThread(threadId);
+      await browser.ensureReady();
+      return await browser.screenshot(input, threadId);
+    },
+    toModelOutput(output) {
+      const result = output;
+      if (typeof result.base64 !== "string") {
+        return {
+          type: "content",
+          value: [{ type: "text", text: result.message ?? "Failed to capture screenshot." }]
+        };
+      }
+      return {
+        type: "content",
+        value: [
+          {
+            type: "media",
+            mediaType: "image/png",
+            data: result.base64
+          }
+        ]
+      };
+    }
+  });
+}
 function createTabsTool(browser) {
   return createTool({
     id: STAGEHAND_TOOLS.TABS,
@@ -277,7 +316,9 @@ function createStagehandTools(browser) {
     // Navigation & State
     [STAGEHAND_TOOLS.NAVIGATE]: createNavigateTool(browser),
     [STAGEHAND_TOOLS.TABS]: createTabsTool(browser),
-    [STAGEHAND_TOOLS.CLOSE]: createCloseTool(browser)
+    [STAGEHAND_TOOLS.CLOSE]: createCloseTool(browser),
+    // Utility
+    [STAGEHAND_TOOLS.SCREENSHOT]: createScreenshotTool(browser)
   };
 }
 function patchProfileExitType(profilePath, logger) {
@@ -636,7 +677,14 @@ var StagehandBrowser = class extends MastraBrowser {
   // Tools - Implements MastraBrowser.getTools()
   // ---------------------------------------------------------------------------
   getTools() {
-    return createStagehandTools(this);
+    const tools = createStagehandTools(this);
+    const exclude = this.stagehandConfig.excludeTools;
+    if (exclude?.length) {
+      for (const name of exclude) {
+        delete tools[name];
+      }
+    }
+    return tools;
   }
   // ---------------------------------------------------------------------------
   // Core AI Methods
@@ -746,6 +794,32 @@ var StagehandBrowser = class extends MastraBrowser {
     }
   }
   // ---------------------------------------------------------------------------
+  // Screenshot
+  // ---------------------------------------------------------------------------
+  /**
+   * Capture a screenshot of the current page
+   * @param input - Screenshot input
+   * @param threadId - Optional thread ID for thread-safe operation
+   */
+  async screenshot(input, threadId) {
+    const page = this.getPage(threadId);
+    if (!page) {
+      return this.createError("browser_error", "Browser page not available.", "Ensure the browser is launched.");
+    }
+    try {
+      const buffer = await page.screenshot({
+        fullPage: input.fullPage ?? false,
+        type: "png"
+      });
+      const base64 = Buffer.from(buffer).toString("base64");
+      const url = page.url();
+      const title = await page.title();
+      return { base64, url, title };
+    } catch (error) {
+      return this.createErrorFromException(error, "Screenshot");
+    }
+  }
+  // ---------------------------------------------------------------------------
   // Tab Management
   // ---------------------------------------------------------------------------
   /**