Add TraceRoot Codex observability plugin (v0.1.0)

[XinweiHe]

Adds the TraceRoot Codex observability plugin (v0.1.0) — a TypeScript plugin that traces OpenAI Codex sessions to TraceRoot.

What it does

Every Codex query becomes one live trace — the agent turn, model calls, tool executions, file edits, and any subagents it spawns — streamed as the agent works and linked to your git repo.

• One trace per query. A query and everything it does is a single trace; multiple queries in a session are linked by session id (Sessions view).
• Live. Spans appear and the trace grows as the agent runs (named Codex Turn from the first span).
• Subagents nested. spawn_agent workers are nested under the spawn tool that created them, in the same trace.
• No daemon. Stateless one-shot hooks; fail-open (tracing never blocks Codex).

How it works

Stateless Codex hooks (PostToolUse/Stop/SubagentStop) read the rollout transcript and emit OpenTelemetry (protobuf) spans. The key idea is deterministic span ids (hash of session/turn/call ids) so a child span can reference its parent before the parent exists and re-emission is idempotent — a sidecar ledger dedups what's been sent. No background process.

What's captured

• Agent turn (prompt + final answer, git repo/ref, model)
• Model steps (input, output incl. reasoning + tool calls, tokens, cache-aware cost)
• Tools — exec_command, apply_patch (file edits), MCP, search — with args, output, and exit code/status/kind where Codex reports it
• Subagents, fully nested in the same trace
• SDK identity (traceroot.sdk.*)

Testing & validation

• 62 unit tests (vitest), tsc --noEmit clean, committed self-contained dist/index.mjs with a build drift-guard (lint:dist)
• End-to-end validated against production — simple single-turn and complex multi-agent sessions; confirmed live streaming, correct subagent nesting, non-zero cache-aware cost, and git correlation

Install

codex plugin marketplace add traceroot-ai/traceroot-codex-plugin

Enable in ~/.codex/config.toml and add ~/.codex/traceroot.json with your API key — see the README.

🤖 Generated with Claude Code

[XinweiHe]

@cubic review it

[cubic-dev-ai]

@cubic review it

@XinweiHe I have started the AI code review. It will take a few minutes to complete.

[cubic-dev-ai]

4 issues found across 51 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="plugins/tracing/src/emit.ts">

<violation number="1" location="plugins/tracing/src/emit.ts:42">
P2: Nested subagent root spans are suppressed while the subagent is running, so live child tool/LLM spans can arrive without their parent AGENT span. This breaks the advertised live nested subagent view until the child turn completes.</violation>
</file>

<sub>You're on the cubic free plan with 11 free PR reviews remaining this month. Upgrade for unlimited reviews.

Re-trigger cubic</sub>

[cubic-dev-ai]

P2: Nested subagent root spans are suppressed while the subagent is running, so live child tool/LLM spans can arrive without their parent AGENT span. This breaks the advertised live nested subagent view until the child turn completes.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At plugins/tracing/src/emit.ts, line 42:

<comment>Nested subagent root spans are suppressed while the subagent is running, so live child tool/LLM spans can arrive without their parent AGENT span. This breaks the advertised live nested subagent view until the child turn completes.</comment>

<file context>
@@ -0,0 +1,154 @@
+  let n = 0;
+
+  for (const span of planTurnSpans(sessionMeta, turn, ctx, opts)) {
+    if (!span.complete) continue;
+    // The trace root (AGENT, no parent) is re-emitted on every hook so the trace
+    // is named "Codex Turn" from the first span (not the first LLM step's model
</file context>