@browserbasehq/stagehand - npm Package Compare versions

Comparing version 1.9.1-alpha-2cee0a45ae2b48d1de6543b196e338e7021e59fe to 1.10.0-alpha-04555d47673eacf8764c78d99034ca93bea960c6

dist/evals/initStagehand.d.ts

@@ -12,3 +12,3 @@ /**
  */
-import { AvailableModel, Stagehand } from "../lib";
+import { AvailableModel, ConstructorParams, Stagehand } from "../lib";
 import { EvalLogger } from "./logger";
@@ -26,6 +26,7 @@ /**
  */
-export declare const initStagehand: ({ modelName, domSettleTimeoutMs, logger, }: {
+export declare const initStagehand: ({ modelName, domSettleTimeoutMs, logger, configOverrides, }: {
     modelName: AvailableModel;
     domSettleTimeoutMs?: number;
     logger: EvalLogger;
+    configOverrides?: Partial<ConstructorParams>;
 }) => Promise<{
@@ -32,0 +33,0 @@ stagehand: Stagehand;

dist/index.d.ts

@@ -59,2 +59,4 @@ import { z, ZodType } from 'zod';
 }
+declare const modelsWithVision: AvailableModel[];
+declare const AnnotatedScreenshotText = "This is a screenshot of the current page state with the elements annotated on it. Each element id is annotated with a number to the top left of it. Duplicate annotations at the same location are under each other vertically.";
 interface ChatCompletionOptions {
@@ -116,3 +118,4 @@ messages: ChatMessage[];
     clientOptions: ClientOptions;
-    constructor(modelName: AvailableModel);
+    userProvidedInstructions?: string;
+    constructor(modelName: AvailableModel, userProvidedInstructions?: string);
     abstract createChatCompletion<T = LLMResponse>(options: CreateChatCompletionOptions): Promise<T>;
@@ -147,2 +150,6 @@ }
     modelClientOptions?: ClientOptions;
+    /**
+     * Instructions for stagehand.
+     */
+    systemPrompt?: string;
 }
@@ -259,3 +266,4 @@ interface InitOptions {
     private llmClient;
-    constructor({ env, apiKey, projectId, verbose, debugDom, llmProvider, llmClient, headless, logger, browserbaseSessionCreateParams, domSettleTimeoutMs, enableCaching, browserbaseSessionID, modelName, modelClientOptions, }?: ConstructorParams);
+    private userProvidedInstructions?;
+    constructor({ env, apiKey, projectId, verbose, debugDom, llmProvider, llmClient, headless, logger, browserbaseSessionCreateParams, domSettleTimeoutMs, enableCaching, browserbaseSessionID, modelName, modelClientOptions, systemPrompt, }?: ConstructorParams);
     get logger(): (logLine: LogLine) => void;
@@ -284,2 +292,2 @@ get page(): Page;
 
-export { type ActOptions, type ActResult, type AnthropicJsonSchemaObject, type AvailableModel, AvailableModelSchema, type Browser, type BrowserContext, type BrowserResult, type ClientOptions, type ConstructorParams, type ExtractOptions, type ExtractResult, type GotoOptions, type InitFromPageOptions, type InitFromPageResult, type InitOptions, type InitResult, LLMClient, type LogLine, type ModelProvider, type ObserveOptions, type ObserveResult, type Page, PlaywrightCommandException, PlaywrightCommandMethodNotSupportedException, Stagehand };
+export { type ActOptions, type ActResult, AnnotatedScreenshotText, type AnthropicJsonSchemaObject, type AvailableModel, AvailableModelSchema, type Browser, type BrowserContext, type BrowserResult, type ChatCompletionOptions, type ChatMessage, type ChatMessageContent, type ChatMessageImageContent, type ChatMessageTextContent, type ClientOptions, type ConstructorParams, type CreateChatCompletionOptions, type ExtractOptions, type ExtractResult, type GotoOptions, type InitFromPageOptions, type InitFromPageResult, type InitOptions, type InitResult, LLMClient, type LLMResponse, type LogLine, type ModelProvider, type ObserveOptions, type ObserveResult, type Page, PlaywrightCommandException, PlaywrightCommandMethodNotSupportedException, Stagehand, modelsWithVision };

dist/lib/handlers/actHandler.d.ts

@@ -14,3 +14,4 @@ import { LogLine } from "../../types/log";
     private readonly actions;
-    constructor({ verbose, llmProvider, enableCaching, logger, stagehandPage, }: {
+    private readonly userProvidedInstructions?;
+    constructor({ verbose, llmProvider, enableCaching, logger, stagehandPage, userProvidedInstructions, }: {
         verbose: 0 | 1 | 2;
@@ -23,2 +24,3 @@ llmProvider: LLMProvider;
         stagehandContext: StagehandContext;
+        userProvidedInstructions?: string;
     });
@@ -25,0 +27,0 @@ private _recordAction;

dist/lib/handlers/extractHandler.d.ts

@@ -78,3 +78,4 @@ import { z } from "zod";
     private readonly logger;
-    constructor({ stagehand, logger, stagehandPage, }: {
+    private readonly userProvidedInstructions?;
+    constructor({ stagehand, logger, stagehandPage, userProvidedInstructions, }: {
         stagehand: Stagehand;
@@ -93,2 +94,3 @@ logger: (message: {
         stagehandPage: StagehandPage;
+        userProvidedInstructions?: string;
     });
@@ -95,0 +97,0 @@ extract<T extends z.AnyZodObject>({ instruction, schema, content, chunksSeen, llmClient, requestId, domSettleTimeoutMs, useTextExtract, }: {

dist/lib/handlers/observeHandler.d.ts

@@ -11,6 +11,8 @@ import { LogLine } from "../../types/log";
     private observations;
-    constructor({ stagehand, logger, stagehandPage, }: {
+    private readonly userProvidedInstructions?;
+    constructor({ stagehand, logger, stagehandPage, userProvidedInstructions, }: {
         stagehand: Stagehand;
         logger: (logLine: LogLine) => void;
         stagehandPage: StagehandPage;
+        userProvidedInstructions?: string;
     });
@@ -17,0 +19,0 @@ private _recordObservation;

dist/lib/index.d.ts

@@ -26,3 +26,4 @@ import { z } from "zod";
     private llmClient;
-    constructor({ env, apiKey, projectId, verbose, debugDom, llmProvider, llmClient, headless, logger, browserbaseSessionCreateParams, domSettleTimeoutMs, enableCaching, browserbaseSessionID, modelName, modelClientOptions, }?: ConstructorParams);
+    private userProvidedInstructions?;
+    constructor({ env, apiKey, projectId, verbose, debugDom, llmProvider, llmClient, headless, logger, browserbaseSessionCreateParams, domSettleTimeoutMs, enableCaching, browserbaseSessionID, modelName, modelClientOptions, systemPrompt, }?: ConstructorParams);
     get logger(): (logLine: LogLine) => void;
@@ -56,2 +57,2 @@ get page(): Page;
 export * from "../types/page";
-export { LLMClient } from "./llm/LLMClient";
+export * from "./llm/LLMClient";

dist/lib/inference.d.ts

@@ -8,4 +8,4 @@ import { z } from "zod";
 export declare function fillInVariables(text: string, variables: Record<string, string>): string;
-export declare function act({ action, domElements, steps, llmClient, screenshot, retries, logger, requestId, variables, }: ActCommandParams): Promise<ActCommandResult | null>;
-export declare function extract({ instruction, previouslyExtractedContent, domElements, schema, llmClient, chunksSeen, chunksTotal, requestId, logger, isUsingTextExtract, }: {
+export declare function act({ action, domElements, steps, llmClient, screenshot, retries, logger, requestId, variables, userProvidedInstructions, }: ActCommandParams): Promise<ActCommandResult | null>;
+export declare function extract({ instruction, previouslyExtractedContent, domElements, schema, llmClient, chunksSeen, chunksTotal, requestId, logger, isUsingTextExtract, userProvidedInstructions, }: {
     instruction: string;
@@ -20,2 +20,3 @@ previouslyExtractedContent: object;
     isUsingTextExtract?: boolean;
+    userProvidedInstructions?: string;
     logger: (message: LogLine) => void;
@@ -28,3 +29,3 @@ }): Promise<{
 }>;
-export declare function observe({ instruction, domElements, llmClient, image, requestId, logger, }: {
+export declare function observe({ instruction, domElements, llmClient, image, requestId, userProvidedInstructions, logger, }: {
     instruction: string;
@@ -35,2 +36,3 @@ domElements: string;
     requestId: string;
+    userProvidedInstructions?: string;
     logger: (message: LogLine) => void;
@@ -37,0 +39,0 @@ }): Promise<{

dist/lib/llm/AnthropicClient.d.ts

@@ -12,3 +12,3 @@ import { ClientOptions } from "@anthropic-ai/sdk";
     clientOptions: ClientOptions;
-    constructor({ enableCaching, cache, modelName, clientOptions, }: {
+    constructor({ enableCaching, cache, modelName, clientOptions, userProvidedInstructions, }: {
         logger: (message: LogLine) => void;
@@ -19,4 +19,5 @@ enableCaching?: boolean;
         clientOptions?: ClientOptions;
+        userProvidedInstructions?: string;
     });
     createChatCompletion<T = LLMResponse>({ options, retries, logger, }: CreateChatCompletionOptions): Promise<T>;
 }

dist/lib/llm/LLMClient.d.ts

@@ -79,4 +79,5 @@ import { ZodType } from "zod";
     clientOptions: ClientOptions;
-    constructor(modelName: AvailableModel);
+    userProvidedInstructions?: string;
+    constructor(modelName: AvailableModel, userProvidedInstructions?: string);
     abstract createChatCompletion<T = LLMResponse>(options: CreateChatCompletionOptions): Promise<T>;
 }

dist/lib/prompt.d.ts

@@ -5,6 +5,7 @@ import { LLMTool } from "../types/llm";
 export declare function buildVerifyActCompletionUserPrompt(goal: string, steps: string, domElements: string | undefined): ChatMessage;
-export declare function buildActSystemPrompt(): ChatMessage;
+export declare function buildUserInstructionsString(userProvidedInstructions?: string): string;
+export declare function buildActSystemPrompt(userProvidedInstructions?: string): ChatMessage;
 export declare function buildActUserPrompt(action: string, steps: string, domElements: string, variables?: Record<string, string>): ChatMessage;
 export declare const actTools: LLMTool[];
-export declare function buildExtractSystemPrompt(isUsingPrintExtractedDataTool?: boolean, useTextExtract?: boolean): ChatMessage;
+export declare function buildExtractSystemPrompt(isUsingPrintExtractedDataTool?: boolean, useTextExtract?: boolean, userProvidedInstructions?: string): ChatMessage;
 export declare function buildExtractUserPrompt(instruction: string, domElements: string, isUsingPrintExtractedDataTool?: boolean): ChatMessage;
@@ -15,3 +16,3 @@ export declare function buildRefineSystemPrompt(): ChatMessage;
 export declare function buildMetadataPrompt(instruction: string, extractionResponse: object, chunksSeen: number, chunksTotal: number): ChatMessage;
-export declare function buildObserveSystemPrompt(): ChatMessage;
+export declare function buildObserveSystemPrompt(userProvidedInstructions?: string): ChatMessage;
 export declare function buildObserveUserMessage(instruction: string, domElements: string): ChatMessage;

dist/lib/StagehandPage.d.ts

@@ -16,3 +16,3 @@ import type { Page as PlaywrightPage, BrowserContext as PlaywrightContext } from "@playwright/test";
     private llmClient;
-    constructor(page: PlaywrightPage, stagehand: Stagehand, context: StagehandContext, llmClient: LLMClient);
+    constructor(page: PlaywrightPage, stagehand: Stagehand, context: StagehandContext, llmClient: LLMClient, userProvidedInstructions?: string);
     init(): Promise<StagehandPage>;
@@ -19,0 +19,0 @@ get page(): Page;

dist/types/act.d.ts

@@ -16,2 +16,3 @@ import { Buffer } from "buffer";
     variables?: Record<string, string>;
+    userProvidedInstructions?: string;
 }
@@ -18,0 +19,0 @@ export interface ActCommandResult {

dist/types/stagehand.d.ts

@@ -24,2 +24,6 @@ import Browserbase from "@browserbasehq/sdk";
     modelClientOptions?: ClientOptions;
+    /**
+     * Instructions for stagehand.
+     */
+    systemPrompt?: string;
 }
@@ -26,0 +30,0 @@ export interface InitOptions {

lib/handlers/actHandler.ts

@@ -26,2 +26,3 @@ import { Locator, Page } from "@playwright/test";
   };
+  private readonly userProvidedInstructions?: string;
 
@@ -34,2 +35,3 @@ constructor({
     stagehandPage,
+    userProvidedInstructions,
   }: {
@@ -43,2 +45,3 @@ verbose: 0 | 1 | 2;
     stagehandContext: StagehandContext;
+    userProvidedInstructions?: string;
   }) {
@@ -52,2 +55,3 @@ this.verbose = verbose;
     this.stagehandPage = stagehandPage;
+    this.userProvidedInstructions = userProvidedInstructions;
   }
@@ -1140,2 +1144,3 @@
         variables,
+        userProvidedInstructions: this.userProvidedInstructions,
       });
@@ -1142,0 +1147,0 @@

lib/handlers/extractHandler.ts

@@ -86,2 +86,3 @@ import { z } from "zod";
   private readonly logger: (logLine: LogLine) => void;
+  private readonly userProvidedInstructions?: string;
 
@@ -92,2 +93,3 @@ constructor({
     stagehandPage,
+    userProvidedInstructions,
   }: {
@@ -102,2 +104,3 @@ stagehand: Stagehand;
     stagehandPage: StagehandPage;
+    userProvidedInstructions?: string;
   }) {
@@ -107,2 +110,3 @@ this.stagehand = stagehand;
     this.stagehandPage = stagehandPage;
+    this.userProvidedInstructions = userProvidedInstructions;
   }
@@ -313,2 +317,3 @@
       requestId,
+      userProvidedInstructions: this.userProvidedInstructions,
       logger: this.logger,
@@ -443,2 +448,3 @@ });
       isUsingTextExtract: false,
+      userProvidedInstructions: this.userProvidedInstructions,
       logger: this.logger,
@@ -445,0 +451,0 @@ });

lib/handlers/observeHandler.ts

@@ -5,5 +5,5 @@ import { LogLine } from "../../types/log";
 import { LLMClient } from "../llm/LLMClient";
+import { StagehandPage } from "../StagehandPage";
 import { generateId } from "../utils";
 import { ScreenshotService } from "../vision";
-import { StagehandPage } from "../StagehandPage";
 
@@ -21,3 +21,3 @@ export class StagehandObserveHandler {
   };
-
+  private readonly userProvidedInstructions?: string;
   constructor({
@@ -27,2 +27,3 @@ stagehand,
     stagehandPage,
+    userProvidedInstructions,
   }: {
@@ -32,2 +33,3 @@ stagehand: Stagehand;
     stagehandPage: StagehandPage;
+    userProvidedInstructions?: string;
   }) {
@@ -37,2 +39,3 @@ this.stagehand = stagehand;
     this.stagehandPage = stagehandPage;
+    this.userProvidedInstructions = userProvidedInstructions;
     this.observations = {};
@@ -128,2 +131,3 @@ }
       requestId,
+      userProvidedInstructions: this.userProvidedInstructions,
       logger: this.logger,
@@ -130,0 +134,0 @@ });

lib/index.ts

@@ -329,2 +329,3 @@ import { Browserbase } from "@browserbasehq/sdk";
   private llmClient: LLMClient;
+  private userProvidedInstructions?: string;
 
@@ -348,2 +349,3 @@ constructor(
       modelClientOptions,
+      systemPrompt,
     }: ConstructorParams = {
@@ -382,2 +384,3 @@ env: "BROWSERBASE",
     this.browserbaseSessionID = browserbaseSessionID;
+    this.userProvidedInstructions = systemPrompt;
   }
@@ -456,2 +459,3 @@
       this.llmClient,
+      this.userProvidedInstructions,
     ).init();
@@ -629,2 +633,2 @@
 export * from "../types/page";
-export { LLMClient } from "./llm/LLMClient";
+export * from "./llm/LLMClient";

lib/inference.ts

@@ -107,5 +107,6 @@ import { z } from "zod";
   variables,
+  userProvidedInstructions,
 }: ActCommandParams): Promise<ActCommandResult | null> {
   const messages: ChatMessage[] = [
-    buildActSystemPrompt(),
+    buildActSystemPrompt(userProvidedInstructions),
     buildActUserPrompt(action, steps, domElements, variables),
@@ -171,2 +172,3 @@ ];
   isUsingTextExtract,
+  userProvidedInstructions,
 }: {
@@ -182,2 +184,3 @@ instruction: string;
   isUsingTextExtract?: boolean;
+  userProvidedInstructions?: string;
   logger: (message: LogLine) => void;
@@ -193,3 +196,7 @@ }) {
       messages: [
-        buildExtractSystemPrompt(isUsingAnthropic, isUsingTextExtract),
+        buildExtractSystemPrompt(
+          isUsingAnthropic,
+          isUsingTextExtract,
+          userProvidedInstructions,
+        ),
         buildExtractUserPrompt(instruction, domElements, isUsingAnthropic),
@@ -284,2 +291,3 @@ ],
   requestId,
+  userProvidedInstructions,
   logger,
@@ -292,2 +300,3 @@ }: {
   requestId: string;
+  userProvidedInstructions?: string;
   logger: (message: LogLine) => void;
@@ -318,3 +327,3 @@ }): Promise<{
         messages: [
-          buildObserveSystemPrompt(),
+          buildObserveSystemPrompt(userProvidedInstructions),
           buildObserveUserMessage(instruction, domElements),
@@ -337,3 +346,2 @@ ],
     });
-
   const parsedResponse = {
@@ -340,0 +348,0 @@ elements:

lib/llm/AnthropicClient.ts

@@ -30,2 +30,3 @@ import Anthropic, { ClientOptions } from "@anthropic-ai/sdk";
     clientOptions,
+    userProvidedInstructions,
   }: {
@@ -37,2 +38,3 @@ logger: (message: LogLine) => void;
     clientOptions?: ClientOptions;
+    userProvidedInstructions?: string;
   }) {
@@ -45,2 +47,3 @@ super(modelName);
     this.clientOptions = clientOptions;
+    this.userProvidedInstructions = userProvidedInstructions;
   }
@@ -67,2 +70,3 @@
     });
+
     // Try to get cached response
@@ -69,0 +73,0 @@ const cacheOptions = {

lib/llm/LLMClient.ts

@@ -97,6 +97,8 @@ import { ZodType } from "zod";
   public clientOptions: ClientOptions;
+  public userProvidedInstructions?: string;
 
-  constructor(modelName: AvailableModel) {
+  constructor(modelName: AvailableModel, userProvidedInstructions?: string) {
     this.modelName = modelName;
     this.hasVision = modelsWithVision.includes(modelName);
+    this.userProvidedInstructions = userProvidedInstructions;
   }
@@ -103,0 +105,0 @@

lib/prompt.ts

@@ -15,2 +15,3 @@ import { LLMTool } from "../types/llm";
 4. Optionally, a list of variable names that the user has provided that you may use to accomplish the goal. To use the variables, you must use the special <|VARIABLE_NAME|> syntax.
+5. Optionally, custom instructions will be provided by the user. If the user's instructions are not relevant to the current task, ignore them. Otherwise, make sure to adhere to them.
 
@@ -25,3 +26,3 @@
 
-Again, if the user's goal will be accomplished after running the playwright action, set completed to true.
+Again, if the user's goal will be accomplished after running the playwright action, set completed to true. Also, if the user provides custom instructions, it is imperative that you follow them no matter what.
 `;
@@ -101,6 +102,28 @@
 
-export function buildActSystemPrompt(): ChatMessage {
+export function buildUserInstructionsString(
+  userProvidedInstructions?: string,
+): string {
+  if (!userProvidedInstructions) {
+    return "";
+  }
+
+  return `\n\n# Custom Instructions Provided by the User
+    
+Please keep the user's instructions in mind when performing actions. If the user's instructions are not relevant to the current task, ignore them.
+
+User Instructions:
+${userProvidedInstructions}`;
+}
+
+export function buildActSystemPrompt(
+  userProvidedInstructions?: string,
+): ChatMessage {
   return {
     role: "system",
-    content: actSystemPrompt,
+    content: [
+      actSystemPrompt,
+      buildUserInstructionsString(userProvidedInstructions),
+    ]
+      .filter(Boolean)
+      .join("\n\n"),
   };
@@ -205,2 +228,3 @@ }
   useTextExtract: boolean = true,
+  userProvidedInstructions?: string,
 ): ChatMessage {
@@ -239,6 +263,10 @@ const baseContent = `You are extracting content on behalf of a user.
 
+  const userInstructions = buildUserInstructionsString(
+    userProvidedInstructions,
+  );
+
   const content =
     `${baseContent}${contentDetail}\n\n${instructions}\n${toolInstructions}${
       additionalInstructions ? `\n\n${additionalInstructions}` : ""
-    }`.replace(/\s+/g, " ");
+    }${userInstructions ? `\n\n${userInstructions}` : ""}`.replace(/\s+/g, " ");
 
@@ -340,3 +368,5 @@ return {
 `;
-export function buildObserveSystemPrompt(): ChatMessage {
+export function buildObserveSystemPrompt(
+  userProvidedInstructions?: string,
+): ChatMessage {
   const content = observeSystemPrompt.replace(/\s+/g, " ");
@@ -346,3 +376,5 @@
     role: "system",
-    content,
+    content: [content, buildUserInstructionsString(userProvidedInstructions)]
+      .filter(Boolean)
+      .join("\n\n"),
   };
@@ -349,0 +381,0 @@ }

lib/StagehandPage.ts

@@ -34,2 +34,3 @@ import type {
     llmClient: LLMClient,
+    userProvidedInstructions?: string,
   ) {
@@ -70,2 +71,3 @@ this.intPage = Object.assign(page, {
         llmClient: llmClient,
+        userProvidedInstructions,
       });
@@ -76,2 +78,3 @@ this.extractHandler = new StagehandExtractHandler({
         stagehandPage: this,
+        userProvidedInstructions,
       });
@@ -82,2 +85,3 @@ this.observeHandler = new StagehandObserveHandler({
         stagehandPage: this,
+        userProvidedInstructions,
       });
@@ -84,0 +88,0 @@ }

package.json

 {
   "name": "@browserbasehq/stagehand",
-  "version": "1.9.1-alpha-2cee0a45ae2b48d1de6543b196e338e7021e59fe",
+  "version": "1.10.0-alpha-04555d47673eacf8764c78d99034ca93bea960c6",
   "description": "An AI web browsing framework focused on simplicity and extensibility.",
@@ -14,2 +14,3 @@ "main": "./dist/index.js",
     "external-client": "npm run build-dom-scripts && tsx examples/external_client.ts",
+    "instructions": "npm run build-dom-scripts && tsx examples/instructions.ts",
     "ai-sdk-client": "npm run build-dom-scripts && tsx examples/ai_sdk_example.ts",
@@ -16,0 +17,0 @@ "format": "prettier --write .",

No alert changes

Improved metrics

Total package byte prevSize

555482

increased by1.33%

Number of package files

163

increased by1.24%

Lines of code

14748

increased by0.98%

No dependency changes