donobu 2.51.0 → 3.0.0

package/dist/esm/lib/DonobuExtendedPage.d.ts

@@ -1,88 +1,85 @@
-import { Page } from 'playwright-core';
-import { ToolCallResult } from '../models/ToolCallResult';
-import { GptClient } from '../clients/GptClient';
-import { LanguageModel } from 'ai';
-import { AnalyzePageTextCoreParameters } from '../tools/AnalyzePageTextTool';
-import { FlowMetadata } from '../models/FlowMetadata';
-import { AssertPageTextCoreParameters } from '../tools/AssertPageTextTool';
-import { AssertCoreSchema } from '../tools/AssertTool';
-import { ChooseSelectOptionNonGptSchema } from '../tools/ChooseSelectOptionTool';
-import { InputRandomizedEmailAddressNonGptSchema } from '../tools/InputRandomizedEmailAddressTool';
-import { InputTextNonGptSchema } from '../tools/InputTextTool';
-import { PressKeyNonGptSchema } from '../tools/PressKeyTool';
-import { ScrollPageNonGptSchema } from '../tools/ScrollPageTool';
-import { SelectorBasedSchema } from '../tools/ReplayableInteraction';
-import { z } from 'zod/v4';
-import { BrowserStorageState } from '../models/BrowserStorageState';
-import { SmartSelector } from './SmartSelector';
-import { PageAi, PageAiOptions } from './PageAi';
-import { DonobuStack } from '../managers/DonobuStack';
-import { FlowsPersistence } from '../persistence/flows/FlowsPersistence';
-export { PageAiOptions };
+import type { LanguageModel } from 'ai';
+import type { Page } from 'playwright-core';
+import type { z } from 'zod/v4';
+import type { GptClient } from '../clients/GptClient';
+import type { DonobuStack } from '../managers/DonobuStack';
+import type { InteractionVisualizer } from '../managers/InteractionVisualizer';
+import type { BrowserStorageState } from '../models/BrowserStorageState';
+import type { FlowMetadata } from '../models/FlowMetadata';
+import type { ToolCallResult } from '../models/ToolCallResult';
+import type { FlowsPersistence } from '../persistence/flows/FlowsPersistence';
+import type { CookieAnalyses } from '../tools/CreateBrowserCookieReportTool';
+import type { AccessibilityResults } from '../tools/RunAccessibilityTestTool';
+import type { PageAi, PageAiNoSchemaOptions, PageAiOptions, PageAiSchemaOptions } from './PageAi';
+import type { SmartSelector } from './SmartSelector';
+export type { PageAiNoSchemaOptions, PageAiOptions, PageAiSchemaOptions };
 /**
  * Extends the Page object with additional test-related methods.
  */
 export interface DonobuExtendedPage extends Page {
-    /**
-     * Launches an autonomous Donobu flow that uses AI to satisfy a natural-language instruction.
-     * The flow may call Donobu tools and mirrors the metadata recorded for the surrounding test run.
-     *
-     * Provide a Zod schema when you want the flow to produce structured output; the AI's response is
-     * validated against the schema and is returned as the result.
-     *
-     * @template T The Zod object schema describing the expected shape of the AI result.
-     * @param instruction High-level description of what the autonomous flow should accomplish.
-     * @returns The parsed schema result when a schema is provided; otherwise, void.
-     * @throws PageAiException if the autonomous flow fails or reaches a terminal non-success state.
-     */
-    ai<Schema extends z.ZodObject | undefined = undefined>(instruction: string, options?: PageAiOptions<Schema>): Promise<Schema extends z.ZodObject ? z.infer<Schema> : void>;
-    /**
-     * Run an arbitrary Donobu tool by name.
-     */
-    run(toolName: string, toolParams?: any, gptClientOverride?: GptClient | LanguageModel): Promise<ToolCallResult>;
-    /**
-     * Run an analysis on the current webpage's full raw text. Note that since this runs an analysis on the raw text,
-     * rather than, the HTML of the page, the raw text may be a bit jumbled, have its styling lost, careful
-     * positioning lost, etc. This tool is useful if there happens to be a lot of text on a page, and it would be
-     * tedious to scroll through the entirety of the page in order to get enough context to run an analysis.
-     *
-     * If there is context relevant to running the analysis that would not be found in the webpage text itself,
-     * perhaps context given in another message, prompt, overall object, etc, then provide it in the
-     * "additionalRelevantContext" parameter.
-     */
-    analyzePageText(params: z.infer<typeof AnalyzePageTextCoreParameters>, gptClientOverride?: GptClient | LanguageModel): Promise<ToolCallResult>;
-    /**
-     * Assert that given text is visible in the current page.
-     */
-    assertPageText(params: z.infer<typeof AssertPageTextCoreParameters>, gptClientOverride?: GptClient | LanguageModel): Promise<ToolCallResult>;
-    /**
-     * Checks all of the pages in the current browser context and returns the one
-     * matching the given URL.
-     */
-    changeTab(url: string): Promise<DonobuExtendedPage>;
-    /**
-     * Choose <option> values for a particular <select> HTML element.
-     */
-    chooseSelectOption(params: z.infer<typeof ChooseSelectOptionNonGptSchema>): Promise<ToolCallResult>;
-    /**
-     * Click an element on a webpage.
-     */
-    clickElement(params: z.infer<typeof SelectorBasedSchema>): Promise<ToolCallResult>;
-    /**
-     * Perform an analysis of the cookies for the current web browsing session.
-     */
-    createCookieReport(gptClientOverride?: GptClient | LanguageModel): Promise<ToolCallResult>;
-    /**
-     * Return an object conforming to the given Zod schema. The object will be
-     * generated considering the following:
-     * - The given instruction (if any).
-     * - A screenshot of the current state of the page.
-     * - The history of actions taken on the page.
-     */
-    extract<T>(params: {
-        instruction?: string;
-        schema: z.ZodSchema<T>;
-    }, gptClientOverride?: GptClient | LanguageModel): Promise<T>;
+    ai: {
+        /**
+         * Launches an autonomous Donobu flow that uses AI to satisfy a natural-language instruction.
+         * The flow may call Donobu tools and mirrors the metadata recorded for the surrounding test run.
+         *
+         * Provide a Zod schema when you want the flow to produce structured output; the AI's response is
+         * validated against the schema and is returned as the result.
+         *
+         * @template Schema The Zod object schema describing the expected shape of the AI result.
+         * @param instruction High-level description of what the autonomous flow should accomplish.
+         * @returns The parsed schema result when a schema is provided; otherwise, void.
+         * @throws PageAiException if the autonomous flow fails or reaches a terminal non-success state.
+         */
+        act<Schema extends z.ZodObject>(instruction: string, options?: Omit<PageAiSchemaOptions<Schema>, 'gptClient'> & {
+            gptClient?: GptClient | Exclude<LanguageModel, string>;
+        }): Promise<z.infer<Schema>>;
+        act(instruction: string, options?: Omit<PageAiNoSchemaOptions, 'gptClient'> & {
+            gptClient?: GptClient | Exclude<LanguageModel, string>;
+        }): Promise<void>;
+        /**
+         * Assert that a given condition about the current page holds true (or throws).
+         *  The assertion is evaluated by AI using the context of the current page's...
+         * - Textual context
+         * - Viewport screenshot
+         * - URL
+         * - Title
+         */
+        assertPage(assertion: string, options?: {
+            retries?: number;
+            retryDelaySeconds?: number;
+            gptClient?: GptClient | Exclude<LanguageModel, string>;
+        }): Promise<void>;
+        /**
+         * Return an object conforming to the given Zod schema. The object will be
+         * generated considering the following:
+         * - The given instruction (if any).
+         * - A screenshot of the current state of the page.
+         * - The history of key actions taken on the page.
+         */
+        extract<Schema extends z.ZodObject>(schema: Schema, options?: {
+            instruction?: string;
+            gptClient?: GptClient | Exclude<LanguageModel, string>;
+        }): Promise<z.infer<Schema>>;
+        /**
+         * Run an analysis on the current webpage's full raw text. Note that since this runs an analysis
+         * on the raw text, rather than, the HTML of the page, the raw text may be a bit jumbled,
+         * have its styling lost, careful positioning lost, etc.
+         *
+         * If there is context relevant to running the analysis that would not be found in the webpage
+         * text itself, perhaps context given in another message, prompt, overall object, etc, then
+         * provide it in the "additionalContext" parameter.
+         */
+        analyzePageText(analysisToRun: string, options?: {
+            additionalContext?: string;
+            gptClient?: GptClient | Exclude<LanguageModel, string>;
+        }): Promise<string>;
+        /**
+         * Perform an analysis of the cookies for the current web browsing session.
+         */
+        createCookieReport(options?: {
+            gptClient?: GptClient | Exclude<LanguageModel, string>;
+        }): Promise<CookieAnalyses>;
+    };
     /**
      * Builds a smart selector object that will automatically failover when performing
      * actions.
@@ -92,44 +89,24 @@ export interface DonobuExtendedPage extends Page {
         frame?: string;
     }): SmartSelector;
     /**
-     * Hover the mouse over a specified element on a webpage.
-     */
-    hoverOverElement(params: z.infer<typeof SelectorBasedSchema>): Promise<ToolCallResult>;
-    /**
-     * Create a new randomized email address based on a given email and inputs it to a specific input text field.
-     * For example if passed "foo@gmail.com", this tool will create "foo+SOMETHING_RANDOM@gmail.com", where
-     * SOMETHING_RANDOM is a random string of characters safe for use in an email address, and input it in the
-     * specified text field.
-     */
-    inputRandomizedEmailAddress(params: z.infer<typeof InputRandomizedEmailAddressNonGptSchema>): Promise<ToolCallResult>;
-    /**
-     * Input text to a webpage's text input box.
+     * Run an arbitrary Donobu tool by name.
      */
-    inputText(params: z.infer<typeof InputTextNonGptSchema>): Promise<ToolCallResult>;
+    run(toolName: string, toolParams?: any, options?: {
+        gptClient?: GptClient | Exclude<LanguageModel, string>;
+    }): Promise<ToolCallResult>;
     /**
-     * Press a single key. Note that if there is existing text in the element, it is appended rather than cleared.
-     *
-     * Generally, prefer using the 'inputText' tool instead as it automatically clears existing text
-     * and it allows the input of multiple characters at a time. The only advantage this tool has is
-     * that it allows the passing of control keys like "Tab", "Backspace", etc.
+     * Checks all of the pages in the current browser context and returns the one
+     * matching the given URL.
      */
-    pressKey(params: z.infer<typeof PressKeyNonGptSchema>): Promise<ToolCallResult>;
+    changeTab(url: string): Promise<DonobuExtendedPage>;
     /**
      * Run an web accessibility (i.e. axe-core) test on the current webpage.
      */
-    runAccessibilityTest(): Promise<ToolCallResult>;
-    /**
-     * Scroll the given element.
-     */
-    scroll(params: z.infer<typeof ScrollPageNonGptSchema>): Promise<ToolCallResult>;
-    /**
-     * Visually assert that a given condition (i.e. the 'assertionToTestFor' field) holds true, using a screenshot of
-     * the current webpage.
-     */
-    visuallyAssert(params: z.infer<typeof AssertCoreSchema>, gptClientOverride?: GptClient | LanguageModel): Promise<ToolCallResult>;
+    runAccessibilityTest(): Promise<AccessibilityResults>;
     _dnb: {
         donobuFlowMetadata: FlowMetadata;
         donobuStack: DonobuStack;
+        interactionVisualizer: InteractionVisualizer;
         pageAi: PageAi | undefined;
         persistence: FlowsPersistence;
         initialBrowserState: BrowserStorageState;

package/dist/esm/lib/DonobuExtendedPage.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"DonobuExtendedPage.d.ts","sourceRoot":"","sources":["../../../src/lib/DonobuExtendedPage.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"DonobuExtendedPage.d.ts","sourceRoot":"","sources":["../../../src/lib/DonobuExtendedPage.ts"],"names":[],"mappings":"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"}

package/dist/esm/lib/PageAi.d.ts

@@ -1,11 +1,11 @@
 import { z } from 'zod/v4';
-import { DonobuStack } from '../managers/DonobuStack';
-import { DonobuExtendedPage } from './DonobuExtendedPage';
-import { FlowMetadata } from '../models/FlowMetadata';
+import type { GptClient } from '../clients/GptClient';
 import { DonobuFlow } from '../managers/DonobuFlow';
-import { GptClient } from '../clients/GptClient';
-import { ProposedToolCall } from '../models/ProposedToolCall';
-import { PageAiCache } from './pageAi/cache';
+import type { DonobuStack } from '../managers/DonobuStack';
+import type { FlowMetadata } from '../models/FlowMetadata';
+import type { ProposedToolCall } from '../models/ProposedToolCall';
+import type { DonobuExtendedPage } from './DonobuExtendedPage';
+import type { PageAiCache } from './pageAi/cache';
 /**
  * Page AI orchestration entry point.
  *
@@ -17,11 +17,11 @@ import { PageAiCache } from './pageAi/cache';
  * - {@link PageAiRunner} sets up the `DonobuFlow` and keeps the persistence
  *   layer in sync. It knows nothing about caches.
  * - {@link PageAi} glues together the runner with a pluggable cache so that
- *   consumers (e.g., Playwright fixtures) keep their simple `page.ai(...)`
+ *   consumers (e.g., Playwright fixtures) keep their simple `page.ai.act(...)`
  *   API while gaining better separation of concerns.
  *
  * The documentation in this file attempts to guide new contributors through
- * the lifecycle of a single `page.ai` call: resolve cache → run flow →
+ * the lifecycle of a single `page.ai.act(...)` call: resolve cache → run flow →
  * persist metadata → update cache.
  */
 type PageAiBaseOptions = {
@@ -29,11 +29,12 @@ type PageAiBaseOptions = {
     allowedTools?: string[];
     maxToolCalls?: number;
     envVars?: string[];
+    gptClient?: GptClient;
 };
-type PageAiSchemaOptions<Schema extends z.ZodObject> = PageAiBaseOptions & {
+export type PageAiSchemaOptions<Schema extends z.ZodObject> = PageAiBaseOptions & {
     schema: Schema;
 };
-type PageAiNoSchemaOptions = PageAiBaseOptions & {
+export type PageAiNoSchemaOptions = PageAiBaseOptions & {
     schema?: undefined;
 };
 export type PageAiOptions<Schema extends z.ZodObject | undefined = undefined> = Schema extends z.ZodObject ? PageAiSchemaOptions<Schema> : PageAiNoSchemaOptions;
@@ -48,6 +49,7 @@ type PageAiRunConfiguration<Schema extends z.ZodObject | undefined> = {
     envVarNames: string[];
     cachedToolCalls: ProposedToolCall[] | null;
     runMode: FlowMetadata['runMode'];
+    gptClient: GptClient | undefined;
 };
 type PageAiRunResult<Schema extends z.ZodObject | undefined> = {
     donobuFlow: DonobuFlow;
@@ -107,9 +109,11 @@ export declare class PageAi {
     static withFileCache(donobu: DonobuStack, gptClient: GptClient, cacheFilepath: string): PageAi;
     static withInMemoryCache(donobu: DonobuStack, gptClient: GptClient): PageAi;
     /**
-     * Public entry point invoked by `page.ai`. Handles cache lookup, delegates to
+     * Public entry point invoked by `page.ai.act`. Handles cache lookup, delegates to
      * the runner, and stores the result back into the cache when appropriate.
      */
+    ai<Schema extends z.ZodObject>(page: DonobuExtendedPage, instruction: string, options: PageAiSchemaOptions<Schema>): Promise<z.infer<Schema>>;
+    ai(page: DonobuExtendedPage, instruction: string, options?: PageAiNoSchemaOptions): Promise<void>;
     ai<Schema extends z.ZodObject | undefined = undefined>(page: DonobuExtendedPage, instruction: string, options?: PageAiOptions<Schema>): Promise<AiResult<Schema>>;
     /**
      * Invalidates cache entries matching the provided invocation parameters.
@@ -127,7 +131,7 @@ export declare class PageAi {
      */
     private buildDescriptor;
     /**
-     * Computes the cache key that uniquely identifies a `page.ai` invocation.
+     * Computes the cache key that uniquely identifies a `page.ai.act(...)` invocation.
      * Keep this logic in sync with any external cache generators (e.g. the code
      * generator) so that hits and invalidations behave the same everywhere.
      */

package/dist/esm/lib/PageAi.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"PageAi.d.ts","sourceRoot":"","sources":["../../../src/lib/PageAi.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"PageAi.d.ts","sourceRoot":"","sources":["../../../src/lib/PageAi.ts"],"names":[],"mappings":"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"}

package/dist/esm/lib/PageAi.js

@@ -2,17 +2,16 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PageAi = exports.PageAiRunner = void 0;
 const v4_1 = require("zod/v4");
-const ToolManager_1 = require("../managers/ToolManager");
-const DonobuFlow_1 = require("../managers/DonobuFlow");
 const PageAiException_1 = require("../exceptions/PageAiException");
+const CodeGenerator_1 = require("../managers/CodeGenerator");
+const DonobuFlow_1 = require("../managers/DonobuFlow");
+const DonobuFlowsManager_1 = require("../managers/DonobuFlowsManager");
+const ToolManager_1 = require("../managers/ToolManager");
 const ControlPanel_1 = require("../models/ControlPanel");
-const InteractionVisualizer_1 = require("../managers/InteractionVisualizer");
 const Logger_1 = require("../utils/Logger");
-const DonobuFlowsManager_1 = require("../managers/DonobuFlowsManager");
+const originalGotoRegistry_1 = require("./originalGotoRegistry");
 const cache_1 = require("./pageAi/cache");
 const cacheEntryBuilder_1 = require("./pageAi/cacheEntryBuilder");
-const CodeGenerator_1 = require("../managers/CodeGenerator");
-const originalGotoRegistry_1 = require("./originalGotoRegistry");
 /**
  * Prepares and executes a Donobu autonomous flow.
  *
@@ -56,7 +55,7 @@ class PageAiRunner {
         const persistence = await this.donobu.flowsPersistenceFactory.createPersistenceLayer();
         const pageWithOriginalGoto = Object.create(config.page);
         pageWithOriginalGoto.goto = (0, originalGotoRegistry_1.getOriginalGoto)(config.page);
-        const donobuFlow = new DonobuFlow_1.DonobuFlow(this.donobu.flowsManager, envData, config.page.context(), persistence, this.gptClient, toolManager, new InteractionVisualizer_1.InteractionVisualizer(augmentedMetadata.defaultMessageDuration ?? 0), config.cachedToolCalls ?? [], [], [], {
+        const donobuFlow = new DonobuFlow_1.DonobuFlow(this.donobu.flowsManager, envData, config.page.context(), persistence, this.gptClient, toolManager, config.page._dnb.interactionVisualizer, config.cachedToolCalls ?? [], [], [], {
             current: pageWithOriginalGoto,
         }, augmentedMetadata, new ControlPanel_1.NoOpControlPanel());
         const rawResult = await donobuFlow.run();
@@ -72,11 +71,7 @@ class PageAiRunner {
             Logger_1.appLogger.warn(`Failed to update metadata for flow: ${updatedMetadata.id}`, error);
         }
         if (donobuFlow.metadata.state !== 'SUCCESS') {
-            const resultBlurb = donobuFlow.metadata.result
-                ? JSON.stringify(donobuFlow.metadata.result, null, 2)
-                : '';
-            Logger_1.appLogger.error(`Failed to complete instruction: ${resultBlurb}`);
-            throw new PageAiException_1.PageAiException(donobuFlow.metadata);
+            throw new PageAiException_1.PageAiException(config.instruction, donobuFlow.metadata);
         }
         const parsedResult = (config.schema?.parse(rawResult) ??
             undefined);
@@ -131,10 +126,6 @@ class PageAi {
     static withInMemoryCache(donobu, gptClient) {
         return new PageAi(donobu, gptClient, new cache_1.InMemoryPageAiCache());
     }
-    /**
-     * Public entry point invoked by `page.ai`. Handles cache lookup, delegates to
-     * the runner, and stores the result back into the cache when appropriate.
-     */
     async ai(page, instruction, options) {
         const descriptor = this.buildDescriptor(page, instruction, options);
         const cachedToolCalls = descriptor.useCache
@@ -150,6 +141,7 @@ class PageAi {
             envVarNames: descriptor.envVarNames,
             cachedToolCalls,
             runMode: cachedToolCalls !== null ? 'DETERMINISTIC' : 'AUTONOMOUS',
+            gptClient: options?.gptClient,
         });
         if (descriptor.useCache) {
             const preparedToolCalls = await CodeGenerator_1.CodeGenerator.prepareToolCallsForRerun(
@@ -201,7 +193,7 @@ class PageAi {
         };
     }
     /**
-     * Computes the cache key that uniquely identifies a `page.ai` invocation.
+     * Computes the cache key that uniquely identifies a `page.ai.act(...)` invocation.
      * Keep this logic in sync with any external cache generators (e.g. the code
      * generator) so that hits and invalidations behave the same everywhere.
      */

package/dist/esm/lib/PageAi.js.map

@@ -1 +1 @@
-{"version":3,"file":"PageAi.js","sourceRoot":"","sources":["../../../src/lib/PageAi.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"PageAi.js","sourceRoot":"","sources":["../../../src/lib/PageAi.ts"],"names":[],"mappings":"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"}

package/dist/esm/lib/SmartSelector.d.ts

@@ -1,36 +1,37 @@
-import { ToolCallResult } from '../models/ToolCallResult';
-import { SelectorBasedSchema } from '../tools/ReplayableInteraction';
-import { DonobuExtendedPage } from './DonobuExtendedPage';
-import { z } from 'zod/v4';
+import type { z } from 'zod/v4';
+import type { SelectorBasedSchema } from '../tools/ReplayableInteraction';
+import type { DonobuExtendedPage } from './DonobuExtendedPage';
 export interface SmartSelector {
     /**
      * Choose <option> values for a particular <select> HTML element.
      */
-    selectOption(optionValues: string[]): Promise<ToolCallResult>;
+    selectOption(optionValues: string[]): Promise<void>;
     /**
      * Click an element on a webpage.
      */
-    click(): Promise<ToolCallResult>;
+    click(): Promise<void>;
     /**
      * Hover the mouse over a specified element on a webpage.
      */
-    hover(): Promise<ToolCallResult>;
+    hover(): Promise<void>;
     /**
      * Create a new randomized email address based on a given email and inputs it to a specific input text field.
      * For example if passed "foo@gmail.com", this tool will create "foo+SOMETHING_RANDOM@gmail.com", where
      * SOMETHING_RANDOM is a random string of characters safe for use in an email address, and input it in the
      * specified text field.
+     *
+     * Returns the randomized email address used.
      */
     inputRandomizedEmailAddress(baseEmail: string, options?: {
         finalizeWithSubmit?: boolean;
-    }): Promise<ToolCallResult>;
+    }): Promise<string>;
     /**
      * Input text to a webpage's text input box.
      */
     inputText(text: string, options?: {
         append?: boolean;
         finalizeWithSubmit?: boolean;
-    }): Promise<ToolCallResult>;
+    }): Promise<void>;
     /**
      * Press a single key. Note that if there is existing text in the element, it is appended rather than cleared.
      *
@@ -38,31 +39,31 @@ export interface SmartSelector {
      * and it allows the input of multiple characters at a time. The only advantage this tool has is
      * that it allows the passing of control keys like "Tab", "Backspace", etc.
      */
-    pressKey(key: string): Promise<ToolCallResult>;
+    pressKey(key: string): Promise<void>;
     /**
      * Scroll the given element.
      */
     scroll(direction: 'UP' | 'DOWN' | 'LEFT' | 'RIGHT', options?: {
         maxScroll?: boolean;
-    }): Promise<ToolCallResult>;
+    }): Promise<void>;
 }
 export declare class SmartSelectorImpl implements SmartSelector {
     page: DonobuExtendedPage;
     selector: z.infer<typeof SelectorBasedSchema.shape.selector>;
     constructor(page: DonobuExtendedPage, selector: z.infer<typeof SelectorBasedSchema.shape.selector>);
-    selectOption(optionValues: string[]): Promise<ToolCallResult>;
-    click(): Promise<ToolCallResult>;
-    hover(): Promise<ToolCallResult>;
+    selectOption(optionValues: string[]): Promise<void>;
+    click(): Promise<void>;
+    hover(): Promise<void>;
     inputRandomizedEmailAddress(baseEmail: string, options?: {
         finalizeWithSubmit?: boolean;
-    }): Promise<ToolCallResult>;
+    }): Promise<string>;
     inputText(text: string, options?: {
         append?: boolean;
         finalizeWithSubmit?: boolean;
-    }): Promise<ToolCallResult>;
-    pressKey(key: string): Promise<ToolCallResult>;
+    }): Promise<void>;
+    pressKey(key: string): Promise<void>;
     scroll(direction: 'UP' | 'DOWN' | 'LEFT' | 'RIGHT', options?: {
         maxScroll?: boolean;
-    }): Promise<ToolCallResult>;
+    }): Promise<void>;
 }
 //# sourceMappingURL=SmartSelector.d.ts.map

package/dist/esm/lib/SmartSelector.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SmartSelector.d.ts","sourceRoot":"","sources":["../../../src/lib/SmartSelector.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC1D,OAAO,EAAE,mBAAmB,EAAE,MAAM,gCAAgC,CAAC;AACrE,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,EAAE,CAAC,EAAE,MAAM,QAAQ,CAAC;AAE3B,MAAM,WAAW,aAAa;IAC5B;;OAEG;IACH,YAAY,CAAC,YAAY,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;IAC9D;;OAEG;IACH,KAAK,IAAI,OAAO,CAAC,cAAc,CAAC,CAAC;IACjC;;OAEG;IACH,KAAK,IAAI,OAAO,CAAC,cAAc,CAAC,CAAC;IACjC;;;;;OAKG;IACH,2BAA2B,CACzB,SAAS,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE;QACR,kBAAkB,CAAC,EAAE,OAAO,CAAC;KAC9B,GACA,OAAO,CAAC,cAAc,CAAC,CAAC;IAC3B;;OAEG;IACH,SAAS,CACP,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE;QACR,MAAM,CAAC,EAAE,OAAO,CAAC;QACjB,kBAAkB,CAAC,EAAE,OAAO,CAAC;KAC9B,GACA,OAAO,CAAC,cAAc,CAAC,CAAC;IAC3B;;;;;;OAMG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;IAC/C;;OAEG;IACH,MAAM,CACJ,SAAS,EAAE,IAAI,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,EAC3C,OAAO,CAAC,EAAE;QACR,SAAS,CAAC,EAAE,OAAO,CAAC;KACrB,GACA,OAAO,CAAC,cAAc,CAAC,CAAC;CAC5B;AAED,qBAAa,iBAAkB,YAAW,aAAa;IAE5C,IAAI,EAAE,kBAAkB;IACxB,QAAQ,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,KAAK,CAAC,QAAQ,CAAC;gBAD5D,IAAI,EAAE,kBAAkB,EACxB,QAAQ,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,KAAK,CAAC,QAAQ,CAAC;IAGxD,YAAY,CAAC,YAAY,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,cAAc,CAAC;IAO7D,KAAK,IAAI,OAAO,CAAC,cAAc,CAAC;IAIhC,KAAK,IAAI,OAAO,CAAC,cAAc,CAAC;IAIhC,2BAA2B,CACtC,SAAS,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE;QACR,kBAAkB,CAAC,EAAE,OAAO,CAAC;KAC9B,GACA,OAAO,CAAC,cAAc,CAAC;IAQb,SAAS,CACpB,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE;QACR,MAAM,CAAC,EAAE,OAAO,CAAC;QACjB,kBAAkB,CAAC,EAAE,OAAO,CAAC;KAC9B,GACA,OAAO,CAAC,cAAc,CAAC;IASb,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC;IAO9C,MAAM,CACjB,SAAS,EAAE,IAAI,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,EAC3C,OAAO,CAAC,EAAE;QACR,SAAS,CAAC,EAAE,OAAO,CAAC;KACrB,GACA,OAAO,CAAC,cAAc,CAAC;CAO3B"}
+{"version":3,"file":"SmartSelector.d.ts","sourceRoot":"","sources":["../../../src/lib/SmartSelector.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,QAAQ,CAAC;AAYhC,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,gCAAgC,CAAC;AAG1E,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAE/D,MAAM,WAAW,aAAa;IAC5B;;OAEG;IACH,YAAY,CAAC,YAAY,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpD;;OAEG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB;;OAEG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB;;;;;;;OAOG;IACH,2BAA2B,CACzB,SAAS,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE;QACR,kBAAkB,CAAC,EAAE,OAAO,CAAC;KAC9B,GACA,OAAO,CAAC,MAAM,CAAC,CAAC;IACnB;;OAEG;IACH,SAAS,CACP,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE;QACR,MAAM,CAAC,EAAE,OAAO,CAAC;QACjB,kBAAkB,CAAC,EAAE,OAAO,CAAC;KAC9B,GACA,OAAO,CAAC,IAAI,CAAC,CAAC;IACjB;;;;;;OAMG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACrC;;OAEG;IACH,MAAM,CACJ,SAAS,EAAE,IAAI,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,EAC3C,OAAO,CAAC,EAAE;QACR,SAAS,CAAC,EAAE,OAAO,CAAC;KACrB,GACA,OAAO,CAAC,IAAI,CAAC,CAAC;CAClB;AAED,qBAAa,iBAAkB,YAAW,aAAa;IAE5C,IAAI,EAAE,kBAAkB;IACxB,QAAQ,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,KAAK,CAAC,QAAQ,CAAC;gBAD5D,IAAI,EAAE,kBAAkB,EACxB,QAAQ,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,KAAK,CAAC,QAAQ,CAAC;IAGxD,YAAY,CAAC,YAAY,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAOnD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAMtB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAMtB,2BAA2B,CACtC,SAAS,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE;QACR,kBAAkB,CAAC,EAAE,OAAO,CAAC;KAC9B,GACA,OAAO,CAAC,MAAM,CAAC;IAWL,SAAS,CACpB,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE;QACR,MAAM,CAAC,EAAE,OAAO,CAAC;QACjB,kBAAkB,CAAC,EAAE,OAAO,CAAC;KAC9B,GACA,OAAO,CAAC,IAAI,CAAC;IASH,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAOpC,MAAM,CACjB,SAAS,EAAE,IAAI,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,EAC3C,OAAO,CAAC,EAAE;QACR,SAAS,CAAC,EAAE,OAAO,CAAC;KACrB,GACA,OAAO,CAAC,IAAI,CAAC;CAOjB"}

package/dist/esm/lib/SmartSelector.js

@@ -1,32 +1,45 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SmartSelectorImpl = void 0;
+const ChooseSelectOptionTool_1 = require("../tools/ChooseSelectOptionTool");
+const ClickTool_1 = require("../tools/ClickTool");
+const HoverOverElementTool_1 = require("../tools/HoverOverElementTool");
+const InputRandomizedEmailAddressTool_1 = require("../tools/InputRandomizedEmailAddressTool");
+const InputTextTool_1 = require("../tools/InputTextTool");
+const PressKeyTool_1 = require("../tools/PressKeyTool");
+const ScrollPageTool_1 = require("../tools/ScrollPageTool");
 class SmartSelectorImpl {
     constructor(page, selector) {
         this.page = page;
         this.selector = selector;
     }
     async selectOption(optionValues) {
-        return this.page.chooseSelectOption({
+        await this.page.run(ChooseSelectOptionTool_1.ChooseSelectOptionTool.NAME, {
             optionValues: optionValues,
             selector: this.selector,
         });
     }
     async click() {
-        return this.page.clickElement({ selector: this.selector });
+        await this.page.run(ClickTool_1.ClickTool.NAME, {
+            selector: this.selector,
+        });
     }
     async hover() {
-        return this.page.hoverOverElement({ selector: this.selector });
+        await this.page.run(HoverOverElementTool_1.HoverOverElementTool.NAME, {
+            selector: this.selector,
+        });
     }
     async inputRandomizedEmailAddress(baseEmail, options) {
-        return this.page.inputRandomizedEmailAddress({
+        const result = await this.page.run(InputRandomizedEmailAddressTool_1.InputRandomizedEmailAddressTool.NAME, {
             baseEmail: baseEmail,
             finalizeWithSubmit: options?.finalizeWithSubmit ?? false,
             selector: this.selector,
         });
+        const email = result.forLlm.match(/^Inputted email: "([^"]+)"/)?.[1] ?? result.forLlm;
+        return email;
     }
     async inputText(text, options) {
-        return this.page.inputText({
+        await this.page.run(InputTextTool_1.InputTextTool.NAME, {
             text: text,
             append: options?.append,
             finalizeWithSubmit: options?.finalizeWithSubmit ?? false,
@@ -34,13 +47,13 @@ class SmartSelectorImpl {
         });
     }
     async pressKey(key) {
-        return this.page.pressKey({
+        await this.page.run(PressKeyTool_1.PressKeyTool.NAME, {
             key: key,
             selector: this.selector,
         });
     }
     async scroll(direction, options) {
-        return this.page.scroll({
+        await this.page.run(ScrollPageTool_1.ScrollPageTool.NAME, {
             direction: direction,
             selector: this.selector,
             maxScroll: options?.maxScroll,