Skip to content

feat(tracing): separate plugin and bt span origin versions #153

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Andrew Kent (realark) merged 1 commit into from
Oct 7, 2026
Merged

feat(tracing): separate plugin and bt span origin versions #153

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
50 changes: 49 additions & 1 deletion bt-daemon/Cargo.lock
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

3 changes: 2 additions & 1 deletion bt-daemon/Cargo.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ required-features = ["cli"]

[dependencies]
# Keep this pinned exactly, matching the dependency policy used by `bt`.
braintrust-sdk-rust = { git = "https://github.com/braintrustdata/braintrust-sdk-rust", rev = "019e428ab80d0da4c00dab383d4b0d1fdf4486fd" }
braintrust-sdk-rust = { git = "https://github.com/braintrustdata/braintrust-sdk-rust", rev = "ac70efca9d2e72e8d5446d73601312e08f1c6148" }
base64 = "0.22"
anyhow = "1"
async-trait = "0.1"
Expand Down Expand Up @@ -46,6 +46,7 @@ windows-sys = { version = "0.61", features = ["Win32_Foundation", "Win32_Securit
[dev-dependencies]
axum = "0.8"
bytes = "1"
parking_lot = "0.12"
reqwest = { version = "0.12", default-features = false, features = ["json", "stream"] }
wiremock = "0.6"
zstd = "0.13"
Expand Down
26 changes: 24 additions & 2 deletions bt-daemon/docs/protocol.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -247,8 +247,30 @@ downgrade it.
}
```

The Braintrust sink records the capture package version in
`context.span_origin.version`.
The shared delivery path snapshots provenance independently on the coding-agent
session root and each turn:
`context.span_origin.name = "braintrust.plugin.<source>"`,
`context.span_origin.version` is the span-creating event's capture package
version, `context.span_origin.<source>.version` is its coding-agent
`source_version`, and `context.span_origin.bt.version` is the daemon version at
span creation. `<source>` is the canonical name, such as `codex` or `claude-code`,
not a literal `agent` key. Unknown plugin and agent versions are explicit JSON
`null`; they never fall back to another component's version. The
destination-scoped delivery ledger persists each snapshot before export; later
updates, resume, and replay reuse it unchanged, even across upgrades.
New turns capture new snapshots instead of inheriting the root's versions.
Provisional roots retain their original snapshot while waiting for work.
An unmaterialized root or turn replayed for a new destination uses its
span-creating journaled event, not the event that triggered recovery. Other
descendants do not receive these snapshots. Transcript backfills capture
versions available at materialization, not unrecorded historical versions. See the
[span-origin contract](../../docs/coding-agent-tracing-plugin-spec.md#621-span-origin-versions).

For acknowledged spans from legacy ledgers without saved snapshots, stateless
updates omit `context.span_origin` entirely, including SDK defaults and inherited
parent origin fields. This preserves existing backend provenance without guessing
historical versions; output, timing, and unrelated propagated context still merge
normally. New turns receive fresh snapshots.

Field notes:

Expand Down
Loading
Loading