sscoble/pi-mono
1
0
Fork 0
mirror of https://github.com/badlogic/pi-mono.git synced 2026-11-06 23:44:36 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 5

docs(agent): make harness v2 telemetry self-contained

Browse source 
Section 18 no longer references observability.md, which described the
superseded ALS/global-context mechanism and is being removed. Absorbed
the two load-bearing points: the multi-runtime rationale for rejecting
ambient context (explicit arguments are the only portable abstraction),
and the adapter framing - the application supplies ExecutionContext to
bridge spans into OTel/Sentry/logs/metrics, pi ships no exporter and no
vendor dependency, adapters allocate their own span/trace ids, and may
use AsyncLocalStorage internally. Dropped the reading-list entry.
This commit is contained in:
Mario Zechner 2026-08-04 15:14:30 +02:00
parent b68decede0
commit 4756e7d122
1 changed files with 3 additions and 2 deletions
Download patch file Download diff file Expand all files Collapse all files

5
packages/agent/docs/harness-v2.md
View file

@ -2657,7 +2657,9 @@ repo.create({ id?, parentSessionId? }): Promise<Session>;
## 18. Telemetry
Telemetry uses explicit context propagation. Core code does not use `AsyncLocalStorage`, global current-span state, or runtime-specific context APIs. This section defines the harness telemetry mechanism; `packages/agent/docs/observability.md` provides background only.
Telemetry uses explicit context propagation. Core code does not use `AsyncLocalStorage`, global current-span state, or runtime-specific context APIs: pi runs in Node, Bun, browsers, and workers, so no runtime's ambient-context mechanism can be the core abstraction, and explicit arguments are the only portable one. This section is the complete telemetry design; no other document defines any of it.
Pi ships no exporter and depends on no telemetry vendor. The application supplies the `ExecutionContext` below; an **adapter** is such an implementation that bridges spans into OTel, Sentry, logs, or metrics. The contract passes live span objects, not span/trace ids — an adapter that needs ids (every OTel-shaped backend does) allocates and correlates them internally, so core never carries id plumbing. An adapter may use `AsyncLocalStorage` inside its own implementation on runtimes that have it; core will never require it.
### Context contract
@ -2876,4 +2878,3 @@ For a fresh implementation session, in this order. This document wins over anyth
15. `packages/storage/sqlite-node/src/sqlite/storage/branch-entries.ts` — the branch cache being generalized.
16. `packages/storage/sqlite-node/src/sqlite/repo.ts` — create/open/fork.
17. `packages/coding-agent/docs/session-format.md` — v3 JSONL, the compatibility target.
18. `packages/agent/docs/observability.md` — telemetry background; section 18 defines context propagation.