Repository navigation
Serve a telemetry snapshot through agentctl telemetry --json #240
Description
Parent
Agent-side change from the map Agent fleet dashboard: map; the consolidated list is in the resolution of Define the dashboard project. The snapshot shape is decided in Define the telemetry snapshot contract and the command mechanics in Decide the agentctl telemetry command. Terms: Telemetry snapshot and Figure basis in CONTEXT.md; ADR 0006.
What to build
The tracer bullet for telemetry. Running agentctl telemetry --json inside an agent container returns a schema-v1 telemetry snapshot built without network or git I/O and without holding up other control commands. Identity and control are real. current_attempt and last_finished are null and recent_events is empty until later tickets fill them.
Acceptance criteria
- The control socket accepts
{"op": "telemetry"}and answers{"ok": true, "telemetry": <snapshot>}. -
agentctl telemetry --jsonprints the bare snapshot to stdout and exits 0. On failure it prints{"ok": false, "error": {"code", "message"}}to stdout:agent_unreachable(socket missing, refused or timed out; exit 2),unsupported_operation(agent answered "Unknown operation"; exit 1),snapshot_failed(agent could not build the snapshot, or the reply is unparsable or oversized; exit 1). No traceback escapes. -
agentctl telemetryuses a 3 s connect+read timeout; other commands keep theirs. There is no human format, andstatusis unchanged. - A new telemetry module owns snapshot assembly behind a small reader interface (
snapshot(control)); later tickets add its writer side (begin_attempt,publish_attempt,finish_attempt). - The snapshot carries
schema_version: 1,generated_at,sequence(process-local),identity(repository,agent_version,sdk_versionandcli_versionfrom provenance evidence, andprocess_started_atrecorded at startup),control,current_attempt: null,last_finished: null,recent_events: [],truncated: false. -
controlis the same payloadstatusbuilds, produced by a network-free variant: no workspace dirty check and no GitHub lookups. Publication fields that would need a lookup arenull("not known yet"). It waits at most 1 s for the control lock. When the lock is busy it reuses the last built control section, andcontrol_observed_atsays when that section was built. If no section has been built yet, the reply issnapshot_failed. - The serialised snapshot is capped at 256 KiB: over the cap it drops
recent_eventsoldest first, thencurrent_attempt.context.subagents, and setstruncated: true. - The handler catches any exception, answers
snapshot_failed, and emits atelemetry_failedevent at most once per minute. It never takes down the control listener. - Tests: a snapshot is served while the main thread holds the control lock; the telemetry path performs no tracker or git calls (fakes that fail when called); each error code and exit code; the snapshot matches the shape of the idle example from the contract examples.
Activity
lbacik commentedon Oct 14, 2026
Agent Attempt Result: handoff
Branch: agent/issue-240
PR: none
Handoff note commit:
dc08872182bc2906fecc46a0135f625576fa730bEvidence
UV_PROJECT_ENVIRONMENT=/home/agent/venv-py311 uv run --python 3.11 --extra dev ruff check && UV_PROJECT_ENVIRONMENT=/home/agent/venv-py311 uv run --python 3.11 --extra dev pytest && UV_PROJECT_ENVIRONMENT=/home/agent/venv-py313 uv run --python 3.13 --extra dev pytest→ exit code NoneDetails
Handoff note: issue #240
Summary
Implemented the telemetry tracer bullet (agent-side
telemetryover the control socket). All new tests pass (22/22 intests/test_telemetry.py), full suite passes (1070 passed, 10 skipped), andruff checkis clean. Thecode-reviewskill was invoked in this run: Standards axis found 0 hard violations + 4 judgement-call smells; Spec axis found 0 missing requirements plus 2 partial gaps, 2 scope-creep notes, and 2 fragility findings (full report in the run transcript).What was built:
simple_coding_agent/telemetry.py:TelemetryReporter(startup identity, process-local sequence,snapshot(control)reader interface, 256 KiB cap viaapply_size_captrimming oldest events then subagents),SnapshotFailedError, timeout/size constants.lifecycle.py:AgentLifecycle(..., telemetry=...),telemetry_snapshot(),telemetry_control_snapshot()(≤1 s control-lock wait, reuse of last built section withcontrol_observed_at,SnapshotFailedErrorwhen none built yet), plus network-free control-section/recovery builders (no workspace/tracker/publisher I/O; publication fieldsNone).control_server.py:{"op": "telemetry"}→{"ok": true, "telemetry": ...};Unknown operationfor readers without telemetry;snapshot_failed+ rate-limitedtelemetry_failedevent (60 s); newUnreadableReplyError;send_request(..., timeout=10.0)default unchanged.agentctl.py:telemetry --json(required flag) printing the bare snapshot, exit 0; failures print{"ok": false, "error": {"code", "message"}}to stdout withagent_unreachable→2,unsupported_operation/snapshot_failed→1; 3 s timeout; no tracebacks.__main__.py: wiresTelemetryReporter(provenance sdk/cli/agent versions,process_started_at) intoAgentLifecycle.tests/test_telemetry.py: socket/shape/sequence, lock-busy cache reuse and empty-cache failure, exploding-fake no-I/O tests (idle + retained hold with null publication), all CLI error codes/exits, 3 s black-hole timeout, size-cap unit tests, rate-limit test.Remaining work
telemetry_control_snapshot; move the finalprint(json.dumps(snapshot))inside the telemetry try inagentctl.py; consider dropping theformat_timestamp/identityextra public surface). None was applied — implementation work is disabled at handoff.PytestUnhandledThreadExceptionWarningin the full-suite output is caused by the new tests (unverified; could be pre-existing).agent/issue-240(nothing committed yet; sealing will commit uncommitted work).Evidence
simple_coding_agent/__main__.py,simple_coding_agent/agentctl.py,simple_coding_agent/control_server.py,simple_coding_agent/lifecycle.py(460 insertions, 7 deletions per diff stat).simple_coding_agent/telemetry.py,tests/test_telemetry.py.tests/test_telemetry.py22 passed; full suite 1070 passed, 10 skipped;ruff checkclean.## Standards/## Specheadings.Automatic continuation 0/2 used; the agent will continue automatically.
lbacik commentedon Oct 14, 2026
Agent Attempt Result: complete
Branch: agent/issue-240
PR: #249
Merge: auto-merge enabled (merge)
Evidence
UV_PROJECT_ENVIRONMENT=/home/agent/venv-py311 uv run --python 3.11 --extra dev ruff check && UV_PROJECT_ENVIRONMENT=/home/agent/venv-py311 uv run --python 3.11 --extra dev pytest && UV_PROJECT_ENVIRONMENT=/home/agent/venv-py313 uv run --python 3.13 --extra dev pytest→ exit code 0Details
Claude SDK completed the implementation workflow.