Skip to content

feat(cli): group advanced verbs under a lab subcommand (keep every verb) - #1169

Merged
Birfy merged 2 commits into
mainfrom
feat/1112-lab-grouping
Nov 19, 2026
Merged

Birfy merged 2 commits into
mainfrom
feat/1112-lab-grouping

Conversation

@HugoXK

@HugoXK HugoXK commented Nov 19, 2026 •

Copy link
Copy Markdown
Collaborator

Fixes #1112.

What changed

agentdescent --help now shows one first-run path; every other verb moved into an additive lab group. Nothing was removed, renamed or deprecated.

  • One declaration per verb. The 41 verb blocks now live in _register_commands(mount, *, with_lab) (agentdescent/cli.py), and build_parser() mounts them twice: at the top level (_CommandMount(..., listed=False), which drops help for anything outside DEFAULT_SURFACE) and under lab (listed=True). No block is copied.
  • Default surface. DEFAULT_SURFACE is demo, init, plan, evolve, show, apply, doctor, status, lab, mcp. It decides the help listing and the usage {…} only — the listing is sorted to that order and the metavar is built from it.
  • Advanced verbs keep their top-level path. They are still registered there; they just carry no help line, the mechanism run has used since cli: agentdescent --help prints run ==SUPPRESS== and advertises the internal run worker in usage #420. agentdescent campaign … and agentdescent lab campaign … both parse; only the listing changed.
  • lab mounts every verb but itself, so the group is not recursive (lab lab is not a command) and the first-run verbs are reachable there too (lab status, lab doctor).
  • The internal run verb is reachable as lab run. agentdescent lab run --run-dir … parses to the same fn, has no help line at either mount (it stays internal), and _INTERNAL_COMMANDS keeps it out of choose from lists.
  • No behavior change. No fn, argument, output or exit code moved; the tests assert both paths parse to the same dispatch and the same namespace apart from the dispatch keys (cmd, lab_cmd).
  • changelog.d/1112-lab-grouping.md added (one Changed entry).
agentdescent lab campaign --spec campaign.json
agentdescent campaign --spec campaign.json          # unchanged path

Verification at the tip

Tip SHA: 7bbb727

Red first, at origin/main f8efc73 with only tests/test_cli_lab_grouping.py added — 77 failed, 32 passed:

  • FAILED tests/test_cli_lab_grouping.py::test_the_usage_line_names_the_same_surface — assert ['demo', 'ini…', 'watch', …] == ['demo', 'ini…', 'show', …] (all 40 public verbs listed)
  • FAILED tests/test_cli_lab_grouping.py::test_lab_path_parses_like_the_top_level[demo] — SystemExit: 2, invalid choice: 'lab'

Ran at this tip:

  • pytest -q tests/test_cli_lab_grouping.py tests/test_cli_help_hides_internal_run.py → 123 passed
  • pytest -q over every CLI/help/integration file (test_cli*, test_meta_cli, test_snapshot_cli, test_runstore_cli, test_plain_cli_warnings, test_missing_cli_kind_remedy, test_plugin_host_cli, test_resume_host_cli, test_mcp_*, test_demo) → 588 passed
  • full suite, 8 parallel chunks: 7 855 passed, 21 failed, 51 skipped, 10 errors. Those 21 failures + 10 errors are the docker / read-only-$HOME files (test_sandbox_container, test_apply_noop, test_era_srbench, test_genesis_example, test_skill_library_*, test_integrations, test_dir_evolution, test_skill_dir_example) and reproduce identically at f8efc73 in the same files: 21 failed, 436 passed, 15 skipped, 10 errors at base and at tip.
  • python -m tools.gen_api_docs --check → docs/api.md is up to date (no regeneration needed)
  • python -m tools.changelog_fragments check → 81 changelog fragment(s) OK
  • tests/test_cli_help_hides_internal_run.py::test_every_public_verb_is_still_listed_in_order updated to the new contract: the usage line lists the surface, and the advanced verbs are hidden from it, not removed.

Not run:

  • the docker sandbox cases and the read-only-$HOME cases — no docker on this host; CI runs them, and they behaved the same at the base commit

Help surface at this tip

usage: agentdescent [-h] [-V] [--store STORE] [--json]
                    {demo,init,plan,evolve,show,apply,doctor,status,lab,mcp}
                    ...

No UI surface: terminal help text only.

@HugoXK HugoXK added enhancement New feature or request area:cli The agentdescent command line (cli.py, doctor, plan/evolve/status/apply) agent-pr Pull request opened by an agent labels Nov 19, 2026
@HugoXK
HugoXK marked this pull request as ready for review November 19, 2026 13:54
@HugoXK

HugoXK commented Nov 19, 2026

Copy link
Copy Markdown
Collaborator Author

Tip SHA: 7bbb72747540c5853edb4c5e604965d1e0a0a999

Base: f8efc7315497191ad35b87105f9d88c1e5119e4e (merge-base; ahead 2 / behind 0; 2 commits, 4 files +220/−8). PR at read: open, non-draft, mergeable: true, mergeable_state: clean, labels enhancement, area:cli, agent-pr.

Ran — fresh clone at this sha, PYTHONPATH=<clone>, pytest -o addopts="" -q -p no:cacheprovider:

  • tests/test_cli_lab_grouping.py tests/test_cli_help_hides_internal_run.py → 123 passed in 17.35s (my own run).
  • Red first, worktree at f8efc731 with only tests/test_cli_lab_grouping.py added → 77 failed, 32 passed in 18.76s. The 32 green rows on base are exactly test_a_hidden_verb_still_answers_help[...] (those verbs do exist at the top level there); the three surface rows and every lab-path row are red. This matches the author's count.
  • CLI subset — every tests/test_cli*.py, plus tests/test_runstore_cli.py and tests/test_api_docs.py (26 files) → 417 passed in 113.83s.
  • Gates: python -m tools.gen_api_docs --check → docs/api.md is up to date; python -m tools.changelog_fragments check → 81 changelog fragment(s) OK.

Independently at this sha:

  • DEFAULT_SURFACE in source is exactly ("demo", "init", "plan", "evolve", "show", "apply", "doctor", "status", "lab", "mcp"); format_help() lists exactly those ten in that order; format_usage() braces are the same ten; run appears in neither the help lines nor the braces.
  • The top parser has 42 choices = the 41 verbs + lab; lab holds 41 (every verb but itself, same registration order), so the group is not recursive and lab lab is not a command.
  • All 41 verbs answer --help with rc 0 and non-empty output at their old top-level path and under lab (82 invocations).
  • The two mounts are declaration-identical: for all 41 verbs, same dests, option strings, action types, required flags, defaults, choices keys and nargs — the grouping changed presentation only.
  • Hidden verbs are hidden from the listing only: campaign/tenant/serve have no help line but are in sub.choices; agentdescent algorithms list and agentdescent lab algorithms list are byte-identical, rc 0.
  • lab <verb> == <verb>, text and rc, byte-for-byte on real commands: doctor --json (2614 B, rc 1 both), status on an empty store (rc 0), show latest (rc 2), plan on an 8-case offline text spec (rc 0, 801 B; --json 2822 B), show --json latest (222 B, rc 2), and --json before the verb at both mounts.
  • lab run --help → rc 0, usage printed; the internal verb stays reachable and still has no help line at either mount.
  • Unknown verb: the top-level message lists 41 names — the 40 public verbs plus lab, with run still stripped (cli: unknown verb error lists the internal run worker and has no did-you-mean #886) — no duplicates, registration order kept, did you mean still appended; lab bogus lists the same 40 minus lab. did you mean 'campaign' fires at both paths.
  • Dispatch: no code branches on args.cmd (only the new lab_cmd dest), so the two paths cannot diverge after parsing.
  • CI at this sha, my own read, all 10 settled: test (3.9) success 14:02:13Z, (3.10) 13:48:46Z, (3.11) 13:47:26Z, (3.12) 13:51:59Z, (3.13) 13:47:29Z, build 13:34:16Z, otel-wire 13:32:58Z, reviewed tip 13:31:51Z, risk tier 13:31:52Z; deploy skipped 13:34:16Z — 9 success + 1 skipped, none red.

Not run:

  • Full pytest -q locally — CI's five pytest -q legs at this sha are the line and all five are green above.
  • mkdocs build --strict — no docs/ page in the diff (only changelog.d/); CI build is green.
  • Docker rows — no daemon on this box.

No UI surface: terminal help text only; there is no rendered interface to screenshot, and the body quotes the usage line instead.

Non-blocking:

  1. agentdescent lab advertises the internal run verb in its usage braces (41 names incl. run); it still has no help line and stays out of every choose from list, so this is cosmetic — the top-level braces remain the ten.
  2. No risk:* label on the PR at read time while the risk tier job is green (report only).
  3. agent-pr is on the PR (the repo's controller applies it; we add it nowhere).

Verdict: PASS — advisory QA verdict at 7bbb72747540c5853edb4c5e604965d1e0a0a999 only. No merge action from QA: this report is advisory, the merge gate is the repo's review decision on the head sha, and the merge itself is executed by the repo's merge process.

@HugoXK

HugoXK commented Nov 19, 2026

Copy link
Copy Markdown
Collaborator Author

7bbb72747540c5853edb4c5e604965d1e0a0a999 — no blocking code finding at this tip.

Fresh clone at the named sha (f8efc731..7bbb7274, fast-forward, 2 commits, 4 files, +220/−8). I read the diff, then re-derived each contract line from the parser and from behaviour rather than from the commit message.

Contract. DEFAULT_SURFACE is exactly demo, init, plan, evolve, show, apply, doctor, status, lab, mcp (cli.py:5954-5955); the usage metavar is built from it in that order (cli.py:6082) and format_help() lists exactly those ten in that order. All 41 pre-existing verbs still parse at the top level, and 41/41 parse under lab to the same fn with the same namespace apart from cmd/lab_cmd. lab mounts 41 verbs and not itself (lab lab → invalid choice, rc 2); advanced verbs are hidden from the listing only and each answers --help at both paths. run keeps its top-level path and lab run parses to cmd_run with the same run_dir/budget.

Zero-change evidence, independent of the new tests. <verb> --help is byte-identical between f8efc731 and the tip for all 41 verbs. Sampled commands are path-independent: status, status --brief, doctor, doctor --json (byte-identical 2254-byte payload, rc 1), algorithms, show latest (rc 2 error) give identical stdout/stderr/rc as <verb> and lab <verb>; lab status --json and --json lab status both rc 0.

Tests and gates. At the tip: tests/test_cli_lab_grouping.py + tests/test_cli_help_hides_internal_run.py → 123 passed; all 26 tests/test_cli*.py → 361 passed. Red first: worktree at f8efc731 with only the new test file → 77 failed, 32 passed (matches the body). python -m tools.gen_api_docs --check → docs/api.md is up to date; python -m tools.changelog_fragments check → 81 fragment(s) OK.

Non-blocking — cli.py:6921. lab.add_subparsers(dest="lab_cmd", required=True) leaves metavar at argparse's default, so agentdescent lab --help and the usage line on a lab usage error print run inside the {…} list — the verb cli.py:5946-5948 says is kept out of --help, the usage line and choose-from lists (and the body says it "stays internal"). The lab positional list and the choose-from lists are clean (40 lines; run absent), so this is presentation only, with no parsing or behaviour effect. One-line fix if wanted: metavar="{" + ",".join(n for n in lsub.choices if n not in _INTERNAL_COMMANDS) + "}" on the lab subparsers, plus an assertion that run is not in lab.format_usage(). Whether that is worth a re-tip is a queue call; it does not change the contract lines above.

Not run: full pytest -q (CLI subsets above only); mkdocs build --strict (no docs change; mkdocs absent here); the docker/read-only-$HOME cases in the body (no docker here).

Merge path: the owner's PASS at this tip and the explicit click; nothing here approves or merges.

@HugoXK

HugoXK commented Nov 19, 2026

Copy link
Copy Markdown
Collaborator Author

Advisory read at 7bbb72747540c5853edb4c5e604965d1e0a0a999 — from the QA seat, not a counting PASS (.github/agent/review-policy.json counts Birfy only), and I take no merge action.

T2 by path (agentdescent/cli.py + tests + one fragment), 4 files +220/−8 = 228 changed lines, under the 250-line T2 cap. Live in the same read as the head: open, draft: false, mergeable_state: clean, base f8efc731, body Tip SHA: == head.

Tip SHA: 7bbb727
Ran:

  • pytest -q -n 8 at the tip → 21 failed, 7843 passed, 63 skipped, 10 errors (312.02s). Same 31 red ids as on unmodified main f8efc731 under the same command: 0 new red, 0 vanished.
  • fail-on-main: tests/test_cli_lab_grouping.py only, onto f8efc731 → 77 failed, 32 passed (the body's exact row); the modified tests/test_cli_help_hides_internal_run.py adds 1 failed, 13 passed.
  • python -m tools.gen_api_docs --check → docs/api.md is up to date.
  • python -m tools.changelog_fragments check → 81 fragments OK.
    Not run:
  • mkdocs build --strict — no docs/ or mkdocs.yml change in the diff.
  • Docker sandboxes, wheel smoke, Ark real-model — the red ids are host state; no model path changed.
  • risk_gate.py — no gh on this box; the tier above is computed from .github/agent/risk-rules.json.

Findings:

  • none. Probe at the tip: 41 top-level verbs, the identical set to main's 41; lab mounts all 41 and not itself; campaign is absent from the top-level listing and present under lab; the usage metavar lists the 10 default verbs in DEFAULT_SURFACE order.
  • Body nit: it has Not run: but no Ran: line; the template asks for both.
  • The agent-pr label is the controller's write (controller.py:187), not this seat's.

No UI surface: the CLI help listing only; nothing rendered changes.

@Birfy

Birfy commented Nov 19, 2026

Copy link
Copy Markdown
Collaborator

Self-review (Birfy)

Tip SHA: 7bbb727
Ran:

  • .github/scripts/risk_gate.py --pr 1169 → T2 (228 lines / 4 files)
  • pytest -q tests/test_cli_lab_grouping.py tests/test_cli_help_hides_internal_run.py → 123 passed
  • python -m tools.changelog_fragments check → 81 fragment(s) OK
  • Red first: tests/test_cli_lab_grouping.py on origin/main (f8efc73) → failed (no lab group / default surface)
  • Required CI at this tip → green (build, test 3.9–3.13, otel-wire)
    Not run:
  • Full offline suite locally — the CI test matrix is the line
  • Ark real-model run — no model path changed
    Findings:
  • No actionable defects. Every verb stays on its top-level path with the same arguments; lab <verb> is a second mount of the same declarations; default --help lists only the first-run surface.
    Verdict: PASS

@Birfy
Birfy merged commit b637606 into main Nov 19, 2026
10 checks passed
@Birfy
Birfy deleted the feat/1112-lab-grouping branch November 19, 2026 16:23
Birfy added a commit that referenced this pull request Nov 19, 2026
Closes #1171

## What changed

After #1169, `lab` mounts every verb, including the internal `run`
worker that `evolve --detach` spawns. Help already omitted its line, and
`_visible_choices` already stripped it from `choose from`, but the `lab`
subparsers left argparse's default metavar, so `agentdescent lab --help`
and the usage line on a `lab` argparse error (plain and `--json`) listed
`run` in the braces.

`build_parser` now sets that metavar from the public choices, the same
#420 contract as the top-level usage line. `agentdescent lab run
--run-dir …` still parses.

- `agentdescent/cli.py`: set `lab_sub.metavar` from choices minus
`_INTERNAL_COMMANDS`.
- `tests/test_cli_help_hides_internal_run.py`: pin help/usage, a typo
error, the `--json` envelope, and that `lab run` still parses.
- `changelog.d/1171-lab-hides-internal-run.md`.

No other verb's arguments, output, or exit code change.

## Verification

Tip SHA: 594b177

Red first, at `origin/main` `367d140f` with only the new tests:

- `FAILED test_lab_help_and_usage_do_not_list_run` — `run` in the braces
- `FAILED test_lab_every_listed_verb_has_a_help_line` — `run` has no
help line
- `FAILED test_lab_unknown_verb_error_does_not_list_run` — usage on `lab
xyz` lists `run`
- `FAILED test_lab_unknown_verb_json_hides_run` — `--json` `usage` lists
`run`
- `test_lab_run_still_parses` passed (already reachable)

Ran:

- `pytest -q tests/test_cli_help_hides_internal_run.py
tests/test_cli_lab_grouping.py` → 128 passed
- `python -m tools.changelog_fragments check` → 83 changelog fragment(s)
OK
- `agentdescent lab --help` usage braces start
`{demo,init,plan,evolve,status,watch,...}` (no `run`)
- `agentdescent --json lab xyz` — `"run"` is not in `error` or `usage`

Not run:

- Full offline suite — this diff is the `lab` usage metavar plus tests
that pin #420; the CI test matrix is the line
- `python -m tools.gen_api_docs --check` — no public API docstring
change

No UI surface: terminal help and argparse error text only.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

agent-pr Pull request opened by an agent area:cli The agentdescent command line (cli.py, doctor, plan/evolve/status/apply) enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

cli: an additive 'lab' grouping so first-run help is one path (keep every verb)

2 participants