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
- 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 %.
- Add
handleAdminCapabilities in internal/api/rest/ that returns the state the agent synth: wired log line captures today, as JSON.
- 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.
Summary
When something goes wrong with deep-QA in production, operators have to SSH to the API pod and
grepthe startup logs to figure out whether agentic wired, whether prompt caching is on, whether the smart classifier ran, etc. Asourcebridge doctorcommand 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
doctorsubcommand undercli/that, when pointed at a running server:/healthzand surfaces theX-SourceBridge-QAcapability header./api/v1/admin/capabilitiesendpoint (new work — JSON dump of the agentic wiring state).handleAdminCapabilitiesininternal/api/rest/that returns the state theagent synth: wiredlog line captures today, as JSON.--server-url,doctorprobeslocalhost:8080or reads the default fromSOURCEBRIDGE_SERVER_PUBLIC_BASE_URL.Example output
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) — addhandleAdminCapabilities.internal/api/rest/router.go— expose the new route under/api/v1/admin/.Acceptance
sourcebridge doctor --server-url URLprints the table above./api/v1/admin/capabilitiesreturns JSON and requires auth.sourcebridge servewithout 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.