donobu 2.46.0 → 2.46.3

package/dist/assets/generated/version

@@ -1 +1 @@
-1398
+1406

package/dist/esm/assets/generated/version

@@ -1 +1 @@
-1398
+1406

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

@@ -15,7 +15,9 @@ import { SelectorBasedSchema } from '../tools/ReplayableInteraction';
 import { z } from 'zod/v4';
 import { BrowserStorageState } from '../models/BrowserStorageState';
 import { SmartSelector } from './SmartSelector';
-import { PageAiOptions } from './PageAi';
+import { PageAi, PageAiOptions } from './PageAi';
+import { DonobuStack } from '../managers/DonobuStack';
+import { FlowsPersistence } from '../persistence/flows/FlowsPersistence';
 export { PageAiOptions };
 /**
  * Extends the Page object with additional test-related methods.
@@ -57,7 +59,7 @@ export interface DonobuExtendedPage extends Page {
      * Checks all of the pages in the current browser context and returns the one
      * matching the given URL.
      */
-    changeTab(url: string): Promise<Page>;
+    changeTab(url: string): Promise<DonobuExtendedPage>;
     /**
      * Choose <option> values for a particular <select> HTML element.
      */
@@ -125,13 +127,13 @@ export interface DonobuExtendedPage extends Page {
      * the current webpage.
      */
     visuallyAssert(params: z.infer<typeof AssertCoreSchema>, gptClientOverride?: GptClient | LanguageModel): Promise<ToolCallResult>;
-    _donobuFlowMetadata: FlowMetadata;
-    _originalGoto: Page['goto'];
-    /**
-     * The state of the browser storage when a test first starts. This is saved so
-     * that if a test has to self-heal, we can restore the browser state to its
-     * original state before starting the self-healing process.
-     */
-    _initialBrowserState: BrowserStorageState;
+    _dnb: {
+        donobuFlowMetadata: FlowMetadata;
+        donobuStack: DonobuStack;
+        pageAi: PageAi | undefined;
+        persistence: FlowsPersistence;
+        initialBrowserState: BrowserStorageState;
+        gptClient: GptClient | undefined;
+    };
 }
 //# sourceMappingURL=DonobuExtendedPage.d.ts.map

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,9 +1,30 @@
 import { z } from 'zod/v4';
 import { DonobuStack } from '../managers/DonobuStack';
 import { DonobuExtendedPage } from './DonobuExtendedPage';
+import { FlowMetadata } from '../models/FlowMetadata';
+import { DonobuFlow } from '../managers/DonobuFlow';
 import { GptClient } from '../clients/GptClient';
 import { FlowsPersistence } from '../persistence/flows/FlowsPersistence';
 import { ProposedToolCall } from '../models/ProposedToolCall';
+import { PageAiCache } from './pageAi/cache';
+/**
+ * Page AI orchestration entry point.
+ *
+ * Historically, `PageAi` owned everything from cache storage to Donobu flow
+ * execution. That made the class hard to test and even harder to modify. The
+ * refactor splits responsibilities into smaller pieces that are easier to
+ * reason about:
+ *
+ * - {@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(...)`
+ *   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 →
+ * persist metadata → update cache.
+ */
 type PageAiBaseOptions = {
     cache?: boolean;
     allowedTools?: string[];
@@ -18,96 +39,101 @@ type PageAiNoSchemaOptions = PageAiBaseOptions & {
 };
 export type PageAiOptions<Schema extends z.ZodObject | undefined = undefined> = Schema extends z.ZodObject ? PageAiSchemaOptions<Schema> : PageAiNoSchemaOptions;
 type AiResult<Schema extends z.ZodObject | undefined> = Schema extends z.ZodObject ? z.infer<Schema> : void;
-export type CacheKey = {
-    pageUrl: string;
-    instruction: string | null;
-    schema: Record<string, unknown> | null;
+type PageAiRunConfiguration<Schema extends z.ZodObject | undefined> = {
+    page: DonobuExtendedPage;
+    instruction: string;
+    schema: Schema;
+    jsonSchema: Record<string, unknown> | null;
     allowedTools: string[];
-    maxToolCalls: number | null;
+    maxToolCalls: number;
+    envVarNames: string[];
+    cachedToolCalls: ProposedToolCall[] | null;
+    runMode: FlowMetadata['runMode'];
 };
-export type CacheEntry = CacheKey & {
-    toolCallCache: ProposedToolCall[];
+type PageAiRunResult<Schema extends z.ZodObject | undefined> = {
+    donobuFlow: DonobuFlow;
+    parsedResult: AiResult<Schema>;
 };
-export declare class PageAi {
+/**
+ * Prepares and executes a Donobu autonomous flow.
+ *
+ * Responsibilities:
+ *  - Gather environment data based on allowed env vars.
+ *  - Seed `DonobuFlow` with deterministic metadata (run mode, allowed tools, etc.).
+ *  - Run the flow, updating persisted metadata regardless of outcome.
+ *
+ * The runner does **not** perform cache lookups or updates. That is deferred to
+ * the higher-level {@link PageAi} facade so that the runner can stay focused on
+ * “how do we execute a flow safely?” rather than “should we execute a flow at
+ * all?”.
+ */
+export declare class PageAiRunner {
     private readonly donobu;
     private readonly persistence;
     private readonly gptClient;
-    private readonly cacheFilepath;
-    constructor(donobu: DonobuStack, persistence: FlowsPersistence, gptClient: GptClient, cacheFilepath: string);
+    constructor(donobu: DonobuStack, persistence: FlowsPersistence, gptClient: GptClient);
     /**
-     * Executes an AI-driven autonomous flow to accomplish a natural language instruction
-     * on a web page. The AI agent can interact with the page using Donobu tools and will
-     * attempt to satisfy the given objective.
-     *
-     * This method supports intelligent caching: successful flows are cached and can be
-     * replayed deterministically on subsequent runs with identical parameters, significantly
-     * reducing AI token usage and execution time. When a cache hit occurs, the flow runs
-     * in INSTRUCT mode using the cached tool calls; otherwise, it runs in AUTONOMOUS mode
-     * where the AI determines the necessary actions.
-     *
-     * @template T The Zod object schema describing the expected shape of the AI result.
-     * @param page The Donobu page instance to use as the starting point of the flow.
-     * @param instruction A high-level, natural language description of what the flow should
-     *                    accomplish (e.g., "Fill out the login form and submit it").
-     * @param options Optional configuration for the flow execution:
-     *                - `cache`: Set to false to bypass cache lookup and population (default: true)
-     *                - `allowedTools`: Restrict the AI to only use specified tools by name
-     *                - `maxToolCalls`: Maximum number of tool invocations allowed (default: 25)
-     * @returns A promise that resolves to the parsed result payload if a schema is provided,
-     *          or void if no schema is specified.
-     * @throws {PageAiException} If the autonomous flow fails, reaches a terminal non-success
-     *                           state, or the result fails schema validation.
-     *
-     * @example
-     * // Simple flow without structured output
-     * await pageAi.ai(page, "Click the 'Get Started' button");
-     *
-     * @example
-     * // Flow with structured output and schema validation
-     * const userSchema = z.object({
-     *   name: z.string(),
-     *   email: z.string().email(),
-     *   isPremium: z.boolean(),
-     * });
-     * const user = await pageAi.ai(
-     *   page,
-     *   "Extract the user profile information from the page",
-     *   { schema: userSchema }
-     * );
+     * Executes a flow using the provided configuration.
      *
-     * @example
-     * // Flow with custom options
-     * await pageAi.ai(
-     *   page,
-     *   "Navigate to the settings page",
-     *   {
-     *     cache: false,
-     *     allowedTools: ['goto', 'click'],
-     *     maxToolCalls: 10,
-     *   }
-     * );
+     * @param config Runtime information prepared by the higher-level facade.
+     * @returns Parsed result (if a schema was provided) along with the executed flow.
+     * @throws PageAiException when the underlying flow fails.
+     */
+    run<Schema extends z.ZodObject | undefined>(config: PageAiRunConfiguration<Schema>): Promise<PageAiRunResult<Schema>>;
+    /**
+     * Builds a `ToolManager` constrained to the tools the flow is allowed to use.
+     * We always allow the objective bookkeeping tools even if the caller supplied
+     * a narrower list.
+     */
+    private buildToolManager;
+}
+/**
+ * High-level API used by Playwright tests. It resolves caching policy,
+ * delegates execution to {@link PageAiRunner}, and records successful runs back
+ * into the configured cache.
+ */
+export declare class PageAi {
+    private readonly cache;
+    private readonly runner;
+    /**
+     * @param donobu Donobu stack providing flow managers and shared services.
+     * @param persistence Persistence layer used to store flow metadata.
+     * @param gptClient GPT client used for autonomous reasoning.
+     * @param cache Pluggable cache implementation the facade should consult.
+     */
+    constructor(donobu: DonobuStack, persistence: FlowsPersistence, gptClient: GptClient, cache: PageAiCache);
+    /**
+     * Builds a `PageAi` instance configured to use the file-backed cache stored
+     * alongside the current test file. This mirrors the behaviour relied upon by
+     * the Playwright fixture.
+     */
+    static withFileCache(donobu: DonobuStack, persistence: FlowsPersistence, gptClient: GptClient, cacheFilepath: string): PageAi;
+    /**
+     * Public entry point invoked by `page.ai`. Handles cache lookup, delegates to
+     * the runner, and stores the result back into the cache when appropriate.
      */
     ai<Schema extends z.ZodObject | undefined = undefined>(page: DonobuExtendedPage, instruction: string, options?: PageAiOptions<Schema>): Promise<AiResult<Schema>>;
-    private ensureCacheFileExists;
     /**
-     * Executes a cache operation within an exclusive file lock to prevent race conditions
-     * across multiple processes. This method handles cache file initialization, locking,
-     * reading, executing the provided operation, and conditionally writing back changes.
+     * Invalidates cache entries matching the provided invocation parameters.
      *
-     * @template T The type of result returned by the cache operation.
-     * @param operation A function that receives the current cache and returns both the
-     *                  modified cache (or the same cache if no modifications) and a result
-     *                  value. If the returned cache reference is different from the input,
-     *                  the cache file will be updated.
-     * @returns A promise that resolves to the result value from the operation.
-     * @throws Any error from the operation or file system operations (except expected ENOENT
-     *         and EEXIST errors which are handled internally).
+     * Returns `true` when a matching record existed and was removed.
+     */
+    invalidate<Schema extends z.ZodObject | undefined>(page: DonobuExtendedPage, instruction: string, options?: PageAiOptions<Schema>): Promise<boolean>;
+    /**
+     * Backwards-compatible alias for callers still using the older API.
+     */
+    deleteCachedFlow<Schema extends z.ZodObject | undefined>(page: DonobuExtendedPage, instruction: string, options?: PageAiOptions<Schema>): Promise<boolean>;
+    /**
+     * Normalises user-provided options into a single structure that can be reused
+     * across cache operations and flow execution.
+     */
+    private buildDescriptor;
+    /**
+     * Computes the cache key that uniquely identifies a `page.ai` 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.
      */
-    private withCacheLock;
-    private getCacheKey;
-    private getCachedFlow;
-    deleteCachedFlow(page: DonobuExtendedPage, instruction: string, options?: PageAiOptions<any>): Promise<boolean>;
-    private cacheFlow;
+    private buildCacheKey;
 }
 export {};
 //# sourceMappingURL=PageAi.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"PageAi.d.ts","sourceRoot":"","sources":["../../../src/lib/PageAi.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,QAAQ,CAAC;AAC3B,OAAO,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AACtD,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAS1D,OAAO,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,uCAAuC,CAAC;AAIzE,OAAO,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AAI9D,KAAK,iBAAiB,GAAG;IAEvB,KAAK,CAAC,EAAE,OAAO,CAAC;IAEhB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IAExB,YAAY,CAAC,EAAE,MAAM,CAAC;IAKtB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;CACpB,CAAC;AAEF,KAAK,mBAAmB,CAAC,MAAM,SAAS,CAAC,CAAC,SAAS,IAAI,iBAAiB,GAAG;IAGzE,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,KAAK,qBAAqB,GAAG,iBAAiB,GAAG;IAC/C,MAAM,CAAC,EAAE,SAAS,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,aAAa,CAAC,MAAM,SAAS,CAAC,CAAC,SAAS,GAAG,SAAS,GAAG,SAAS,IAC1E,MAAM,SAAS,CAAC,CAAC,SAAS,GACtB,mBAAmB,CAAC,MAAM,CAAC,GAC3B,qBAAqB,CAAC;AAE5B,KAAK,QAAQ,CAAC,MAAM,SAAS,CAAC,CAAC,SAAS,GAAG,SAAS,IAClD,MAAM,SAAS,CAAC,CAAC,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC;AAEtD,MAAM,MAAM,QAAQ,GAAG;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IACvC,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B,CAAC;AAEF,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG;IAClC,aAAa,EAAE,gBAAgB,EAAE,CAAC;CACnC,CAAC;AAMF,qBAAa,MAAM;IAEf,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,WAAW;IAC5B,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,aAAa;gBAHb,MAAM,EAAE,WAAW,EACnB,WAAW,EAAE,gBAAgB,EAC7B,SAAS,EAAE,SAAS,EACpB,aAAa,EAAE,MAAM;IAGxC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAoDG;IACU,EAAE,CAAC,MAAM,SAAS,CAAC,CAAC,SAAS,GAAG,SAAS,GAAG,SAAS,EAChE,IAAI,EAAE,kBAAkB,EACxB,WAAW,EAAE,MAAM,EACnB,OAAO,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,GAC9B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;YAiGd,qBAAqB;IAiBnC;;;;;;;;;;;;;OAaG;YACW,aAAa;IA+D3B,OAAO,CAAC,WAAW;YAmBL,aAAa;IAwBd,gBAAgB,CAC3B,IAAI,EAAE,kBAAkB,EACxB,WAAW,EAAE,MAAM,EACnB,OAAO,CAAC,EAAE,aAAa,CAAC,GAAG,CAAC,GAC3B,OAAO,CAAC,OAAO,CAAC;YAgCL,SAAS;CA0CxB"}
+{"version":3,"file":"PageAi.d.ts","sourceRoot":"","sources":["../../../src/lib/PageAi.ts"],"names":[],"mappings":"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"}