donobu 5.53.0 → 5.55.0

package/dist/models/FlowMetadata.js

@@ -12,6 +12,7 @@ exports.StateSchema = v4_1.z
     'INITIALIZING',
     'QUERYING_LLM_FOR_NEXT_ACTION',
     'WAITING_ON_USER_FOR_NEXT_ACTION',
+    'WAITING_FOR_APPROVAL',
     'PAUSED',
     'RESUMING',
     'RUNNING_ACTION',
@@ -22,8 +23,9 @@ exports.StateSchema = v4_1.z
  - UNSTARTED: Flow created but not yet initialized.
  - INITIALIZING: Setting up browser context and initial state.
  - RUNNING_ACTION: Executing a tool call.
- - QUERYING_LLM_FOR_NEXT_ACTION: AI determining next action (AUTONOMOUS mode).
+ - QUERYING_LLM_FOR_NEXT_ACTION: AI determining next action (AUTONOMOUS/SUPERVISED mode).
  - WAITING_ON_USER_FOR_NEXT_ACTION: Waiting for user input (INSTRUCT mode).
+ - WAITING_FOR_APPROVAL: An AI-proposed action is waiting for the user to approve or reject it (SUPERVISED mode).
  - PAUSED: Flow execution temporarily suspended.
  - RESUMING: Transitioning from paused to active state.
  - FAILED: Flow terminated unsuccessfully.

package/dist/models/RunMode.d.ts

@@ -1,6 +1,7 @@
 import { z } from 'zod/v4';
 export declare const RunModeSchema: z.ZodEnum<{
     AUTONOMOUS: "AUTONOMOUS";
+    SUPERVISED: "SUPERVISED";
     INSTRUCT: "INSTRUCT";
     DETERMINISTIC: "DETERMINISTIC";
 }>;

package/dist/models/RunMode.js

@@ -3,7 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.RunModeSchema = void 0;
 const v4_1 = require("zod/v4");
 exports.RunModeSchema = v4_1.z
-    .enum(['AUTONOMOUS', 'INSTRUCT', 'DETERMINISTIC'])
+    .enum(['AUTONOMOUS', 'SUPERVISED', 'INSTRUCT', 'DETERMINISTIC'])
     .describe(`The execution mode that determines how a flow operates and makes decisions:
 
 - AUTONOMOUS: The flow is driven by an AI agent (GPT) that autonomously decides what actions to
@@ -11,6 +11,12 @@ exports.RunModeSchema = v4_1.z
               determines the next appropriate action, and executes it without human intervention.
               This mode requires a valid GPT client configuration.
 
+- SUPERVISED: The flow is driven by an AI agent (GPT) that proposes the next action, but a human
+              supervises each proposal: every AI-proposed action waits for the user to approve it,
+              or reject it with optional feedback, before it executes. Rejecting discards the
+              proposal and lets the AI try again with the feedback in mind. Like AUTONOMOUS, this
+              mode pursues an overall objective and requires a valid GPT client configuration.
+
 - INSTRUCT: The flow waits for explicit user instructions for each action. The user manually
             directs what tools to call and when, making this mode suitable for guided walkthroughs
             or when human oversight is required for each step. No GPT client is required.

package/dist/models/TestMetadata.d.ts

@@ -141,6 +141,7 @@ export declare const TestMetadataSchema: z.ZodObject<{
     suiteId: z.ZodNullable<z.ZodString>;
     nextRunMode: z.ZodEnum<{
         AUTONOMOUS: "AUTONOMOUS";
+        SUPERVISED: "SUPERVISED";
         INSTRUCT: "INSTRUCT";
         DETERMINISTIC: "DETERMINISTIC";
     }>;
@@ -324,6 +325,7 @@ export declare const TestListItemSchema: z.ZodObject<{
     suiteId: z.ZodNullable<z.ZodString>;
     nextRunMode: z.ZodEnum<{
         AUTONOMOUS: "AUTONOMOUS";
+        SUPERVISED: "SUPERVISED";
         INSTRUCT: "INSTRUCT";
         DETERMINISTIC: "DETERMINISTIC";
     }>;
@@ -486,6 +488,7 @@ export declare const TestListItemSchema: z.ZodObject<{
         defaultMessageDuration: z.ZodNullable<z.ZodNumber>;
         runMode: z.ZodEnum<{
             AUTONOMOUS: "AUTONOMOUS";
+            SUPERVISED: "SUPERVISED";
             INSTRUCT: "INSTRUCT";
             DETERMINISTIC: "DETERMINISTIC";
         }>;
@@ -500,6 +503,7 @@ export declare const TestListItemSchema: z.ZodObject<{
             INITIALIZING: "INITIALIZING";
             QUERYING_LLM_FOR_NEXT_ACTION: "QUERYING_LLM_FOR_NEXT_ACTION";
             WAITING_ON_USER_FOR_NEXT_ACTION: "WAITING_ON_USER_FOR_NEXT_ACTION";
+            WAITING_FOR_APPROVAL: "WAITING_FOR_APPROVAL";
             PAUSED: "PAUSED";
             RESUMING: "RESUMING";
             RUNNING_ACTION: "RUNNING_ACTION";
@@ -511,6 +515,7 @@ export declare const TestListItemSchema: z.ZodObject<{
             INITIALIZING: "INITIALIZING";
             QUERYING_LLM_FOR_NEXT_ACTION: "QUERYING_LLM_FOR_NEXT_ACTION";
             WAITING_ON_USER_FOR_NEXT_ACTION: "WAITING_ON_USER_FOR_NEXT_ACTION";
+            WAITING_FOR_APPROVAL: "WAITING_FOR_APPROVAL";
             PAUSED: "PAUSED";
             RESUMING: "RESUMING";
             RUNNING_ACTION: "RUNNING_ACTION";
@@ -676,6 +681,7 @@ export declare const TestListItemPaginatedResultSchema: z.ZodObject<{
         suiteId: z.ZodNullable<z.ZodString>;
         nextRunMode: z.ZodEnum<{
             AUTONOMOUS: "AUTONOMOUS";
+            SUPERVISED: "SUPERVISED";
             INSTRUCT: "INSTRUCT";
             DETERMINISTIC: "DETERMINISTIC";
         }>;
@@ -838,6 +844,7 @@ export declare const TestListItemPaginatedResultSchema: z.ZodObject<{
             defaultMessageDuration: z.ZodNullable<z.ZodNumber>;
             runMode: z.ZodEnum<{
                 AUTONOMOUS: "AUTONOMOUS";
+                SUPERVISED: "SUPERVISED";
                 INSTRUCT: "INSTRUCT";
                 DETERMINISTIC: "DETERMINISTIC";
             }>;
@@ -852,6 +859,7 @@ export declare const TestListItemPaginatedResultSchema: z.ZodObject<{
                 INITIALIZING: "INITIALIZING";
                 QUERYING_LLM_FOR_NEXT_ACTION: "QUERYING_LLM_FOR_NEXT_ACTION";
                 WAITING_ON_USER_FOR_NEXT_ACTION: "WAITING_ON_USER_FOR_NEXT_ACTION";
+                WAITING_FOR_APPROVAL: "WAITING_FOR_APPROVAL";
                 PAUSED: "PAUSED";
                 RESUMING: "RESUMING";
                 RUNNING_ACTION: "RUNNING_ACTION";
@@ -863,6 +871,7 @@ export declare const TestListItemPaginatedResultSchema: z.ZodObject<{
                 INITIALIZING: "INITIALIZING";
                 QUERYING_LLM_FOR_NEXT_ACTION: "QUERYING_LLM_FOR_NEXT_ACTION";
                 WAITING_ON_USER_FOR_NEXT_ACTION: "WAITING_ON_USER_FOR_NEXT_ACTION";
+                WAITING_FOR_APPROVAL: "WAITING_FOR_APPROVAL";
                 PAUSED: "PAUSED";
                 RESUMING: "RESUMING";
                 RUNNING_ACTION: "RUNNING_ACTION";

package/dist/persistence/DonobuSqliteDb.js

@@ -471,7 +471,8 @@ CREATE INDEX IF NOT EXISTS idx_ai_queries_flow_id_started_at ON ai_queries(flow_
                     // value (likely null) if no autonomous flow exists in the group.
                     const newestAutonomous = [...group.flows]
                         .reverse()
-                        .find((f) => f.metadata.runMode === 'AUTONOMOUS')?.metadata;
+                        .find((f) => f.metadata.runMode === 'AUTONOMOUS' ||
+                        f.metadata.runMode === 'SUPERVISED')?.metadata;
                     const maxToolCalls = newestAutonomous?.maxToolCalls ?? newest.maxToolCalls;
                     const testName = (0, displayName_1.getDisplayName)(newest, 'Untitled Test');
                     const testMetadata = {
@@ -649,7 +650,7 @@ CREATE INDEX IF NOT EXISTS idx_ai_queries_flow_id_started_at ON ai_queries(flow_
                     // value (likely null) if no autonomous flow exists in the group.
                     const newestAutonomous = [...flows]
                         .reverse()
-                        .find((f) => f.runMode === 'AUTONOMOUS');
+                        .find((f) => f.runMode === 'AUTONOMOUS' || f.runMode === 'SUPERVISED');
                     const maxToolCalls = newestAutonomous?.maxToolCalls ?? newestFlow.maxToolCalls;
                     const testName = (0, displayName_1.getDisplayName)(newestFlow, 'Untitled Test');
                     const testMetadata = {

package/dist/tools/ReplayableInteraction.d.ts

@@ -84,8 +84,28 @@ export declare abstract class ReplayableInteraction<CoreSchema extends z.ZodObje
     readonly coreSchema: CoreSchema;
     static readonly MAX_SELECTOR_FAILOVERS = 3;
     static readonly MAX_LOCATOR_MATCH_COUNT = 3;
+    /**
+     * How long the preview cursor takes to glide to (and dwell on) the proposed
+     * target, in milliseconds. {@link InteractionVisualizer.pointAt} animates the
+     * move over half this duration.
+     */
+    static readonly PREVIEW_CURSOR_DURATION_MILLIS = 900;
     constructor(name: string, description: string, coreSchema: CoreSchema, inputSchema: NonGptSchema, inputSchemaForGpt: GptSchema, requiresGpt?: boolean);
     call(context: ToolCallContext, parameters: z.infer<NonGptSchema>): Promise<ToolCallResult>;
+    /**
+     * SUPERVISED-mode preview: resolve the element this interaction *would*
+     * target (from either an annotation- or selector-based proposal) and move the
+     * on-screen cursor to it, without performing the interaction. Best-effort —
+     * an unresolvable element simply leaves the cursor where it is.
+     */
+    previewInteraction(context: ToolCallContext, parameters: Record<string, unknown>): Promise<void>;
+    /**
+     * Resolve a proposed interaction's parameters to the {@link Locator} it would
+     * act on, mirroring the resolution in {@link call} (selector-based) and
+     * {@link callFromGpt} (annotation-based) but returning only the locator and
+     * never invoking anything. Returns `null` if the element can't be found.
+     */
+    private resolvePreviewLocator;
     callFromGpt(context: ToolCallContext, parameters: z.infer<GptSchema>): Promise<ToolCallResult>;
     /**
      * **Concrete subclasses implement the actual user action here.**

package/dist/tools/ReplayableInteraction.js

@@ -96,6 +96,63 @@ class ReplayableInteraction extends Tool_1.Tool {
         }
         return this.callCore(context, parameters, locators, parameters.selector);
     }
+    /**
+     * SUPERVISED-mode preview: resolve the element this interaction *would*
+     * target (from either an annotation- or selector-based proposal) and move the
+     * on-screen cursor to it, without performing the interaction. Best-effort —
+     * an unresolvable element simply leaves the cursor where it is.
+     */
+    async previewInteraction(context, parameters) {
+        const page = (0, TargetUtils_1.webPage)(context);
+        const locator = await this.resolvePreviewLocator(context, page, parameters);
+        if (!locator) {
+            return;
+        }
+        // Point at the same visible target (or its label) the real interaction
+        // would, so the preview matches what approval will touch.
+        const pointTarget = await ReplayableInteraction.getLocatorOrItsLabel(locator.first());
+        // Only reveal the cursor now that we have a real target to point at, so a
+        // non-interactive proposal never pops a stationary cursor.
+        await context.targetInspector.showInteractionCursor();
+        await context.interactionVisualizer.pointAt(page, pointTarget.first(), undefined, ReplayableInteraction.PREVIEW_CURSOR_DURATION_MILLIS);
+    }
+    /**
+     * Resolve a proposed interaction's parameters to the {@link Locator} it would
+     * act on, mirroring the resolution in {@link call} (selector-based) and
+     * {@link callFromGpt} (annotation-based) but returning only the locator and
+     * never invoking anything. Returns `null` if the element can't be found.
+     */
+    async resolvePreviewLocator(context, page, parameters) {
+        // Selector-based (deterministic) proposal.
+        if (parameters.selector) {
+            const parsed = ElementSelector_1.ElementSelectorSchema.safeParse(parameters.selector);
+            if (!parsed.success) {
+                return null;
+            }
+            const locators = await ReplayableInteraction.getLocatorsOrderedByMatchCount(page, parsed.data, ReplayableInteraction.MAX_LOCATOR_MATCH_COUNT, ReplayableInteraction.MAX_SELECTOR_FAILOVERS);
+            return locators[0]?.locator ?? null;
+        }
+        // Annotation-based (LLM-driven) proposal.
+        if (typeof parameters.annotation === 'string' ||
+            typeof parameters.annotation === 'number') {
+            const elementSelector = `[${context.targetInspector.interactableElementAttribute}="${parameters.annotation}"]`;
+            for (const frame of page.frames()) {
+                if (frame.isDetached()) {
+                    continue;
+                }
+                try {
+                    const candidate = frame.locator(elementSelector);
+                    if ((await candidate.count()) > 0) {
+                        return candidate;
+                    }
+                }
+                catch {
+                    // Detached or cross-origin frame — skip it.
+                }
+            }
+        }
+        return null;
+    }
     async callFromGpt(context, parameters) {
         const page = (0, TargetUtils_1.webPage)(context);
         const elementSelector = `[${context.targetInspector.interactableElementAttribute}="${parameters.annotation}"]`;
@@ -655,4 +712,10 @@ class ReplayableInteraction extends Tool_1.Tool {
 exports.ReplayableInteraction = ReplayableInteraction;
 ReplayableInteraction.MAX_SELECTOR_FAILOVERS = 3;
 ReplayableInteraction.MAX_LOCATOR_MATCH_COUNT = 3;
+/**
+ * How long the preview cursor takes to glide to (and dwell on) the proposed
+ * target, in milliseconds. {@link InteractionVisualizer.pointAt} animates the
+ * move over half this duration.
+ */
+ReplayableInteraction.PREVIEW_CURSOR_DURATION_MILLIS = 900;
 //# sourceMappingURL=ReplayableInteraction.js.map

package/dist/tools/SetRunModeTool.d.ts

@@ -5,6 +5,7 @@ import { Tool } from './Tool';
 export declare const SetRunModeCoreSchema: z.ZodObject<{
     runMode: z.ZodEnum<{
         AUTONOMOUS: "AUTONOMOUS";
+        SUPERVISED: "SUPERVISED";
         INSTRUCT: "INSTRUCT";
         DETERMINISTIC: "DETERMINISTIC";
     }>;
@@ -12,6 +13,7 @@ export declare const SetRunModeCoreSchema: z.ZodObject<{
 export declare const SetRunModeGptSchema: z.ZodObject<{
     runMode: z.ZodEnum<{
         AUTONOMOUS: "AUTONOMOUS";
+        SUPERVISED: "SUPERVISED";
         INSTRUCT: "INSTRUCT";
         DETERMINISTIC: "DETERMINISTIC";
     }>;

package/dist/tools/Tool.d.ts

@@ -36,6 +36,22 @@ export declare abstract class Tool<CallSchema extends z.ZodObject, CallFromGptSc
      * Invoke the tool as made from a GPT with the given context and parameters.
      */
     abstract callFromGpt(context: ToolCallContext, parameters: z.infer<CallFromGptSchema>): Promise<ToolCallResult>;
+    /**
+     * Move the on-screen cursor to where this tool *would* interact, WITHOUT
+     * performing the action. Used by SUPERVISED mode to show the user what an
+     * AI-proposed action would touch while it awaits their approval.
+     *
+     * The default is a no-op — only tools with a visible interaction target
+     * (e.g. {@link ReplayableInteraction}-derived click/type/hover tools)
+     * override it. Implementations must be best-effort and side-effect-free with
+     * respect to the page: they may move the visual cursor but must never click,
+     * type, navigate, or otherwise mutate page state.
+     *
+     * @param context - The active {@link ToolCallContext}.
+     * @param parameters - The proposed tool call's raw parameters (as proposed by
+     *   the LLM or a user); implementations validate/resolve these themselves.
+     */
+    previewInteraction(_context: ToolCallContext, _parameters: Record<string, unknown>): Promise<void>;
     /**
      * Transform a completed tool call into a {@link ProposedToolCall} suitable
      * for deterministic replay / code generation.

package/dist/tools/Tool.js

@@ -27,6 +27,22 @@ class Tool {
         this.controlPanelMessage = controlPanelMessage;
         this.supportedTargets = supportedTargets;
     }
+    /**
+     * Move the on-screen cursor to where this tool *would* interact, WITHOUT
+     * performing the action. Used by SUPERVISED mode to show the user what an
+     * AI-proposed action would touch while it awaits their approval.
+     *
+     * The default is a no-op — only tools with a visible interaction target
+     * (e.g. {@link ReplayableInteraction}-derived click/type/hover tools)
+     * override it. Implementations must be best-effort and side-effect-free with
+     * respect to the page: they may move the visual cursor but must never click,
+     * type, navigate, or otherwise mutate page state.
+     *
+     * @param context - The active {@link ToolCallContext}.
+     * @param parameters - The proposed tool call's raw parameters (as proposed by
+     *   the LLM or a user); implementations validate/resolve these themselves.
+     */
+    async previewInteraction(_context, _parameters) { }
     /**
      * Transform a completed tool call into a {@link ProposedToolCall} suitable
      * for deterministic replay / code generation.

package/dist/tools/TriggerDonobuFlowTool.d.ts

@@ -138,6 +138,7 @@ export declare const TriggerDonobuFlowCoreSchema: z.ZodObject<{
         gptConfigNameOverride: z.ZodOptional<z.ZodNullable<z.ZodString>>;
         initialRunMode: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
             AUTONOMOUS: "AUTONOMOUS";
+            SUPERVISED: "SUPERVISED";
             INSTRUCT: "INSTRUCT";
             DETERMINISTIC: "DETERMINISTIC";
         }>>>;
@@ -286,6 +287,7 @@ export declare const TriggerDonobuFlowGptSchema: z.ZodObject<{
         gptConfigNameOverride: z.ZodOptional<z.ZodNullable<z.ZodString>>;
         initialRunMode: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
             AUTONOMOUS: "AUTONOMOUS";
+            SUPERVISED: "SUPERVISED";
             INSTRUCT: "INSTRUCT";
             DETERMINISTIC: "DETERMINISTIC";
         }>>>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "donobu",
-  "version": "5.53.0",
+  "version": "5.55.0",
   "description": "Create browser automations with an LLM agent and replay them as Playwright scripts.",
   "main": "dist/main.js",
   "module": "dist/esm/main.js",