telemetry-steward

Telemetry Steward

FlowDeck generates a steady stream of operational signals — context compactions, agent handoffs, recorded decisions, readiness scores. Telemetry Steward captures these as structured, append-only events so operators can observe patterns, diagnose drift, and validate improvement over time.

Purpose

Telemetry answers three questions:

1. Context health — Are we pruning, compacting, or checkpointing effectively? Are token savings trending up or down?
2. Agent performance — Which agents are fastest? Which fail most often? Where does routing latency spike?
3. Decision quality — Are decisions backed by evidence? Is confidence calibrated to actual risk?

It is not a control plane. It does not trigger actions. It exists purely for observability, retrospection, and baseline-setting.

Storage

All events are written to ~/.fd-plan/<slug>/.codebase/TELEMETRY.jsonl.

• One JSON object per line. No outer array.
• Append only. Never rewrite the file in place.
• Each line is self-contained and independently parseable.
• Invalid lines are skipped during read, not repaired.

Event Schema

Every event has a top-level type field. All other fields are type-specific.

context_action

Recorded when the context steward prunes, compacts, or checkpoints.

{
  "type": "context_action",
  "action": "prune",
  "tokens_before": 12400,
  "tokens_after": 8200,
  "timestamp": "2026-06-11T09:23:17.000Z"
}

Field	Type	Description
action	string	"prune", "compact", or "checkpoint"
tokens_before	integer	Context size in tokens before the action
tokens_after	integer	Context size in tokens after the action
timestamp	ISO 8601	When the action occurred

agent_routing

Recorded when the orchestrator dispatches work to an agent.

{
  "type": "agent_routing",
  "agent": "backend-coder",
  "category": "implementation",
  "task_type": "bugfix",
  "duration_ms": 14520,
  "success": true,
  "timestamp": "2026-06-11T09:45:02.000Z"
}