Add JavaScript span transform plugins

[Stephen Belanger (Qard)]

Summary

• add ordered synchronous JavaScript span transforms powered by per-worker QuickJS runtimes
• bridge spans and context directly with rquickjs-serde, using strict result decoding without intermediate JSON text
• expose operation, source, session ID, and an environment snapshot captured once when each daemon worker processor is constructed
• canonicalize plugin paths to absolute paths before validation and persistent enable storage
• persist enabled plugins for ordinary sessions while keeping managed runs and import/attach plugin chains invocation-local
• replay raw journal events through the resumed session's current plugin chain
• fail closed when any plugin errors by withholding that span operation and retaining its raw journal entry for replay after repair
• persist bounded, deduplicated raw QuickJS exceptions in private daemon state and surface them through bt trace doctor

Example

Create a synchronous ES module:

// tag-ci.mjs
export default function tagCi(span, context) {
  if (!context.env.CI) return span;

  return {
    ...span,
    tags: [...new Set([...(span.tags ?? []), "ci"])],
    metadata: {
      ...(span.metadata ?? {}),
      deployment: context.env.DEPLOYMENT_ENV ?? "unknown",
      trace_source: context.source,
    },
  };
}

Choose the scope when registering it:

# Persist an ordered global chain for ordinary Codex sessions.
bt trace enable codex --plugin ./redact.mjs --plugin ./tag-ci.mjs

# Only local.mjs runs for this managed invocation; enabled plugins are not merged.
bt trace run --plugin ./local.mjs codex -- "summarize this change"

# Only sanitize-history.mjs runs for this import; enabled plugins are not merged.
bt trace import codex SESSION_ID --plugin ./sanitize-history.mjs

Each function receives the previous plugin's returned span plus { operation, source, session_id, env }. Plugins may change span content but not span_id, root_span_id, or parent_span_ids.

Raw input events are journaled before transformation. On recovery, an ordinary session uses the current globally configured plugin chain, while an isolated managed session continues using its invocation-local chain. Import and attach are separate from journal recovery and use only their command-line plugins.

If any plugin throws, times out, returns a promise, or returns an invalid span, that span operation is discarded instead of being sent unredacted. The raw exception is stored locally in a bounded, deduplicated diagnostics registry and can be inspected with:

bt trace doctor codex

The failed plugin remains quarantined on that worker while its file is unchanged. Editing the plugin retries it; restarting the daemon then replays withheld journal operations through the repaired current plugin chain.

See the README examples for redaction, environment handling, chaining, replay, failure diagnostics, and security guidance.

Validation

• cargo test --manifest-path bt-daemon/Cargo.toml --all-features --locked
• cargo clippy --manifest-path bt-daemon/Cargo.toml --all-targets --all-features --locked -- -D warnings
• cargo fmt --manifest-path bt-daemon/Cargo.toml -- --check
• cargo metadata --manifest-path bt-daemon/Cargo.toml --locked --no-deps --format-version 1
• make test
• git diff --check

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

[Andrew Kent (realark)]

nice!

we should consider making the fail state configurable in the future. secret-scrubbing plugins that fail may wish to trigger a data drop instead, etc

[Stephen Belanger (Qard)]

Good point. I had went for failing plugins just get skipped, since we don't really have a way to surface errors immediately, only logs. But in some cases a failure may actually be a critical thing that should block reporting. 🤔

[Stephen Belanger (Qard)]

Addressed the redaction-failure concern: plugin processing now fails closed for every plugin error, so the affected span operation is withheld rather than sent unredacted. The raw QuickJS exception is stored in a bounded, deduplicated local diagnostics registry and shown by bt trace doctor. A failed plugin stays quarantined while its file is unchanged; editing it retries processing, and daemon recovery replays withheld journal operations through the repaired current plugin chain.