Response schema

Visor returns a structured JSON envelope for normal commands. If you run visor --help, visor -h, or invoke the CLI with no command, the CLI prints a plain-text usage summary instead. If you run visor --version or visor -v, the CLI prints the package version instead.

Top-level envelope

Field	Type	Meaning
`status`	string	`ok` or `fail`
`command_id`	string	Unique command invocation id
`started_at`	string	UTC timestamp
`ended_at`	string	UTC timestamp
`artifacts`	array of string	Artifact paths associated with the response
`next_action`	string	Hint for the next logical operation
`error`	object	Present only on failure
`data`	object	Command-specific payload

Error payload

Field	Type	Meaning
`code`	string	Structured error code
`message`	string	Human-readable summary
`likely_cause`	string	Best current explanation
`next_step`	string	Suggested remediation

Run result

When a scenario run succeeds or fails, data.run contains a run result.

Field	Type	Meaning
`run_id`	string	Unique run id
`platform`	string	`android` or `ios`
`device`	string	Resolved device name
`started_at`	string	Run start timestamp
`ended_at`	string	Run end timestamp
`status`	string	`ok` or `fail`
`steps`	array	Ordered step results
`assertions`	array	Assertion results
`artifacts`	array of string	Final copied artifact paths
`determinism_signature`	string	SHA-256 signature of normalized run data
`seed`	number	Present when the scenario provides a seed
`map`	object	Present when mapped execution was considered for the run
`error`	object	Present when the run failed

Step result

Field	Type	Meaning
`id`	string	Step id
`command`	string	Executed command
`status`	string	`ok` or `fail`
`duration_ms`	number	Step duration
`details`	object	Adapter-returned payload
`error`	object	Present when the step failed

Map metadata

Mapped execution metadata uses these fields:

Field	Type	Meaning
`enabled`	boolean	Whether Visor enabled map reads and writes
`used`	boolean	Whether Visor used cached map knowledge for routing
`updated`	boolean	Whether the host app map changed during the command
`repaired`	boolean	Whether Visor repaired a stale or missing route
`repairs`	number	Count of bounded repair passes used
`schema_version`	number	App-map schema version
`path`	string	Host path to the persisted app map when enabled
`agent_path`	string	Host path to compact AI-only semantic memory
`identity`	string	App-map identity, scoped by platform and app id
`summary`	object	Path-free app-map inventory attached to `visor discover` responses when the persisted map can be read

Direct action commands return this object in data.map. Scenario runs return it in data.run.map. A routed or repaired step may also include details.map.route, an ordered list of hidden route actions Visor performed before the requested step action. visor discover adds data.map.summary when Visor enables mapped execution and can read the persisted map file. You can safely share the summary in reviews because it does not include the host map path.

Summary field	Type	Meaning
`schema_version`	number	App-map schema version read from disk
`identity`	string	App-map identity, scoped by platform and app id
`app_id`	string	App id used for the map
`platform`	string	`android` or `ios`
`screens`	number	Count of discovered logical screens
`variants`	number	Count of discovered screen variants
`edges`	number	Count of recorded navigation edges
`actions`	number	Count of stored action affordances
`auth_required_variants`	number	Count of variants marked as requiring authentication
`updated_at`	string	Last persisted map update timestamp

Discovery annotation result

When visor discover --annotate-current <file|-> succeeds, data.annotation confirms the semantic update applied to the variant observed by that command.

Field	Type	Meaning
`screen_applied`	boolean	Whether Visor applied screen semantics
`actions_inserted`	number	Standalone actions newly stored
`actions_updated`	number	Existing semantic actions changed
`actions_merged`	number	Source-derived actions enriched while retaining execution metadata

The same response includes data.screen.variant_id and data.screen.screen_id. Visor applies annotation before data.crawl when you use both options. data.observation_token identifies the exact discovery observation. Pass it back with --observation-token to annotate without another device source read. data.memory contains the compact current-screen slice, relevant routes, and semantic gaps.

Route result

visor route returns these fields in data:

Field	Type	Meaning
`action`	string	Always `route`
`status`	string	`completed`, `failed`, or `needs_discovery`
`goal`	string	Semantic plan goal
`selected_path`	string	Path that completed, when successful
`attempts`	array	Ordered path attempts and typed step outcomes
`checkpoint_path`	string	Atomic checkpoint with the plan, attempts, current observation token, and resume position
`current_screen`	object	Compact final screen after success
`rediscovery`	object	Exact observation token and compact unknown-state context
`recovery`	object	Prior attempts when the daemon recreated a dropped Appium session

Each step reports success, runtime_failure, or verification_failure. A path reports completed, failed, or skipped.

Assertion result

Assertion results are plain objects with these fields:

Field	Type	Meaning
`id`	string	Assertion id
`type`	string	Assertion type
`target`	string	Selector that was checked
`status`	string	`passed` or `failed`
`details`	string	Failure or informational detail

Benchmark result payload

Benchmark responses store their command-specific payload in data.

Field	Type	Meaning
`runs`	number	Number of iterations attempted
`threshold`	number	Required determinism threshold
`determinismScore`	number	Calculated score
`pass`	boolean	Whether the benchmark passed
`failures`	number	Count of failed iterations
`runIds`	array of string	Run ids created during the benchmark
`warnings`	array	Validation warnings carried through from scenario parsing

Validation payload

Validation responses use this data structure:

Field	Type	Meaning
`valid`	boolean	Whether the scenario passed validation
`issues`	array	Validation errors and warnings

Important behavior:

schema-invalid scenarios return status: "ok" with data.valid: false and a non-zero process exit code
malformed JSON or unreadable files return a failure envelope with status: "fail"

Each issue contains:

severity
code
message
path

Example envelope

{
  "status": "ok",
  "command_id": "cmd_123456789abc",
  "started_at": "2026-03-29T16:00:00Z",
  "ended_at": "2026-03-29T16:00:01Z",
  "artifacts": [
    "artifacts/run_123/screenshots/001-app-opened.png"
  ],
  "next_action": "report",
  "data": {
    "run": {
      "run_id": "run_123456789abc",
      "platform": "android",
      "device": "emulator-5554",
      "started_at": "2026-03-29T16:00:00Z",
      "ended_at": "2026-03-29T16:00:01Z",
      "status": "ok",
      "steps": [],
      "assertions": [],
      "artifacts": [],
      "determinism_signature": "...",
      "seed": 42
    },
    "warnings": []
  }
}

​Top-level envelope

​Error payload

​Run result

​Step result

​Map metadata

​Discovery annotation result

​Route result

​Assertion result

​Benchmark result payload

​Validation payload

​Example envelope