Build AI methods with your coding agent, then run them anywhere: as an MCP for chatbots, as a webapp for people, or via API for your software.
feat(cli): --version reports the protocol and standard versions (#1192)
Louis Choquelcd1c5d09e8cf
diff --git a/.badges/tests.json b/.badges/tests.jsonindex 46a860505..62a1a19e9 100644--- a/.badges/tests.json+++ b/.badges/tests.json@@ -1,7 +1,7 @@{"schemaVersion": 1,"label": "tests",- "message": "11696",+ "message": "11720","color": "blue","cacheSeconds": 300-}\ No newline at end of file+}diff --git a/.claude/skills/bump-mthds/SKILL.md b/.claude/skills/bump-mthds/SKILL.mdindex fdc104b07..405fff73c 100644--- a/.claude/skills/bump-mthds/SKILL.md+++ b/.claude/skills/bump-mthds/SKILL.md@@ -80,7 +80,7 @@ are visible in the same sentence of an upstream changelog.| Number | Where it lives | What it means ||---|---|---|| The **`mthds` package version** | `mthds-python/pyproject.toml`, PyPI | The Python client's own release number. **This is what you are bumping.** |-| The **MTHDS standard version** | `MTHDS_STANDARD_VERSION` in `mthds/package/manifest/schema.py` | The version of the *standard* that client implements. Currently `1.0.0`. |+| The **MTHDS standard version** | `MTHDS_STANDARD_VERSION` in `mthds/package/manifest/schema.py` | The version of the *standard* that client implements. Read it from the installed package rather than from memory — step 6 prints it. || The **spec site's release number** | the `mthds/` repo's own CHANGELOG | The documentation site's release, e.g. `v0.9.0`. Coincidentally close to the package number; unrelated to it. |So "mthds 0.9.0 ships the artifacts the standard owns since MTHDS v0.9.0, whichdiff --git a/.drift/acks/cli-docs.toml b/.drift/acks/cli-docs.tomlindex de642dbda..dae687201 100644--- a/.drift/acks/cli-docs.toml+++ b/.drift/acks/cli-docs.toml@@ -1,14 +1,14 @@contract = "cli-docs"-digest = "sha256:3c08bd5d68b5a30d96399cbe4f28ddec9734f9a92023bbf951984ea2a13bb32d"+digest = "sha256:0dc602377aa1b1aab044025bbe8935467d71ae88b3098978f4e3a1adf6a55ed7"reviewed_by = "Louis Choquel"-reviewed_at = "2026-09-03T12:55:36Z"-rationale = "Merge of origin/dev into feature/Two-gateways-2, re-reviewed on the merged tree. The triggers are this branch's half of the resolution: doctor_cmd, init/backends.py and init/command.py all move from the single-file reader to the merged backends document dev introduced, while keeping this branch's broad question — any Pipelex-managed gateway backend rather than pipelex_gateway by name. Concretely: the doctor's Models row now calls enabled_managed_gateway_sections(config_dir=...) inside dev's parse-error clause, so a broken override still answers as a Models-row failure and no row, flag, output key or exit code moved; init gates the terms prompt on the merged document via the same broad reader; and dev's override warning is generalized to warn_if_managed_gateway_pinned_by_override, which now names which managed backends an override still keeps enabled instead of naming the gateway alone. Reviewed docs/tools/cli/: init.md already states the broad terms rule for pipelex_gateway and pipelex_manifold and the cache-priming sentence already says any managed gateway backend, show.md already names both personal override files, and there is no doctor page there, so nothing under that directory is stale. pipelex/cli/agent_cli/CLAUDE.md documents init at the level of its flags and formats, none of which moved. Outside the declared targets I did update the two pages that describe the warning by name: under-the-hood/init-cli-flows.md and config-technical/inference-backend-config.md now state the broad reader and the renamed function."+reviewed_at = "2026-09-07T06:07:51Z"+rationale = "Re-ack after the round-1 review changed the same trigger files. The review found the docs half wrong in two ways and both are fixed here. First, I had listed --version under 'Global flags', whose lead sentence promises the flags are position-agnostic; only --no-logo and --traceback are, because PipelexCLI.make_context strips those two out of args by hand, and 'pipelex show --version' really does answer 'No such option'. The flag now sits outside that list with a sentence saying it goes before any subcommand. Second, the handshake section and the module docstring described mthds's PipelexRunner as already parsing these lines; it does not — the Python runner still raises and the TypeScript one assigns stdout wholesale — so the prose now states the contract a consumer should follow (match on the label, never take stdout as one version string) and says plainly that no consumer parses it yet. Filed the two consumer items, L-260907-da820f and L-260907-1aa8cf. Re-reviewed pipelex/cli/agent_cli/CLAUDE.md: its only mention is the code-layout line naming the version callback in _agent_cli.py, still accurate, and an eager --version short-circuits before the success and error format streams that doc's contract sections govern."[trigger_files]"pipelex/cli/__init__.py" = "blob:8b137891791fe96927ad78e64b0aad7bded08bdc"-"pipelex/cli/_cli.py" = "blob:55a391d3eb92fb041c0e58292e048c41fa903234"+"pipelex/cli/_cli.py" = "blob:899a40b2440a27a433a14f18d22ac8574855a358""pipelex/cli/agent_cli/__init__.py" = "blob:e69de29bb2d1d6434b8b29ae775ad8c2e48c5391"-"pipelex/cli/agent_cli/_agent_cli.py" = "blob:8d1bdb80e7a45eb2fbc71df18cf983eaba1dc446"+"pipelex/cli/agent_cli/_agent_cli.py" = "blob:e49ea3d36aa0e964e6d2cc66e901f8362c9ae76b""pipelex/cli/agent_cli/commands/__init__.py" = "blob:e69de29bb2d1d6434b8b29ae775ad8c2e48c5391""pipelex/cli/agent_cli/commands/accept_gateway_terms_cmd.py" = "blob:cb8338c09a7b5dee6088551c156d69dab613213a""pipelex/cli/agent_cli/commands/agent_cli_factory.py" = "blob:c9a251db61d8655bdb41002c62eab88b486fc32f"@@ -132,3 +132,4 @@ rationale = "Merge of origin/dev into feature/Two-gateways-2, re-reviewed on the"pipelex/cli/installed_methods.py" = "blob:09197f47baf8d7251d28d148a0544b4a23ee7365""pipelex/cli/method_resolver.py" = "blob:1230dde5f89ac28bbdcbcbbd0c1d485c71803caf""pipelex/cli/readiness.py" = "blob:6d185324ed0784663e1dc78d1194a28312c54798"+"pipelex/cli/version_report.py" = "blob:f4a2311bb629bd77196ea2f6b031c166db0d362a"diff --git a/.test_durations b/.test_durationsindex e751b48d8..a5a22ba2f 100644--- a/.test_durations+++ b/.test_durations@@ -2926,6 +2926,12 @@"tests/unit/pipelex/cli/test_validate_suggested_fix_rendering.py::TestValidateSuggestedFixRendering::test_footer_preserves_allow_signatures": 0.0043,"tests/unit/pipelex/cli/test_validate_suggested_fix_rendering.py::TestValidateSuggestedFixRendering::test_footer_shell_quotes_paths_with_spaces": 0.0029,"tests/unit/pipelex/cli/test_validate_suggested_fix_rendering.py::TestValidateSuggestedFixRendering::test_non_fixable_errors_keep_generic_tip_and_no_fix_line": 0.0038,+ "tests/unit/pipelex/cli/test_version_report.py::TestVersionHandshake::test_agent_cli_prints_exactly_the_handshake": 1.3299,+ "tests/unit/pipelex/cli/test_version_report.py::TestVersionHandshake::test_bare_cli_prints_exactly_the_handshake": 1.6771,+ "tests/unit/pipelex/cli/test_version_report.py::TestVersionHandshake::test_labels_are_the_literal_strings_a_client_parses": 1.2996,+ "tests/unit/pipelex/cli/test_version_report.py::TestVersionHandshake::test_no_banner_or_other_noise_precedes_the_first_line": 1.4521,+ "tests/unit/pipelex/cli/test_version_report.py::TestVersionHandshake::test_program_name_names_the_first_line_only": 1.2913,+ "tests/unit/pipelex/cli/test_version_report.py::TestVersionHandshake::test_reports_the_three_numbers_in_order": 1.3249,"tests/unit/pipelex/cli/test_which_cmd.py::TestWhichCmd::test_ambiguous_bare_code_reports_candidates": 0.0024,"tests/unit/pipelex/cli/test_which_cmd.py::TestWhichCmd::test_bracketed_pipe_code_renders_literally": 0.0049,"tests/unit/pipelex/cli/test_which_cmd.py::TestWhichCmd::test_empty_library_dirs": 0.003,@@ -10547,6 +10553,24 @@"tests/unit/pipelex/tools/misc/test_semver.py::TestSemver::test_version_satisfies_wildcard[==1.*-1.0.0-True]": 0.001,"tests/unit/pipelex/tools/misc/test_semver.py::TestSemver::test_version_satisfies_wildcard[==1.*-1.9.9-True]": 0.0012,"tests/unit/pipelex/tools/misc/test_semver.py::TestSemver::test_version_satisfies_wildcard[==1.*-2.0.0-False]": 0.0006,+ "tests/unit/pipelex/tools/misc/test_semver_spec_constraint_syntax.py::TestSpecVersionConstraintSyntax::test_an_empty_clause_is_still_a_parse_error": 0.0154,+ "tests/unit/pipelex/tools/misc/test_semver_spec_constraint_syntax.py::TestSpecVersionConstraintSyntax::test_every_documented_form_parses_and_evaluates[!=1.0.0-1.5.0-1.0.0]": 1.593,+ "tests/unit/pipelex/tools/misc/test_semver_spec_constraint_syntax.py::TestSpecVersionConstraintSyntax::test_every_documented_form_parses_and_evaluates[*-1.5.0-None]": 1.3151,+ "tests/unit/pipelex/tools/misc/test_semver_spec_constraint_syntax.py::TestSpecVersionConstraintSyntax::test_every_documented_form_parses_and_evaluates[1.*-1.5.0-2.0.0]": 0.0149,+ "tests/unit/pipelex/tools/misc/test_semver_spec_constraint_syntax.py::TestSpecVersionConstraintSyntax::test_every_documented_form_parses_and_evaluates[1.0-1.0.9-1.5.0]": 0.0143,+ "tests/unit/pipelex/tools/misc/test_semver_spec_constraint_syntax.py::TestSpecVersionConstraintSyntax::test_every_documented_form_parses_and_evaluates[1.0.*-1.0.9-1.5.0]": 1.2988,+ "tests/unit/pipelex/tools/misc/test_semver_spec_constraint_syntax.py::TestSpecVersionConstraintSyntax::test_every_documented_form_parses_and_evaluates[1.0.0-1.0.0-1.5.0]": 1.3083,+ "tests/unit/pipelex/tools/misc/test_semver_spec_constraint_syntax.py::TestSpecVersionConstraintSyntax::test_every_documented_form_parses_and_evaluates[<2.0.0-1.5.0-2.0.0]": 1.3182,+ "tests/unit/pipelex/tools/misc/test_semver_spec_constraint_syntax.py::TestSpecVersionConstraintSyntax::test_every_documented_form_parses_and_evaluates[<=2.0.0-2.0.0-2.0.1]": 1.2897,+ "tests/unit/pipelex/tools/misc/test_semver_spec_constraint_syntax.py::TestSpecVersionConstraintSyntax::test_every_documented_form_parses_and_evaluates[==1.0.0-1.0.0-1.5.0]": 0.0152,+ "tests/unit/pipelex/tools/misc/test_semver_spec_constraint_syntax.py::TestSpecVersionConstraintSyntax::test_every_documented_form_parses_and_evaluates[>1.0.0-1.5.0-1.0.0]": 0.0165,+ "tests/unit/pipelex/tools/misc/test_semver_spec_constraint_syntax.py::TestSpecVersionConstraintSyntax::test_every_documented_form_parses_and_evaluates[>=1.0.0, <2.0.0-1.5.0-2.0.0]": 0.0277,+ "tests/unit/pipelex/tools/misc/test_semver_spec_constraint_syntax.py::TestSpecVersionConstraintSyntax::test_every_documented_form_parses_and_evaluates[>=1.0.0-2.0.0-0.9.0]": 0.015,+ "tests/unit/pipelex/tools/misc/test_semver_spec_constraint_syntax.py::TestSpecVersionConstraintSyntax::test_every_documented_form_parses_and_evaluates[^1.0.0-1.5.0-2.0.0]": 1.676,+ "tests/unit/pipelex/tools/misc/test_semver_spec_constraint_syntax.py::TestSpecVersionConstraintSyntax::test_every_documented_form_parses_and_evaluates[~1.0.0-1.0.0-1.5.0]": 1.305,+ "tests/unit/pipelex/tools/misc/test_semver_spec_constraint_syntax.py::TestSpecVersionConstraintSyntax::test_whitespace_around_clauses_is_not_part_of_the_constraint[ ^1.0.0 -^1.0.0]": 1.2739,+ "tests/unit/pipelex/tools/misc/test_semver_spec_constraint_syntax.py::TestSpecVersionConstraintSyntax::test_whitespace_around_clauses_is_not_part_of_the_constraint[>=1.0.0 , <2.0.0->=1.0.0,<2.0.0]": 0.0114,+ "tests/unit/pipelex/tools/misc/test_semver_spec_constraint_syntax.py::TestSpecVersionConstraintSyntax::test_whitespace_around_clauses_is_not_part_of_the_constraint[>=1.0.0, <2.0.0->=1.0.0,<2.0.0]": 1.8643,"tests/unit/pipelex/tools/misc/test_string_utils.py::TestMatchesWildcardPattern::test_matches_wildcard_pattern[-**-True]": 0.0011,"tests/unit/pipelex/tools/misc/test_string_utils.py::TestMatchesWildcardPattern::test_matches_wildcard_pattern[-*-True]": 0.0009,"tests/unit/pipelex/tools/misc/test_string_utils.py::TestMatchesWildcardPattern::test_matches_wildcard_pattern[-*middle*-False]": 0.0004,diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 658c8c0de..14b8f5a2c 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -1,5 +1,19 @@# Changelog+## [Unreleased]++### Added++- **The `--version` handshake reports three numbers (breaking):** `pipelex --version` and `pipelex-agent --version` now print the runtime version, the MTHDS Protocol version and the MTHDS standard version, one `<label> <version>` line each, instead of the runtime version alone. A client needs all three to know what it is talking to, and they move on independent cadences under the standard's own versioning rule, so no one of them can be inferred from another. The first line keeps its historical `<program> <version>` form, so a consumer that matches a version out of the text is unaffected — but one that treats the whole of stdout as a single version string now holds three lines, and both `mthds` runners have to be adapted. Match on the label, not on the shape of the output as a whole. The two MTHDS numbers are read from the `mthds` package rather than restated here. See [CLI Reference](tools/cli/index.md#the-version-handshake).++### Changed++- **The MTHDS standard version this runtime implements is now `2.0.0` (breaking):** `mthds` moves to `==0.14.0`, whose `MTHDS_STANDARD_VERSION` was cut from `1.0.0` to `2.0.0` — the standard's first cut under its own versioning rule, accounting for breaking changes to the native set and to the manifest, lock and resolution rules that had already shipped unversioned. Two things follow for users, and no pipelex line caused either: every normalized crate this engine emits is stamped `2.0.0` instead of `1.0.0` (crate fingerprints are unaffected — `mthds_version` is excluded from the hashed payload by design), and a `METHODS.toml` whose `mthds_version` pinned the old major, such as `^1.0.0`, now warns where it did not before. A plain floor like `>=1.0.0` is still satisfied. The protocol version is unchanged at `0.6.0`. The pin stays exact, so everyone downstream inherits `mthds==0.14.0`; a consumer depending on `mthds` directly must move in step.++### Fixed++- **Compound version constraints written the documented way now parse:** `parse_constraint` stripped no whitespace around the comma that ANDs a compound constraint's clauses, so `>=1.0.0, <2.0.0` — the exact spelling of the MTHDS standard's own example — was rejected while the identical `>=1.0.0,<2.0.0` parsed. A manifest's `mthds_version` written that way therefore got no compatibility check at all, since the load path degrades an unparseable constraint to a log line. A malformed compound such as `>=1.0.0,,<2.0.0` still fails, because normalizing whitespace must not repair a broken constraint.+## [v0.56.0] - 2026-09-03### Addeddiff --git a/docs/tools/cli/agent-cli.md b/docs/tools/cli/agent-cli.mdindex 4c8fe33de..765957ca8 100644--- a/docs/tools/cli/agent-cli.md+++ b/docs/tools/cli/agent-cli.md@@ -13,7 +13,7 @@ It is consumed by the `mthds-agent` CLI (from the `mthds` npm package) which its| Option | Description ||--------|-------------|| `--runner` | Select the runner backend to use (`pipelex` or `api`) |-| `--version` | Print the version and exit |+| `--version` | Print the version handshake — the runtime version, the MTHDS Protocol version and the MTHDS standard version — and exit. Same three lines as `pipelex --version`; see the [CLI reference](index.md#the-version-handshake) |There is no `--log-level` flag: `pipelex-agent` is machine-consumed, so logging is cut off process-wide by design.diff --git a/docs/tools/cli/index.md b/docs/tools/cli/index.mdindex 9d3a109ed..22a316786 100644--- a/docs/tools/cli/index.md+++ b/docs/tools/cli/index.md@@ -30,6 +30,26 @@ These flags work on any `pipelex` command and are position-agnostic — place th- `--traceback` - print the full Rich-rendered stack trace before the friendly one-line error. Off by default. Both `pipelex run --traceback pipe ...` and `pipelex run pipe ... --traceback` work.- `--no-logo` - suppress the startup logo banner. Handy for clean logs and to save tokens in agent output.+`--version` / `-V` is **not** one of these: it is an option on the root command, so it goes before any subcommand (`pipelex --version`, never `pipelex show --version`). See below.++## The version handshake++`pipelex --version` reports three numbers, not one, because a client needs all three to know what it is talking to and they move on independent cadences:++```+pipelex <runtime version>+mthds-protocol <MTHDS Protocol version>+mthds-standard <MTHDS standard version>+```++- `pipelex` — the installed runtime's own version.+- `mthds-protocol` — the version of the MTHDS Protocol this runtime speaks — the request and response shapes of the runner operations.+- `mthds-standard` — the version of the [MTHDS standard](https://mthds.ai/latest/) it implements: the language, the native concept set, and what a manifest's `mthds_version` constraint is evaluated against.++`pipelex-agent --version` prints the same three lines, with `pipelex-agent` naming the first.++The shape is a contract rather than presentation: the output is exactly these three lines, each `<label> <version>`, the labels are stable, and the first line keeps the historical `<program> <version>` form. It is meant to be read by clients that drive the CLI as a subprocess and turn it into a protocol `VersionInfo` — a consumer should match on the label rather than on line position, and must not treat the whole of stdout as a single version string.+## Related CLI SurfacePackage manifest management currently lives in the `mthds` CLI:diff --git a/pipelex/cli/_cli.py b/pipelex/cli/_cli.pyindex 55a391d3e..899a40b24 100644--- a/pipelex/cli/_cli.py+++ b/pipelex/cli/_cli.py@@ -24,6 +24,7 @@ from pipelex.cli.commands.which_cmd import which_cmdfrom pipelex.cli.deck_notice import warn_if_deck_stalefrom pipelex.cli.error_handlers import set_traceback_requestedfrom pipelex.cli.readiness import check_readiness+from pipelex.cli.version_report import version_report_linesfrom pipelex.runtime_hub import get_consolefrom pipelex.tools.misc.package_utils import get_package_version@@ -104,10 +105,10 @@ app = typer.Typer(def version_callback(value: bool) -> None: # kw-only: ignore — click invokes Option callbacks positionally- """Print version and exit when --version is passed."""+ """Print the version handshake and exit when --version is passed."""if value:- package_version = get_package_version()- typer.echo(f"pipelex {package_version}")+ for line in version_report_lines(program_name="pipelex"):+ typer.echo(line)raise typer.Exitdiff --git a/pipelex/cli/agent_cli/_agent_cli.py b/pipelex/cli/agent_cli/_agent_cli.pyindex 8d1bdb80e..e49ea3d36 100644--- a/pipelex/cli/agent_cli/_agent_cli.py+++ b/pipelex/cli/agent_cli/_agent_cli.py@@ -25,7 +25,7 @@ from pipelex.cli.agent_cli.commands.models_cmd import agent_models_cmdfrom pipelex.cli.agent_cli.commands.pipe_cmd import pipe_cmdfrom pipelex.cli.agent_cli.commands.run.app import run_appfrom pipelex.cli.agent_cli.commands.validate.app import validate_app-from pipelex.tools.misc.package_utils import get_package_version+from pipelex.cli.version_report import version_report_linesclass PipelexAgentCLI(TyperGroup):@@ -77,10 +77,10 @@ app = typer.Typer(def version_callback(value: bool) -> None: # kw-only: ignore — click invokes Option callbacks positionally- """Print version and exit when --version is passed."""+ """Print the version handshake and exit when --version is passed."""if value:- package_version = get_package_version()- typer.echo(f"pipelex-agent {package_version}")+ for line in version_report_lines(program_name="pipelex-agent"):+ typer.echo(line)raise typer.Exitdiff --git a/pipelex/cli/version_report.py b/pipelex/cli/version_report.pynew file mode 100644index 000000000..f4a2311bb--- /dev/null+++ b/pipelex/cli/version_report.py@@ -0,0 +1,51 @@+"""The version handshake both CLIs print for `--version`.++A client of the `pipelex` CLI needs three numbers, not one: the runner's own version,+the MTHDS Protocol version it speaks, and the MTHDS standard version it implements.+The runner version alone cannot answer either question — the three move on independent+cadences by the standard's own versioning rule (`mthds/docs/spec/versioning.md`).++The two numbers that are not pipelex's own are read from the `mthds` package rather+than restated here, so this repo never becomes a second place a version is written.++**This output is a contract, and it is a breaking change to what `--version` printed+before.** A client that drives the CLI as a subprocess should match a line on its label+and read the version after it; one that takes the whole of stdout as a single version+string now holds three lines. The `mthds` runners are that consumer and both still have+to be adapted — the Python one raises rather than reporting a version at all, and the+TypeScript one assigns stdout wholesale — so nothing parses these labels yet.+"""++from mthds.package.manifest.schema import MTHDS_STANDARD_VERSION+from mthds.protocol.protocol import PROTOCOL_VERSION++from pipelex.tools.misc.package_utils import get_package_version++MTHDS_PROTOCOL_LABEL = "mthds-protocol"+"""Label of the MTHDS Protocol line. Part of the CLI's parsed contract — see the module docstring."""++MTHDS_STANDARD_LABEL = "mthds-standard"+"""Label of the MTHDS standard line. Part of the CLI's parsed contract — see the module docstring."""+++def version_report_lines(*, program_name: str) -> list[str]:+ """The `--version` output, one `<label> <version>` line per number.++ The shape is a stable contract, not presentation — see the module docstring for what a+ consumer may rely on. The first line keeps the pre-existing `<program> <version>` form,+ so a consumer that matches a version out of the text still works; the two MTHDS lines+ are appended below it, which does break one that consumed stdout whole.++ Args:+ program_name: The console script the caller invoked (`pipelex`, `pipelex-agent`),+ which names the first line.++ Returns:+ The lines to print, in order: the runner version, the protocol version, the+ standard version.+ """+ return [+ f"{program_name} {get_package_version()}",+ f"{MTHDS_PROTOCOL_LABEL} {PROTOCOL_VERSION}",+ f"{MTHDS_STANDARD_LABEL} {MTHDS_STANDARD_VERSION}",+ ]diff --git a/pipelex/tools/misc/semver.py b/pipelex/tools/misc/semver.pyindex 99a79636d..6182eff94 100644--- a/pipelex/tools/misc/semver.py+++ b/pipelex/tools/misc/semver.py@@ -40,8 +40,18 @@ def parse_version(version_str: str) -> Version:def parse_constraint(constraint_str: str) -> SimpleSpec:"""Parse a constraint string into a semantic_version.SimpleSpec.+ The MTHDS grammar ANDs the clauses of a compound constraint with a comma and writes+ that form with a space after it (`>=1.0.0, <2.0.0` — the "Compound" row of the spec's+ version-constraint table, whose syntax column is literally ``constraint ", " constraint``).+ ``SimpleSpec`` splits on the comma but does not strip the clauses, so it rejects the+ documented form on the leading space alone. Normalizing the whitespace around each+ clause is what makes the two spellings the same constraint, as they are in the grammar.++ An empty clause is deliberately left empty rather than dropped, so `>=1.0.0,,<2.0.0`+ stays a parse error instead of being silently repaired.+Args:- constraint_str: The constraint string to parse (e.g. "^1.2.3", ">=1.0.0,<2.0.0").+ constraint_str: The constraint string to parse (e.g. "^1.2.3", ">=1.0.0, <2.0.0").Returns:The parsed SimpleSpec object.@@ -49,8 +59,9 @@ def parse_constraint(constraint_str: str) -> SimpleSpec:Raises:SemVerError: If the constraint string is not valid."""+ normalized = ",".join(clause.strip() for clause in constraint_str.split(","))try:- return SimpleSpec(constraint_str)+ return SimpleSpec(normalized)except ValueError as exc:msg = f"Invalid semver constraint: {constraint_str!r}"raise SemVerError(msg) from excdiff --git a/pyproject.toml b/pyproject.tomlindex 4f2a2757a..d4c1d8317 100644--- a/pyproject.toml+++ b/pyproject.toml@@ -31,7 +31,7 @@ dependencies = ["json2html>=1.3.0","kajson==0.7.1","markdown>=3.6",- "mthds==0.13.0",+ "mthds==0.14.0","networkx>=3.4.2","openai>=2.0.0","opentelemetry-api",diff --git a/tests/unit/pipelex/cli/test_version_report.py b/tests/unit/pipelex/cli/test_version_report.pynew file mode 100644index 000000000..590a8ce7a--- /dev/null+++ b/tests/unit/pipelex/cli/test_version_report.py@@ -0,0 +1,60 @@+"""The `--version` handshake: three numbers, on both CLIs, in a shape a client can parse.++The output is a contract rather than presentation — a client drives the CLI as a subprocess+and turns these lines into a protocol `VersionInfo`. So the assertions here pin the contract+itself: the labels as literal strings, and the output as *exactly* the three lines. Bounding+the output is the half that matters for a machine consumer, since anything printed ahead of+the handshake (a logo banner, a warning) breaks it just as surely as a missing line.+"""++from mthds.package.manifest.schema import MTHDS_STANDARD_VERSION+from mthds.protocol.protocol import PROTOCOL_VERSION+from typer.testing import CliRunner++from pipelex.cli._cli import app as pipelex_app+from pipelex.cli.agent_cli._agent_cli import app as agent_app+from pipelex.cli.version_report import MTHDS_PROTOCOL_LABEL, MTHDS_STANDARD_LABEL, version_report_lines+from pipelex.tools.misc.package_utils import get_package_version+++class TestVersionHandshake:+ """The shared builder, and what each CLI's `--version` actually prints."""++ def test_labels_are_the_literal_strings_a_client_parses(self) -> None:+ """Pinned as literals on purpose: reading them from the constants under test+ would let a rename pass, and a rename is exactly the break that reaches a client.+ """+ assert MTHDS_PROTOCOL_LABEL == "mthds-protocol"+ assert MTHDS_STANDARD_LABEL == "mthds-standard"++ def test_reports_the_three_numbers_in_order(self) -> None:+ lines = version_report_lines(program_name="pipelex")+ assert lines == [+ f"pipelex {get_package_version()}",+ f"{MTHDS_PROTOCOL_LABEL} {PROTOCOL_VERSION}",+ f"{MTHDS_STANDARD_LABEL} {MTHDS_STANDARD_VERSION}",+ ]++ def test_program_name_names_the_first_line_only(self) -> None:+ lines = version_report_lines(program_name="pipelex-agent")+ assert lines[0] == f"pipelex-agent {get_package_version()}"+ assert lines[1:] == version_report_lines(program_name="pipelex")[1:]++ def test_bare_cli_prints_exactly_the_handshake(self) -> None:+ result = CliRunner().invoke(pipelex_app, ["--version"])+ assert result.exit_code == 0+ assert result.output.splitlines() == version_report_lines(program_name="pipelex")++ def test_agent_cli_prints_exactly_the_handshake(self) -> None:+ result = CliRunner().invoke(agent_app, ["--version"])+ assert result.exit_code == 0+ assert result.output.splitlines() == version_report_lines(program_name="pipelex-agent")++ def test_no_banner_or_other_noise_precedes_the_first_line(self) -> None:+ """The logo banner does print ahead of output on other paths, and anything ahead of+ the handshake breaks a machine consumer as surely as a missing line does.+ """+ for app, program_name in ((pipelex_app, "pipelex"), (agent_app, "pipelex-agent")):+ output = CliRunner().invoke(app, ["--version"]).output+ assert output.startswith(f"{program_name} ")+ assert len(output.splitlines()) == 3diff --git a/tests/unit/pipelex/tools/misc/test_semver_spec_constraint_syntax.py b/tests/unit/pipelex/tools/misc/test_semver_spec_constraint_syntax.pynew file mode 100644index 000000000..19fc8ff2f--- /dev/null+++ b/tests/unit/pipelex/tools/misc/test_semver_spec_constraint_syntax.py@@ -0,0 +1,63 @@+# pyright: reportUnknownMemberType=false, reportUnknownVariableType=false, reportUnknownArgumentType=false+"""The MTHDS standard's "Version Constraint Syntax" table, exercised row by row.++That table in `mthds/docs/spec/manifest-format.md` is the contract `parse_constraint`+implements, so it gets a module of its own rather than riding along in the wrapper's unit+tests. Its compound row is written `>=1.0.0, <2.0.0` — with the space — and that row was+the one form never exercised: `SimpleSpec` splits on the comma without stripping, so the+leading space of the second clause made the whole constraint invalid.+"""++import pytest++from pipelex.tools.misc.semver import SemVerError, parse_constraint, parse_version, version_satisfies+++class TestSpecVersionConstraintSyntax:+ """Every row of the table, as written there, plus the whitespace equivalences it implies."""++ @pytest.mark.parametrize(+ ("constraint", "satisfying", "unsatisfying"),+ [+ ("1.0.0", "1.0.0", "1.5.0"),+ ("^1.0.0", "1.5.0", "2.0.0"),+ ("~1.0.0", "1.0.0", "1.5.0"),+ (">=1.0.0", "2.0.0", "0.9.0"),+ ("<2.0.0", "1.5.0", "2.0.0"),+ (">1.0.0", "1.5.0", "1.0.0"),+ ("<=2.0.0", "2.0.0", "2.0.1"),+ ("==1.0.0", "1.0.0", "1.5.0"),+ ("!=1.0.0", "1.5.0", "1.0.0"),+ (">=1.0.0, <2.0.0", "1.5.0", "2.0.0"),+ ("*", "1.5.0", None),+ ("1.*", "1.5.0", "2.0.0"),+ ("1.0.*", "1.0.9", "1.5.0"),+ ("1.0", "1.0.9", "1.5.0"),+ ],+ )+ def test_every_documented_form_parses_and_evaluates(self, constraint: str, satisfying: str, unsatisfying: str | None) -> None:+ parsed = parse_constraint(constraint)+ assert version_satisfies(parse_version(satisfying), constraint=parsed)+ if unsatisfying is not None:+ assert not version_satisfies(parse_version(unsatisfying), constraint=parsed)++ @pytest.mark.parametrize(+ ("spaced", "tight"),+ [+ (">=1.0.0, <2.0.0", ">=1.0.0,<2.0.0"),+ (">=1.0.0 , <2.0.0", ">=1.0.0,<2.0.0"),+ (" ^1.0.0 ", "^1.0.0"),+ ],+ )+ def test_whitespace_around_clauses_is_not_part_of_the_constraint(self, spaced: str, tight: str) -> None:+ """The two spellings are one constraint in the grammar, so they must agree on every version."""+ spaced_spec = parse_constraint(spaced)+ tight_spec = parse_constraint(tight)+ for version_str in ("0.9.0", "1.0.0", "1.5.0", "2.0.0"):+ version = parse_version(version_str)+ assert version_satisfies(version, constraint=spaced_spec) == version_satisfies(version, constraint=tight_spec)++ def test_an_empty_clause_is_still_a_parse_error(self) -> None:+ """Stripping normalizes whitespace; it must not silently repair a malformed compound."""+ with pytest.raises(SemVerError):+ parse_constraint(">=1.0.0,,<2.0.0")diff --git a/uv.lock b/uv.lockindex 72e0ba8e2..9cea9be83 100644--- a/uv.lock+++ b/uv.lock@@ -2552,7 +2552,7 @@ wheels = [[[package]]name = "mthds"-version = "0.13.0"+version = "0.14.0"source = { registry = "https://pypi.org/simple" }dependencies = [{ name = "httpx" },@@ -2561,9 +2561,9 @@ dependencies = [{ name = "tomlkit" },{ name = "typing-extensions" },]-sdist = { url = "https://files.pythonhosted.org/packages/e4/b6/6c67b86693d01d473444523db0aeadc1afdffaa1748a264dfab9c1c77b1c/mthds-0.13.0.tar.gz", hash = "sha256:ef59ffa94902da72371390cc39d8c0d85dfd2a524dbca2a8909a0a1ba6255607", size = 216142, upload-time = "2026-09-02T15:09:15.937Z" }+sdist = { url = "https://files.pythonhosted.org/packages/92/59/4ca9539571a2030f9427aeddb01bc334910953ebdfa4ab7db2051a6b8ae7/mthds-0.14.0.tar.gz", hash = "sha256:d2b4a9cd064004dfd5b802bb71c9894601fba9e598426f96e4bede16d52c3900", size = 221186, upload-time = "2026-09-06T21:44:54.585Z" }wheels = [- { url = "https://files.pythonhosted.org/packages/89/26/f73e625b54cfba2e09a29df5e7173e508c25d3f7ce106be69fae6065d76c/mthds-0.13.0-py3-none-any.whl", hash = "sha256:606fef7978bbc8a5b249882c0b9377fed37123f618f8183f29e89b71a4eadac0", size = 85993, upload-time = "2026-09-02T15:09:14.334Z" },+ { url = "https://files.pythonhosted.org/packages/28/0b/32908eeed33396c5aafd4bcb2a1adc38d0ab8d85c2fde3af0bf4c2f73745/mthds-0.14.0-py3-none-any.whl", hash = "sha256:59a706205b6e6df47345caac01038588d21ab9e9c246afc765ee50b5f27f05a8", size = 87192, upload-time = "2026-09-06T21:44:53.022Z" },][[package]]@@ -3472,7 +3472,7 @@ requires-dist = [{ name = "mkdocs-meta-manager", marker = "extra == 'docs'", specifier = ">=1.1.0" },{ name = "mkdocs-redirects", marker = "extra == 'docs'", specifier = "==1.2.2" },{ name = "moto", extras = ["dynamodb", "s3"], marker = "extra == 'dev'", specifier = ">=5.0.0" },- { name = "mthds", specifier = "==0.13.0" },+ { name = "mthds", specifier = "==0.14.0" },{ name = "mypy", marker = "extra == 'dev'", specifier = "==1.19.1" },{ name = "networkx", specifier = ">=3.4.2" },{ name = "openai", specifier = ">=2.0.0" },