donobu 2.46.0 → 2.46.3

package/dist/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/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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"}