import { z } from 'zod';
import { defineTool, } from '../toolDefinition.js';
import { AgentToolNames } from './agentToolNames.js';
/**
 * GetTestRunScreenshotsDefinition - Tool definition for fetching screenshots from a test run.
 */
export const getTestRunScreenshotsParamsSchema = z.object({
    test_run_id: z.string().meta({
        description: 'Required. Test run ID to fetch screenshots from.',
    }),
    step_indices: z
        .array(z.number())
        .optional()
        .meta({
        // The `Failed Step Number` reference below mirrors the label rendered by
        // `server-agents/src/agent/artifacts/testRecoveryContextArtifact.ts` — keep them in sync.
        description: [
            'Specific step indices to get screenshots for.',
            `These are 0-based execution-order indices (flat across nested steps and loop iterations) — they match the \`stepIndex\` returned by \`${AgentToolNames.GetTestRunInfo}\` and the \`stepIndex\` in this tool's response.`,
            'They are NOT the user-facing dotted step numbers like "21" or "5.2" (that is `stepNumber`, and the same value also appears in the failure prompt as `Failed Step Number`).',
            `Prefer \`step_id_in_flow\` when you have the step's stable ID (e.g. from the failure prompt or a previous \`${AgentToolNames.GetTestRunInfo}\` call), especially when comparing screenshots across runs.`,
            'If not specified, uses step_start_index and step_end_index.',
        ].join(' '),
    }),
    step_start_index: z
        .number()
        .optional()
        .meta({
        description: [
            'Start of an execution-order step range (0-based, inclusive).',
            'Same index space as `step_indices` — NOT the dotted step number.',
            'Used if step_indices not specified. Default: 0',
        ].join(' '),
    }),
    step_end_index: z
        .number()
        .optional()
        .meta({
        description: [
            'End of an execution-order step range (0-based, inclusive).',
            'Same index space as `step_indices` — NOT the dotted step number.',
            'Used if step_indices not specified. Default: last step',
        ].join(' '),
    }),
    step_run_ids: z.array(z.string()).optional().meta({
        description: 'Filter screenshots by step_run_id. Takes precedence over all other filter params.',
    }),
    step_id_in_flow: z
        .array(z.string())
        .optional()
        .meta({
        description: 'Filter screenshots by stable step ID (step_id_in_flow). ' +
            'Unlike step_run_id, this ID is stable across runs — the same step definition always has the same step_id_in_flow. ' +
            'Use this to find screenshots of a specific step from a previous run without needing to look up execution indices. ' +
            'Takes precedence over step_indices and index range params. Lower precedence than step_run_ids.',
    }),
    include_element_highlights: z
        .boolean()
        .optional()
        .meta({
        description: 'Whether to draw element highlight overlays on screenshots that have bounding box data. ' +
            'Default: true. Set to false to get the original unmodified screenshots.',
    }),
});
const screenshotInfoSchema = z.object({
    stepIndex: z.number().meta({
        description: 'Execution-order step index (0-based). This matches the step indices from get_test_run_info. ' +
            'For looped flows, each iteration has unique indices.',
    }),
    stepNumber: z.string().meta({
        description: 'Human-readable step number with dotted notation for nested steps (1-based). ' +
            'Examples: "5" for step 5, "3.2" for step 2 inside step group at position 3. ' +
            'Use this for display purposes instead of computing from stepIndex/nestedStepPath.',
    }),
    nestedStepPath: z
        .array(z.number())
        .optional()
        .meta({
        description: 'Path of step indices for nested steps. Format: [flow_index, step_index_in_flow, ...]. ' +
            'Example: [2, 1] means this step is within flow at index 2, and is step 1 within that flow. ' +
            'For step groups: [flow_index, step_group_index, step_in_group]. ' +
            'Empty or undefined for top-level steps in the main flow.',
    }),
    flowRunIndex: z
        .number()
        .optional()
        .meta({
        description: 'For flows that execute multiple times (loops), the 0-based loop iteration (0=first, 1=second, etc). ' +
            'Only present if the flow ran more than once.',
    }),
    stepDescription: z.string().meta({ description: 'Step description' }),
    screenshotUrl: z.string().optional().meta({
        description: 'URL to the screenshot (gs:// format).',
    }),
    mediaType: z.string().meta({ description: 'Media type of the screenshot' }),
    stepId: z.string().optional().meta({
        description: 'Stable step identifier within the flow. Cross-reference with get_test_run_info step data.',
    }),
    stepRunId: z.string().optional().meta({
        description: 'Unique identifier for this specific step execution instance.',
    }),
    hasElementHighlight: z.boolean().meta({
        description: 'When true, the screenshot image has an orange (#FD812A) bounding box outline drawn around ' +
            'the element that was interacted with during this step (clicks, text entry, etc.).',
    }),
});
export const getTestRunScreenshotsResponseSchema = z.object({
    screenshots: z.array(screenshotInfoSchema).meta({ description: 'List of screenshots with metadata' }),
    totalAvailable: z.number().meta({ description: 'Total number of screenshots available in the test run' }),
    note: z.string().optional().meta({ description: 'Any notes about the response, e.g., if screenshots were truncated' }),
});
export const GetTestRunScreenshotsToolDefinition = defineTool({
    name: AgentToolNames.GetTestRunScreenshots,
    description: `Retrieves screenshots from a test run for visual analysis.

Use this tool to:
- View what the application looked like at specific steps
- Analyze visual differences or issues
- Understand the state of the UI when failures occurred
- Compare screenshots from different steps

You can request screenshots by:
- Specific step execution IDs (step_run_ids) - most precise, from get_test_run_info results
- Stable step IDs (step_id_in_flow) - same step definition across runs, from get_test_run_info or get_test_run_screenshots results
- Specific step indices (step_indices) - use execution-order indices from get_test_run_info
- A range of steps (step_start_index to step_end_index)

Best practices:
- First use get_test_run_info to see all steps and identify the failed/important ones
- Request only the steps you need to analyze (e.g., failed step, steps around the failure)

The tool returns:
- Screenshot metadata for each step (step index, description, loop info)
- Actual image data for you to analyze visually`,
    argumentsSchema: getTestRunScreenshotsParamsSchema,
    responseSchema: getTestRunScreenshotsResponseSchema,
});
//# sourceMappingURL=GetTestRunScreenshotsDefinition.js.map