donobu 5.54.0 → 5.56.0

package/dist/esm/apis/FlowsApi.js

@@ -5,6 +5,16 @@ const v4_1 = require("zod/v4");
 const CodeGenerationOptions_1 = require("../models/CodeGenerationOptions");
 const CreateDonobuFlow_1 = require("../models/CreateDonobuFlow");
 const FlowMetadata_1 = require("../models/FlowMetadata");
+const RunMode_1 = require("../models/RunMode");
+/** Body schema for the reject-proposal endpoint (SUPERVISED mode). */
+const RejectProposalBodySchema = v4_1.z.object({
+    feedback: v4_1.z.string().optional(),
+});
+/** Body schema for the set-run-mode endpoint (live autonomy switching). */
+const SetRunModeBodySchema = v4_1.z.object({
+    runMode: RunMode_1.RunModeSchema,
+    approvePending: v4_1.z.boolean().optional(),
+});
 /**
  * API controller for managing Donobu flows throughout their lifecycle.
  *
@@ -284,9 +294,11 @@ class FlowsApi {
     /**
      * Pauses execution of an active flow.
      *
-     * Signals the flow to pause after completing its current action. The flow
-     * will transition to PAUSED state and can be resumed later. Only works
-     * for flows that are not already in a terminal state.
+     * Submits a PAUSE user action; the flow's run loop applies it after its
+     * current action, transitioning to PAUSED. Like the desktop control panel's
+     * pause, this goes through the single user-action channel
+     * ({@link DonobuFlow.submitUserAction}) rather than mutating flow state
+     * directly.
      *
      * @throws {@link ActiveFlowNotFoundException} When the flow is not active locally
      *
@@ -294,7 +306,8 @@ class FlowsApi {
      * ```http
      * POST /api/flows/abc123/pause
      *
-     * Response: FlowMetadata with nextState set to "PAUSED"
+     * Response: the flow's FlowMetadata (the pause is applied asynchronously by
+     * the run loop, so the returned metadata may not yet show PAUSED)
      * ```
      *
      * @remarks
@@ -304,16 +317,18 @@ class FlowsApi {
     async pauseFlow(req, res) {
         const flowId = String(req.params.flowId);
         const flow = this.donobuFlowsManager.getActiveFlow(flowId);
-        if (!(0, FlowMetadata_1.isComplete)(flow.metadata.state)) {
-            flow.metadata.nextState = 'PAUSED';
-        }
+        // The PAUSE handler in onUserInterruption no-ops if the flow is already
+        // complete, so no guard is needed here.
+        flow.submitUserAction({ type: 'PAUSE' });
         res.json(flow.metadata);
     }
     /**
      * Resumes execution of a paused flow.
      *
-     * Signals a paused flow to continue execution. The flow will transition
-     * from PAUSED to RESUMING state and then continue normal operation.
+     * Submits a RESUME user action (only when the flow is currently PAUSED); the
+     * run loop transitions PAUSED → RESUMING → normal operation. Like the desktop
+     * control panel's resume, this goes through the single user-action channel
+     * ({@link DonobuFlow.submitUserAction}).
      *
      * @throws {@link ActiveFlowNotFoundException} When the flow is not active locally
      *
@@ -321,7 +336,8 @@ class FlowsApi {
      * ```http
      * POST /api/flows/abc123/resume
      *
-     * Response: FlowMetadata with nextState set to "RESUMING"
+     * Response: the flow's FlowMetadata (the resume is applied asynchronously by
+     * the run loop, so the returned metadata may not yet show RESUMING)
      * ```
      *
      * @remarks
@@ -332,8 +348,120 @@ class FlowsApi {
         const flowId = String(req.params.flowId);
         const flow = this.donobuFlowsManager.getActiveFlow(flowId);
         if (flow.metadata.state === 'PAUSED') {
-            flow.metadata.nextState = 'RESUMING';
+            flow.submitUserAction({ type: 'RESUME' });
+        }
+        res.json(flow.metadata);
+    }
+    /**
+     * Approves the AI-proposed action(s) a SUPERVISED flow is waiting on.
+     *
+     * The flow leaves WAITING_FOR_APPROVAL and executes the proposed action(s)
+     * as-is, then continues (proposing its next action for approval).
+     *
+     * @throws {@link ActiveFlowNotFoundException} When the flow is not active locally
+     *
+     * @example
+     * ```http
+     * POST /api/flows/abc123/approve
+     *
+     * Response: FlowMetadata
+     * ```
+     *
+     * @remarks
+     * This endpoint is only available in LOCAL deployment environments for security.
+     * Only has an effect on flows currently in WAITING_FOR_APPROVAL state.
+     */
+    async approveProposal(req, res) {
+        const flowId = String(req.params.flowId);
+        const flow = this.donobuFlowsManager.getActiveFlow(flowId);
+        flow.submitUserAction({ type: 'APPROVE' });
+        res.json(flow.metadata);
+    }
+    /**
+     * Rejects the AI-proposed action(s) a SUPERVISED flow is waiting on.
+     *
+     * The proposed action(s) are discarded and the optional feedback is fed back
+     * to the AI, which then proposes a different next action (again awaiting
+     * approval).
+     *
+     * @throws {@link ActiveFlowNotFoundException} When the flow is not active locally
+     *
+     * @example
+     * ```http
+     * POST /api/flows/abc123/reject
+     * { "feedback": "Use the search box instead of the menu." }
+     *
+     * Response: FlowMetadata
+     * ```
+     *
+     * @remarks
+     * This endpoint is only available in LOCAL deployment environments for security.
+     * Only has an effect on flows currently in WAITING_FOR_APPROVAL state.
+     */
+    async rejectProposal(req, res) {
+        const flowId = String(req.params.flowId);
+        const flow = this.donobuFlowsManager.getActiveFlow(flowId);
+        const { feedback } = RejectProposalBodySchema.parse(req.body ?? {});
+        flow.submitUserAction({ type: 'REJECT', feedback });
+        res.json(flow.metadata);
+    }
+    /**
+     * Returns the AI-proposed tool call(s) a SUPERVISED flow is currently waiting
+     * on for approval. Empty when the flow is not active locally or is not in the
+     * WAITING_FOR_APPROVAL state. Polled by the UI to render what the user is
+     * being asked to approve or reject.
+     *
+     * @example
+     * ```http
+     * GET /api/flows/abc123/pending-tool-calls
+     *
+     * Response: { pendingToolCalls: ProposedToolCall[] }
+     * ```
+     *
+     * @remarks
+     * This endpoint is only available in LOCAL deployment environments.
+     */
+    async getPendingToolCalls(req, res) {
+        const flowId = String(req.params.flowId);
+        let pendingToolCalls = [];
+        try {
+            const flow = this.donobuFlowsManager.getActiveFlow(flowId);
+            if (flow.metadata.state === 'WAITING_FOR_APPROVAL') {
+                pendingToolCalls = [...flow.proposedToolCalls];
+            }
         }
+        catch {
+            // Flow isn't active locally — nothing is pending approval.
+        }
+        res.json({ pendingToolCalls });
+    }
+    /**
+     * Changes the run mode of an active flow at runtime — the autonomy selector.
+     *
+     * This is the general primitive behind "start asking me each step"
+     * (→ SUPERVISED), "go fully autonomous" (→ AUTONOMOUS), and "I'll take over"
+     * (→ INSTRUCT). When switching to AUTONOMOUS with `approvePending: true` and a
+     * proposal is awaiting approval, that proposal is approved and run as part of
+     * the switch (the "approve & let it run" shortcut).
+     *
+     * @throws {@link ActiveFlowNotFoundException} When the flow is not active locally
+     *
+     * @example
+     * ```http
+     * POST /api/flows/abc123/run-mode
+     * { "runMode": "AUTONOMOUS", "approvePending": true }
+     *
+     * Response: FlowMetadata
+     * ```
+     *
+     * @remarks
+     * This endpoint is only available in LOCAL deployment environments.
+     */
+    async setRunMode(req, res) {
+        const flowId = String(req.params.flowId);
+        const flow = this.donobuFlowsManager.getActiveFlow(flowId);
+        const { runMode, approvePending } = SetRunModeBodySchema.parse(req.body ?? {});
+        flow.submitUserAction({ type: 'SET_RUN_MODE', runMode, approvePending });
         res.json(flow.metadata);
     }
     /**

package/dist/esm/apis/TestsApi.js

@@ -70,9 +70,10 @@ class TestsApi {
         const testId = String(req.params.testId);
         const newFlowConfig = await this.testsManager.getNewFlowFromTest(testId);
         const flowHandle = await this.flowsManager.createFlow(newFlowConfig);
-        // After starting an autonomous run, switch the test to deterministic
-        // so subsequent runs replay the recorded actions.
-        if (newFlowConfig.initialRunMode === 'AUTONOMOUS') {
+        // After starting an AI-driven run (autonomous or supervised), switch the
+        // test to deterministic so subsequent runs replay the recorded actions.
+        if (newFlowConfig.initialRunMode === 'AUTONOMOUS' ||
+            newFlowConfig.initialRunMode === 'SUPERVISED') {
             const test = await this.testsManager.getTestById(testId);
             await this.testsManager.updateTest({
                 ...test,

package/dist/esm/codegen/CodeGenerator.js

@@ -480,7 +480,9 @@ async function buildCacheContents(flowsWithToolCalls, toolRegistry) {
     const minimalToolNames = new Set(toolRegistry.minimalTools().map((t) => t.name));
     const entries = flowsWithToolCalls
         // We can only create page.ai caches for flows that have an objective.
-        .filter(({ metadata }) => metadata.overallObjective?.trim() && metadata.runMode === 'AUTONOMOUS')
+        .filter(({ metadata }) => metadata.overallObjective?.trim() &&
+        (metadata.runMode === 'AUTONOMOUS' ||
+            metadata.runMode === 'SUPERVISED'))
         .map(({ metadata, toolCalls }) => {
         const [firstToolCall, ...remaingToolCalls] = toolCalls;
         // If the first tool call is "GoToWebpage", then we peel it off and treat it
@@ -805,7 +807,7 @@ async function generateTestFiles(flowsWithToolCalls, options, toolRegistry) {
         const fileName = getTestFileName(metadata);
         const content = scriptVariant === 'classic' ||
             !metadata.overallObjective?.trim() ||
-            metadata.runMode !== 'AUTONOMOUS'
+            (metadata.runMode !== 'AUTONOMOUS' && metadata.runMode !== 'SUPERVISED')
             ? await getFlowAsPlaywrightScript(metadata, toolCalls, options, toolRegistry)
             : await getFlowAsAiPlaywrightScript(metadata, toolCalls, options, toolRegistry);
         files.push({

package/dist/esm/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)));
     }
     /**

package/dist/esm/managers/DonobuFlow.d.ts

@@ -1,7 +1,7 @@
 import type { z } from 'zod/v4';
 import type { GptClient } from '../clients/GptClient';
 import type { AiQuery } from '../models/AiQuery';
-import type { ControlPanel } from '../models/ControlPanel';
+import type { ControlPanel, UserAction } from '../models/ControlPanel';
 import type { FlowMetadata } from '../models/FlowMetadata';
 import type { GptMessage, StructuredOutputMessage, TextItem } from '../models/GptMessage';
 import type { SystemMessage } from '../models/GptMessage';
@@ -40,8 +40,23 @@ export declare class DonobuFlow {
     readonly controlPanel: ControlPanel;
     private static readonly MAIN_MESSAGE_ELEMENT_LIST_MARKER;
     static readonly USER_INTERRUPT_MARKER = "[User interruption while flow was paused, this MUST be acknowledged]";
+    static readonly REJECTION_MARKER = "[The user rejected your previously proposed action(s). Do NOT repeat them. Propose a different next action, taking the following feedback into account]";
     inProgressToolCall: ToolCall | null;
     readonly aiQueries: AiQuery[];
+    /**
+     * In SUPERVISED mode, the set of `toolCallId`s the user has explicitly
+     * approved. A proposed tool call only executes once its id is in this set;
+     * AI-proposed calls whose id is absent park the flow in
+     * `WAITING_FOR_APPROVAL`. Ids are removed as their calls run, so the set only
+     * ever holds currently-pending approvals.
+     */
+    private readonly approvedToolCallIds;
+    /**
+     * User actions submitted out-of-band (e.g. via REST endpoints rather than the
+     * desktop control panel). Drained by the run loop alongside the control
+     * panel, so both surfaces drive the flow through the same code path.
+     */
+    private readonly userActionInbox;
     constructor(flowsManager: DonobuFlowsManager, envData: Record<string, string>, persistence: FlowsPersistence, gptClient: GptClient | null, toolManager: ToolManager, interactionVisualizer: InteractionVisualizer, proposedToolCalls: ProposedToolCall[], invokedToolCalls: ToolCall[], gptMessages: GptMessage[], targetInspector: TargetInspector, metadata: FlowMetadata, controlPanel: ControlPanel);
     /**
      * Drives the entire Donobu flow state-machine until it reaches a
@@ -78,6 +93,25 @@ export declare class DonobuFlow {
      *          explicit result.
      */
     run(): Promise<FlowMetadata['result']>;
+    /**
+     * The single entry point for external user imperatives. Every cooperative
+     * control interrupt — pause, resume, end, approve, reject, run-mode change —
+     * arrives here as a {@link UserAction}, whether it came from a REST endpoint
+     * (web frontend / SDK) or the desktop control panel. The action is queued and
+     * drained by the run loop ({@link popUserAction}) and handled uniformly by
+     * {@link onUserInterruption}, so all transports drive the flow identically.
+     *
+     * (The forceful `cancelFlow` and the queue-injecting `proposeToolCall` on
+     * {@link DonobuFlowsManager} intentionally do NOT use this path — see their
+     * docs.)
+     */
+    submitUserAction(action: UserAction): void;
+    /**
+     * Returns and clears the next pending user action, preferring out-of-band
+     * actions (REST) over the control panel. Both sources feed the same
+     * intervention path so the desktop and web surfaces behave identically.
+     */
+    private popUserAction;
     /**
      * Delegates to the inspector to attempt recovery after the target is
      * closed. If recovery fails, the flow is marked as failed.
@@ -100,6 +134,53 @@ export declare class DonobuFlow {
      * Note that this *bypasses* the normal state transition logic!
      */
     private onUserInterruption;
+    /**
+     * Incorporates the compose-field text from a ▶/⏩ action: if the flow has no
+     * standing goal yet, the text becomes the `overallObjective`; otherwise it's
+     * added as extra guidance. Either way it's injected into the LLM history (the
+     * system prompt was built at init, possibly before any objective existed) and
+     * recorded in the timeline. No-op for empty text.
+     */
+    private applyComposeInstruction;
+    /**
+     * Closes out the currently-proposed AI tool call(s) without executing them:
+     * emits a `tool_call_result` for each (so the LLM message history stays
+     * well-formed — every tool call needs a matching result) and clears the
+     * proposal queue and any pending approvals. Shared by REJECT and manual
+     * takeover.
+     */
+    private closeOutPendingProposals;
+    /**
+     * Records a synthetic {@link AcknowledgeUserInstructionTool} tool call so a
+     * user-driven event (rejection, mode change) shows up in the flow timeline.
+     * Mirrors how RESUME records a user instruction.
+     */
+    private recordAdHocToolCall;
+    /**
+     * Moves the flow along the autonomy axis at runtime — the primitive behind
+     * "start asking me" (→ SUPERVISED), "go fully autonomous" (→ AUTONOMOUS),
+     * and "I'll take over" (→ INSTRUCT). After adjusting `runMode` and the
+     * pending proposal as appropriate, it routes through RESUMING so the next
+     * {@link transitionState} recomputes the correct state under the new mode.
+     *
+     * @param runMode - The target live mode. DETERMINISTIC is not a live mode and
+     *   is ignored. AI modes (AUTONOMOUS/SUPERVISED) require a GPT client.
+     * @param approvePending - When switching to AUTONOMOUS with an AI proposal
+     *   awaiting approval, approve and run it as part of the switch.
+     */
+    private applyRunModeChange;
+    /**
+     * Whether the flow can hand control to the AI: it needs both a GPT client and
+     * a goal to pursue.
+     */
+    private canHandOffToAi;
+    /**
+     * Whether there is a standing goal for the AI to pursue (a non-empty
+     * `overallObjective`). Surfaced to the UI as `hasGoal` to drive the
+     * transport: ⏩ Fast-forward (autonomous run) is only offered with a goal,
+     * and ▶ Play needs either a goal or a typed instruction.
+     */
+    private hasGoal;
     /**
      * This method is called if there is an unhandled unexpected exception. This
      * method will mark the flow as a failure.
@@ -171,9 +252,38 @@ export declare class DonobuFlow {
      * initializes the GPT message history.
      */
     private onInitializing;
+    /**
+     * Assembles the {@link ToolCallContext} handed to a tool. Shared by actual
+     * execution ({@link onRunningAction}) and the SUPERVISED-mode cursor preview
+     * ({@link previewProposedInteraction}) so both see an identical environment.
+     */
+    private buildToolCallContext;
+    /**
+     * SUPERVISED mode: move the on-screen cursor to where the head proposed
+     * action *would* interact, so the user can see the target while deciding
+     * whether to approve it. This never executes the action — it only previews
+     * the interaction point. Best-effort: tools without a visible target (and any
+     * resolution failure) are simply skipped.
+     */
+    private previewProposedInteraction;
     private onRunningAction;
     private onQueryingLlmForNextAction;
     private onWaitingForUserForNextAction;
+    /**
+     * SUPERVISED mode: an AI-proposed action is parked awaiting the user's
+     * decision. We idle here until an APPROVE/REJECT (or other intervention)
+     * arrives via the control panel or a REST endpoint, which the run loop picks
+     * up as a {@link UserInterruptException}. Mirrors
+     * {@link onWaitingForUserForNextAction}.
+     *
+     * Unlike {@link onPaused}, we must NOT pin `nextState` here: the proposal
+     * still sits in `proposedToolCalls`, so the approval gate in
+     * {@link transitionState} re-parks us each poll on its own. Pinning it would
+     * also leave a stale `nextState` that survives an APPROVE interrupt (which
+     * sets `state` directly), causing the next transition to skip querying the
+     * LLM and park forever with an empty proposal queue.
+     */
+    private onWaitingForApproval;
     private onPaused;
     private onResuming;
     private onFailed;