Skip to content

Expose AMS per-repo run-state as a read-only MCP tool (gittensory_miner_get_run_state) #5160

Description

@JSONbored

Context

AMS tracks per-repo run-state (idle/discovering/planning/preparing, keyed by owner/repo) in packages/gittensory-miner/lib/run-state.js. ORB already exposes an analogous surface as gittensory_get_automation_state. AMS has no MCP-exposed read path into this state today, so a caller cannot tell what an autonomously running miner is currently doing on a given repo without inspecting local state directly.

Dependencies

Requires the AMS MCP server scaffold to exist first (same scaffold C06/C07 depend on). Otherwise independent — not mentioned in Wave 5 or Wave 3.5, and unrelated to #4840 (cron/systemd/alerting guidance docs).

Requirements

  1. Add a new MCP tool, gittensory_miner_get_run_state, registered on the AMS MCP server.
  2. The tool must read via packages/gittensory-miner/lib/run-state.js's existing state accessor(s) — reuse the existing read function rather than re-implementing state lookup.
  3. Accept an owner/repo key as an input parameter; if run-state.js already supports listing all repos' states, also support an unfiltered "list all" mode.
  4. Return the state string (idle/discovering/planning/preparing) plus any other already-existing per-repo metadata run-state.js exposes for that key — do not invent new state fields.
  5. This PR must be strictly read-only: it must NOT add a state set or any other mutation tool. A remote mutation capability is explicitly out of scope for this issue and needs its own separate safety discussion/issue.
  6. Handle the "unknown repo" / "no state yet" case explicitly (e.g. return an explicit idle/unknown result rather than throwing), with a test covering that path.
  7. The tool's MCP-facing description must state that this is the read-only analog of ORB's gittensory_get_automation_state.

Deliverables / Acceptance Criteria

  • gittensory_miner_get_run_state tool implemented and registered on the AMS MCP server
  • Tool reads via run-state.js's existing accessor (no duplicated state logic)
  • Single-repo read mode, plus list-all-repos mode if run-state.js supports it
  • Explicit handling of unknown/no-state-yet repos
  • Tool description cross-references ORB's gittensory_get_automation_state
  • No mutation ("state set") capability added in this PR
  • Unit tests for known-state, unknown-repo, and (if applicable) list-all paths

Test Coverage Requirements

This PR must ship with full test coverage for every changed line and branch — the repo's Codecov patch gate requires 99%+ coverage and the house standard is to aim for 100%, including both sides of every conditional/nullish-coalescing branch introduced. Add: (1) unit tests covering the new/changed logic's success and failure paths (known state, unknown repo, list-all mode if applicable, malformed input), (2) an invariant test asserting the read-only run-state tool never triggers a state transition as a side effect of being queried, and (3) no regression test is required since this is new functionality, not a bug fix.

Codecov visibility note: packages/gittensory-miner/**, apps/gittensory-miner-ui/**, and apps/gittensory-miner-extension/** currently sit entirely outside vitest's coverage.include glob, so codecov/patch cannot measure changes there yet — closing that gap is exactly what #4864 and #4865 (in this same milestone) do. Any part of this change under packages/gittensory-engine/src/** or the repo's own src/** remains fully Codecov-instrumented as usual. Either way, this does not lower the bar: treat the 100%-including-invariants-and-regression target above as the enforced house standard regardless of what Codecov can currently see, and it becomes gate-enforced for real once #4864/#4865 ship.

Expected Outcome

An operator or MCP-connected agent can check what an AMS miner is currently doing on a given repo (idle, discovering, planning, preparing) over MCP, matching the visibility ORB already provides for its own automation state.

Links & Resources

Metadata

Metadata

Assignees

No one assigned

    Labels

    gittensor:featureGittensor-scored feature linked to a feature issue — scores a 0.25x multiplier.help wantedExtra attention is needed

    Projects

    No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions