import type { Request, Response } from 'express';
import type { 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);
    /**
     * 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>;
    /**
     * 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>;
    /**
     * 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>;
}
//# sourceMappingURL=FlowsToolCallsApi.d.ts.map