From 457b102beed66ef49ea26f3a8c3eaca5e50ed02e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=81ukasz=20Bacik?= Date: Wed, 14 Oct 2026 12:11:26 +0200 Subject: [PATCH 1/3] docs: define Dashboard and Managed instance Glossary terms resolved in the wayfinder ticket "Decide instance discovery and the dashboard's Docker access" (#226). Co-Authored-By: Claude Opus 5.5 --- CONTEXT.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/CONTEXT.md b/CONTEXT.md index dd68e0e..eee806d 100644 --- a/CONTEXT.md +++ b/CONTEXT.md @@ -75,3 +75,11 @@ _Avoid_: Budget cap, kill limit **Pinned runtime**: The single approved agent-SDK release, together with the Claude Code CLI shipped inside it, that every model execution must run on. Pinning the SDK pins the CLI; the CLI never has a version of its own to keep in step. Provenance verification confirms at startup that the CLI about to run is exactly the one this release ships, and refuses to start otherwise. _Avoid_: Runtime pair, SDK and CLI pins, the CLI on PATH + +**Dashboard**: +A separate operator view over the managed instances on one Docker host. It observes instances and, from its second version, relays operator commands to them; it never claims issues or takes part in an implementation attempt. +_Avoid_: Control panel, monitor, fleet manager + +**Managed instance**: +One agent container that a dashboard discovers and observes, serving exactly one target repository. It is identified by its container name, so recreating the container keeps the same managed instance; a container started for a one-off command is never a managed instance. +_Avoid_: Agent, worker, node From 17fec3424fdfabfa3ceb2e648db746169814d128 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=81ukasz=20Bacik?= Date: Wed, 14 Oct 2026 12:45:25 +0200 Subject: [PATCH 2/3] docs: define Telemetry snapshot and Figure basis Co-Authored-By: Claude Opus 5.5 --- CONTEXT.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/CONTEXT.md b/CONTEXT.md index eee806d..6ec6616 100644 --- a/CONTEXT.md +++ b/CONTEXT.md @@ -83,3 +83,11 @@ _Avoid_: Control panel, monitor, fleet manager **Managed instance**: One agent container that a dashboard discovers and observes, serving exactly one target repository. It is identified by its container name, so recreating the container keeps the same managed instance; a container started for a one-off command is never a managed instance. _Avoid_: Agent, worker, node + +**Telemetry snapshot**: +A point-in-time, read-only report a managed instance gives about itself: its control state, the current (or last finished) implementation attempt's token, budget and context figures, and its most recent events. The agent owns and versions it; a dashboard only reads it and tolerates versions it does not fully know. +_Avoid_: Status, metrics, heartbeat + +**Figure basis**: +How a figure in a telemetry snapshot was obtained: `measured` (reported by the provider), `estimated` (computed by the agent), `configured` (set by the operator), `sdk_assumed` (a default the runtime assumes for an unknown model), or `unavailable` (no trustworthy source). An unavailable figure is never shown as zero. +_Avoid_: Provenance (reserved for provenance verification of the pinned runtime), source, confidence From 44235f0b9ded070be2277b7a8ddead92d8752207 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=81ukasz=20Bacik?= Date: Wed, 14 Oct 2026 12:51:09 +0200 Subject: [PATCH 3/3] docs: record ADR 0006 on serving telemetry through agentctl Co-Authored-By: Claude Opus 5.5 --- .../0006-telemetry-through-agentctl-not-http.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) create mode 100644 docs/adr/0006-telemetry-through-agentctl-not-http.md diff --git a/docs/adr/0006-telemetry-through-agentctl-not-http.md b/docs/adr/0006-telemetry-through-agentctl-not-http.md new file mode 100644 index 0000000..94f3adb --- /dev/null +++ b/docs/adr/0006-telemetry-through-agentctl-not-http.md @@ -0,0 +1,14 @@ +# Serve fleet telemetry through agentctl over the control socket, not an HTTP endpoint + +A dashboard needs each managed instance's telemetry snapshot. We decided the agent serves it only as a read-only `telemetry` operation on the existing container-local control socket, exposed as `agentctl telemetry --json`, and the dashboard reads it by running `docker exec --user agent /usr/local/bin/agentctl telemetry --json`. The agent publishes no port and opens no listener beyond the control socket, so "container = instance, no published control port" stays true, and the telemetry needs neither a token nor a setting to turn it on. + +## Considered Options + +- **An opt-in HTTP endpoint inside the agent, guarded by a token.** Rejected: it adds a network listener, a secret to provision and rotate per instance, and a second protocol to keep in step with `agentctl`, all to save the dashboard from needing Docker `exec`. The operator commands planned for the dashboard's second version would need the same endpoint to become writable, which would turn a read-only convenience into a remote control surface. +- **Status written to a shared volume or file.** Rejected: it needs a mount per instance and gives no way to tell a stalled agent from a quiet one, which a live socket reply does. + +## Consequences + +- The dashboard holds more Docker power than an HTTP pull would need (`exec` into the agent containers). The dashboard project contains this by running as the operator's own host process, bound to `127.0.0.1`, with one gateway module that can only list instances and run `agentctl telemetry`. +- The control server answers connections one at a time, so the `telemetry` handler must only serialise data that is already prepared. It does no network or git I/O, waits at most briefly for the control lock, and never lets an error escape into the listener. +- Every poll costs one `docker exec` and one Python start-up per instance, so dashboards poll on the order of seconds, not sub-second.