donobu 5.54.0 → 5.56.0

package/dist/apis/FlowsApi.d.ts

@@ -230,9 +230,11 @@ export declare 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
      *
@@ -240,7 +242,8 @@ export declare 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
@@ -251,8 +254,10 @@ export declare class FlowsApi {
     /**
      * 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
      *
@@ -260,7 +265,8 @@ export declare 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
@@ -268,6 +274,88 @@ export declare class FlowsApi {
      * Only works on flows currently in PAUSED state.
      */
     resumeFlow(req: Request, res: Response): Promise<void>;
+    /**
+     * 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.
+     */
+    approveProposal(req: Request, res: Response): Promise<void>;
+    /**
+     * 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.
+     */
+    rejectProposal(req: Request, res: Response): Promise<void>;
+    /**
+     * 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.
+     */
+    getPendingToolCalls(req: Request, res: Response): Promise<void>;
+    /**
+     * 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.
+     */
+    setRunMode(req: Request, res: Response): Promise<void>;
     /**
      * Cancels and terminates an active flow.
      *

package/dist/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/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/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/apis/FlowsApi.d.ts

@@ -230,9 +230,11 @@ export declare 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
      *
@@ -240,7 +242,8 @@ export declare 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
@@ -251,8 +254,10 @@ export declare class FlowsApi {
     /**
      * 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
      *
@@ -260,7 +265,8 @@ export declare 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
@@ -268,6 +274,88 @@ export declare class FlowsApi {
      * Only works on flows currently in PAUSED state.
      */
     resumeFlow(req: Request, res: Response): Promise<void>;
+    /**
+     * 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.
+     */
+    approveProposal(req: Request, res: Response): Promise<void>;
+    /**
+     * 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.
+     */
+    rejectProposal(req: Request, res: Response): Promise<void>;
+    /**
+     * 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.
+     */
+    getPendingToolCalls(req: Request, res: Response): Promise<void>;
+    /**
+     * 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.
+     */
+    setRunMode(req: Request, res: Response): Promise<void>;
     /**
      * Cancels and terminates an active flow.
      *