@stablyai/playwright-base 0.2.1 → 1.0.0

package/dist/index.d.ts

@@ -1,25 +1,89 @@
-import * as _stablyai_internal_playwright_test from '@stablyai/internal-playwright-test';
-import { Browser, BrowserContext, BrowserType, Locator, Page, MatcherReturnType } from '@stablyai/internal-playwright-test';
+import * as _playwright_test from '@playwright/test';
+import { BrowserContext, Page, Locator, MatcherReturnType, Browser, BrowserType } from '@playwright/test';
 import * as z4 from 'zod/v4/core';
 
+type AnthropicModel = "anthropic/claude-sonnet-4-5-20250929";
+type GeminiModel = "google/gemini-2.5-computer-use-preview-10-2025";
+type Model = AnthropicModel | GeminiModel | (string & {});
+
+/**
+ * Options for configuring agent behavior during execution.
+ */
+type AgentActOptions = {
+    /**
+     * The page the agent will operate on.
+     */
+    page: Page;
+    /**
+     * Maximum number of thinking cycles the agent can perform.
+     * Each cycle includes observing the page, planning, and executing one or more actions.
+     * @default 30
+     */
+    maxCycles?: number;
+    /**
+     * AI model to use for agent reasoning.
+     * Different models may have different capabilities and performance characteristics.
+     */
+    model?: Model;
+};
+/**
+ * AI agent for automating browser interactions using natural language.
+ *
+ * The Agent can perform complex browser actions by interpreting natural language instructions.
+ * It observes the page state, makes decisions, and executes actions autonomously.
+ *
+ * Agents are created via {@link BrowserContext.newAgent} or {@link Browser.newAgent}.
+ *
+ * @example
+ * ```typescript
+ * const agent = context.newAgent();
+ * await agent.act('Fill out the login form and submit', { page });
+ * ```
+ */
+declare class Agent {
+    readonly browserContext: BrowserContext;
+    constructor(browserContext: BrowserContext);
+    /**
+     * Instructs the agent to perform actions on the page using natural language.
+     *
+     * The agent will analyze the page, plan actions, and execute them autonomously.
+     * It can perform multiple actions such as clicking, typing, navigating, and verifying
+     * page state based on the provided instruction.
+     *
+     * @param prompt - Natural language instruction describing what the agent should do
+     * @param options - Configuration for the agent's behavior including the page to operate on
+     * @returns Promise that resolves with the result of the agent's actions
+     *
+     * @example
+     * ```typescript
+     * // Simple action
+     * await agent.act('Click the login button', { page });
+     *
+     * // Complex multi-step action
+     * await agent.act('Navigate to settings, enable notifications, and save changes', { page });
+     *
+     * // With custom options
+     * const result = await agent.act('Complete the checkout process', {
+     *   page,
+     *   maxCycles: 20,
+     *   model: 'gpt-4'
+     * });
+     *
+     * if (result.success) {
+     *   console.log('Agent completed the task successfully');
+     * }
+     * ```
+     */
+    act(prompt: string, options: AgentActOptions): Promise<{
+        success: boolean;
+    }>;
+}
+
 type ExtractSchema = {
     safeParseAsync(data: unknown, params?: z4.ParseContext<z4.$ZodIssue>): Promise<z4.util.SafeParseResult<z4.output<any>>>;
 } & z4.$ZodType;
 type SchemaOutput<T extends ExtractSchema> = z4.output<T>;
 
-type LocatorDescribeOptions = {
-    autoHeal?: boolean;
-};
-declare function augmentLocator<T extends Locator>(locator: T): T;
-declare function augmentPage<T extends Page>(page: T): T;
-declare function augmentBrowserContext<T extends BrowserContext>(context: T): T;
-declare function augmentBrowser<T extends Browser>(browser: T): T;
-declare function augmentBrowserType<TBrowser extends Browser>(browserType: BrowserType<TBrowser>): BrowserType<TBrowser>;
-
-type AnthropicModel = "anthropic/claude-sonnet-4-5-20250929";
-type GeminiModel = "google/gemini-2.5-computer-use-preview-10-2025";
-type Model = AnthropicModel | GeminiModel | string;
-
 type MatcherContext = {
     isNot: boolean;
     message?: () => string;
@@ -28,15 +92,21 @@ declare const stablyPlaywrightMatchers: {
     readonly toMatchScreenshotPrompt: (this: MatcherContext, received: Page | Locator, condition: string, options?: ScreenshotPromptOptions) => Promise<MatcherReturnType>;
 };
 
+declare function augmentLocator<T extends Locator>(locator: T): T;
+declare function augmentPage<T extends Page>(page: T): T;
+declare function augmentBrowserContext<T extends BrowserContext>(context: T): T;
+declare function augmentBrowser<T extends Browser>(browser: T): T;
+declare function augmentBrowserType<TBrowser extends Browser>(browserType: BrowserType<TBrowser>): BrowserType<TBrowser>;
+
 declare function setApiKey(apiKey: string): void;
 declare function requireApiKey(): string;
 
-type ScreenshotPromptOptions = _stablyai_internal_playwright_test.PageAssertionsToHaveScreenshotOptions;
+type ScreenshotPromptOptions = _playwright_test.PageAssertionsToHaveScreenshotOptions;
 
 type Expect<T = Page> = {
     toMatchScreenshotPrompt(condition: string, options?: ScreenshotPromptOptions): Promise<void>;
 };
-declare module "@stablyai/internal-playwright-test" {
+declare module "@playwright/test" {
     interface Locator {
         /**
          * Extracts information from this locator using Stably AI.
@@ -63,7 +133,6 @@ declare module "@stablyai/internal-playwright-test" {
         extract<T extends ExtractSchema>(prompt: string, options: {
             schema: T;
         }): Promise<SchemaOutput<T>>;
-        describe(description: string, options?: LocatorDescribeOptions): Locator;
     }
     interface Page {
         /**
@@ -93,23 +162,61 @@ declare module "@stablyai/internal-playwright-test" {
         }): Promise<SchemaOutput<T>>;
     }
     interface BrowserContext {
-        agent(prompt: string, options: {
-            page: Page;
-            maxCycles?: number;
-            model?: Model;
-        }): Promise<{
-            success: boolean;
-        }>;
+        /**
+         * Creates a new AI agent instance for automating browser interactions.
+         *
+         * An agent can perform complex browser actions by interpreting natural language instructions.
+         * It observes the page, makes autonomous decisions, and executes actions like clicking,
+         * typing, navigating, and verifying page state.
+         *
+         * The agent operates within this browser context and can interact with all pages in the context.
+         * Use the returned agent's [agent.act(prompt, options)](#agent-act) method to give instructions.
+         * The page to operate on is specified when calling `act()`.
+         *
+         * **Usage**
+         *
+         * ```js
+         * const context = await browser.newContext();
+         * const page = await context.newPage();
+         * await page.goto('https://example.com');
+         *
+         * // Create an agent for this context
+         * const agent = context.newAgent();
+         *
+         * // Give the agent natural language instructions with the page to operate on
+         * await agent.act('Click the login button and enter credentials', { page });
+         * ```
+         */
+        newAgent(): Agent;
     }
     interface Browser {
-        agent(prompt: string, options: {
-            page: Page;
-            maxCycles?: number;
-            model?: Model;
-        }): Promise<{
-            success: boolean;
-        }>;
+        /**
+         * Creates a new AI agent instance for automating browser interactions.
+         *
+         * An agent can perform complex browser actions by interpreting natural language instructions.
+         * It observes the page, makes autonomous decisions, and executes actions like clicking,
+         * typing, navigating, and verifying page state.
+         *
+         * The agent operates within a browser context and can interact with all pages in that context.
+         * Use the returned agent's [agent.act(prompt, options)](#agent-act) method to give instructions.
+         * The page to operate on is specified when calling `act()`.
+         *
+         * **Usage**
+         *
+         * ```js
+         * const browser = await chromium.launch();
+         * const page = await browser.newPage();
+         * await page.goto('https://example.com');
+         *
+         * // Create an agent
+         * const agent = browser.newAgent();
+         *
+         * // Give the agent natural language instructions with the page to operate on
+         * await agent.act('Fill out the registration form and submit', { page });
+         * ```
+         */
+        newAgent(): Agent;
     }
 }
 
-export { type Expect, type ExtractSchema, type LocatorDescribeOptions, type SchemaOutput, type ScreenshotPromptOptions, augmentBrowser, augmentBrowserContext, augmentBrowserType, augmentLocator, augmentPage, requireApiKey, setApiKey, stablyPlaywrightMatchers };
+export { Agent, type Expect, type ExtractSchema, type SchemaOutput, type ScreenshotPromptOptions, augmentBrowser, augmentBrowserContext, augmentBrowserType, augmentLocator, augmentPage, requireApiKey, setApiKey, stablyPlaywrightMatchers };

package/dist/index.mjs

@@ -6,7 +6,7 @@ var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require
 });
 
 // src/expect.ts
-import { test } from "@stablyai/internal-playwright-test";
+import { test } from "@playwright/test";
 
 // src/runtime.ts
 var configuredApiKey = process.env.STABLY_API_KEY;
@@ -34,11 +34,16 @@ var isObject = (value) => {
 // src/ai/metadata.ts
 var SDK_METADATA_HEADERS = {
   "X-Client-Name": "stably-playwright-sdk-js",
-  "X-Client-Version": "0.2.1"
+  "X-Client-Version": "1.0.0-next.1"
 };
 
 // src/ai/verify-prompt.ts
-var PROMPT_ASSERTION_ENDPOINT = "https://api.stably.ai/internal/v1/assert";
+var PROMPT_ASSERTION_PATH = "internal/v1/assert";
+var STABLY_API_URL = process.env.STABLY_API_URL || "https://api.stably.ai";
+var PROMPT_ASSERTION_ENDPOINT = new URL(
+  PROMPT_ASSERTION_PATH,
+  STABLY_API_URL
+).toString();
 var parseSuccessResponse = (value) => {
   if (!isObject(value)) {
     throw new Error("Verify prompt returned unexpected response shape");
@@ -413,7 +418,7 @@ var stablyPlaywrightMatchers = {
 };
 
 // src/playwright-augment/methods/agent.ts
-import { test as test2 } from "@stablyai/internal-playwright-test";
+import { test as test2 } from "@playwright/test";
 
 // src/utils/truncate.ts
 var truncate = (inp, length) => inp.length <= length || inp.length <= 3 ? inp : `${inp.slice(0, length - 3)}...`;
@@ -621,16 +626,48 @@ ${ariaSnapshot}` }
 
 // src/playwright-augment/methods/agent.ts
 var AGENT_PATH = "internal/v3/agent";
-var STABLY_API_URL = process.env.STABLY_API_URL || "https://api.stably.ai";
-var AGENT_ENDPOINT = new URL(AGENT_PATH, STABLY_API_URL).toString();
-function createAgentStub() {
-  let thoughtsIndex = 0;
-  return async (prompt, options) => {
+var STABLY_API_URL2 = process.env.STABLY_API_URL || "https://api.stably.ai";
+var AGENT_ENDPOINT = new URL(AGENT_PATH, STABLY_API_URL2).toString();
+var Agent = class {
+  constructor(browserContext) {
+    this.browserContext = browserContext;
+  }
+  /**
+   * Instructs the agent to perform actions on the page using natural language.
+   *
+   * The agent will analyze the page, plan actions, and execute them autonomously.
+   * It can perform multiple actions such as clicking, typing, navigating, and verifying
+   * page state based on the provided instruction.
+   *
+   * @param prompt - Natural language instruction describing what the agent should do
+   * @param options - Configuration for the agent's behavior including the page to operate on
+   * @returns Promise that resolves with the result of the agent's actions
+   *
+   * @example
+   * ```typescript
+   * // Simple action
+   * await agent.act('Click the login button', { page });
+   *
+   * // Complex multi-step action
+   * await agent.act('Navigate to settings, enable notifications, and save changes', { page });
+   *
+   * // With custom options
+   * const result = await agent.act('Complete the checkout process', {
+   *   page,
+   *   maxCycles: 20,
+   *   model: 'gpt-4'
+   * });
+   *
+   * if (result.success) {
+   *   console.log('Agent completed the task successfully');
+   * }
+   * ```
+   */
+  async act(prompt, options) {
     const apiKey = requireApiKey();
     const maxCycles = options.maxCycles ?? 30;
-    const browserContext = options.page.context();
     const tabManager = /* @__PURE__ */ new Map();
-    browserContext.pages().forEach((page, index) => {
+    this.browserContext.pages().forEach((page, index) => {
       tabManager.set(page, `page${index + 1}`);
     });
     let activePage = options.page;
@@ -653,14 +690,14 @@ function createAgentStub() {
       const alias = tabManager.get(page);
       newPageOpenedMsg = `opened new tab ${alias} (${page.url()})`;
     };
-    browserContext.on("page", onNewPage);
+    this.browserContext.on("page", onNewPage);
     return await test2.step(`[Agent] ${prompt}`, async () => {
       try {
         for (let i = 0; i < maxCycles; i++) {
           if (agentMessage.shouldTerminate) {
             break;
           }
-          const agentResponses = await test2.step(`[Thinking ${thoughtsIndex + 1}]`, async (stepInfo) => {
+          const agentResponses = await test2.step(`[Thinking ${i + 1}]`, async (stepInfo) => {
             const screenshot = await takeStableScreenshot(activePage);
             const response = await fetch(AGENT_ENDPOINT, {
               body: constructAgentPayload({
@@ -690,13 +727,12 @@ function createAgentStub() {
             const reasoningText = reasoningTexts.join("\n\n");
             const truncatedReasoningText = truncate(reasoningText, 120);
             await stepInfo.attach(
-              `[Thinking ${thoughtsIndex + 1}] ${truncatedReasoningText}`,
+              `[Thinking ${i + 1}] ${truncatedReasoningText}`,
               {
                 body: reasoningText,
                 contentType: "text/plain"
               }
             );
-            thoughtsIndex++;
             return responseJson;
           });
           let combinedMessages = [];
@@ -710,7 +746,7 @@ function createAgentStub() {
             } = await execResponse({
               activePage,
               agentResponse,
-              browserContext,
+              browserContext: this.browserContext,
               tabManager
             });
             activePage = newActivePage;
@@ -731,17 +767,19 @@ function createAgentStub() {
           };
         }
       } finally {
-        browserContext.off("page", onNewPage);
+        this.browserContext.off("page", onNewPage);
       }
       return { success: finalSuccess ?? false };
     });
-  };
-}
+  }
+};
+var createNewAgent = (browserContext) => new Agent(browserContext);
 
 // src/ai/extract.ts
+import { test as test3 } from "@playwright/test";
 var EXTRACT_PATH = "internal/v2/extract";
-var STABLY_API_URL2 = process.env.STABLY_API_URL || "https://api.stably.ai";
-var EXTRACT_ENDPOINT = new URL(EXTRACT_PATH, STABLY_API_URL2).toString();
+var STABLY_API_URL3 = process.env.STABLY_API_URL || "https://api.stably.ai";
+var EXTRACT_ENDPOINT = new URL(EXTRACT_PATH, STABLY_API_URL3).toString();
 var zodV4 = (() => {
   try {
     return __require("zod/v4/core");
@@ -771,7 +809,10 @@ var ExtractValidationError = class extends Error {
 async function validateWithSchema(schema, value) {
   const result = await schema.safeParseAsync(value);
   if (!result.success) {
-    throw new ExtractValidationError("Validation failed", result.error.issues);
+    throw new ExtractValidationError(
+      "AI is unable to return the data in the desired format",
+      result.error.issues
+    );
   }
   return result.data;
 }
@@ -789,36 +830,47 @@ async function extract({
     // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
     schema
   ) : void 0;
-  const apiKey = requireApiKey();
-  const form = new FormData();
-  form.append("prompt", prompt);
-  if (jsonSchema) {
-    form.append("jsonSchema", JSON.stringify(jsonSchema));
-  }
-  const pngBuffer = await pageOrLocator.screenshot({ type: "png" });
-  const u8 = Uint8Array.from(pngBuffer);
-  const blob = new Blob([u8], { type: "image/png" });
-  form.append("image", blob, "screenshot.png");
-  const response = await fetch(EXTRACT_ENDPOINT, {
-    body: form,
-    headers: {
-      ...SDK_METADATA_HEADERS,
-      Authorization: `Bearer ${apiKey}`
-    },
-    method: "POST"
-  });
-  const raw = await response.json().catch(() => void 0);
-  if (response.ok) {
-    if (!isExtractionResponse(raw)) {
-      throw new Error("Extract returned unexpected response shape");
+  return await test3.step(`[Extract] ${prompt}`, async (stepInfo) => {
+    const apiKey = requireApiKey();
+    const form = new FormData();
+    form.append("prompt", prompt);
+    if (jsonSchema) {
+      form.append("jsonSchema", JSON.stringify(jsonSchema));
     }
-    if (!raw.success) {
-      throw new Error(`Extract failed: ${raw.error}`);
+    const pngBuffer = await pageOrLocator.screenshot({ type: "png" });
+    const u8 = Uint8Array.from(pngBuffer);
+    const blob = new Blob([u8], { type: "image/png" });
+    form.append("image", blob, "screenshot.png");
+    const response = await fetch(EXTRACT_ENDPOINT, {
+      body: form,
+      headers: {
+        ...SDK_METADATA_HEADERS,
+        Authorization: `Bearer ${apiKey}`
+      },
+      method: "POST"
+    });
+    const raw = await response.json().catch(() => void 0);
+    if (response.ok) {
+      if (!isExtractionResponse(raw)) {
+        throw new Error("Extract returned unexpected response shape");
+      }
+      if (!raw.success) {
+        await stepInfo.attach("[Extract] error", {
+          body: raw.error,
+          contentType: "text/plain"
+        });
+        throw new Error(`Extract failed: ${raw.error}`);
+      }
+      const { value } = raw;
+      const body = typeof value === "string" ? value : JSON.stringify(value, null, 2);
+      await stepInfo.attach("[Extract] result", {
+        body,
+        contentType: "text/plain"
+      });
+      return schema ? await validateWithSchema(schema, value) : typeof value === "string" ? value : JSON.stringify(value);
     }
-    const { value } = raw;
-    return schema ? await validateWithSchema(schema, value) : typeof value === "string" ? value : JSON.stringify(value);
-  }
-  throw new Error(isErrorResponse(raw) ? raw.error : "Extract failed");
+    throw new Error(isErrorResponse(raw) ? raw.error : "Extract failed");
+  });
 }
 
 // src/playwright-augment/methods/extract.ts
@@ -840,9 +892,6 @@ var createPageExtract = (page) => createExtract(page);
 
 // src/playwright-augment/augment.ts
 var LOCATOR_PATCHED = Symbol.for("stably.playwright.locatorPatched");
-var LOCATOR_DESCRIBE_WRAPPED = Symbol.for(
-  "stably.playwright.locatorDescribeWrapped"
-);
 var PAGE_PATCHED = Symbol.for("stably.playwright.pagePatched");
 var CONTEXT_PATCHED = Symbol.for("stably.playwright.contextPatched");
 var BROWSER_PATCHED = Symbol.for("stably.playwright.browserPatched");
@@ -860,15 +909,6 @@ function augmentLocator(locator) {
     return locator;
   }
   defineHiddenProperty(locator, "extract", createLocatorExtract(locator));
-  const markerTarget = locator;
-  if (typeof locator.describe === "function" && !markerTarget[LOCATOR_DESCRIBE_WRAPPED]) {
-    const originalDescribe = locator.describe.bind(locator);
-    locator.describe = (description, options) => {
-      const result = originalDescribe(description, options);
-      return result ? augmentLocator(result) : result;
-    };
-    defineHiddenProperty(locator, LOCATOR_DESCRIBE_WRAPPED, true);
-  }
   defineHiddenProperty(locator, LOCATOR_PATCHED, true);
   return locator;
 }
@@ -896,13 +936,12 @@ function augmentBrowserContext(context) {
   };
   const originalPages = context.pages?.bind(context);
   if (originalPages) {
-    context.pages = () => originalPages().map(
-      (page) => augmentPage(page)
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    );
+    context.pages = () => originalPages().map((page) => augmentPage(page));
   }
-  if (!context.agent) {
-    defineHiddenProperty(context, "agent", createAgentStub());
+  if (!context.newAgent) {
+    defineHiddenProperty(context, "newAgent", () => {
+      return createNewAgent(context);
+    });
   }
   defineHiddenProperty(context, CONTEXT_PATCHED, true);
   return context;
@@ -924,10 +963,13 @@ function augmentBrowser(browser) {
   const originalContexts = browser.contexts.bind(browser);
   browser.contexts = () => originalContexts().map(
     (context) => augmentBrowserContext(context)
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
   );
-  if (!browser.agent) {
-    defineHiddenProperty(browser, "agent", createAgentStub());
+  if (!browser.newAgent) {
+    defineHiddenProperty(browser, "newAgent", () => {
+      const contexts = browser.contexts();
+      const context = contexts.length > 0 ? contexts[0] : browser.contexts()[0];
+      return createNewAgent(context);
+    });
   }
   defineHiddenProperty(browser, BROWSER_PATCHED, true);
   return browser;
@@ -957,10 +999,7 @@ function augmentBrowserType(browserType) {
       return augmentBrowser(browser);
     };
   }
-  const originalLaunchPersistentContext = (
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    browserType.launchPersistentContext?.bind(browserType)
-  );
+  const originalLaunchPersistentContext = browserType.launchPersistentContext?.bind(browserType);
   if (originalLaunchPersistentContext) {
     browserType.launchPersistentContext = async (...args) => {
       const context = await originalLaunchPersistentContext(...args);
@@ -971,6 +1010,7 @@ function augmentBrowserType(browserType) {
   return browserType;
 }
 export {
+  Agent,
   augmentBrowser,
   augmentBrowserContext,
   augmentBrowserType,