Skip to content

Add sourcebridge doctor command to dump deployment capability state #11

@jstuart0

Description

@jstuart0

Summary

When something goes wrong with deep-QA in production, operators have to SSH to the API pod and grep the startup logs to figure out whether agentic wired, whether prompt caching is on, whether the smart classifier ran, etc. A sourcebridge doctor command that dumps this state in one place would cut troubleshooting time significantly.

(This gap is real — we hit it twice during the rc.1 → rc.2 push when pods silently landed in single-shot mode after a probe race. See 6de34cd.)

What needs to happen

  1. Add a doctor subcommand under cli/ that, when pointed at a running server:
    • Hits /healthz and surfaces the X-SourceBridge-QA capability header.
    • Calls a new /api/v1/admin/capabilities endpoint (new work — JSON dump of the agentic wiring state).
    • Prints a human-readable table: provider, model, agentic wired Y/N, smart classifier, prompt caching, query decomposition, canary %.
  2. Add handleAdminCapabilities in internal/api/rest/ that returns the state the agent synth: wired log line captures today, as JSON.
  3. When run without a --server-url, doctor probes localhost:8080 or reads the default from SOURCEBRIDGE_SERVER_PUBLIC_BASE_URL.

Example output

$ sourcebridge doctor --server-url https://sourcebridge.example.com
SourceBridge Doctor
  server:            sourcebridge.example.com  (v0.9.0-rc.2)
  provider:          anthropic / claude-sonnet-4-5
  agentic retrieval: wired (enabled=true, canary=0%)
  smart classifier:  on
  prompt caching:    on (99.6% cache-read on last 100 asks)
  query decomp:      on (arch-only)
  worker:            ready (grpc healthy)

Where to look

  • cli/root.go — register the new subcommand.
  • cli/doctor.go — new file; small HTTP client that pretty-prints the response.
  • internal/api/rest/admin_handlers.go (or similar) — add handleAdminCapabilities.
  • internal/api/rest/router.go — expose the new route under /api/v1/admin/.

Acceptance

  • sourcebridge doctor --server-url URL prints the table above.
  • /api/v1/admin/capabilities returns JSON and requires auth.
  • The command works against a local sourcebridge serve without any flags (defaults to localhost).

Difficulty

Beginner-friendly for Go developers. The hardest part is deciding which fields to surface; the wire protocol is a small JSON shape.

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or requestgood first issueGood for newcomers — well-scoped, isolated, clear acceptance criteria

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions