donobu 5.54.0 → 5.56.0

package/dist/esm/managers/DonobuFlowsManager.js

@@ -151,7 +151,8 @@ class DonobuFlowsManager {
                     ? flowParams.toolCallsOnStart
                     : targetRuntime.getInitialToolCalls(flowParams);
                 let maxToolCalls = null;
-                if (initialRunMode === 'AUTONOMOUS') {
+                if (initialRunMode === 'AUTONOMOUS' ||
+                    initialRunMode === 'SUPERVISED') {
                     maxToolCalls =
                         flowParams.maxToolCalls ??
                             DonobuFlowsManager.DEFAULT_MAX_TOOL_CALLS;
@@ -352,7 +353,15 @@ class DonobuFlowsManager {
             videoDisabled: config.videoDisabled,
         };
     }
-    /** Add a proposed tool call the tool call queue for the given flow by ID. */
+    /**
+     * Add a proposed tool call to the tool call queue for the given flow by ID.
+     *
+     * This intentionally does NOT go through {@link DonobuFlow.submitUserAction}:
+     * it *appends* a step to `proposedToolCalls` and validates the tool name
+     * synchronously (throwing {@link UnknownToolException}), whereas the
+     * `RUN_TOOL` user action clears the queue, runs immediately, and validates
+     * only at run time. This is queue input, not a cooperative control interrupt.
+     */
     async proposeToolCall(flowId, toolName, parameters) {
         const activeFlowHandle = this.isLocallyRunning()
             ? this.flowRuntime.get(flowId)
@@ -433,6 +442,11 @@ class DonobuFlowsManager {
      * Attempts to cancel a flow by ID. If the flow is active, the flow is ended
      * with a state of `FAILED`. If the flow is not active, this method has no
      * effect.
+     *
+     * This intentionally does NOT go through {@link DonobuFlow.submitUserAction}:
+     * cancellation is a forceful lifecycle/teardown operation owned by the
+     * manager — it sets the terminal state and tears down the browser context —
+     * not a cooperative control interrupt handled by the run loop.
      */
     async cancelFlow(flowId) {
         const activeFlowHandle = this.isLocallyRunning()
@@ -813,12 +827,15 @@ async function validateFlowParams(flowParams, gptClient, initialRunMode, toolReg
     validateFlowName(flowParams.name);
     switch (initialRunMode) {
         case 'AUTONOMOUS':
-            if ((flowParams.overallObjective?.trim().length ?? 0) === 0) {
-                throw new InvalidParamValueException_1.InvalidParamValueException('overallObjective', flowParams.overallObjective, `'initialRunMode' has a value of '${initialRunMode}'`);
-            }
+        case 'SUPERVISED':
+            // Both modes are AI-driven, so both need a GPT client and an objective
+            // to pursue.
             if (!gptClient) {
                 throw new InvalidParamValueException_1.InvalidParamValueException('initialRunMode', initialRunMode, `no GPT client is available`);
             }
+            if ((flowParams.overallObjective?.trim().length ?? 0) === 0) {
+                throw new InvalidParamValueException_1.InvalidParamValueException('overallObjective', flowParams.overallObjective, 'an AI-driven flow needs an objective to pursue');
+            }
             break;
         case 'INSTRUCT':
             break;
@@ -966,7 +983,12 @@ async function prepareToolCallsForRerun(toolCalls, options, toolRegistry) {
             continue;
         }
         try {
-            proposedToolCalls.push(tool.prepareForRerun(toolCall, options));
+            // A tool returns null to exclude itself from replay (e.g. a recorded
+            // user instruction, which is a live artifact, not a replayable action).
+            const prepared = tool.prepareForRerun(toolCall, options);
+            if (prepared) {
+                proposedToolCalls.push(prepared);
+            }
         }
         catch (e) {
             Logger_1.appLogger.warn(`Failed to prepare tool call for rerun: ${JSON.stringify(toolCall)}`, e);

package/dist/esm/models/ControlPanel.d.ts

@@ -1,4 +1,6 @@
 import type { State } from '../models/FlowMetadata';
+import type { ProposedToolCall } from '../models/ProposedToolCall';
+import type { RunMode } from '../models/RunMode';
 export type UserAction = {
     type: 'PAUSE';
 } | {
@@ -10,13 +12,38 @@ export type UserAction = {
     type: 'RUN_TOOL';
     toolName: string;
     parameters: Record<string, unknown>;
+} | {
+    type: 'APPROVE';
+} | {
+    type: 'REJECT';
+    feedback?: string;
+} | {
+    type: 'SET_RUN_MODE';
+    runMode: RunMode;
+    approvePending?: boolean;
+} | {
+    type: 'STEP';
+    instruction?: string;
+} | {
+    type: 'RUN';
+    instruction?: string;
 };
 export type ControlPanelDataUpdate = {
     state: State;
+    runMode?: RunMode;
+    /** The flow's overall objective; the panel treats a non-empty value (or a
+     * typed instruction) as a "goal", which gates ⏩ Fast-forward and ▶ Play. */
+    overallObjective?: string | null;
+    /** The tools the flow can actually run (resolved from the ToolManager). */
+    allowedTools?: string[] | null;
     headline?: string;
-    /** Names of tools loaded in the flow's ToolManager. Surfaced to the UI so
-     * the control panel can offer only tools the flow can actually run. */
-    availableToolNames?: string[];
+    /** AI-proposed tool call(s) awaiting approval (SUPERVISED). */
+    pendingToolCalls?: ProposedToolCall[];
+    /** Whether the flow has a GPT client (AI available at all). Not cleanly a
+     * FlowMetadata field — a client can come from env/default config, not just a
+     * named gptConfig — so it's surfaced explicitly. Drives whether the compose
+     * surface and the ▶/⏩ transport are offered at all. */
+    hasGptClient?: boolean;
 };
 export interface ControlPanel {
     /** Cheap, idempotent render update. */

package/dist/esm/models/CreateDonobuFlow.d.ts

@@ -141,6 +141,7 @@ export declare const CreateDonobuFlowSchema: 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/dist/esm/models/CreateTest.d.ts

@@ -143,6 +143,7 @@ export declare const CreateTestSchema: z.ZodObject<{
     suiteId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     nextRunMode: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
         AUTONOMOUS: "AUTONOMOUS";
+        SUPERVISED: "SUPERVISED";
         INSTRUCT: "INSTRUCT";
         DETERMINISTIC: "DETERMINISTIC";
     }>>>;

package/dist/esm/models/FlowMetadata.d.ts

@@ -4,6 +4,7 @@ export declare const StateSchema: z.ZodEnum<{
     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";
@@ -151,6 +152,7 @@ export declare const FlowMetadataSchema: z.ZodObject<{
     defaultMessageDuration: z.ZodNullable<z.ZodNumber>;
     runMode: z.ZodEnum<{
         AUTONOMOUS: "AUTONOMOUS";
+        SUPERVISED: "SUPERVISED";
         INSTRUCT: "INSTRUCT";
         DETERMINISTIC: "DETERMINISTIC";
     }>;
@@ -165,6 +167,7 @@ export declare const FlowMetadataSchema: 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";
@@ -176,6 +179,7 @@ export declare const FlowMetadataSchema: 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";
@@ -212,6 +216,7 @@ export declare const FlowsQuerySchema: z.ZodObject<{
     startedBefore: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
     runMode: z.ZodOptional<z.ZodEnum<{
         AUTONOMOUS: "AUTONOMOUS";
+        SUPERVISED: "SUPERVISED";
         INSTRUCT: "INSTRUCT";
         DETERMINISTIC: "DETERMINISTIC";
     }>>;
@@ -220,6 +225,7 @@ export declare const FlowsQuerySchema: 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/esm/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/esm/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/esm/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/esm/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/esm/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/esm/tools/AcknowledgeUserInstruction.d.ts

@@ -1,4 +1,5 @@
 import { z } from 'zod/v4';
+import type { ProposedToolCall } from '../models/ProposedToolCall';
 import type { ToolCallContext } from '../models/ToolCallContext';
 import type { ToolCallResult } from '../models/ToolCallResult';
 import { Tool } from './Tool';
@@ -20,5 +21,10 @@ export declare class AcknowledgeUserInstructionTool extends Tool<typeof Acknowle
     constructor();
     call(_context: ToolCallContext, parameters: z.infer<typeof AcknowledgeUserInstructionCoreSchema>): Promise<ToolCallResult>;
     callFromGpt(context: ToolCallContext, parameters: z.infer<typeof AcknowledgeUserInstructionGptSchema>): Promise<ToolCallResult>;
+    /**
+     * A user instruction is a live-interaction artifact, not a replayable action,
+     * so it is excluded from reruns and generated scripts.
+     */
+    prepareForRerun(): ProposedToolCall | null;
 }
 //# sourceMappingURL=AcknowledgeUserInstruction.d.ts.map

package/dist/esm/tools/AcknowledgeUserInstruction.js

@@ -33,6 +33,13 @@ class AcknowledgeUserInstructionTool extends Tool_1.Tool {
     async callFromGpt(context, parameters) {
         return this.call(context, parameters);
     }
+    /**
+     * A user instruction is a live-interaction artifact, not a replayable action,
+     * so it is excluded from reruns and generated scripts.
+     */
+    prepareForRerun() {
+        return null;
+    }
 }
 exports.AcknowledgeUserInstructionTool = AcknowledgeUserInstructionTool;
 AcknowledgeUserInstructionTool.NAME = 'acknowledgeUserInstruction';

package/dist/esm/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/esm/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/esm/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/esm/tools/Tool.d.ts

@@ -36,16 +36,35 @@ 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.
+     * for deterministic replay / code generation, or `null` to exclude the call
+     * from replay entirely.
      *
      * The default implementation is a passthrough — `{ name, parameters }` —
      * which is correct for tools that have no replay-specific logic
      * (waits, assertions, markers, etc.). Tools that need to hoist
      * selector metadata out of their outcome, strip LLM-only fields, or
-     * otherwise rewrite themselves override this method.
+     * otherwise rewrite themselves override this method. Tools that record
+     * live-interaction artifacts rather than replayable actions (e.g. a user
+     * instruction) return `null` so they don't reappear on reruns.
      */
-    prepareForRerun(toolCall: ToolCall, _options: CodeGenerationOptions): ProposedToolCall;
+    prepareForRerun(toolCall: ToolCall, _options: CodeGenerationOptions): ProposedToolCall | null;
 }
 //# sourceMappingURL=Tool.d.ts.map

package/dist/esm/tools/Tool.js

@@ -27,15 +27,34 @@ 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.
+     * for deterministic replay / code generation, or `null` to exclude the call
+     * from replay entirely.
      *
      * The default implementation is a passthrough — `{ name, parameters }` —
      * which is correct for tools that have no replay-specific logic
      * (waits, assertions, markers, etc.). Tools that need to hoist
      * selector metadata out of their outcome, strip LLM-only fields, or
-     * otherwise rewrite themselves override this method.
+     * otherwise rewrite themselves override this method. Tools that record
+     * live-interaction artifacts rather than replayable actions (e.g. a user
+     * instruction) return `null` so they don't reappear on reruns.
      */
     prepareForRerun(toolCall, _options) {
         return {

package/dist/esm/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/dist/managers/AdminApiController.js

@@ -287,6 +287,10 @@ class AdminApiController {
         app.post('/api/flows/:flowId/cancel', this.asyncHandler(apis.flowsApi.cancelFlow.bind(apis.flowsApi)));
         app.post('/api/flows/:flowId/pause', this.asyncHandler(apis.flowsApi.pauseFlow.bind(apis.flowsApi)));
         app.post('/api/flows/:flowId/resume', this.asyncHandler(apis.flowsApi.resumeFlow.bind(apis.flowsApi)));
+        app.post('/api/flows/:flowId/approve', this.asyncHandler(apis.flowsApi.approveProposal.bind(apis.flowsApi)));
+        app.post('/api/flows/:flowId/reject', this.asyncHandler(apis.flowsApi.rejectProposal.bind(apis.flowsApi)));
+        app.get('/api/flows/:flowId/pending-tool-calls', this.asyncHandler(apis.flowsApi.getPendingToolCalls.bind(apis.flowsApi)));
+        app.post('/api/flows/:flowId/run-mode', this.asyncHandler(apis.flowsApi.setRunMode.bind(apis.flowsApi)));
         app.post('/api/flows/:flowId/tool-calls', this.asyncHandler(apis.flowsToolCallsApi.postToolCalls.bind(apis.flowsToolCallsApi)));
     }
     /**