mcap-run-topic-inspector

name	mcap-run-topic-inspector
description	Find a Gen2 MCAP from a run (or model-derived run), list topics, and extract topic/field values at a specific log time. Use when debugging run-level protobuf signals such as controller_state.
args	<run_id_or_model_ref> <topic_or_topic_field_path> [target_log_time_us]

MCAP Run Topic Inspector

Use this skill to answer:

• "Given a run id, where is the MCAP and what topics does it have?"
• "What is the value of <nested protobuf field> near a specific time?"
• "I have a model ref; how do I get to the run and inspect its MCAP?"

Inputs

• run_id_or_model_ref: Either a run id (vehicle/YYYY-...) or a model reference.
• topic_or_topic_field_path: Either a pure topic (/robot/control/controller_state) or topic + nested field path (for example /robot/control/controller_state.internal_state.input_vehicle_state.current_drive_position).
• target_log_time_us (optional): Timestamp in microseconds for nearest-message lookup.

1) Resolve run id

• If input already looks like vehicle/YYYY-..., use it directly as RUN_ID.
• If input is a model ref, first use model-info-finder (or model-lookup-basic + model-checkpoint-inspector) to resolve candidate run ids, then continue with selected RUN_ID.

2) Discover available MCAP sources for the run

bazel run //wayve/services/foxglove_adaptor/gen2:cli -- list-sources "$RUN_ID"

If empty, retry against production-backed source discovery:

WAYVE_PRODUCTION=true bazel run //wayve/services/foxglove_adaptor:cli -- sources "$RUN_ID"

Typical source for controller signals is av_data.

3) Materialize a local MCAP

• If target_log_time_us is known, prefer a narrow time window to reduce file size:

START_US=$((TARGET_US - 5000000))
END_US=$((TARGET_US + 5000000))
bazel run //wayve/services/foxglove_adaptor:cli -- \
  convert av_data \
  --run-id "$RUN_ID" \
  --output "/tmp/run_slice.mcap" \
  --start_usec "$START_US" \
  --end_usec "$END_US"

• If no time is known yet, fetch full source:

bazel run //wayve/services/foxglove_adaptor/gen2:cli -- \
  convert-cloud "$RUN_ID" "/tmp/run_full.mcap" --sources av_data

4) List topics in local MCAP

bazel run //wayve/robot/tools/mcap_utils:read_mcap_topics -- -f /tmp/run_slice.mcap | sort -u

5) Extract topic/field values (with optional nearest time)

• Use the helper:

bazel run //wayve/robot/tools/mcap_utils:query_mcap_topic -- \
  -f /tmp/run_slice.mcap \
  -t "/robot/control/controller_state" \
  --field_path "internal_state.input_vehicle_state.current_drive_position" \
  --target_log_time_us "$TARGET_US" \
  --window_us 500000 \
  --max_messages 10

Notes:

• topic_name must be the MCAP topic only.
• Nested protobuf path goes in --field_path.
• target_log_time_us is optional; without it, the command prints the first messages.

6) Example requested in prompt

For run: fme10010/2026-04-15--19-10-20--gen2-av-cd9496c5-ad6e-4dc5-a227-8d9a06b3e089

Requested path: /robot/control/controller_state.internal_state.input_vehicle_state.current_drive_position

Split it into:

• topic: /robot/control/controller_state
• field path: internal_state.input_vehicle_state.current_drive_position

Then run steps 2-5 above with those values.

Troubleshooting

• [] or no rows from source listing: verify az login --use-device-code, then retry with WAYVE_PRODUCTION=true.
• No messages found for topic: confirm topic via read_mcap_topics and check you converted the right source.
• Field path ... is invalid: field moved/renamed in proto; decode whole message once by omitting --field_path.