topicforge 0.5.6__tar.gz → 0.6.1__tar.gz

{topicforge-0.5.6 → topicforge-0.6.1}/CHANGELOG.md

@@ -5,6 +5,98 @@ All notable changes to TopicForge are documented in this file.
 The format is based on [Keep a Changelog 1.1.0](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning 2.0.0](https://semver.org/spec/v2.0.0.html).
 
+## [0.6.1] - 2026-10-06
+
+### Added
+
+- A Claude plugin bundle in `plugin/`: the TopicForge MCP server (started with
+  `uvx`, version pinned) and two skills, `diagnose-dds-bus` and
+  `inspect-ros2-robot`. Install with `claude plugin marketplace add
+  yaniswav/TopicForge`.
+- [docs/VALIDATION.md](docs/VALIDATION.md): the OmniSim team's external validation
+  against a simulated robot's ground truth, published as approved by them.
+- `MessageSample.recorded_ns`: the bag record time of a `peek_bag_samples` sample.
+- `MessageSample.stamp_source` value `recorded`: `timestamp_ns` is the bag record
+  time because the message has no top-level header.
+- `HealthReport.sim_clock_published` (live ROS 2 only, else null): whether `/clock`
+  has a publisher, a hint that nodes may run on simulated time.
+
+### Changed
+
+- `peek_bag_samples` `timestamp_ns` is now `header.stamp` when the message has a
+  top-level header (`stamp_source` `header`), else the bag record time (`stamp_source`
+  `recorded`). It used to be the bag record time for every message, with
+  `stamp_source` null. The tool description says it returns the first `count`
+  messages, not the last.
+- CI: `actions/checkout` v7, `actions/setup-python` v7, `actions/cache` v6. Jobs
+  that run tests or the demos use `ubuntu-24.04` instead of `ubuntu-latest`.
+
+### Fixed
+
+- `peek_bag_samples` payloads no longer carry `__msgtype__` in every nested object
+  nor a top-level `_msgtype`; the message type stays at the sample level.
+
+## [0.6.0] - 2026-10-05
+
+`sample_messages` (live) rewritten after the OmniSim team's report (count
+ignored, empty results on latched topics, wrong timestamps and shifted columns
+on simulated time).
+
+### Breaking
+
+- `sample_messages` payloads are nested named fields (`payload.header.stamp.sec`,
+  `payload.ranges`) instead of positional `col_0`, `col_1`, ... columns. The
+  verbatim row under `_raw_text` is gone: it is present only when a message could
+  not be parsed.
+- `_truncated_after_columns` and `_truncated_columns` are replaced by
+  `_truncated_fields`, a list of dotted field paths (`["ranges", "intensities"]`)
+  for arrays, strings or bytes cut at `max_array_length`. A cut array no longer
+  carries the CLI's `'...'` element.
+- `nan`, `inf` and `-inf` floats are returned as the strings `"nan"`, `"inf"`,
+  `"-inf"`.
+- `MiddlewareAdapter.sample_messages` returns a `SampleResult` instead of a list
+  of `MessageSample` and takes `timeout_s`. `parse_csv_echo` and `parse_echo_yaml`
+  are removed.
+- `pyyaml>=6` is a runtime dependency.
+- A failing `ros2 topic echo` (non-zero exit with no message, or a CLI that cannot
+  be started) raises an MCP error instead of returning an empty list. `count` 0 now
+  validates the topic in live mode too, as it already did in the mock.
+
+### Added
+
+- `sample_messages` parameter `timeout_s` (1..45, default 10): a wall deadline for
+  the whole call, topic lookup included. The call returns within about `timeout_s`
+  plus 2 s (stopping the CLI, decoding what arrived).
+- `MessageSample.stamp_source` (`header` or `none`) and `received_ns` (wall clock
+  when TopicForge read the message).
+- A short result carries a `note` (`N of M messages within T s`) that tells "no
+  publisher is announced" from "a publisher exists but nothing arrived in time",
+  hints `count` 1 for a latched topic, and gives the exit code and stderr when the
+  CLI exited early.
+- A message over the per-message size cap (`TOPICFORGE_MAX_SAMPLE_BYTES`, 1 MiB) is
+  dropped while it streams and counted in the `note`, so a large `Image` no longer
+  costs tens of seconds of YAML decoding. Decoding uses libyaml when available and
+  stops at the call deadline.
+- `count` above 50 is capped with a note, and the tool schema declares the
+  maximum.
+
+### Fixed
+
+- `sample_messages` honours `count`: it streams `ros2 topic echo` and stops at
+  `count` messages or the deadline, then stops the process tree (SIGINT then
+  SIGKILL on POSIX, `taskkill /F /T` on Windows) (OmniSim D3). The echo is
+  started with explicit `--qos-reliability` and `--qos-durability` taken from the
+  publishers, so a latched (`transient_local`) topic is no longer returned empty
+  because the CLI picked its QoS against a cold daemon.
+- Stopping the CLI kills the whole process tree even when the launcher already
+  exited (POSIX: always signals the process group; Windows: a Job Object), so no
+  orphan `ros2` process keeps running. The CLI is started with UTF-8 output.
+- The mock `sample_messages` matches the live shape: headerless messages have
+  `timestamp_ns` 0 and `stamp_source` `none`.
+- `timestamp_ns` is the top-level `header.stamp` whatever its value, so a
+  simulated clock (seconds since the simulation start) no longer falls back to 0
+  and shifts every following column by two (OmniSim D4).
+
 ## [0.5.6] - 2026-10-02
 
 Fixes from a live run of 0.5.3 and 0.5.5 against OmniSim's simulated
@@ -1202,7 +1294,9 @@ Initial MVP release of TopicForge: ROS Topic Inspector & Bag Analyzer MCP server
 - The write path (publishing, commanding robots) is intentionally out of scope for the MVP.
 - `analyze_bag` in live mode parses `ros2 bag info` text output; deeper anomaly detection remains mock-only for now.
 
-[Unreleased]: https://github.com/yaniswav/TopicForge/compare/v0.5.6...HEAD
+[Unreleased]: https://github.com/yaniswav/TopicForge/compare/v0.6.1...HEAD
+[0.6.1]: https://github.com/yaniswav/TopicForge/compare/v0.6.0...v0.6.1
+[0.6.0]: https://github.com/yaniswav/TopicForge/compare/v0.5.6...v0.6.0
 [0.5.6]: https://github.com/yaniswav/TopicForge/compare/v0.5.5...v0.5.6
 [0.5.5]: https://github.com/yaniswav/TopicForge/compare/v0.5.4...v0.5.5
 [0.5.4]: https://github.com/yaniswav/TopicForge/compare/v0.5.3...v0.5.4

{topicforge-0.5.6 → topicforge-0.6.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: topicforge
-Version: 0.5.6
+Version: 0.6.1
 Summary: ROS Topic Inspector & Bag Analyzer MCP server for AI agents
 Project-URL: Homepage, https://github.com/yaniswav/TopicForge
 Project-URL: Repository, https://github.com/yaniswav/TopicForge
@@ -42,6 +42,7 @@ Classifier: Programming Language :: Python :: 3.13
 Requires-Python: >=3.10
 Requires-Dist: mcp<2,>=1.0.0
 Requires-Dist: pydantic>=2.6
+Requires-Dist: pyyaml>=6
 Provides-Extra: all
 Requires-Dist: cyclonedds>=0.10; extra == 'all'
 Provides-Extra: bags
@@ -108,8 +109,8 @@ Every response except `health_check` carries `mode_effective` (`"live"` or `"moc
 | `health_check`          | Environment and mode introspection. Always succeeds; reports `mode` next to `requested_mode`      |
 | `list_topics`           | Discover the ROS2 graph                                                                          |
 | `get_topic_info`        | Message type, publisher/subscriber counts and QoS for one topic                                  |
-| `sample_messages`       | Peek recent messages on a ROS2 topic (count clamped to 50)                                       |
-| `analyze_bag`           | Summarize a `.mcap` / `.db3` recording or `rosbag2_*` directory (via `ros2 bag info`)      |
+| `sample_messages`       | Peek recent messages on a ROS2 topic (count capped at 50)                                        |
+| `analyze_bag`           | Summarize a `.mcap` / `.db3` recording or `rosbag2_*` directory (via `ros2 bag info`)            |
 | `list_participants`     | DDS participants on the domain: vendor, `name` (EntityName QoS, Cyclone) and `hostname`          |
 | `detect_qos_mismatches` | Incompatible QoS pairs between DDS readers and writers                                           |
 | `peek_dds_samples`      | Raw DDS samples; structured on the three builtin discovery topics, presence-only on user topics   |
@@ -157,15 +158,17 @@ Samples with comments are in [`.env.example`](.env.example). Any invalid value s
 
 ## Limitations
 
+External validation against a simulated robot's ground truth: [docs/VALIDATION.md](docs/VALIDATION.md).
+
 - DDS validation is partial. The Cyclone adapter has run against a real bus, with Cyclone and Dust DDS participants, on Windows and in CI on Ubuntu and Windows (`.github/workflows/demo.yml`). The Fast DDS adapter has never run against a bus, and no RTI, OpenDDS, CoreDX or OpenSplice participant has been observed by this project. The multi-vendor claim rests on the RTPS protocol guarantee, not on a recorded cross-vendor run.
 - User-topic payloads are not decoded. `peek_dds_samples` on a user topic returns count 0 and a note that the topic is announced on the bus; no traffic is read. `topic_metrics` therefore has data only for the builtin discovery topics and says so in its `status`. It is a discovery-layer probe, not a publish-rate monitor.
-- Liveliness at runtime is not observed. A writer that is alive but silent (a hung process whose lease is still renewed) looks healthy, because TopicForge reads discovery, not data. An opt-in data probe is planned for 0.5.6. A crash and a clean leave cannot be told apart, and `lost_ns` is an upper bound of the death.
+- Liveliness at runtime is not observed. A writer that is alive but silent (a hung process whose lease is still renewed) looks healthy, because TopicForge reads discovery, not data. An opt-in data probe is planned. A crash and a clean leave cannot be told apart, and `lost_ns` is an upper bound of the death.
 - Cyclone vendor ids: participants that do not follow the RTPS vendor-id convention in their GUID prefix (Dust DDS, and RTI by default) are reported with vendor `unknown`.
 - Single domain: the server observes the domain it joined at startup; changing it needs a restart.
 - DDS Security is not handled. A participant without credentials sees an empty secure bus. `detect_qos_mismatches` checks Partition, type name, Reliability, Durability, Deadline, Liveliness, LatencyBudget, Ownership (kind), DestinationOrder and DataRepresentation (History as a risk); Presentation, XTypes assignability and runtime behavior are not checked, and the result lists them in `policies_unchecked`. It returns a `MismatchScan` envelope: read `reports` for the mismatches.
 - Fast DDS serves no `list_endpoints`.
-- `sample_messages` (live) runs `ros2 topic echo --csv --once` with a short timeout, so it returns at most one message, and a topic with no current publisher returns an empty sample. `timestamp_ns` is the message `header.stamp` for `Header`-stamped types and `0` for headerless ones. Arrays are cut at 128 elements by default; `max_array_length` (1..65536, or null for no cut) and `arrays_summary_only` change that, and a cut is listed under `_truncated_after_columns`.
-- `analyze_bag` (live) parses `ros2 bag info` text for the totals and counts; anomaly detection is mock-only. Per-topic times, rates (`(n - 1) / span`) and `latched` are added when the bag can be read locally (`.db3` with the standard library, `.mcap` with `rosbags`), else rates fall back to count / bag duration (`frequency_basis`). `peek_bag_samples` reads the file itself, through `rosbags`, and is served only by the ROS2 CLI adapter or the mock; bags that embed no message definitions (Humble `.db3`) are decoded with the Humble definitions, or the distro the bag records, and `note` says so. Without `ros2`, bag tools return fixtures: check `health_check` for `mode: "mock"` before trusting bag output.
+- `sample_messages` (live) streams `ros2 topic echo` until `count` messages arrive or `timeout_s` (1..45, default 10, for the whole call) runs out, and returns what arrived with a `note` (`N of M messages within T s`, saying whether a publisher exists). QoS is matched to the publishers, so latched topics work. The payload has nested named fields (`payload.header.stamp.sec`); `timestamp_ns` is `header.stamp` (the publisher's clock, sim time on a simulation) or 0 for headerless types, with `stamp_source` and `received_ns` (wall clock when the CLI printed it). Arrays are cut at 128 elements by default; `max_array_length` (1..65536, or null for no cut) and `arrays_summary_only` change that, and a cut is listed under `_truncated_fields`. `nan` and `inf` come back as strings. `count` above 50 is capped with a note.
+- `analyze_bag` (live) parses `ros2 bag info` text for the totals and counts; anomaly detection is mock-only. Per-topic times, rates (`(n - 1) / span`) and `latched` are added when the bag can be read locally (`.db3` with the standard library, `.mcap` with `rosbags`), else rates fall back to count / bag duration (`frequency_basis`). `peek_bag_samples` reads the file itself, through `rosbags`, returns the first `count` messages in recording order (not the last), and is served only by the ROS2 CLI adapter or the mock; its `timestamp_ns` is the message's `header.stamp` (`stamp_source` `header`) or, without a top-level header, the bag record time (`stamp_source` `recorded`), and `recorded_ns` is always the bag record time; bags that embed no message definitions (Humble `.db3`) are decoded with the Humble definitions, or the distro the bag records, and `note` says so. Without `ros2`, bag tools return fixtures: check `health_check` for `mode: "mock"` before trusting bag output. `health_check` also reports `sim_clock_published` (live only): true when `/clock` has a publisher, a hint that header stamps may be simulation time.
 - Synchronous handlers: the tools run on the MCP event loop; on Windows a hung `ros2` launcher can block the server.
 - No streaming or push subscriptions: tools are strictly request/response.
 
@@ -188,7 +191,7 @@ When on, each tool call emits one event with exactly six fields:
 | `tool_name`  | `"list_topics"` | One of the twelve tools, never argument values              |
 | `latency_ms` | `12.34`         | Handler wall-clock duration, 2 decimals                     |
 | `mode`       | `"mock"`        | Mode of the adapter actually serving: `mock` or `live`      |
-| `version`    | `"0.5.6"`       | TopicForge server version                                   |
+| `version`    | `"0.6.1"`       | TopicForge server version                                   |
 | `session_id` | `"a1b2c3..."`   | Random UUID per process, never persisted                    |
 | `success`    | `true`          | Whether the handler returned or raised                      |
 

{topicforge-0.5.6 → topicforge-0.6.1}/README.md

@@ -49,8 +49,8 @@ Every response except `health_check` carries `mode_effective` (`"live"` or `"moc
 | `health_check`          | Environment and mode introspection. Always succeeds; reports `mode` next to `requested_mode`      |
 | `list_topics`           | Discover the ROS2 graph                                                                          |
 | `get_topic_info`        | Message type, publisher/subscriber counts and QoS for one topic                                  |
-| `sample_messages`       | Peek recent messages on a ROS2 topic (count clamped to 50)                                       |
-| `analyze_bag`           | Summarize a `.mcap` / `.db3` recording or `rosbag2_*` directory (via `ros2 bag info`)      |
+| `sample_messages`       | Peek recent messages on a ROS2 topic (count capped at 50)                                        |
+| `analyze_bag`           | Summarize a `.mcap` / `.db3` recording or `rosbag2_*` directory (via `ros2 bag info`)            |
 | `list_participants`     | DDS participants on the domain: vendor, `name` (EntityName QoS, Cyclone) and `hostname`          |
 | `detect_qos_mismatches` | Incompatible QoS pairs between DDS readers and writers                                           |
 | `peek_dds_samples`      | Raw DDS samples; structured on the three builtin discovery topics, presence-only on user topics   |
@@ -98,15 +98,17 @@ Samples with comments are in [`.env.example`](.env.example). Any invalid value s
 
 ## Limitations
 
+External validation against a simulated robot's ground truth: [docs/VALIDATION.md](docs/VALIDATION.md).
+
 - DDS validation is partial. The Cyclone adapter has run against a real bus, with Cyclone and Dust DDS participants, on Windows and in CI on Ubuntu and Windows (`.github/workflows/demo.yml`). The Fast DDS adapter has never run against a bus, and no RTI, OpenDDS, CoreDX or OpenSplice participant has been observed by this project. The multi-vendor claim rests on the RTPS protocol guarantee, not on a recorded cross-vendor run.
 - User-topic payloads are not decoded. `peek_dds_samples` on a user topic returns count 0 and a note that the topic is announced on the bus; no traffic is read. `topic_metrics` therefore has data only for the builtin discovery topics and says so in its `status`. It is a discovery-layer probe, not a publish-rate monitor.
-- Liveliness at runtime is not observed. A writer that is alive but silent (a hung process whose lease is still renewed) looks healthy, because TopicForge reads discovery, not data. An opt-in data probe is planned for 0.5.6. A crash and a clean leave cannot be told apart, and `lost_ns` is an upper bound of the death.
+- Liveliness at runtime is not observed. A writer that is alive but silent (a hung process whose lease is still renewed) looks healthy, because TopicForge reads discovery, not data. An opt-in data probe is planned. A crash and a clean leave cannot be told apart, and `lost_ns` is an upper bound of the death.
 - Cyclone vendor ids: participants that do not follow the RTPS vendor-id convention in their GUID prefix (Dust DDS, and RTI by default) are reported with vendor `unknown`.
 - Single domain: the server observes the domain it joined at startup; changing it needs a restart.
 - DDS Security is not handled. A participant without credentials sees an empty secure bus. `detect_qos_mismatches` checks Partition, type name, Reliability, Durability, Deadline, Liveliness, LatencyBudget, Ownership (kind), DestinationOrder and DataRepresentation (History as a risk); Presentation, XTypes assignability and runtime behavior are not checked, and the result lists them in `policies_unchecked`. It returns a `MismatchScan` envelope: read `reports` for the mismatches.
 - Fast DDS serves no `list_endpoints`.
-- `sample_messages` (live) runs `ros2 topic echo --csv --once` with a short timeout, so it returns at most one message, and a topic with no current publisher returns an empty sample. `timestamp_ns` is the message `header.stamp` for `Header`-stamped types and `0` for headerless ones. Arrays are cut at 128 elements by default; `max_array_length` (1..65536, or null for no cut) and `arrays_summary_only` change that, and a cut is listed under `_truncated_after_columns`.
-- `analyze_bag` (live) parses `ros2 bag info` text for the totals and counts; anomaly detection is mock-only. Per-topic times, rates (`(n - 1) / span`) and `latched` are added when the bag can be read locally (`.db3` with the standard library, `.mcap` with `rosbags`), else rates fall back to count / bag duration (`frequency_basis`). `peek_bag_samples` reads the file itself, through `rosbags`, and is served only by the ROS2 CLI adapter or the mock; bags that embed no message definitions (Humble `.db3`) are decoded with the Humble definitions, or the distro the bag records, and `note` says so. Without `ros2`, bag tools return fixtures: check `health_check` for `mode: "mock"` before trusting bag output.
+- `sample_messages` (live) streams `ros2 topic echo` until `count` messages arrive or `timeout_s` (1..45, default 10, for the whole call) runs out, and returns what arrived with a `note` (`N of M messages within T s`, saying whether a publisher exists). QoS is matched to the publishers, so latched topics work. The payload has nested named fields (`payload.header.stamp.sec`); `timestamp_ns` is `header.stamp` (the publisher's clock, sim time on a simulation) or 0 for headerless types, with `stamp_source` and `received_ns` (wall clock when the CLI printed it). Arrays are cut at 128 elements by default; `max_array_length` (1..65536, or null for no cut) and `arrays_summary_only` change that, and a cut is listed under `_truncated_fields`. `nan` and `inf` come back as strings. `count` above 50 is capped with a note.
+- `analyze_bag` (live) parses `ros2 bag info` text for the totals and counts; anomaly detection is mock-only. Per-topic times, rates (`(n - 1) / span`) and `latched` are added when the bag can be read locally (`.db3` with the standard library, `.mcap` with `rosbags`), else rates fall back to count / bag duration (`frequency_basis`). `peek_bag_samples` reads the file itself, through `rosbags`, returns the first `count` messages in recording order (not the last), and is served only by the ROS2 CLI adapter or the mock; its `timestamp_ns` is the message's `header.stamp` (`stamp_source` `header`) or, without a top-level header, the bag record time (`stamp_source` `recorded`), and `recorded_ns` is always the bag record time; bags that embed no message definitions (Humble `.db3`) are decoded with the Humble definitions, or the distro the bag records, and `note` says so. Without `ros2`, bag tools return fixtures: check `health_check` for `mode: "mock"` before trusting bag output. `health_check` also reports `sim_clock_published` (live only): true when `/clock` has a publisher, a hint that header stamps may be simulation time.
 - Synchronous handlers: the tools run on the MCP event loop; on Windows a hung `ros2` launcher can block the server.
 - No streaming or push subscriptions: tools are strictly request/response.
 
@@ -129,7 +131,7 @@ When on, each tool call emits one event with exactly six fields:
 | `tool_name`  | `"list_topics"` | One of the twelve tools, never argument values              |
 | `latency_ms` | `12.34`         | Handler wall-clock duration, 2 decimals                     |
 | `mode`       | `"mock"`        | Mode of the adapter actually serving: `mock` or `live`      |
-| `version`    | `"0.5.6"`       | TopicForge server version                                   |
+| `version`    | `"0.6.1"`       | TopicForge server version                                   |
 | `session_id` | `"a1b2c3..."`   | Random UUID per process, never persisted                    |
 | `success`    | `true`          | Whether the handler returned or raised                      |
 

{topicforge-0.5.6 → topicforge-0.6.1}/docs/TESTING.md

@@ -15,7 +15,7 @@ How to get a working ROS2 environment to point TopicForge at, and how to wire it
 ```bash
 python -m venv .venv && source .venv/bin/activate   # Windows: .venv\Scripts\Activate.ps1
 pip install topicforge
-python -m topicforge --version                      # -> topicforge 0.5.6
+python -m topicforge --version                      # -> topicforge 0.6.1
 TOPICFORGE_MODE=mock python -m topicforge           # blocks on stdio; MCP clients spawn it
 ```
 
@@ -41,7 +41,7 @@ python3 -m venv ~/topicforge-venv && source ~/topicforge-venv/bin/activate
 pip install topicforge          # Ubuntu 22.04 ships Python 3.10, which is enough
 ```
 
-Then run live mode with three terminals. In the first, `ros2 run demo_nodes_cpp talker` publishes `/chatter` at about 1 Hz. In the second, `ros2 topic list` should show `/chatter`. In the third, source ROS2, activate the venv and run `TOPICFORGE_MODE=live python -m topicforge`. The startup line reads `topicforge 0.5.6 ready (mode=live, requested_mode=live, adapter=ros2_cli, telemetry=off)`; `mode=mock` means `ros2` was not found and the server fell back to fixtures.
+Then run live mode with three terminals. In the first, `ros2 run demo_nodes_cpp talker` publishes `/chatter` at about 1 Hz. In the second, `ros2 topic list` should show `/chatter`. In the third, source ROS2, activate the venv and run `TOPICFORGE_MODE=live python -m topicforge`. The startup line reads `topicforge 0.6.1 ready (mode=live, requested_mode=live, adapter=ros2_cli, telemetry=off)`; `mode=mock` means `ros2` was not found and the server fell back to fixtures.
 
 ## Linux native
 
@@ -77,7 +77,7 @@ TopicForge resolves the `ros2` launcher with `shutil.which` (normally `ros2.exe`
 
 Discover the graph. Ask "What topics are currently being published, and what message types do they carry?" TopicForge calls `list_topics`. Live mode shows `/chatter` plus `/rosout` and `/parameter_events`; mock mode shows `/cmd_vel`, `/odom`, `/scan`, `/tf` and `/camera/image_raw`.
 
-Inspect and sample. Ask "Show me the latest message on /chatter." TopicForge calls `get_topic_info` then `sample_messages`. The payload exposes fields as positional CSV columns (`col_0`, `col_1`, ...) plus `_raw_text`, the verbatim row from `ros2 topic echo --csv --once`. `timestamp_ns` is `0` for headerless types such as `std_msgs/String`.
+Inspect and sample. Ask "Show me the latest message on /chatter." TopicForge calls `get_topic_info` then `sample_messages`. The payload has the message fields as nested named values. `timestamp_ns` is the `header.stamp` and `0` for headerless types such as `std_msgs/String` (`stamp_source` says which).
 
 Record and analyze a bag.
 

{topicforge-0.5.6 → topicforge-0.6.1}/docs/TROUBLESHOOTING.md

@@ -63,12 +63,12 @@ The adapter was written against the 2.6.x binding and has never run against a bu
 - `lookback_seconds must be in 1..86400` (`participant_events`): default 300. The lifecycle buffer keeps at most 200 events, newest first, regardless of window.
 - `window_seconds must be in 1..3600` (`topic_metrics`): default 60. The buffer holds 1000 samples per topic, drop-oldest, so frequency is computed from buffered samples, not a true rolling window.
 - `DDS topic name is malformed`: DDS names match `^[A-Za-z_/][A-Za-z0-9_/:]*$` (builtin names like `DCPSParticipant` and `::` separators are allowed; whitespace and dashes are not). ROS2 names start with `/` and use `_`, so `my-topic` becomes `/my_topic`.
-- `sample_messages` and `peek_*` silently clamp `count` to 50; the `count` field of the result is what was actually returned.
+- `sample_messages` caps `count` at 50 and says so in `note`; `peek_*` clamp silently. The `count` field of the result is what was actually returned.
 
 ## Other
 
 - `topicforge: command not found`: the entry point is not on PATH. Re-activate the venv, or use `python -m topicforge`.
-- `sample_messages` returns no samples: live mode runs `ros2 topic echo --once` with a 3 second timeout; a topic with no active publisher returns nothing. Check `ros2 topic info -v <topic>`.
+- `sample_messages` returns fewer samples than asked: live mode waits `timeout_s` seconds (default 10, max 60, counted from the start of the `ros2` CLI, which can take a few seconds on a slow machine) and `note` says `N of M messages` and whether a publisher exists. Raise `timeout_s` for a topic slower than 1 Hz; check `ros2 topic info -v <topic>`.
 - `analyze_bag` says the path does not exist: the path is resolved in the shell where TopicForge runs. Under WSL use `/mnt/c/demos/run.mcap`, not `C:\demos\run.mcap`. In mock mode only `.mcap`, `.db3`, `.bag` or extensionless paths are accepted.
 - Claude Desktop shows no tools: check Help -> View Logs -> MCP, confirm `topicforge --version` runs from the same environment (or use the absolute path of the binary in the config), and validate the config with `python -m json.tool claude_desktop_config.json`, since a JSON error silently drops the whole file.
 - First live call is slow: `ros2 topic list -t` initializes the DDS middleware, a 1-2 second warm-up.

topicforge-0.6.1/docs/VALIDATION.md

@@ -0,0 +1,15 @@
+# External validation
+
+## OmniSim (October 2026)
+
+The OmniSim team ran TopicForge against a simulated robot and compared its answers with the simulator's ground truth.
+
+Setup: [OmniSim v9.1.3](https://github.com/omnilink-tech/omnisim/releases/tag/v9.1.3), a simulated Clearpath Husky with a 541-beam SICK LMS111 lidar in a room with walls at known positions, robot stationary. ROS 2 Humble on Ubuntu 22.04 (WSL2), Fast DDS. TopicForge 0.5.3 in live mode for the ROS 2 tools, and 0.5.5 with the Cyclone backend for the DDS tools.
+
+What matched:
+- Every lidar scan TopicForge sampled was bit-identical to the simulator's raw data on the beams it delivered.
+- `list_topics` and `get_topic_info` returned the same names, types and publisher/subscriber counts as the `ros2` CLI.
+- `analyze_bag` returned the same duration and message counts as `ros2 bag info` and an independent read of the bag.
+- With the Cyclone backend, TopicForge saw all seven Fast DDS participants of the ROS 2 graph without extra configuration, and reported participants leaving within about 10 ms of the actual time.
+
+What it found: seven discrepancies on TopicForge's side, including lidar arrays cut at 128 values, one message per `sample_messages` call, zero timestamps on simulated time, and Humble bags that `peek_bag_samples` could not decode. All seven are addressed in 0.5.6 and 0.6.0 (full arrays through a `max_array_length` option) and covered by a ROS 2 Humble/Jazzy test bench; the OmniSim run itself has not been repeated on these versions yet. The bag recorded during the run is part of TopicForge's test fixtures (`tests/fixtures/bags/omnisim_humble/`).

topicforge-0.6.1/plugin/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yanis ETHVIGNOT
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

topicforge-0.6.1/plugin/README.md

@@ -0,0 +1,60 @@
+# TopicForge plugin for Claude
+
+TopicForge is a read-only MCP server for ROS 2 and DDS. This plugin bundles the server with two short skills so Claude can inspect a robot stack and diagnose a DDS bus. It cannot publish, command a robot, or change QoS: the server has no write path.
+
+## What is included
+
+- MCP server `topicforge`, started with `uvx` from the `topicforge` package on PyPI (version pinned to 0.6.1). It exposes twelve read-only tools: `health_check`, `list_topics`, `get_topic_info`, `sample_messages`, `analyze_bag`, `peek_bag_samples`, `list_participants`, `list_endpoints`, `detect_qos_mismatches`, `participant_events`, `peek_dds_samples`, `topic_metrics`.
+- Skill `diagnose-dds-bus`: what to call, and in which order, when nodes do not talk, a topic gets no data, or a node crashed or restarts.
+- Skill `inspect-ros2-robot`: listing topics, sampling messages and reading bags, including large arrays and simulation time.
+
+## Requirements
+
+- [`uv`](https://docs.astral.sh/uv/) on PATH, which provides `uvx`. The first start downloads the package and the Cyclone DDS binding, so it can take a little while.
+- A local MCP server: it runs on your machine, in Claude Code and in Cowork sessions that run on your computer. It does not run in claude.ai chat.
+- ROS 2 on PATH is optional. Without it the ROS 2 tools fall back to fixtures (a fictional demo robot) and `health_check` reports `mode: mock`. The DDS tools work without ROS 2.
+
+## Install
+
+From a marketplace, once the plugin is listed:
+
+```
+/plugin install topicforge
+```
+
+Meanwhile, from this repository (Claude Code):
+
+```
+claude plugin marketplace add yaniswav/TopicForge
+claude plugin install topicforge@topicforge
+```
+
+Or load the folder for one session: `claude --plugin-dir ./plugin`.
+
+## Configuration
+
+Claude Code asks for two options when the plugin is enabled:
+
+| Option | Default | Meaning |
+| --- | --- | --- |
+| `dds_backend` | `cyclone` | `cyclone` joins the DDS bus as a read-only participant. `mock` serves fixtures. `auto` picks the best available. |
+| `dds_domain_id` | `0` | The one DDS domain observed (0 to 232). Fixed at startup. |
+
+The server runs with `TOPICFORGE_MODE=auto`: live ROS 2 when `ros2` is on PATH, fixtures otherwise. Cowork does not prompt for options and uses the defaults. To use other settings there, edit `.mcp.json`.
+
+Without DDS, set `dds_backend` to `mock`, or use the standalone install `uvx topicforge`.
+
+## Privacy
+
+The server reads the local ROS 2 graph and the DDS discovery traffic on the machine and network it runs on, and returns the result to the Claude session. It makes no outbound network calls. Anonymous telemetry exists but is off by default and is not enabled by this plugin. See the main [README](https://github.com/yaniswav/TopicForge#telemetry) for the telemetry contract and [SECURITY.md](https://github.com/yaniswav/TopicForge/blob/main/SECURITY.md).
+
+## Limits
+
+TopicForge sees what DDS discovery announces. It cannot see whether data flows, a writer that is alive but silent, other DDS domains, or secured (DDS Security) endpoints. The skills tell Claude to say so.
+
+## Links
+
+- Project: https://github.com/yaniswav/TopicForge
+- Site: https://topicforge.horizonvista.xyz
+- Issues: https://github.com/yaniswav/TopicForge/issues
+- License: MIT

{topicforge-0.5.6 → topicforge-0.6.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "topicforge"
-version = "0.5.6"
+version = "0.6.1"
 description = "ROS Topic Inspector & Bag Analyzer MCP server for AI agents"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -25,6 +25,7 @@ classifiers = [
 dependencies = [
     "mcp>=1.0.0,<2",
     "pydantic>=2.6",
+    "pyyaml>=6",
 ]
 
 [project.optional-dependencies]

{topicforge-0.5.6 → topicforge-0.6.1}/src/topicforge/__init__.py

@@ -1,5 +1,5 @@
 """TopicForge: ROS Topic Inspector & Bag Analyzer MCP server."""
 
-__version__ = "0.5.6"
+__version__ = "0.6.1"
 
 __all__ = ["__version__"]

{topicforge-0.5.6 → topicforge-0.6.1}/src/topicforge/adapters/base.py

@@ -9,11 +9,10 @@ from __future__ import annotations
 
 from typing import Literal, Protocol, runtime_checkable
 
-from topicforge.constants import DEFAULT_MAX_ARRAY_LENGTH
+from topicforge.constants import DEFAULT_MAX_ARRAY_LENGTH, DEFAULT_SAMPLE_TIMEOUT_S
 from topicforge.models import (
     BagAnalysis,
     EndpointListing,
-    MessageSample,
     MismatchScan,
     ParticipantEvent,
     ParticipantInfo,
@@ -96,7 +95,8 @@ class MiddlewareAdapter(Protocol):
         *,
         max_array_length: int | None = DEFAULT_MAX_ARRAY_LENGTH,
         arrays_summary_only: bool = False,
-    ) -> list[MessageSample]: ...
+        timeout_s: float = DEFAULT_SAMPLE_TIMEOUT_S,
+    ) -> SampleResult: ...
 
     def analyze_bag(self, path: str) -> BagAnalysis: ...
 

{topicforge-0.5.6 → topicforge-0.6.1}/src/topicforge/adapters/common/cdr_decoder.py

@@ -59,8 +59,18 @@ def iter_field_names(sample: Any) -> list[str]:
     """List field names on a dynamic-type sample.
 
     Tries `__dataclass_fields__`, `__fields__`, `__slots__`, then public
-    `__dict__` keys. Returns an empty list when none apply.
+    `__dict__` keys. Returns an empty list when none apply. Dunder names
+    such as the `__msgtype__` marker that `rosbags` messages carry are
+    not data and are left out.
     """
+    return [name for name in _raw_field_names(sample) if not _is_dunder(name)]
+
+
+def _is_dunder(name: str) -> bool:
+    return name.startswith("__") and name.endswith("__")
+
+
+def _raw_field_names(sample: Any) -> list[str]:
     fields = getattr(sample, "__dataclass_fields__", None)
     if fields:
         return list(fields)

{topicforge-0.5.6 → topicforge-0.6.1}/src/topicforge/adapters/composite.py

@@ -15,11 +15,10 @@ from __future__ import annotations
 from typing import Any
 
 from topicforge.adapters.base import AdapterName, EffectiveMode, MiddlewareAdapter
-from topicforge.constants import DEFAULT_MAX_ARRAY_LENGTH
+from topicforge.constants import DEFAULT_MAX_ARRAY_LENGTH, DEFAULT_SAMPLE_TIMEOUT_S
 from topicforge.models import (
     BagAnalysis,
     EndpointListing,
-    MessageSample,
     MismatchScan,
     ParticipantEvent,
     ParticipantInfo,
@@ -69,17 +68,24 @@ class CompositeAdapter:
         *,
         max_array_length: int | None = DEFAULT_MAX_ARRAY_LENGTH,
         arrays_summary_only: bool = False,
-    ) -> list[MessageSample]:
+        timeout_s: float = DEFAULT_SAMPLE_TIMEOUT_S,
+    ) -> SampleResult:
         return self._ros.sample_messages(
             topic,
             count,
             max_array_length=max_array_length,
             arrays_summary_only=arrays_summary_only,
+            timeout_s=timeout_s,
         )
 
     def analyze_bag(self, path: str) -> BagAnalysis:
         return self._ros.analyze_bag(path)
 
+    def sim_clock_published(self) -> bool | None:
+        """The ROS 2 half's `/clock` probe, `None` when it has none."""
+        probe = getattr(self._ros, "sim_clock_published", None)
+        return probe() if callable(probe) else None
+
     # ----- DDS surface -> DDS adapter -----
 
     def observer_status(self) -> dict[str, Any] | None:

{topicforge-0.5.6 → topicforge-0.6.1}/src/topicforge/adapters/dds_cyclone/adapter.py

@@ -63,7 +63,7 @@ from topicforge.adapters.common import (
 from topicforge.adapters.common import (
     cyclone_extract_topic_name as _extract_topic_name,
 )
-from topicforge.constants import DEFAULT_MAX_ARRAY_LENGTH
+from topicforge.constants import DEFAULT_MAX_ARRAY_LENGTH, DEFAULT_SAMPLE_TIMEOUT_S
 from topicforge.models import (
     BagAnalysis,
     EndpointListing,
@@ -334,7 +334,8 @@ class CycloneDdsAdapter:
         *,
         max_array_length: int | None = DEFAULT_MAX_ARRAY_LENGTH,
         arrays_summary_only: bool = False,
-    ) -> list[MessageSample]:
+        timeout_s: float = DEFAULT_SAMPLE_TIMEOUT_S,
+    ) -> SampleResult:
         raise AdapterError(DDS_ONLY_ERROR_MSG)
 
     def analyze_bag(self, path: str) -> BagAnalysis:

{topicforge-0.5.6 → topicforge-0.6.1}/src/topicforge/adapters/dds_dust/adapter.py

@@ -12,11 +12,10 @@ import logging
 
 from topicforge.adapters.base import AdapterError, AdapterName, EffectiveMode
 from topicforge.adapters.common import validate_domain_id
-from topicforge.constants import DEFAULT_MAX_ARRAY_LENGTH
+from topicforge.constants import DEFAULT_MAX_ARRAY_LENGTH, DEFAULT_SAMPLE_TIMEOUT_S
 from topicforge.models import (
     BagAnalysis,
     EndpointListing,
-    MessageSample,
     MismatchScan,
     ParticipantEvent,
     ParticipantInfo,
@@ -66,7 +65,8 @@ class DustDdsAdapter:
         *,
         max_array_length: int | None = DEFAULT_MAX_ARRAY_LENGTH,
         arrays_summary_only: bool = False,
-    ) -> list[MessageSample]:
+        timeout_s: float = DEFAULT_SAMPLE_TIMEOUT_S,
+    ) -> SampleResult:
         raise AdapterError(_DUST_ROADMAP_MSG)
 
     def analyze_bag(self, path: str) -> BagAnalysis:

{topicforge-0.5.6 → topicforge-0.6.1}/src/topicforge/adapters/dds_fast/adapter.py

@@ -52,7 +52,7 @@ from topicforge.adapters.common import (
 from topicforge.adapters.common import (
     is_removal as _is_removal,
 )
-from topicforge.constants import DEFAULT_MAX_ARRAY_LENGTH
+from topicforge.constants import DEFAULT_MAX_ARRAY_LENGTH, DEFAULT_SAMPLE_TIMEOUT_S
 from topicforge.models import (
     BagAnalysis,
     EndpointListing,
@@ -241,7 +241,8 @@ class FastDdsAdapter:
         *,
         max_array_length: int | None = DEFAULT_MAX_ARRAY_LENGTH,
         arrays_summary_only: bool = False,
-    ) -> list[MessageSample]:
+        timeout_s: float = DEFAULT_SAMPLE_TIMEOUT_S,
+    ) -> SampleResult:
         raise AdapterError(DDS_ONLY_ERROR_MSG)
 
     def analyze_bag(self, path: str) -> BagAnalysis:

{topicforge-0.5.6 → topicforge-0.6.1}/src/topicforge/adapters/dds_opendds/adapter.py

@@ -16,11 +16,10 @@ import logging
 
 from topicforge.adapters.base import AdapterError, AdapterName, EffectiveMode
 from topicforge.adapters.common import validate_domain_id
-from topicforge.constants import DEFAULT_MAX_ARRAY_LENGTH
+from topicforge.constants import DEFAULT_MAX_ARRAY_LENGTH, DEFAULT_SAMPLE_TIMEOUT_S
 from topicforge.models import (
     BagAnalysis,
     EndpointListing,
-    MessageSample,
     MismatchScan,
     ParticipantEvent,
     ParticipantInfo,
@@ -72,7 +71,8 @@ class OpenDdsAdapter:
         *,
         max_array_length: int | None = DEFAULT_MAX_ARRAY_LENGTH,
         arrays_summary_only: bool = False,
-    ) -> list[MessageSample]:
+        timeout_s: float = DEFAULT_SAMPLE_TIMEOUT_S,
+    ) -> SampleResult:
         raise AdapterError(_OPENDDS_ROADMAP_MSG)
 
     def analyze_bag(self, path: str) -> BagAnalysis: