ExplorationLaunchRequest

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/revyl/json-schema/revyl-exploration-launch-request-schema.json",
  "title": "ExplorationLaunchRequest",
  "x-generated": "2026-11-10",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/revyl-explorations-api-openapi.yml#/components/schemas/ExplorationLaunchRequest",
  "properties": {
    "auth_instructions": {
      "anyOf": [
        {
          "maxLength": 4000,
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Auth Instructions"
    },
    "branch_id": {
      "anyOf": [
        {
          "format": "uuid",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Branch Id"
    },
    "branch_name": {
      "anyOf": [
        {
          "maxLength": 255,
          "minLength": 1,
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Branch Name"
    },
    "build_id": {
      "anyOf": [
        {
          "format": "uuid",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Build Id"
    },
    "build_selection": {
      "$ref": "#/$defs/BuildSelectionMode",
      "default": "inherit"
    },
    "context_branch_name": {
      "anyOf": [
        {
          "maxLength": 4096,
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Context Branch Name"
    },
    "device_model": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Device Model"
    },
    "env_vars": {
      "additionalProperties": {
        "type": "string"
      },
      "title": "Env Vars",
      "type": "object"
    },
    "idle_timeout_seconds": {
      "anyOf": [
        {
          "maximum": 7200.0,
          "minimum": 60.0,
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": 900,
      "title": "Idle Timeout Seconds"
    },
    "lane_count": {
      "default": 3,
      "maximum": 100.0,
      "minimum": 1.0,
      "title": "Lane Count",
      "type": "integer"
    },
    "lanes": {
      "items": {
        "$ref": "#/$defs/ExplorationLaneConfig"
      },
      "title": "Lanes",
      "type": "array"
    },
    "launch_env_var_ids": {
      "items": {
        "format": "uuid",
        "type": "string"
      },
      "title": "Launch Env Var Ids",
      "type": "array"
    },
    "max_duration_seconds": {
      "default": 1800,
      "maximum": 7200.0,
      "minimum": 60.0,
      "title": "Max Duration Seconds",
      "type": "integer"
    },
    "max_turns": {
      "anyOf": [
        {
          "maximum": 50.0,
          "minimum": 1.0,
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "title": "Max Turns"
    },
    "os_version": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Os Version"
    },
    "pinned_build_id": {
      "anyOf": [
        {
          "format": "uuid",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Pinned Build Id"
    },
    "platform": {
      "default": "ios",
      "title": "Platform",
      "type": "string"
    },
    "run_config": {
      "anyOf": [
        {
          "$ref": "#/$defs/TestRunConfig"
        },
        {
          "type": "null"
        }
      ]
    },
    "seed_instructions": {
      "anyOf": [
        {
          "maxLength": 4000,
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Seed Instructions"
    },
    "swarm_strategy": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": "balanced",
      "description": "Swarm allocation strategy; roles are derived programmatically.",
      "title": "Swarm Strategy"
    }
  },
  "type": "object",
  "$defs": {
    "BuildSelectionMode": {
      "enum": [
        "inherit",
        "latest",
        "pinned",
        "latest_all_branches"
      ],
      "title": "BuildSelectionMode",
      "type": "string"
    },
    "CacheRetryMode": {
      "description": "Cache retry policy for test execution.\n\n- NONE: No cache fallback, fail if cached steps fail\n- FULL_RERUN: If cached run fails, rerun entire test without cache",
      "enum": [
        "none",
        "full_rerun"
      ],
      "title": "CacheRetryMode",
      "type": "string"
    },
    "CleanupLevel": {
      "description": "Cleanup intensity level for AVD state reset between test runs.",
      "enum": [
        "none",
        "thorough",
        "deep_clean"
      ],
      "title": "CleanupLevel",
      "type": "string"
    },
    "DeviceCleanupConfig": {
      "description": "Configuration for AVD cleanup between test runs.\n\nControls what gets reset when resetting device state between tests\nwhile keeping the emulator running.",
      "properties": {
        "cleanup_level": {
          "$ref": "#/$defs/CleanupLevel",
          "default": "thorough",
          "description": "Level of cleanup to perform (default: THOROUGH for maximum cleanup)"
        },
        "clear_app_data": {
          "default": true,
          "description": "Clear app data and cache via pm clear",
          "title": "Clear App Data",
          "type": "boolean"
        },
        "clear_browser_data": {
          "default": true,
          "description": "Clear browsing data (history, cookies, cache) from all browsers",
          "title": "Clear Browser Data",
          "type": "boolean"
        },
        "clear_clipboard": {
          "default": true,
          "description": "Clear clipboard contents",
          "title": "Clear Clipboard",
          "type": "boolean"
        },
        "clear_downloads": {
          "default": true,
          "description": "Clear /sdcard/Download folder",
          "title": "Clear Downloads",
          "type": "boolean"
        },
        "clear_notifications": {
          "default": true,
          "description": "Clear all pending notifications from previous test sessions",
          "title": "Clear Notifications",
          "type": "boolean"
        },
        "clear_recent_apps": {
          "default": false,
          "description": "Clear recent apps list (requires root access, restarts framework). Expensive (~15-30s), broken on Play Store images. Auto-enabled for DEEP_CLEAN.",
          "title": "Clear Recent Apps",
          "type": "boolean"
        },
        "clear_shared_storage": {
          "default": true,
          "description": "Clear Pictures, DCIM, Movies, Music, Documents folders",
          "title": "Clear Shared Storage",
          "type": "boolean"
        },
        "custom_paths_to_clear": {
          "description": "Additional paths to clear on device",
          "items": {
            "type": "string"
          },
          "title": "Custom Paths To Clear",
          "type": "array"
        },
        "kill_background_apps": {
          "default": true,
          "description": "Kill all background applications",
          "title": "Kill Background Apps",
          "type": "boolean"
        },
        "reset_system_ui": {
          "default": false,
          "description": "Reset SystemUI state including wallpaper to defaults. Expensive (~2-3s). Auto-enabled for DEEP_CLEAN.",
          "title": "Reset System Ui",
          "type": "boolean"
        },
        "revoke_permissions": {
          "default": true,
          "description": "Revoke runtime permissions granted during test",
          "title": "Revoke Permissions",
          "type": "boolean"
        },
        "uninstall_new_apps": {
          "default": true,
          "description": "Uninstall apps that were installed during the test session",
          "title": "Uninstall New Apps",
          "type": "boolean"
        }
      },
      "title": "DeviceCleanupConfig",
      "type": "object"
    },
    "ExecutionModeConfig": {
      "description": "Configuration for execution modes and features.",
      "properties": {
        "cleanup_config": {
          "anyOf": [
            {
              "$ref": "#/$defs/DeviceCleanupConfig"
            },
            {
              "type": "null"
            }
          ],
          "description": "Configuration for AVD cleanup between test runs"
        },
        "enable_planning": {
          "default": false,
          "description": "Enable planning for complex steps",
          "title": "Enable Planning",
          "type": "boolean"
        },
        "enable_reflection": {
          "default": true,
          "description": "Enable reflection on failed steps",
          "title": "Enable Reflection",
          "type": "boolean"
        },
        "grounder_type": {
          "anyOf": [
            {
              "$ref": "#/$defs/GrounderType"
            },
            {
              "type": "null"
            }
          ],
          "default": "moondream3"
        },
        "initial_locale": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "description": "Initial device locale identifier, for example 'en_US' or 'fr_FR'",
          "title": "Initial Locale"
        },
        "initial_location": {
          "anyOf": [
            {
              "$ref": "#/$defs/LocationConfig"
            },
            {
              "type": "null"
            }
          ],
          "description": "Initial GPS location to set when simulator boots"
        },
        "initial_orientation": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "description": "Initial device orientation: 'portrait' or 'landscape'",
          "title": "Initial Orientation"
        },
        "network_capture": {
          "default": true,
          "description": "Attach an in-process TLS-capture agent to the (debuggable) app under test to record decrypted HTTP traffic. On by default (no-op/graceful on non-debuggable apps or attach failure); set False to disable as a per-run kill switch.",
          "title": "Network Capture",
          "type": "boolean"
        },
        "reflection_retries": {
          "default": 1,
          "description": "Number of reflection retry attempts",
          "title": "Reflection Retries",
          "type": "integer"
        },
        "retries": {
          "default": 1,
          "description": "Number of retry attempts",
          "title": "Retries",
          "type": "integer"
        },
        "skip_app_install": {
          "default": false,
          "description": "Skip app installation during test execution",
          "title": "Skip App Install",
          "type": "boolean"
        }
      },
      "title": "ExecutionModeConfig",
      "type": "object"
    },
    "ExplorationLaneConfig": {
      "properties": {
        "auth_instructions": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Auth Instructions"
        },
        "lane_index": {
          "title": "Lane Index",
          "type": "integer"
        },
        "role": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Role"
        },
        "seed_instructions": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Seed Instructions"
        }
      },
      "required": [
        "lane_index"
      ],
      "title": "ExplorationLaneConfig",
      "type": "object"
    },
    "FallbackTrigger": {
      "description": "When to trigger cache fallback.\n\n- FINAL_FAIL: Only trigger fallback if overall test fails",
      "enum": [
        "final_fail"
      ],
      "title": "FallbackTrigger",
      "type": "string"
    },
    "GrounderType": {
      "description": "Grounder configuration that determines the grounding model.\n\n- MOONDREAM/MOONDREAM3/MOONDREAM_CUSTOM/MODAL_CUSTOM: Two-step grounding\n- AUTO: Use GROUNDER_TYPE env var to determine grounder\n- NULL: Skip grounding (for testing/debugging)",
      "enum": [
        "moondream",
        "moondream3",
        "moondream_custom",
        "modal-custom",
        "auto",
        "null"
      ],
      "title": "GrounderType",
      "type": "string"
    },
    "LLMConfig": {
      "description": "Configuration for LLM models used in different stages.",
      "properties": {
        "planning_model": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "description": "LLM model for planning, defaults to primary_model if not set",
          "title": "Planning Model"
        },
        "primary_model": {
          "default": "gemini/gemini-3.8-flash",
          "description": "Primary LLM model for step execution",
          "title": "Primary Model",
          "type": "string"
        },
        "reflection_model": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "description": "LLM model for reflection, defaults to primary_model if not set",
          "title": "Reflection Model"
        }
      },
      "title": "LLMConfig",
      "type": "object"
    },
    "LocationConfig": {
      "description": "GPS location configuration for simulator/emulator.",
      "properties": {
        "latitude": {
          "description": "GPS latitude coordinate (-90 to 90)",
          "maximum": 90.0,
          "minimum": -90.0,
          "title": "Latitude",
          "type": "number"
        },
        "longitude": {
          "description": "GPS longitude coordinate (-180 to 180)",
          "maximum": 180.0,
          "minimum": -180.0,
          "title": "Longitude",
          "type": "number"
        }
      },
      "required": [
        "latitude",
        "longitude"
      ],
      "title": "LocationConfig",
      "type": "object"
    },
    "TestRunConfig": {
      "description": "Complete configuration for a test run.",
      "properties": {
        "cache_retry_mode": {
          "$ref": "#/$defs/CacheRetryMode",
          "default": "full_rerun",
          "description": "Cache retry policy"
        },
        "disable_grid": {
          "anyOf": [
            {
              "type": "boolean"
            },
            {
              "type": "null"
            }
          ],
          "description": "Admin-only: Disable grid preprocessing for grounding",
          "title": "Disable Grid"
        },
        "disable_video_validation": {
          "default": false,
          "description": "When true, skip the background video validation check on VALIDATION steps; the screenshot verdict alone decides validation outcomes.",
          "title": "Disable Video Validation",
          "type": "boolean"
        },
        "execution_mode": {
          "$ref": "#/$defs/ExecutionModeConfig",
          "default": {
            "enable_planning": false,
            "enable_reflection": true,
            "grounder_type": "moondream3",
            "network_capture": true,
            "reflection_retries": 1,
            "retries": 1,
            "skip_app_install": false
          },
          "description": "Execution mode configuration"
        },
        "fail_fast": {
          "anyOf": [
            {
              "type": "boolean"
            },
            {
              "type": "null"
            }
          ],
          "description": "When true, the test halts immediately on the first failed validation or non-zero script exit code instead of continuing through remaining steps. Unset inherits the test-level value under a workflow override and otherwise behaves as false.",
          "title": "Fail Fast"
        },
        "fallback_trigger": {
          "$ref": "#/$defs/FallbackTrigger",
          "default": "final_fail",
          "description": "When to trigger cache fallback"
        },
        "llm_config": {
          "$ref": "#/$defs/LLMConfig",
          "default": {
            "planning_model": "gemini/gemini-3.8-flash",
            "primary_model": "gemini/gemini-3.8-flash",
            "reflection_model": "gemini/gemini-3.8-flash"
          },
          "description": "LLM model configuration"
        },
        "run_id": {
          "anyOf": [
            {
              "format": "uuid",
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Run Id"
        }
      },
      "title": "TestRunConfig",
      "type": "object"
    }
  }
}