Skip to content

MCPJVM-370: Public MCP query support for watcher_state #370

Description

@nimbly-dev

Description

Once SQLite-backed watcher state exists, Regression Suite needs a public MCP query surface for bounded inspection of persisted watcher lifecycle information. This story exposes watcher_state through artifact_management as a query-oriented state surface for understanding long-running bounded waits, intermediate progress, and final watcher outcomes.

This story should define the public request/response shape, filtering behavior, paging, sorting, and fail-closed behavior for watcher_state queries.

Scope

In scope:

  • Add watcher_state as a public artifact_management state surface
  • Expose query support for persisted watcher state
  • Support bounded filtering by projectName, planName, runId, watcherName, provider type, and watcher status
  • Support deterministic paging and sorting for watcher histories and long-running flows
  • Keep the public surface query-oriented and read-only for runtime-owned rows

Out of scope:

  • Watcher runtime execution semantics themselves
  • Storage implementation internals
  • Manual mutation of runtime-owned watcher rows
  • Legacy migration/backfill semantics

Acceptance Criteria

  • artifact_management supports public query access for watcher_state
  • Query behavior is bounded, deterministic, and fail-closed
  • Watcher-specific lookup fields are supported in the public contract
  • Paging and sorting are supported for large or long-running watcher histories
  • Response output is sufficient for agents/users to inspect bounded watcher progress and terminal outcomes without loading full Artifact history by default

Implementation Notes

  • Ensure query results can represent pending, in_progress, ok, fail_closed, and timed_out style watcher outcomes cleanly.
  • Keep the public shape useful for observing multi-pass execution where tooling timeout limits may prevent one long synchronous orchestration call.

Testing

  • UT for watcher_state query validation and watcher-specific filter normalization
  • UT for paging/sorting behavior on watcher histories
  • IT for querying intermediate and terminal watcher states
  • IT for fail-closed behavior on invalid watcher query inputs

Metadata

Metadata

Assignees

Labels

enhancementNew feature or request

Projects

No projects

Relationships

None yet

Development

No branches or pull requests

Issue actions