@stablyai/playwright-base 0.2.1 → 1.0.0

package/dist/index.cjs

@@ -30,6 +30,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  Agent: () => Agent,
   augmentBrowser: () => augmentBrowser,
   augmentBrowserContext: () => augmentBrowserContext,
   augmentBrowserType: () => augmentBrowserType,
@@ -42,7 +43,7 @@ __export(index_exports, {
 module.exports = __toCommonJS(index_exports);
 
 // src/expect.ts
-var import_internal_playwright_test = require("@stablyai/internal-playwright-test");
+var import_test = require("@playwright/test");
 
 // src/runtime.ts
 var configuredApiKey = process.env.STABLY_API_KEY;
@@ -70,11 +71,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");
@@ -417,7 +423,7 @@ var stablyPlaywrightMatchers = {
     const targetType = isPage(target) ? "page" : "locator";
     const screenshot = await takeStableScreenshot(target, options);
     const verifyResult = await verifyPrompt({ prompt: condition, screenshot });
-    const testInfo = import_internal_playwright_test.test.info();
+    const testInfo = import_test.test.info();
     testInfo.attachments.push({
       body: Buffer.from(
         JSON.stringify(
@@ -449,7 +455,7 @@ var stablyPlaywrightMatchers = {
 };
 
 // src/playwright-augment/methods/agent.ts
-var import_internal_playwright_test2 = require("@stablyai/internal-playwright-test");
+var import_test2 = require("@playwright/test");
 
 // src/utils/truncate.ts
 var truncate = (inp, length) => inp.length <= length || inp.length <= 3 ? inp : `${inp.slice(0, length - 3)}...`;
@@ -657,16 +663,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;
@@ -689,14 +727,14 @@ function createAgentStub() {
       const alias = tabManager.get(page);
       newPageOpenedMsg = `opened new tab ${alias} (${page.url()})`;
     };
-    browserContext.on("page", onNewPage);
-    return await import_internal_playwright_test2.test.step(`[Agent] ${prompt}`, async () => {
+    this.browserContext.on("page", onNewPage);
+    return await import_test2.test.step(`[Agent] ${prompt}`, async () => {
       try {
         for (let i = 0; i < maxCycles; i++) {
           if (agentMessage.shouldTerminate) {
             break;
           }
-          const agentResponses = await import_internal_playwright_test2.test.step(`[Thinking ${thoughtsIndex + 1}]`, async (stepInfo) => {
+          const agentResponses = await import_test2.test.step(`[Thinking ${i + 1}]`, async (stepInfo) => {
             const screenshot = await takeStableScreenshot(activePage);
             const response = await fetch(AGENT_ENDPOINT, {
               body: constructAgentPayload({
@@ -726,13 +764,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 = [];
@@ -746,7 +783,7 @@ function createAgentStub() {
             } = await execResponse({
               activePage,
               agentResponse,
-              browserContext,
+              browserContext: this.browserContext,
               tabManager
             });
             activePage = newActivePage;
@@ -767,17 +804,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
+var import_test3 = require("@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");
@@ -807,7 +846,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;
 }
@@ -825,36 +867,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 import_test3.test.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
@@ -876,9 +929,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");
@@ -896,15 +946,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;
 }
@@ -932,13 +973,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;
@@ -960,10 +1000,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;
@@ -993,10 +1036,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);
@@ -1008,6 +1048,7 @@ function augmentBrowserType(browserType) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  Agent,
   augmentBrowser,
   augmentBrowserContext,
   augmentBrowserType,