donobu/dist/apis/FlowsToolCallsApi.js

Create browser automations with an LLM agent and replay them as Playwright scripts.

"use strict";
Object.defineProperty(exports, "__esModule", { value: true });
exports.FlowsToolCallsApi = void 0;
const ToolCallNotFoundException_1 = require("../exceptions/ToolCallNotFoundException");
const ProposedToolCall_1 = require("../models/ProposedToolCall");
/**
 * 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
 */
class FlowsToolCallsApi {
    constructor(donobuFlowsManager) {
        this.donobuFlowsManager = donobuFlowsManager;
    }
    /**
     * 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
     */
    async getToolCalls(req, res) {
        const flowId = String(req.params.flowId);
        const toolCalls = await this.donobuFlowsManager.getToolCalls(flowId);
        res.json(toolCalls);
    }
    /**
     * 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
     */
    async getToolCall(req, res) {
        const flowId = String(req.params.flowId);
        const toolCallId = String(req.params.toolCallId);
        const toolCalls = await this.donobuFlowsManager.getToolCalls(flowId);
        const response = toolCalls.find((call) => call.id === toolCallId);
        if (!response) {
            throw new ToolCallNotFoundException_1.ToolCallNotFoundException(toolCallId);
        }
        res.json(response);
    }
    /**
     * 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
     */
    async postToolCalls(req, res) {
        const flowId = String(req.params.flowId);
        const parsedBody = ProposedToolCall_1.ProposedToolCallSchema.parse(req.body);
        await this.donobuFlowsManager.proposeToolCall(flowId, parsedBody.name, parsedBody.parameters);
        res.sendStatus(200);
    }
}
exports.FlowsToolCallsApi = FlowsToolCallsApi;
//# sourceMappingURL=FlowsToolCallsApi.js.map