Tracing & observability
Every meaningful operation writes a TraceEvent to
.ai/observability/generated/. The trace log is the
source of truth for debugging, replay, and review.
Event shape
{
"trace_id": "tr_2f9a...",
"ts": "2026-06-30T18:02:11.123Z",
"kind": "provider.request",
"actor": "developer",
"tenant": "my-project",
"decision": "local-only",
"payload": { "avoided_cost_usd": 0.002 }
}
Event kinds
| Kind | Meaning |
|---|---|
provider.request |
An LLM call was considered or made. |
provider.avoided |
A provider call was skipped because local work handled it. |
permission.request |
An agent asked to read or write a protected path. |
permission.decision |
A human approved or denied an escalation. |
eval.run |
An eval case was executed; status + baseline delta. |
skill.activated |
A skill was lazy-loaded by trigger. |
specialist.spawn |
A temporary subagent came online. |
specialist.retire |
A temporary subagent went offline. |
Tail & filter
ls .ai/observability/generated # generated project traces ls .alfred/observability # local runtime traces node -e "console.log(require('fs').readdirSync('.ai/observability/generated'))"
Reproducibility
A trace includes the prompt version, the model assignment, the skill set, the config snapshot, and the seed of any randomized eval. Given the trace, you can replay the run byte-for-byte.