Embed the coding-agent tracing daemon

[Stephen Belanger (Qard)]

Dependencies

Depends on merged braintrustdata/braintrust-coding-agent-plugins#1, pinned at its squash-merge commit bebff4e0349fd9d2ee4a8ce1eeeafafee91ac74b.

That daemon PR in turn depends on braintrustdata/braintrust-sdk-rust#86, pinned at commit d33e806bf6ab9548d37355f6a5098a971ef150aa.

The plugin source cutover is intentionally deferred to stacked braintrustdata/braintrust-coding-agent-plugins#3, which must land only after this daemon is available in a released bt CLI.

Summary

This embeds the shared coding-agent tracing daemon in bt under the bt trace command family. bt trace setup and bt trace import are the user-facing commands. The daemon, hook, status, and stop subcommands remain directly callable by plugins and operators who know their names, but are hidden from public help and usage output as implementation details.

bt trace import codex <session-id> and bt trace import claude <session-id> locate and snapshot native session transcripts in the agents' standard data directories, resolve the current bt profile and project, and send the reconstructed historical trace through the production Braintrust sink. The source is explicit because session IDs alone do not identify their producer. Codex snapshots are streamed once, native turn IDs and compaction history replacements are retained, and large imports drain in small bounded operation batches to avoid losing later turns to bounded delivery queues without serializing a network flush for every boundary. Claude imports preserve native turn ownership when physical record order is not timestamp-monotonic and propagate Claude API-error markers into turn and LLM errors. Daemon restart recovery remains an internal WAL operation; it may idempotently resubmit rows under stable backend row IDs, but cannot create duplicate logical spans.

The foreground daemon initializes structured logging at INFO by default, or DEBUG with --verbose, and emits safe request lifecycle fields such as JSON-RPC method, request ID, event type, source, and session ID. Payloads and credentials are not logged.

bt trace setup codex and bt trace setup claude use the coding agents' own plugin managers to add the official Braintrust marketplaces and install the currently published tracing plugins. Setup also creates the shared tracing settings when needed, enables tracing, and accepts --project for routing. It performs a non-destructive merge: every other setting, including legacy authentication and backend fields needed by currently published plugins, is preserved unchanged.

The bt host resolves its normal profile, OAuth, keychain, or API-key credentials for each hook invocation and transcript import, passing the resulting token, backend URLs, organization, and project to the credential-passive daemon library. Hook errors remain fail-open so tracing cannot break a Codex or Claude Code turn.

The daemon is consumed from the exact Git commit of its migration PR rather than through a local path dependency. The integration is rebased on current bt main and preserves the newer top-level update command and command routing introduced there.

CLI regression tests verify that setup and import are advertised by bt trace --help, while the four hidden operational commands remain directly callable. They also cover the required import source and session ID, rejection of the removed replay spelling, hook options, graceful and idempotent stop, Codex and Claude plugin-manager invocations, default and explicit project selection, and preservation of existing settings. The superseded bt daemon and bt agents paths remain rejected.

Validation

• cargo fmt --check
• cargo test --test cli
  • all 30 CLI tests passed.
• Daemon dependency suite: 60 tests passed under all features, including multi-turn native Codex and Claude transcript imports, non-monotonic Claude record ordering and API errors, compaction-state replacement, turn-checkpoint delivery, and restart ID stability.
• Real installed Codex and Claude Code sessions completed against deterministic mock inference and satisfied their mock ingest trace scenarios.
• Manual isolated lifecycle smoke delivered deterministic Codex rows to a local mock Braintrust backend with project routing and braintrust.plugin.codex span-origin metadata.
• A real three-turn Claude transcript with non-monotonic record timestamps was imported into Braintrust; all three LLM spans were parented to their corresponding turns, native API failures were marked as errors, and re-import retained the same seven span IDs.

Project selection and managed runs

• expose bt trace run codex|claude with invocation-local hooks and routing
• reuse an explicit or configured project for setup, run, and project-default imports
• prompt with the existing project selector when an interactive user has not selected a project
• require --project with actionable guidance in non-interactive mode
• persist setup profile, organization, and project selection as the typed daemon route while leaving managed-run selection process-local

Covers SDK-128 and SDK-129.

[github-actions]

Latest downloadable build artifacts for this PR commit 8c7b795f2308:

• Workflow run: https://github.com/braintrustdata/bt/actions/runs/31507685516
• Download all artifacts (GitHub CLI): gh run download 31507685516 --repo braintrustdata/bt
• Installers are published from main automatically. To publish one for a PR branch, run release-canary manually via workflow_dispatch.

Available artifact names

• artifacts-build-global
• artifacts-build-local-x86_64-apple-darwin
• artifacts-build-local-aarch64-pc-windows-msvc
• artifacts-build-local-x86_64-pc-windows-msvc
• artifacts-build-local-aarch64-apple-darwin
• artifacts-build-local-x86_64-unknown-linux-musl
• artifacts-build-local-x86_64-unknown-linux-gnu
• artifacts-build-local-aarch64-unknown-linux-gnu
• artifacts-plan-dist-manifest
• cargo-dist-cache

[Ankur Goyal (ankrgyl)]

A-Goyal:~/projects/bt ankur$ bt trace import codex 019fba28-c05a-7fc2-8122-f60591056541

This worked, but i had no idea which org, project, etc. it wrote to. With other commands, if this is ambiguous, we show you a selector where you pick it.

Also, instead of just accepting a "project", we should accept the same destination format as bt sync push, which can also be to experiments, etc. Eventually we will want this to accept serialized SpanComponents so you can write to arbitrary parents.

[Cedric / ViaDézo1er (viadezo1er)]

Should respect the --json flag (same comment for other commands like bt trace setup codex --json)

❯ bt trace status --json
bt-daemon is not running

[Cedric / ViaDézo1er (viadezo1er)]

❯ bt trace -v
error: 'bt trace' requires a subcommand but one was not provided
  [subcommands: setup, daemon, hook, status, stop, import, run, help]

Usage: bt trace [OPTIONS] <COMMAND>

For more information, try '--help'.

This is kinda user-facing yet exposes the hidden subcommands. Not an issue for me but maybe that goes against what you wanted.

[Cedric / ViaDézo1er (viadezo1er)]

bt trace import only works with a specific session id. I think new users might want to bulk import all of their sessions in Braintrust so a flag to allow that might be neat.
I'm unsure how to expose a way to select specific sessions so users could unselect sensitive sessions from being imported.

[Stephen Belanger (Qard)]

Cedric / ViaDézo1er (@viadezo1er) Do you think any of those are necessary for the initial release? Those all sound like reasonable follow-up tasks to me. 🤔

As for the hidden subcommands being visible there, I think that's a Clap bug. I'll see if that can get fixed upstream.

[Abhijeet Prasad (AbhiPrasad)]

let's get the --json flag working, bt trace import improvements as a follow up feels fine after we merge this in