docs(gateway): propose /status Phase 2 health checks
Phase 1 (archie-core-wp9s) shipped /tasks and the /status queue-depth aggregate. This documents the remaining ask -- broker connectivity, provider reachability, channel state, container pool, last poll -- split into cheap wiring (nats.Conn.Status(), container.Pool's already-tracked active count, a new last-poll timestamp) versus two real product decisions (live-probe vs last-known-outcome for provider reachability; the ChannelManager-backed shape for channel state). Proposed resolution, awaiting Sam's sign-off before Phase 2 lands.
This commit is contained in:
1 parent
b698322505
commit
9b9539fe81
1 file changed
+108
@@ -0,0 +1,108 @@
|
||||
# /status health surface -- what's shipped, what's proposed
|
||||
|
||||
**Status:** Phase 1 shipped 2026-09-03 (archie-core-wp9s). Phase 2 below is
|
||||
a **proposed resolution, awaiting Sam's sign-off** -- not yet implemented.
|
||||
|
||||
## Background
|
||||
|
||||
`archie-core-wp9s` ("/status and /tasks have the wrong division of labour")
|
||||
asked for two things: `/tasks` owning the live per-task work view, and
|
||||
`/status` owning daemon health -- "broker connectivity, provider
|
||||
reachability, channel state, container pool, queue depth, last poll,
|
||||
version" -- with neither duplicating the other or static config available
|
||||
elsewhere (`/model` already lists active provider/model).
|
||||
|
||||
## Phase 1 -- shipped
|
||||
|
||||
- `/tasks`: new command, `gateway.ChatTaskSummary` extended with
|
||||
`Stage`/`Attempt`/`ParkReason`/`UpdatedAt` (all already persisted on
|
||||
`store.Task`, zero new instrumentation), sorted actionable-first.
|
||||
- `/status`: itemized per-status task counts replaced with one aggregate
|
||||
`Queue: N in flight (...)` line (running/waiting/parked only -- queued and
|
||||
terminal states excluded as not a health concern). Runtime
|
||||
(provider/model) is temporarily left in place; see the open question
|
||||
below.
|
||||
|
||||
Not touched: `/agents` (`gateway.AgentReader`/`Router.Agents`) is a separate,
|
||||
pre-existing command that already has the right shape for "list active
|
||||
work" but is never wired to a real implementation in any composition-root
|
||||
call site (`bootstrap.go`, `telegram_setup.go`) -- it always answers "Agent
|
||||
listing is not configured." in production. That is a standalone bug
|
||||
(`archie-core-mxls`), not folded into this work: deciding whether to wire
|
||||
it, repurpose it, or delete it in favor of `/tasks` is Sam's call, not
|
||||
something to resolve by implication here.
|
||||
|
||||
## Phase 2 -- health checks, verified against the actual tree
|
||||
|
||||
Each bullet below was checked against real code before being called cheap
|
||||
or not; nothing here is guessed.
|
||||
|
||||
### Cheap -- no design decision needed, straightforward to add
|
||||
|
||||
- **Broker connectivity.** `internal/infrastructure/eventbus/nats.Client`
|
||||
already exposes `CoreConn() (*nats.Conn, error)`
|
||||
(`client.go:134`). The underlying `nats.Conn` (nats.go) has its own
|
||||
`Status()`/`IsConnected()`. A `Client.Connected() bool` wrapper is a few
|
||||
lines.
|
||||
- **Container pool.** `container.Pool` already tracks `active int` under
|
||||
its own mutex (`pool.go:90`) but has no public accessor. A
|
||||
`Pool.Active() int` getter is a few lines.
|
||||
- **Last poll.** Nothing tracks this today. The daemon's poll loop
|
||||
(`internal/daemon`) needs one `lastPollAt time.Time` field (atomic or
|
||||
mutex-guarded, matching the pool's own pattern) set at the top of each
|
||||
poll tick, with a getter.
|
||||
- **Queue depth.** Already shipped in Phase 1.
|
||||
|
||||
### Not cheap -- needs a decision before coding
|
||||
|
||||
- **Provider reachability.** No existing check anywhere. The only way to
|
||||
answer "is the provider reachable" is a real network call, which means:
|
||||
a `/status` invocation either pays that latency and cost every time
|
||||
(bad -- `/status` should be instant, matching `/model`'s and `/tasks`'
|
||||
own current behaviour), or `/status` reports the **last** call's
|
||||
outcome (success/failure/never-called) rather than probing live. The
|
||||
latter needs a small success/failure counter or timestamp recorded at
|
||||
the one place LLM calls already go through (`ai-sdk` responder path),
|
||||
not a new probe. Recommend: last-known-outcome, not live probing --
|
||||
but this is a real product tradeoff (freshness vs. cost) worth Sam's
|
||||
explicit sign-off before it's built into a command he uses daily.
|
||||
- **Channel state.** `channels.Channel` (embeds `gateway.Gateway`:
|
||||
`Name()/Start()/Stop()`) has no connectivity/health method today, and
|
||||
telegram/email/webhook each manage their own connection lifecycle
|
||||
independently. Answering "is Telegram actually connected" needs either
|
||||
(a) a new method on the `Channel`/`Gateway` contract every implementation
|
||||
must satisfy, or (b) each channel self-reporting into a shared registry
|
||||
the daemon already holds (`ChannelManager` -- `bootstrap.go` already
|
||||
calls `b.channelManager.MarkStarting/MarkRunning/MarkFailed` per
|
||||
channel). (b) is very likely the right shape since `ChannelManager`
|
||||
already exists and already tracks exactly this kind of state for the
|
||||
dashboard; needs a read method exposed to `/status`. Flagging as
|
||||
"needs a decision" only because it touches a contract multiple
|
||||
implementations satisfy, not because the shape is unclear -- ChannelManager
|
||||
is the obvious answer.
|
||||
- **Version.** Deliberately **not** proposed for `/status`: `/version`
|
||||
already owns this (`Router.Version`, `handleVersion`), and duplicating it
|
||||
back into `/status` would reintroduce the exact "answers something
|
||||
available elsewhere in chat" complaint this ticket exists to fix.
|
||||
|
||||
## Recommendation
|
||||
|
||||
Ship the three cheap items (broker connectivity, container pool, last
|
||||
poll) as a mechanical follow-up alongside Phase 1's `Queue:` line --
|
||||
same shape, same non-duplication reasoning, no new design surface. Land
|
||||
provider reachability and channel state only after Sam confirms the
|
||||
last-known-outcome approach (provider) and the ChannelManager-read
|
||||
approach (channel), since both are choices about a command's behaviour
|
||||
he already has strong, specific opinions about.
|
||||
|
||||
## Packages this touches (Phase 2)
|
||||
|
||||
- `internal/infrastructure/eventbus/nats`: `Client.Connected() bool`.
|
||||
- `internal/container`: `Pool.Active() int` (and `Pool.Cap() int` for
|
||||
"N/M" display, from the already-configured `MaxConcurrency`).
|
||||
- `internal/daemon`: last-poll timestamp, read accessor.
|
||||
- `internal/gateway`: `formatStatus` gains the new lines; `Router` gains
|
||||
whatever read surfaces back them (mirrors `StatusReader`'s existing
|
||||
pattern -- a narrow interface, not a daemon-internals handle).
|
||||
- Provider reachability and channel state: packages TBD pending the two
|
||||
decisions above.
|
||||
Reference in new issue
Block a user