Skip to content
Luotsi Luotsi

Output Envelopes

Luotsi uses two output contracts on purpose.

For a faster first-pass mental model, start with First Five Minutes. This page is the reference for the underlying output contracts.

One-shot command mode

Section titled “One-shot command mode”

Most commands return a single final JSON envelope with:

  • schema
  • ok
  • command
  • started_at
  • ended_at
  • data
  • artifacts
  • provenance
  • error

This is the default contract for CLI commands, including scenario execution unless you explicitly request raw replay output modes.

For local terminal readability, one-shot commands also accept --human or --console-output human. That mode leads with the artifact path, a guide: reminder that the artifact root is durable evidence, and a next: command when Luotsi can name the follow-up before the rest of the concise text summary. The default and --json keep the full machine-readable envelope. Use --quiet or --console-output quiet to suppress successful command output while still printing failure envelopes. Luotsi does not use a global --output switch for this because some commands already use --output for file paths.

When an agent or CI job needs the next action, read command hints in this order:

  1. data.recommended_next_action_command when a check result exposes the direct continuation command; command-envelope data fields use snake_case.
  2. data.recommended_next_action.command when the command can name one best action.
  3. data.primary_failure.source_command or data.primaryFailure.sourceCommand when a packet/check result has focused failure evidence but no recommended action.
  4. data.triage_checklist[].command or data.triageChecklist[].command when a packet/check result exposes a structured first-minute checklist.
  5. data.recommended_next_steps[], data.next_actions[], or data.suggested_commands[] when the workflow returns an ordered handoff.
  6. artifacts.artifact_root as the fallback evidence pointer; run replay packet first so the loop has run-summary.json and run-summary.md.
  7. data.commands[], data.artifact_commands[], or data.recommended_commands[] only when there is no artifact root to packetize; use artifacts open only when you specifically need the generic artifact browser.

The source tree includes executable examples of this priority order at examples/agents/extract-next-command.py and examples/agents/extract-next-command.mjs. The same parsers accept persisted run-summary.json packets with schema luotsi-run-summary.v1; the source contract is documented at docs/schemas/luotsi-run-summary-v1.md, and replay packet --check is the pass/fail gate for an existing packet. After choosing the command, use packet evidenceFiles[] or check-envelope data.evidence_files[] as proof-file context for the focused failure rather than scraping Markdown.

When an artifact root has a persisted package intake audit, human output for artifacts info and replay capsule includes a compact intake: line with status, share-safety, SHA verification, and package path. Received-package handoffs from artifacts info, artifacts verify, artifacts unpack, and artifacts intake include a replay packet --check command so humans and agents validate run-summary.json before opening broader replay surfaces.

Long-lived session mode

Section titled “Long-lived session mode”

inspect is a JSONL session instead of one final object. view prints human startup/runtime progress by default, can stream raw JSONL events with view -o jsonl, view --output jsonl, or view --json, and always writes its JSONL timeline artifact for replay.

Typical inspect events:

  • session_started
  • screen_snapshot
  • screen_delta
  • command_result
  • session_ended
  • protocol_error
  • session_error

Typical view events:

  • view_started
  • view_startup_phase
  • view_diagnostic
  • view_stats
  • view_reconnect_requested
  • view_reconnected
  • view_recording_started
  • view_recording_stopped
  • view_screenshot_captured
  • view_share_started
  • view_share_client_connected
  • view_artifacts_opened
  • view_file_pushed
  • view_file_pulled
  • view_package_installed
  • view_error
  • view_ended

Not every session emits every event family. Startup diagnostics appear during bring-up, share events only appear for shared sessions, and recording or file-transfer events only appear when the operator actually uses those controls.

Replay export exception

Section titled “Replay export exception”

replay summarize --format json|jsonl and replay timeline --format json|jsonl are intentional exceptions. They can emit raw replay output for CI-oriented consumers instead of the normal envelope.

Raw replay --format modes cannot be combined with --human, --quiet, --json, or --console-output because those flags control envelope presentation, while --format replaces the envelope entirely.

Artifact and replay commands that keep the normal envelope put their command-specific contract under data:

  • artifacts info returns root/package metadata. For artifact roots, persisted intake audits appear as has_artifact_intake_summary plus optional artifact_intake_summary fields for restored package status, share safety, SHA-256, verification, and persisted audit paths.
  • replay capsule returns a failure-capsule summary with primary_failure, failure_timeline, artifact_manifest, optional artifact_intake_artifacts / artifact_intake_summary fields for restored package audit status, optional scenario draft summary fields including bounded next_actions and run_handoff, draft-led recommended_next_steps that promote ready dry-run/preflight/claimed-run/direct-run commands first, and suggested_commands.
  • replay summarize returns session summaries plus commands that route into capsule, open, scrub, graph, and clustering when failures are present.
  • replay timeline returns ordered events plus commands that route into capsule, open, scrub, and graph when selected events include failures.
  • replay search returns text matches plus commands back into capsule, open, scrub, and graph when matches are replay-relevant.
  • replay scenario-draft returns draft metadata, warnings, suggestions, review items, ordered next_actions, optional package_provenance, optional device_provenance, optional static validation, optional gated run_handoff with claimed_run_command only when package and device serial are concrete, source summaries, step origins, normalizations such as inserted pre-tap waits or dropped duplicate waits, and the generated output paths. When persisted, the main review artifacts are scenario-draft-summary.json and scenario-draft.md.
  • replay graph returns a stable graph payload with query, agent_summary, counts, taxonomy, insights, actions, evidence, facts, causal chains, hypotheses, optional output paths, plus returned nodes and edges; scenario-draft step and normalization nodes preserve source audit fields when available.
  • replay cluster groups failed replay sessions by normalized failure shape and returns cluster summaries plus suggested next triage commands.

Error categories

Section titled “Error categories”

The current public error categories include:

  • usage_error
  • log_wait_timeout
  • oracle_timeout
  • configuration_error
  • selector_or_screen_state
  • scenario_error

Treat these as current API-visible values derived from the active failure paths rather than as a permanently closed enum.

Why this split matters

Section titled “Why this split matters”
  • One-shot commands are easy to consume from scripts and CI
  • JSONL sessions are better for agents and long-lived operator loops
  • Keeping the split explicit prevents ambiguous mixed-output contracts
Section titled “Related pages”