← Files VeraARCHIVED FILE
modules/browser-automation/capabilities/gmail-search-export/capability.json
25 KB · Oct 2, 2026 · 00:29 UTC
{
"authority": {
"authentication": "operator_only",
"consequential_actions": "confirm_at_action_time",
"operator_authorized": true,
"secret_policy": "never_request_read_store"
},
"capability_id": "gmail-search-export",
"completion": {
"required_outputs": [
"messages"
],
"terminal_milestones": [
"collect-results",
"no-results"
]
},
"entry_milestone": "open-gmail",
"inputs": [
{
"enum_values": [],
"name": "query",
"purpose": "The Gmail search expression supplied for this run.",
"required": true,
"sensitivity": "private_runtime_only",
"type": "text"
},
{
"enum_values": [],
"name": "max-results",
"purpose": "Maximum number of currently visible result rows to export.",
"required": true,
"sensitivity": "non_sensitive",
"type": "number"
}
],
"milestones": [
{
"actions": [
{
"confirmation": "none",
"effect": "read_only",
"extract": null,
"id": "navigate-gmail-root",
"input_ref": null,
"intent": "Reset to the declared Gmail start state.",
"key": null,
"locator_candidates": [],
"operation": "goto",
"output_ref": null,
"path": "/mail/u/0/",
"postcondition": {
"comparator": null,
"expected": null,
"kind": "none",
"locator_candidates": [],
"output_ref": null,
"timeout_ms": 10000,
"value": null
},
"target_origin": "https://mail.google.com",
"timeout_ms": 10000
},
{
"confirmation": "none",
"effect": "read_only",
"extract": null,
"id": "wait-gmail-search",
"input_ref": null,
"intent": "Wait for Gmail's search control to become ready.",
"key": null,
"locator_candidates": [
{
"exact": true,
"kind": "role",
"role": "textbox",
"value": "Search mail"
},
{
"exact": true,
"kind": "role",
"role": "searchbox",
"value": "Search mail"
},
{
"exact": true,
"kind": "role",
"role": "combobox",
"value": "Search mail"
},
{
"exact": true,
"kind": "placeholder",
"role": null,
"value": "Search mail"
},
{
"exact": true,
"kind": "label",
"role": null,
"value": "Search mail"
}
],
"operation": "wait_for",
"output_ref": null,
"path": null,
"postcondition": {
"comparator": null,
"expected": null,
"kind": "locator_visible",
"locator_candidates": [
{
"exact": true,
"kind": "role",
"role": "textbox",
"value": "Search mail"
},
{
"exact": true,
"kind": "role",
"role": "searchbox",
"value": "Search mail"
},
{
"exact": true,
"kind": "role",
"role": "combobox",
"value": "Search mail"
},
{
"exact": true,
"kind": "placeholder",
"role": null,
"value": "Search mail"
},
{
"exact": true,
"kind": "label",
"role": null,
"value": "Search mail"
}
],
"output_ref": null,
"timeout_ms": 10000,
"value": null
},
"target_origin": null,
"timeout_ms": 10000
}
],
"id": "open-gmail",
"intent": "Reach the authenticated Gmail mailbox without inspecting message rows.",
"preconditions": [
"The operator has authenticated personally in the connected Chrome session."
],
"transitions": [
{
"next_milestone": "submit-search",
"terminal": false,
"when": {
"comparator": null,
"expected": null,
"kind": "always",
"locator_candidates": [],
"output_ref": null,
"timeout_ms": 10000,
"value": null
}
}
]
},
{
"actions": [
{
"confirmation": "none",
"effect": "reversible",
"extract": null,
"id": "fill-gmail-search",
"input_ref": "query",
"intent": "Fill Gmail's search control with the runtime query.",
"key": null,
"locator_candidates": [
{
"exact": true,
"kind": "role",
"role": "textbox",
"value": "Search mail"
},
{
"exact": true,
"kind": "role",
"role": "searchbox",
"value": "Search mail"
},
{
"exact": true,
"kind": "role",
"role": "combobox",
"value": "Search mail"
},
{
"exact": true,
"kind": "placeholder",
"role": null,
"value": "Search mail"
},
{
"exact": true,
"kind": "label",
"role": null,
"value": "Search mail"
}
],
"operation": "fill",
"output_ref": null,
"path": null,
"postcondition": {
"comparator": null,
"expected": null,
"kind": "locator_visible",
"locator_candidates": [
{
"exact": true,
"kind": "role",
"role": "textbox",
"value": "Search mail"
},
{
"exact": true,
"kind": "role",
"role": "searchbox",
"value": "Search mail"
},
{
"exact": true,
"kind": "role",
"role": "combobox",
"value": "Search mail"
},
{
"exact": true,
"kind": "placeholder",
"role": null,
"value": "Search mail"
},
{
"exact": true,
"kind": "label",
"role": null,
"value": "Search mail"
}
],
"output_ref": null,
"timeout_ms": 10000,
"value": null
},
"target_origin": null,
"timeout_ms": 10000
},
{
"confirmation": "none",
"effect": "reversible",
"extract": null,
"id": "press-gmail-search",
"input_ref": null,
"intent": "Run the search.",
"key": "Enter",
"locator_candidates": [
{
"exact": true,
"kind": "role",
"role": "textbox",
"value": "Search mail"
},
{
"exact": true,
"kind": "role",
"role": "searchbox",
"value": "Search mail"
},
{
"exact": true,
"kind": "role",
"role": "combobox",
"value": "Search mail"
},
{
"exact": true,
"kind": "placeholder",
"role": null,
"value": "Search mail"
},
{
"exact": true,
"kind": "label",
"role": null,
"value": "Search mail"
}
],
"operation": "press",
"output_ref": null,
"path": null,
"postcondition": {
"comparator": null,
"expected": null,
"kind": "url_includes",
"locator_candidates": [],
"output_ref": null,
"timeout_ms": 10000,
"value": "#search/{{query}}"
},
"target_origin": null,
"timeout_ms": 10000
}
],
"id": "submit-search",
"intent": "Submit the operator-supplied Gmail search expression.",
"preconditions": [
"The search expression has been supplied for this run.",
"Reading visible sender and displayed date metadata has been authorized for this process."
],
"transitions": [
{
"next_milestone": "collect-results",
"terminal": false,
"when": {
"comparator": null,
"expected": null,
"kind": "locator_visible",
"locator_candidates": [
{
"exact": false,
"kind": "role",
"role": "row",
"value": null
},
{
"exact": false,
"kind": "css",
"role": null,
"value": "tr.zA:visible"
}
],
"output_ref": null,
"timeout_ms": 5000,
"value": null
}
},
{
"next_milestone": "no-results",
"terminal": false,
"when": {
"comparator": null,
"expected": null,
"kind": "locator_visible",
"locator_candidates": [
{
"exact": false,
"kind": "text",
"role": null,
"value": "No emails matched your search"
},
{
"exact": false,
"kind": "text",
"role": null,
"value": "No emails"
},
{
"exact": false,
"kind": "text",
"role": null,
"value": "No messages matched your search"
}
],
"output_ref": null,
"timeout_ms": 5000,
"value": null
}
},
{
"next_milestone": "search-transient",
"terminal": false,
"when": {
"comparator": null,
"expected": null,
"kind": "locator_visible",
"locator_candidates": [
{
"exact": false,
"kind": "role",
"role": "progressbar",
"value": null
},
{
"exact": false,
"kind": "text",
"role": null,
"value": "Loading"
}
],
"output_ref": null,
"timeout_ms": 1000,
"value": null
}
},
{
"next_milestone": "search-transient",
"terminal": false,
"when": {
"comparator": null,
"expected": null,
"kind": "always",
"locator_candidates": [],
"output_ref": null,
"timeout_ms": 1000,
"value": null
}
}
]
},
{
"actions": [
{
"confirmation": "none",
"effect": "read_only",
"extract": {
"dedupe_by": [
"sender",
"displayed-date"
],
"empty_allowed": false,
"fields": [
{
"locator_candidates": [
{
"exact": false,
"kind": "css",
"role": null,
"value": "span[email]:visible"
},
{
"exact": false,
"kind": "css",
"role": null,
"value": ".yW:visible"
}
],
"name": "sender",
"read": {
"attribute": null,
"kind": "inner_text"
},
"required": true
},
{
"locator_candidates": [
{
"exact": false,
"kind": "css",
"role": null,
"value": "td.xW span:visible"
},
{
"exact": false,
"kind": "css",
"role": null,
"value": "td.xW:visible"
}
],
"name": "displayed-date",
"read": {
"attribute": null,
"kind": "inner_text"
},
"required": false
}
],
"limit_input_ref": "max-results",
"max_items": 100,
"mode": "list"
},
"id": "extract-gmail-results",
"input_ref": null,
"intent": "Extract sender and displayed date without opening messages or reading subjects.",
"key": null,
"locator_candidates": [
{
"exact": false,
"kind": "role",
"role": "row",
"value": null
},
{
"exact": false,
"kind": "css",
"role": null,
"value": "tr.zA:visible"
}
],
"operation": "extract",
"output_ref": "messages",
"path": null,
"postcondition": {
"comparator": "gte",
"expected": 1,
"kind": "output_count",
"locator_candidates": [],
"output_ref": "messages",
"timeout_ms": 10000,
"value": null
},
"target_origin": null,
"timeout_ms": 10000
}
],
"id": "collect-results",
"intent": "Extract the bounded visible search-result metadata to the private run artifact.",
"preconditions": [
"At least one visible Gmail result row is present."
],
"transitions": [
{
"next_milestone": null,
"terminal": true,
"when": {
"comparator": null,
"expected": null,
"kind": "output_nonempty",
"locator_candidates": [],
"output_ref": "messages",
"timeout_ms": 10000,
"value": null
}
}
]
},
{
"actions": [
{
"confirmation": "none",
"effect": "read_only",
"extract": null,
"id": "verify-empty-gmail-results",
"input_ref": null,
"intent": "Verify Gmail's accessible no-results state without reading any message row.",
"key": null,
"locator_candidates": [
{
"exact": false,
"kind": "text",
"role": null,
"value": "No emails matched your search"
},
{
"exact": false,
"kind": "text",
"role": null,
"value": "No emails"
},
{
"exact": false,
"kind": "text",
"role": null,
"value": "No messages matched your search"
}
],
"operation": "wait_for",
"output_ref": null,
"path": null,
"postcondition": {
"comparator": "eq",
"expected": 0,
"kind": "output_count",
"locator_candidates": [],
"output_ref": "messages",
"timeout_ms": 10000,
"value": null
},
"target_origin": null,
"timeout_ms": 10000
}
],
"id": "no-results",
"intent": "Complete with an empty structured result set when Gmail shows no matching conversations.",
"preconditions": [
"A declared accessible Gmail no-results marker is visible and no result row will be read."
],
"transitions": [
{
"next_milestone": null,
"terminal": true,
"when": {
"comparator": null,
"expected": null,
"kind": "output_empty",
"locator_candidates": [],
"output_ref": "messages",
"timeout_ms": 10000,
"value": null
}
}
]
},
{
"actions": [
{
"confirmation": "none",
"effect": "read_only",
"extract": null,
"id": "wait-gmail-result-state",
"input_ref": null,
"intent": "Wait once for Gmail's transient loading state to resolve to results or an accessible no-results marker.",
"key": null,
"locator_candidates": [
{
"exact": false,
"kind": "role",
"role": "row",
"value": null
},
{
"exact": false,
"kind": "text",
"role": null,
"value": "No emails matched your search"
},
{
"exact": false,
"kind": "text",
"role": null,
"value": "No emails"
},
{
"exact": false,
"kind": "text",
"role": null,
"value": "No messages matched your search"
},
{
"exact": false,
"kind": "css",
"role": null,
"value": "tr.zA:visible"
}
],
"operation": "wait_for",
"output_ref": null,
"path": null,
"postcondition": {
"comparator": null,
"expected": null,
"kind": "locator_visible",
"locator_candidates": [
{
"exact": false,
"kind": "role",
"role": "row",
"value": null
},
{
"exact": false,
"kind": "text",
"role": null,
"value": "No emails matched your search"
},
{
"exact": false,
"kind": "text",
"role": null,
"value": "No emails"
},
{
"exact": false,
"kind": "text",
"role": null,
"value": "No messages matched your search"
},
{
"exact": false,
"kind": "css",
"role": null,
"value": "tr.zA:visible"
}
],
"output_ref": null,
"timeout_ms": 10000,
"value": null
},
"target_origin": null,
"timeout_ms": 10000
}
],
"id": "search-transient",
"intent": "Bound one retry while Gmail is loading or has not yet exposed a terminal result state.",
"preconditions": [
"The mailbox is ready and the exact search route is active.",
"Neither result rows nor an accessible no-results marker appeared during the initial bounded probe."
],
"transitions": [
{
"next_milestone": "collect-results",
"terminal": false,
"when": {
"comparator": null,
"expected": null,
"kind": "locator_visible",
"locator_candidates": [
{
"exact": false,
"kind": "role",
"role": "row",
"value": null
},
{
"exact": false,
"kind": "css",
"role": null,
"value": "tr.zA:visible"
}
],
"output_ref": null,
"timeout_ms": 1000,
"value": null
}
},
{
"next_milestone": "no-results",
"terminal": false,
"when": {
"comparator": null,
"expected": null,
"kind": "locator_visible",
"locator_candidates": [
{
"exact": false,
"kind": "text",
"role": null,
"value": "No emails matched your search"
},
{
"exact": false,
"kind": "text",
"role": null,
"value": "No emails"
},
{
"exact": false,
"kind": "text",
"role": null,
"value": "No messages matched your search"
}
],
"output_ref": null,
"timeout_ms": 1000,
"value": null
}
}
]
}
],
"outputs": [
{
"delivery": "artifact_only",
"description": "Visible Gmail sender and displayed-date metadata written to outputs.json without storing search text, subjects, message content, or emitting record values in the model response.",
"fields": [
{
"name": "sender",
"required": true,
"type": "text"
},
{
"name": "displayed-date",
"required": false,
"type": "text"
}
],
"name": "messages",
"sensitivity": "private",
"type": "record_set"
}
],
"privacy": {
"model_data": [
"Capability instructions, action outcomes, branch result, output record count, hashes, and sanitized errors",
"During discovery only, the exact private result fields named by the operator may enter the selected model context after a separate query-specific authorization; observed values are not written to the discovery record or portable capability",
"Sender and displayed date values remain in the owner-only outputs.json artifact unless the operator separately requests model interpretation; raw Gmail search text, message subjects, and message content are not read into or written to receipts or artifacts",
"For bounded locator recovery, the current model receives the action intent and contract, declared locator candidates, current origin and query-free path, postcondition kind, and a sanitized failure hash, but not the Gmail query or output values"
],
"portable_artifact_excludes": [
"credentials",
"cookies",
"browser_storage",
"session_urls",
"page_html",
"screenshots",
"network_bodies",
"downloaded_file_bytes",
"observed_private_values"
],
"private_evidence_retained": false
},
"process": {
"name": "Gmail search-result metadata export",
"objective": "Run an operator-supplied Gmail search and write sender and displayed date metadata for the bounded visible result set to a private local JSON artifact without storing the search text or message subjects.",
"out_of_scope": [
"Open or read message bodies",
"Send, draft, label, archive, move, or delete mail",
"Download attachments",
"Retain account identifiers, browser state, or authentication material"
]
},
"provenance": {
"discovery_approval_id": null,
"discovery_approved_at": null,
"discovery_record_sha256": "0eb57b46f09c73dbeadde046765da746458ee35d841f4c02a6b6af2c34d1ca93",
"portable_bundle_contains_private_evidence": false,
"source": "live_discovery_unreviewed"
},
"runtime": {
"browser": "existing_chrome",
"controller": "chrome_extension",
"mechanical_driver": "playwright",
"os_fallback": "operator_handoff_on_native_gap",
"semantic_driver": "model"
},
"schema_version": "browser-capability/v2",
"site": {
"allowed_origins": [
"https://mail.google.com"
],
"name": "Gmail",
"start_url": "https://mail.google.com/mail/u/0/"
},
"status": "draft",
"validation": {
"environment_scope": "not_validated",
"execution_contract_sha256": null,
"known_limits": [
"The four-state Gmail readiness contract and runtime/11 bounded extraction retry create a new unreviewed draft lineage; prior receipts do not validate this execution contract.",
"Search submission fails closed unless the current Gmail URL, after bounded percent-decoding, contains the exact #search/{{query}} route; inbox-root rows cannot satisfy this proof.",
"Mailbox ready, results available, accessible no-results, and transient/loading are separate states; a persistent transient state fails closed after one bounded retry.",
"The Gmail row and field locators were observed in one authorized account, but this updated contract requires renewed query-scoped authoring review and two clean runtime replays.",
"The accessible no-results labels may vary by locale; a new semantic variant requires bounded model-led recovery and operator review before persistence."
],
"receipts": []
},
"version": "0.6.0"
}
SHA-256: b28b8001f181f823d4eb65794acb3763f4838abbc7e5ec9a08ee8176eca0868c