/**
 * Tool Response Helpers
 * Functions for modifying tool responses with pre/post content
 */
import type { PortFailureInfo, PendingStartupFailureInfo, PendingRestartInfo } from './server-manager.js';
import type { Connection } from './connection-manager.js';
/**
 * Tool response content item
 */
export interface ContentItem {
    type: string;
    text?: string;
    [key: string]: unknown;
}
/**
 * Click action metadata
 */
export interface ClickActionMeta {
    selector: string;
    preClickUrl: string;
    postClickUrl: string;
    navigationOccurred: boolean;
    hasClickHandler: boolean;
    domChanges: {
        mutationCount: number;
        added: number;
        removed: number;
        shown: number;
        hidden: number;
    } | null;
}
/**
 * Type action metadata
 */
export interface TypeActionMeta {
    selector: string;
    text: string;
    actualValue: string;
}
/**
 * Navigate action metadata
 */
export interface NavigateActionMeta {
    url: string;
    title: string;
    action: string;
}
/**
 * Console tool metadata
 */
export interface ConsoleToolMeta {
    totalCount: number;
    matchCount?: number;
    errorCount?: number;
    warnCount?: number;
    /** Number of messages that were truncated */
    truncatedCount?: number;
    /** Total estimated tokens for all full messages */
    totalTokens?: number;
}
/**
 * Network tool metadata
 */
export interface NetworkToolMeta {
    totalCount: number;
    matchCount?: number;
}
/**
 * Content tool metadata (findInteractive)
 */
export interface ContentToolMeta {
    /** interactive elements on the page */
    totalCount: number;
    /** of those, not currently visible */
    hiddenCount?: number;
}
/**
 * Request tool metadata (HTTP request/response, capturable via saveAs)
 */
export interface RequestToolMeta {
    ok: boolean;
    status: number;
    statusText: string;
    headers: Record<string, string>;
    body: string;
    durationMs: number;
}
/**
 * Inspect tool metadata (evaluateExpression result, capturable via saveAs).
 *
 * `value` is a best-effort de-formatted view of the evaluated result: the
 * CDP layer returns values already shaped for display (strings arrive quoted,
 * numbers/booleans arrive as strings), so this reverses that so a captured
 * variable holds the real type rather than its display text.
 */
export interface InspectToolMeta {
    expression: string;
    value: unknown;
    /** typeof `value` ('undefined' when the expression evaluated to undefined) */
    valueType: string;
    /**
     * How `value` was obtained: 'exact' = by-value CDP capture (faithful
     * machine-readable value); 'display' = reconstructed from the rendered
     * display text (best effort - non-serializable values only).
     */
    valueSource?: 'exact' | 'display';
    /** Set when the expression was evaluated against a paused call frame */
    callFrameId?: string;
}
/**
 * Storage tool metadata (IndexedDB reads).
 *
 * Exists so a caller can ask "is this record there?" without grepping the
 * rendered markdown: a stored value that happens to contain the tool's own
 * "No record found for this key." text made a present record read as absent.
 */
export interface StorageToolMeta {
    /** IndexedDB only */
    database?: string;
    /** IndexedDB only */
    store?: string;
    /** idbGet / getLocalStorage / getSessionStorage: whether the key resolved */
    found?: boolean;
    /** the key that was probed, where the call named one */
    key?: string;
    /** getCookies: the names present, so a caller can test for one without reading the rendered text */
    cookieNames?: string[];
    /** idbGetAll: records returned (bounded by `limit`). getCookies / whole-store reads: entries present */
    count?: number;
    /** idbGetAll: records in the store, ignoring `limit` */
    total?: number;
}
/**
 * Assert tool metadata
 */
export interface AssertToolMeta {
    left: unknown;
    operator: string;
    right?: unknown;
    passed: boolean;
}
/**
 * Wait tool metadata
 */
export interface WaitToolMeta {
    /** Which form ran */
    form: 'selector' | 'selectorGone' | 'expression' | 'ms';
    /** The selector/expression waited on (or "Nms" for the sleep form) */
    condition: string;
    /** True when the condition was met (always true for the sleep form) */
    satisfied: boolean;
    elapsedMs: number;
    /** Number of MCP-side evaluations performed (0 for the sleep form) */
    polls: number;
}
/**
 * Replay run metadata - structured completion signal, since a "run" can
 * finish with failed steps or pause (stepTo/breakpoint/click-validation)
 * while still returning a non-isError response (a caller has to read this
 * to tell those apart from a clean run instead of text-scraping the reply).
 */
export interface ReplayRunMeta {
    /** Not set on a background-start response (runId + background instead). */
    success?: boolean;
    totalSteps: number;
    failedSteps?: number;
    paused?: boolean;
    /** Id of the registered background run (background start / status replies). */
    runId?: string;
    /** True on the immediate response of a background `run` start. */
    background?: boolean;
    /** Registry status of the run (status action replies). */
    runStatus?: string;
    /** 1-based step currently executing (status action replies). */
    currentStep?: number;
    /** recordInteraction: the person closed the recorder without saving. */
    cancelled?: boolean;
}
/**
 * Root metadata structure for tool responses
 * This provides structured data for programmatic use (validation, replay)
 * while keeping text content free to evolve for human/LLM display
 */
export interface ToolResponseMeta {
    tool: string;
    action?: string;
    timestamp: number;
    click?: ClickActionMeta;
    type?: TypeActionMeta;
    navigate?: NavigateActionMeta;
    console?: ConsoleToolMeta;
    network?: NetworkToolMeta;
    content?: ContentToolMeta;
    request?: RequestToolMeta;
    inspect?: InspectToolMeta;
    assert?: AssertToolMeta;
    wait?: WaitToolMeta;
    storage?: StorageToolMeta;
    replay?: ReplayRunMeta;
}
/**
 * Tool response structure
 */
export interface ToolResponse {
    content: ContentItem[];
    isError?: boolean;
    /** Structured metadata for programmatic use (validation, replay). Decoupled from text output. */
    _meta?: ToolResponseMeta;
}
/**
 * Blocking response - prevents tool execution
 */
export interface BlockingResponse {
    blocked: true;
    response: ToolResponse;
}
/**
 * Non-blocking response - allows tool execution with optional modifications
 */
export interface NonBlockingResponse {
    blocked: false;
    prefix: string;
    markAsError: boolean;
}
export type PreExecutionResult = BlockingResponse | NonBlockingResponse;
/**
 * Check for port failures and determine pre-execution behavior
 */
export declare function checkPortFailures(failedPorts: PortFailureInfo[], toolName: string): PreExecutionResult;
/**
 * Check for blocking bugs from recordings
 * Only allows the 'acknowledge' action in the issues tool
 */
export declare function checkBugBlocking(toolName: string, toolArgs?: Record<string, unknown>): Promise<PreExecutionResult>;
/**
 * Information about a paused breakpoint
 */
export interface BreakpointPauseInfo {
    reference: string;
    location?: {
        url: string;
        lineNumber: number;
    };
    callFrameId?: string;
    /** Set when a watch-mode restart is queued behind this pause - see server-manager's WatchRestartState. */
    pendingRestart?: PendingRestartInfo;
}
/**
 * Check for breakpoint pauses and determine pre-execution behavior
 * Similar to checkPortFailures, but for breakpoint blocking
 */
export declare function checkBreakpointPause(connections: Connection[], toolName: string, getPendingRestart?: (port: number) => PendingRestartInfo | null, action?: string): PreExecutionResult;
/**
 * Check for pending startup failures and determine pre-execution behavior
 * Blocks tools when servers have failed to start (timeout or died) and not acknowledged
 */
export declare function checkPendingStartups(failures: PendingStartupFailureInfo[], toolName: string): PreExecutionResult;
/**
 * Duplicate session info for blocking check
 */
export interface DuplicateSessionInfo {
    sessionId: string;
    shortId: string;
    allPids: number[];
    allPpids: number[];
    currentPid: number;
    currentPpid: number;
}
/**
 * Check for duplicate session (multiple MCPs sharing same Claude session)
 * Both original and duplicate sessions are blocked with appropriate messages
 */
export declare function checkDuplicateSession(info: DuplicateSessionInfo | null, toolName: string): PreExecutionResult;
/**
 * Prepend text to the first text content item in a response
 */
export declare function prependToResponse(response: ToolResponse, prefix: string): void;
/**
 * Append text to the last text content item in a response
 */
export declare function appendToResponse(response: ToolResponse, suffix: string): void;
/**
 * Status line item for post-response status
 */
export interface StatusLineItem {
    label: string;
    value: string;
}
/**
 * Build status lines suffix from items
 */
export declare function buildStatusSuffix(items: StatusLineItem[]): string;
//# sourceMappingURL=tool-response.d.ts.map