donobu 2.20.1 → 2.21.0

package/dist/apis/FlowsApi.js

@@ -1,16 +1,55 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.FlowsApi = void 0;
+const CreateDonobuFlow_1 = require("../models/CreateDonobuFlow");
 const FlowMetadata_1 = require("../models/FlowMetadata");
 const InvalidParamValueException_1 = require("../exceptions/InvalidParamValueException");
-const JsonUtils_1 = require("../utils/JsonUtils");
+const zod_1 = require("zod");
+/**
+ * API controller for managing Donobu flows throughout their lifecycle.
+ *
+ * The FlowsApi provides endpoints for creating, querying, controlling, and managing
+ * Donobu flows. It handles flow metadata operations, code generation, project export,
+ * and runtime control operations like pause/resume/cancel.
+ *
+ * @remarks
+ * This class serves as the HTTP API layer for the {@link DonobuFlowsManager}, translating
+ * REST requests into appropriate manager method calls. All methods are designed to be
+ * used as Express.js route handlers.
+ *
+ * Flow States:
+ * - 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)
+ * - WAITING_ON_USER_FOR_NEXT_ACTION: Waiting for user input (INSTRUCT mode)
+ * - PAUSED: Flow execution temporarily suspended
+ * - RESUMING: Transitioning from paused to active state
+ * - FAILED: Flow terminated unsuccessfully
+ * - SUCCESS: Flow completed successfully
+ */
 class FlowsApi {
     constructor(donobuFlowsManager) {
         this.donobuFlowsManager = donobuFlowsManager;
     }
     /**
-     * Attempts to create a Node.js Microsoft Playwright script to replay the
-     * given flow.
+     * Generates Playwright code that can replay a completed flow.
+     *
+     * Creates a Node.js Microsoft Playwright script that reproduces the actions
+     * taken during the specified flow. The generated code uses the Donobu Playwright
+     * extension and can be executed independently.
+     *
+     * @throws {@link FlowNotFoundException} When the specified flow doesn't exist
+     *
+     * @example
+     * ```http
+     * GET /api/flows/abc123/code
+     *
+     * Response:
+     * {
+     *   "script": "import { test } from 'donobu';\n\ntest('My Flow', async ({ page }) => {\n  await page.goto('https://example.com');\n  // ... more actions\n});"
+     * }
+     * ```
      */
     async getFlowAsCode(req, res) {
         const flowId = req.params.flowId;
@@ -18,23 +57,64 @@ class FlowsApi {
         res.send({ script: draftedPlaywrightScript });
     }
     /**
-     * Generates a complete Playwright project structure for multiple flows with dependency management
+     * Generates a complete Playwright project structure for multiple flows.
+     *
+     * Creates a full Playwright project with proper dependency management, configuration,
+     * and test files. Automatically resolves and includes flow dependencies to ensure
+     * a complete, runnable project.
+     *
+     * @throws {@link FlowNotFoundException} When any specified flow doesn't exist
+     *
+     * @example
+     * ```http
+     * POST /api/flows/project
+     * Content-Type: application/json
+     *
+     * {
+     *   "flowIds": ["flow1", "flow2", "flow3"]
+     * }
+     *
+     * Response:
+     * {
+     *   "files": [
+     *     {
+     *       "path": "tests/login-flow.spec.ts",
+     *       "content": "import { test } from 'donobu';\n..."
+     *     },
+     *     {
+     *       "path": "playwright.config.ts",
+     *       "content": "import { defineConfig } from 'donobu';\n..."
+     *     }
+     *   ]
+     * }
+     * ```
      */
     async getFlowsAsProject(req, res) {
-        const flowIds = req.body.flowIds;
-        if (!Array.isArray(flowIds) || flowIds.length === 0) {
-            throw new InvalidParamValueException_1.InvalidParamValueException('flowIds', '' + flowIds, 'must be a non-empty array of flow IDs');
-        }
-        // Generate the project structure using the flows manager
-        const project = await this.donobuFlowsManager.getFlowsAsPlaywrightProject(flowIds);
+        const parsedBody = zod_1.z
+            .object({ flowIds: zod_1.z.array(zod_1.z.string()) })
+            .parse(req.body);
+        const project = await this.donobuFlowsManager.getFlowsAsPlaywrightProject(parsedBody.flowIds);
         res.json({
             files: project.files,
         });
     }
     /**
-     * Get a given flow by ID as an appropriately formatted
-     * {@link CreateDonobuFlow} object fit for direct replay by calling the
-     * {@link FlowsApi.createFlow} endpoint.
+     * Converts a flow into a rerunnable format.
+     *
+     * Returns a {@link CreateDonobuFlow} object that can be used to replay the specified
+     * flow deterministically. The returned parameters include all original tool calls
+     * configured for deterministic execution.
+     *
+     * @throws {@link FlowNotFoundException} When the specified flow doesn't exist
+     *
+     * @example
+     * ```http
+     * GET /api/flows/abc123/rerun
+     *
+     * Response: CreateDonobuFlow object ready for POST to /api/flows
+     * ```
+     *
+     * @public
      */
     async getFlowAsRerun(req, res) {
         const flowId = req.params.flowId;
@@ -42,7 +122,41 @@ class FlowsApi {
         res.json(createDonobuFlow);
     }
     /**
-     * Serves up flows' metadata as JSON with optional filtering.
+     * Retrieves paginated flows with optional filtering.
+     *
+     * Returns a list of flow metadata objects matching the specified criteria.
+     * Supports pagination, filtering by name/state/runMode, and time-based filtering.
+     * Results are ordered by startedAt timestamp in descending order (newest first).
+     *
+     * @throws {@link InvalidParamValueException} When query parameters are invalid
+     *
+     * @example
+     * ```http
+     * GET /api/flows?limit=10&state=SUCCESS&startedAfter=1640995200000
+     *
+     * Response:
+     * {
+     *   "flows": [
+     *     {
+     *       "id": "abc123",
+     *       "name": "Login Test",
+     *       "state": "SUCCESS",
+     *       "startedAt": 1641000000000,
+     *       // ... other metadata
+     *     }
+     *   ],
+     *   "nextPageToken": "eyJ..."
+     * }
+     * ```
+     *
+     * Query Parameters:
+     * - `pageToken`: Pagination token for subsequent pages
+     * - `limit`: Maximum results per page (1-100, default varies)
+     * - `name`: Filter by exact flow name
+     * - `runMode`: Filter by execution mode (AUTONOMOUS|INSTRUCT|DETERMINISTIC)
+     * - `state`: Filter by current state
+     * - `startedAfter`: Unix timestamp - flows started after this time
+     * - `startedBefore`: Unix timestamp - flows started before this time
      */
     async getFlows(req, res) {
         const query = {
@@ -82,52 +196,123 @@ class FlowsApi {
         res.json({ flows: flows.items, nextPageToken: flows.nextPageToken });
     }
     /**
-     * Creates a new DonobuFlow flow.
+     * Creates and starts a new Donobu flow.
+     *
+     * Validates the provided parameters, creates a new flow instance, and begins
+     * execution according to the specified run mode. The flow runs asynchronously
+     * after this method returns.
+     *
+     * @throws {@link InvalidParamValueException} When flow parameters are invalid
+     * @throws {@link ToolRequiresGptException} When tools require GPT but none configured
+     *
+     * @example
+     * ```http
+     * POST /api/flows
+     * Content-Type: application/json
+     *
+     * {
+     *   "targetWebsite": "https://example.com",
+     *   "overallObjective": "Sign up for an account",
+     *   "initialRunMode": "AUTONOMOUS",
+     *   "maxIterations": 20
+     * }
+     *
+     * Response: FlowMetadata object with state "UNSTARTED" or "INITIALIZING"
+     * ```
      */
     async createFlow(req, res) {
-        const flowParams = req.body;
+        const flowParams = CreateDonobuFlow_1.CreateDonobuFlowSchema.parse(req.body);
         const flow = (await this.donobuFlowsManager.createFlow(flowParams))
             .donobuFlow;
         res.json(flow.metadata);
     }
     /**
-     * Rename a flow.
+     * Updates the name of an existing flow.
+     *
+     * Changes the display name of the specified flow. The name is used for
+     * identification and organization purposes and can be null to clear the name.
+     *
+     * @throws {@link FlowNotFoundException} When the specified flow doesn't exist
+     * @throws {@link InvalidParamValueException} When the name exceeds 255 characters
+     *
+     * @example
+     * ```http
+     * POST /api/flows/abc123/rename
+     * Content-Type: application/json
+     *
+     * {
+     *   "name": "Updated Flow Name"
+     * }
+     * ```
      */
     async renameFlow(req, res) {
         const flowId = req.params.flowId;
-        const flowParams = req.body;
-        // Check if body is an object
-        if (!flowParams ||
-            typeof flowParams !== 'object' ||
-            Array.isArray(flowParams)) {
-            throw new InvalidParamValueException_1.InvalidParamValueException('requestBody', '(non-object)', 'expected an object');
-        }
-        // Validate that name exists and is either a string or null
-        if (!('name' in flowParams)) {
-            throw new InvalidParamValueException_1.InvalidParamValueException('name', 'undefined');
-        }
-        const { name } = flowParams;
-        if (name !== null && typeof name !== 'string') {
-            throw new InvalidParamValueException_1.InvalidParamValueException('name', JsonUtils_1.JsonUtils.objectToJson(name), `expected a string or null value`);
-        }
-        const metadata = await this.donobuFlowsManager.renameFlow(flowId, name);
+        const flowParams = zod_1.z.object({ name: zod_1.z.string() }).parse(req.body);
+        const metadata = await this.donobuFlowsManager.renameFlow(flowId, flowParams.name);
         res.json(metadata);
     }
     /**
-     * Delete a given flow by ID.
+     * Permanently deletes a flow and all associated data.
+     *
+     * Removes the flow from storage including metadata, tool calls, screenshots,
+     * and video recordings. This operation cannot be undone.
+     *
+     * @throws {@link FlowNotFoundException} When the specified flow doesn't exist
+     * @throws {@link CannotDeleteRunningFlowException} When attempting to delete an active flow
+     *
+     * @example
+     * ```http
+     * DELETE /api/flows/abc123
+     *
+     * Response: HTTP 200 OK
+     * ```
      */
     async deleteFlow(req, res) {
         const flowId = req.params.flowId;
         await this.donobuFlowsManager.deleteFlowById(flowId);
         res.sendStatus(200);
     }
+    /**
+     * Retrieves complete metadata for a specific flow.
+     *
+     * Returns the full {@link FlowMetadata} object containing current state,
+     * configuration, execution history, and results.
+     *
+     * @throws {@link FlowNotFoundException} When the specified flow doesn't exist
+     *
+     * @example
+     * ```http
+     * GET /api/flows/abc123
+     *
+     * Response: Complete FlowMetadata object
+     * ```
+     *
+     * @public
+     */
     async getFlowMetadata(req, res) {
         const flowId = req.params.flowId;
         const metadata = await this.donobuFlowsManager.getFlowById(flowId);
         res.json(metadata);
     }
     /**
-     * Pause the active flow by ID.
+     * 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.
+     *
+     * @throws {@link ActiveFlowNotFoundException} When the flow is not active locally
+     *
+     * @example
+     * ```http
+     * POST /api/flows/abc123/pause
+     *
+     * Response: FlowMetadata with nextState set to "PAUSED"
+     * ```
+     *
+     * @remarks
+     * This endpoint is only available in LOCAL deployment environments for security.
+     * The flow will complete its current action before pausing.
      */
     async pauseFlow(req, res) {
         const flowId = req.params.flowId;
@@ -138,7 +323,23 @@ class FlowsApi {
         res.json(flow.metadata);
     }
     /**
-     * Resume the paused active flow by ID.
+     * 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.
+     *
+     * @throws {@link ActiveFlowNotFoundException} When the flow is not active locally
+     *
+     * @example
+     * ```http
+     * POST /api/flows/abc123/resume
+     *
+     * Response: FlowMetadata with nextState set to "RESUMING"
+     * ```
+     *
+     * @remarks
+     * This endpoint is only available in LOCAL deployment environments for security.
+     * Only works on flows currently in PAUSED state.
      */
     async resumeFlow(req, res) {
         const flowId = req.params.flowId;
@@ -148,11 +349,39 @@ class FlowsApi {
         }
         res.json(flow.metadata);
     }
+    /**
+     * Cancels and terminates an active flow.
+     *
+     * Forcibly stops flow execution and sets the state to FAILED. For active
+     * flows, this closes the browser context and terminates the execution thread.
+     *
+     * @throws {@link FlowNotFoundException} When the specified flow doesn't exist
+     *
+     * @example
+     * ```http
+     * POST /api/flows/abc123/cancel
+     *
+     * Response: FlowMetadata with state "FAILED"
+     * ```
+     *
+     * @remarks
+     * This endpoint is only available in LOCAL deployment environments for security.
+     * Cannot be undone - the flow will need to be recreated to retry.
+     */
     async cancelFlow(req, res) {
         const flowId = req.params.flowId;
         const metadata = await this.donobuFlowsManager.cancelFlow(flowId);
         res.json(metadata);
     }
+    /**
+     * Parses and validates the limit query parameter.
+     *
+     * Converts the limit string to a number with appropriate defaults and bounds.
+     * Returns Number.MAX_SAFE_INTEGER if parsing fails to avoid artificial limits.
+     *
+     * @param limit - The limit query parameter value
+     * @returns Parsed limit number or maximum safe integer
+     */
     parseLimit(limit) {
         try {
             return limit ? parseInt(limit) : Number.MAX_SAFE_INTEGER;

package/dist/apis/FlowsApi.js.map

@@ -1 +1 @@
-{"version":3,"file":"FlowsApi.js","sourceRoot":"","sources":["../../src/apis/FlowsApi.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"FlowsApi.js","sourceRoot":"","sources":["../../src/apis/FlowsApi.ts"],"names":[],"mappings":"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"}

package/dist/apis/FlowsFilesApi.d.ts

@@ -1,9 +1,55 @@
 import { Request, Response } from 'express';
 import { FlowsPersistenceFactory } from '../persistence/flows/FlowsPersistenceFactory';
+/**
+ * API controller for serving flow-related binary files including images and video content.
+ *
+ * The FlowsFilesApi provides HTTP endpoints for retrieving binary assets associated with
+ * Donobu flows, specifically screenshots and video recordings captured during flow execution.
+ * This class handles proper content type detection, HTTP range requests for video streaming,
+ * and multi-layer persistence fallback for file retrieval.
+ */
 export declare class FlowsFilesApi {
     private readonly flowsPersistenceFactory;
     constructor(flowsPersistenceFactory: FlowsPersistenceFactory);
+    /**
+     * Retrieves and serves a flow-related image file (screenshot).
+     *
+     * This endpoint serves screenshot images captured during flow execution. The method:
+     * 1. Iterates through all available persistence layers in priority order
+     * 2. Attempts to locate the requested image in each layer
+     * 3. Automatically detects the image format (PNG/JPEG) and sets appropriate Content-Type
+     * 4. Returns 404 if the image is not found in any persistence layer
+     *
+     * **Supported Image Formats:**
+     * - PNG (`image/png`)
+     * - JPEG (`image/jpeg`)
+     *
+     * @throws {FlowNotFoundException} When the flow doesn't exist in any persistence layer
+     */
     getFlowImage(req: Request, res: Response): Promise<void>;
+    /**
+     * Retrieves and serves flow video recordings with HTTP range request support.
+     *
+     * This endpoint serves video recordings of flow executions, typically in WebM format.
+     * The method supports HTTP range requests for efficient video streaming and seeking,
+     * allowing clients to request specific byte ranges of large video files.
+     *
+     * **Key Features:**
+     * - HTTP Range Request support for video streaming
+     * - Automatic Content-Type detection (typically `video/webm`)
+     * - Partial content responses (HTTP 206) for range requests
+     * - Multi-layer persistence fallback
+     * - Proper Accept-Ranges header for client compatibility
+     *
+     * **Range Request Handling:**
+     * - Parses Range header to determine requested byte range
+     * - Supports single-range requests (e.g., `bytes=0-1023`)
+     * - Supports open-ended ranges (e.g., `bytes=1024-`)
+     * - Returns appropriate Content-Range header for partial responses
+     * - Falls back to full video if no Range header is provided
+     *
+     * @throws {FlowNotFoundException} When the flow doesn't exist in any persistence layer
+     */
     getFlowVideo(req: Request, res: Response): Promise<void>;
 }
 //# sourceMappingURL=FlowsFilesApi.d.ts.map

package/dist/apis/FlowsFilesApi.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"FlowsFilesApi.d.ts","sourceRoot":"","sources":["../../src/apis/FlowsFilesApi.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAC5C,OAAO,EAAE,uBAAuB,EAAE,MAAM,8CAA8C,CAAC;AAKvF,qBAAa,aAAa;IAEtB,OAAO,CAAC,QAAQ,CAAC,uBAAuB;gBAAvB,uBAAuB,EAAE,uBAAuB;IAGtD,YAAY,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IA6BxD,YAAY,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;CAmEtE"}
+{"version":3,"file":"FlowsFilesApi.d.ts","sourceRoot":"","sources":["../../src/apis/FlowsFilesApi.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAC5C,OAAO,EAAE,uBAAuB,EAAE,MAAM,8CAA8C,CAAC;AAKvF;;;;;;;GAOG;AACH,qBAAa,aAAa;IAEtB,OAAO,CAAC,QAAQ,CAAC,uBAAuB;gBAAvB,uBAAuB,EAAE,uBAAuB;IAGnE;;;;;;;;;;;;;;OAcG;IACU,YAAY,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IA6BrE;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACU,YAAY,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;CAmEtE"}

package/dist/apis/FlowsFilesApi.js

@@ -4,10 +4,33 @@ exports.FlowsFilesApi = void 0;
 const FlowNotFoundException_1 = require("../exceptions/FlowNotFoundException");
 const Logger_1 = require("../utils/Logger");
 const MiscUtils_1 = require("../utils/MiscUtils");
+/**
+ * API controller for serving flow-related binary files including images and video content.
+ *
+ * The FlowsFilesApi provides HTTP endpoints for retrieving binary assets associated with
+ * Donobu flows, specifically screenshots and video recordings captured during flow execution.
+ * This class handles proper content type detection, HTTP range requests for video streaming,
+ * and multi-layer persistence fallback for file retrieval.
+ */
 class FlowsFilesApi {
     constructor(flowsPersistenceFactory) {
         this.flowsPersistenceFactory = flowsPersistenceFactory;
     }
+    /**
+     * Retrieves and serves a flow-related image file (screenshot).
+     *
+     * This endpoint serves screenshot images captured during flow execution. The method:
+     * 1. Iterates through all available persistence layers in priority order
+     * 2. Attempts to locate the requested image in each layer
+     * 3. Automatically detects the image format (PNG/JPEG) and sets appropriate Content-Type
+     * 4. Returns 404 if the image is not found in any persistence layer
+     *
+     * **Supported Image Formats:**
+     * - PNG (`image/png`)
+     * - JPEG (`image/jpeg`)
+     *
+     * @throws {FlowNotFoundException} When the flow doesn't exist in any persistence layer
+     */
     async getFlowImage(req, res) {
         const flowId = req.params.flowId;
         const imageId = req.params.imageId;
@@ -33,6 +56,29 @@ class FlowsFilesApi {
         }
         res.sendStatus(404);
     }
+    /**
+     * Retrieves and serves flow video recordings with HTTP range request support.
+     *
+     * This endpoint serves video recordings of flow executions, typically in WebM format.
+     * The method supports HTTP range requests for efficient video streaming and seeking,
+     * allowing clients to request specific byte ranges of large video files.
+     *
+     * **Key Features:**
+     * - HTTP Range Request support for video streaming
+     * - Automatic Content-Type detection (typically `video/webm`)
+     * - Partial content responses (HTTP 206) for range requests
+     * - Multi-layer persistence fallback
+     * - Proper Accept-Ranges header for client compatibility
+     *
+     * **Range Request Handling:**
+     * - Parses Range header to determine requested byte range
+     * - Supports single-range requests (e.g., `bytes=0-1023`)
+     * - Supports open-ended ranges (e.g., `bytes=1024-`)
+     * - Returns appropriate Content-Range header for partial responses
+     * - Falls back to full video if no Range header is provided
+     *
+     * @throws {FlowNotFoundException} When the flow doesn't exist in any persistence layer
+     */
     async getFlowVideo(req, res) {
         const flowId = req.params.flowId;
         const rangeHeader = req.header('Range');

package/dist/apis/FlowsFilesApi.js.map

@@ -1 +1 @@
-{"version":3,"file":"FlowsFilesApi.js","sourceRoot":"","sources":["../../src/apis/FlowsFilesApi.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"FlowsFilesApi.js","sourceRoot":"","sources":["../../src/apis/FlowsFilesApi.ts"],"names":[],"mappings":"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"}

package/dist/apis/FlowsToolCallsApi.d.ts

@@ -1,18 +1,96 @@
 import { Request, Response } from 'express';
 import { DonobuFlowsManager } from '../managers/DonobuFlowsManager';
+/**
+ * API controller for managing tool calls within Donobu flows.
+ *
+ * The FlowsToolCallsApi provides endpoints for retrieving and proposing tool calls
+ * that are executed during flow runs. Tool calls represent individual actions taken
+ * by flows, such as clicking elements, inputting text, or analyzing page content.
+ * This API enables both historical analysis of flow execution and real-time
+ * interaction with running flows.
+ *
+ * **Key Concepts:**
+ * - **Tool Call**: A completed action with parameters, results, and metadata
+ * - **Proposed Tool Call**: A queued action waiting to be executed
+ * - **Tool Call History**: Chronological sequence of all actions in a flow
+ * - **Interactive Flow Control**: Real-time tool call injection during execution
+ *
+ * **Use Cases:**
+ * - Debugging flow execution by examining tool call sequences
+ * - Analyzing flow performance and action outcomes
+ * - Manual intervention during INSTRUCT mode flows
+ * - Flow replay and deterministic execution
+ *
+ * **Security Considerations:**
+ * - Tool call proposal is restricted to LOCAL deployment environments
+ * - Only active flows accept new tool call proposals
+ * - Tool parameters are validated before execution
+ */
 export declare class FlowsToolCallsApi {
     private readonly donobuFlowsManager;
     constructor(donobuFlowsManager: DonobuFlowsManager);
     /**
-     * Get all tool calls for a specific flow
+     * Retrieves all tool calls for a specific flow.
+     *
+     * Returns the complete chronological history of tool calls executed within
+     * the specified flow. Each tool call includes comprehensive execution details
+     * including parameters, outcomes, timing information, and associated metadata.
+     * The results are ordered by execution time (startedAt) to provide a clear
+     * sequence of actions.
+     *
+     * **Returned Information:**
+     * - Tool call ID and name
+     * - Input parameters and execution context
+     * - Success/failure status and result messages
+     * - Execution timing (start and completion timestamps)
+     * - Page URLs
+     * - Error details and debugging information
+     * - Screenshot references are included but image data is served separately
+     *   via the FlowsFilesApi
      */
     getToolCalls(req: Request, res: Response): Promise<void>;
     /**
-     * Get a specific tool call for a flow
+     * Retrieves a specific tool call by ID within a flow.
+     *
+     * Returns detailed information about a single tool call execution, including
+     * all parameters, results, and metadata. This endpoint is useful for detailed
+     * analysis of specific actions or troubleshooting particular tool call failures.
+     *
+     * **Response Details:**
+     * - Tool call ID and name
+     * - Input parameters and execution context
+     * - Success/failure status and result messages
+     * - Execution timing (start and completion timestamps)
+     * - Page URLs
+     * - Error details and debugging information
+     * - Screenshot references are included but image data is served separately
+     *   via the FlowsFilesApi
      */
     getToolCall(req: Request, res: Response): Promise<void>;
     /**
-     * Propose a new tool call for a flow
+     * Proposes a new tool call for execution in an active flow.
+     *
+     * This endpoint allows real-time injection of tool calls into running flows,
+     * primarily used during INSTRUCT mode execution where manual intervention
+     * is required. The proposed tool call is validated and queued for execution
+     * by the flow's main execution loop.
+     *
+     * **Important Restrictions:**
+     * - Available only in LOCAL deployment environments for security
+     * - Target flow must be actively running (not completed or failed)
+     * - Tool name must correspond to a valid, available tool
+     * - Parameters must conform to the tool's expected schema
+     *
+     * **Execution Flow:**
+     * 1. Validates the tool name and parameters
+     * 2. Checks that the target flow is active and accepting proposals
+     * 3. Queues the tool call in the flow's execution pipeline
+     * 4. Returns success confirmation (execution happens asynchronously)
+     *
+     * **Integration with Flow States:**
+     * - INSTRUCT mode: Tool calls are executed when proposed
+     * - AUTONOMOUS mode: Proposals may be ignored in favor of AI decisions
+     * - PAUSED flows: Proposals are queued until flow resumes
      */
     postToolCalls(req: Request, res: Response): Promise<void>;
 }

package/dist/apis/FlowsToolCallsApi.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"FlowsToolCallsApi.d.ts","sourceRoot":"","sources":["../../src/apis/FlowsToolCallsApi.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAC5C,OAAO,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAC;AAKpE,qBAAa,iBAAiB;IAChB,OAAO,CAAC,QAAQ,CAAC,kBAAkB;gBAAlB,kBAAkB,EAAE,kBAAkB;IAEnE;;OAEG;IACU,YAAY,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAMrE;;OAEG;IACU,WAAW,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAapE;;OAEG;IACU,aAAa,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;CAYvE"}
+{"version":3,"file":"FlowsToolCallsApi.d.ts","sourceRoot":"","sources":["../../src/apis/FlowsToolCallsApi.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAC5C,OAAO,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAC;AAIpE;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,qBAAa,iBAAiB;IACT,OAAO,CAAC,QAAQ,CAAC,kBAAkB;gBAAlB,kBAAkB,EAAE,kBAAkB;IAE1E;;;;;;;;;;;;;;;;;;OAkBG;IACU,YAAY,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAMrE;;;;;;;;;;;;;;;;OAgBG;IACU,WAAW,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAapE;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACU,aAAa,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;CAYvE"}