Add JavaScript span transform plugins

bt-daemon/Cargo.toml

@@ -24,6 +24,8 @@ async-trait = "0.1"
 chrono = "0.4"
 clap = { version = "4", features = ["derive", "env"] }
 regex = "1"
+rquickjs = "0.12.2"
+rquickjs-serde = "0.6.1"
 serde = { version = "1", features = ["derive"] }
 serde_json = "1"
 sha2 = "0.10"

bt-daemon/README.md

@@ -59,6 +59,101 @@ the default `bt` profile. Credentials and backend URLs are never stored here;
 production resolves and refreshes them through `bt`. `bt trace run` supplies a
 process-local settings overlay and never changes any of these files.
 
+### JavaScript span plugins
+
+`--plugin PATH` registers a synchronous ES module that transforms each
+sink-neutral span row after translation and immediately before delivery. Repeat
+the flag to compose plugins from left to right. `enable` persists its ordered list
+for ordinary agent sessions. Managed runs and imports are isolated from that
+list and use only the `--plugin` flags passed to their command. Each path is
+canonicalized to an absolute path before it is validated or stored.
+
+Each module must default-export a synchronous function. It receives a span and
+`{ operation, source, session_id, env }`, and must return a JSON-compatible span
+object. Span, root, and parent identities cannot be changed:
+
+```js
+// redact.mjs
+function redact(value) {
+ if (typeof value === "string") {
+ return value.replace(/sk-[A-Za-z0-9_-]+/g, "[REDACTED]");
+ }
+ if (Array.isArray(value)) return value.map(redact);
+ if (value && typeof value === "object") {
+ return Object.fromEntries(
+ Object.entries(value).map(([key, child]) => [key, redact(child)]),
+ );
+ }
+ return value;
+}
+
+export default function redactSpan(span) {
+ const next = { ...span };
+ for (const field of ["input", "output", "error"]) {
+ if (field in next) next[field] = redact(next[field]);
+ }
+ return next;
+}
+```
+
+The context can drive a second transform without changing the first one:
+
+```js
+// 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,
+ },
+ };
+}
+```
+
+Register both transforms persistently for ordinary Codex sessions. The
+redactor runs first and its returned span becomes the tagger's input:
+
+```bash
+bt trace enable codex --plugin ./redact.mjs --plugin ./tag-ci.mjs
+```
+
+`run` and `import` plugins apply only to that command. They replace, rather than
+merge with, plugins saved by `enable`:
+
+```bash
+# Only local.mjs runs; redact.mjs and tag-ci.mjs remain global enable behavior.
+bt trace run --plugin ./local.mjs codex -- "summarize this change"
+
+# Only sanitize-history.mjs transforms spans produced by this import.
+bt trace import codex SESSION_ID --plugin ./sanitize-history.mjs
+```
+
+The journal stores raw input events, not transformed spans. After daemon
+recovery, replayed events therefore pass through the resumed session's current
+route: ordinary sessions use the current globally configured plugins, while a
+managed session continues using only that run's isolated plugins.
+
+`context.operation` is `"insert"` or `"merge"`; `context.source` and
+`context.session_id` identify the translated event stream; and `context.env`
+contains the daemon process environment. Environment variable names are
+uppercased on Windows so common lookups such as `context.env.PATH` remain
+portable.
+
+The environment map is captured from the daemon process when each worker-local
+span processor is constructed. Plugins execute in bounded, thread-local
+QuickJS runtimes with no filesystem or network host APIs. Modules must be
+self-contained and transforms must be stateless: module globals belong to a
+worker thread, not a session. If a plugin fails, that worker reports and skips
+only that plugin on subsequent spans; the remaining plugins continue to run.
+Plugins are trusted local code: although they have no host APIs, they can copy
+environment values into spans that are delivered to Braintrust. Read only the
+specific variables needed by the transform; never attach `context.env` itself.
+
 ### Additional root metadata
 
 `additional_metadata` is a JSON object merged into each traced session's root

bt-daemon/config.json.example

@@ -14,6 +14,9 @@
  "additional_metadata": {
  "team": "platform",
  "environment": "development"
- }
+ },
+ "span_plugins": [
+ "/absolute/path/to/redact.mjs"
+ ]
  }
 }

bt-daemon/docs/protocol.md

@@ -205,7 +205,8 @@ Used for version handover and by tests.
  "project_name": "codex"
  },
  "flush_mode": "fire_and_forget",
- "additional_metadata": { "…": "…" }
+ "additional_metadata": { "…": "…" },
+ "span_plugins": ["/absolute/path/redact.mjs"]
  }
 }
 ```
@@ -270,7 +271,9 @@ Field notes:
 
 Live credentials returned by the host provider are **never** written to the
 journal, logs, status, or RPC response. Envelopes journal only their non-secret
-`route`, allowing restart recovery to resolve a fresh lease.
+`route`, allowing restart recovery to resolve a fresh lease. Span plugins read
+an environment snapshot captured inside their daemon worker process; it is not
+part of the envelope or journal schema.
 
 ## Daemon lifecycle
 
@@ -337,8 +340,10 @@ profiles, organizations, and destinations while sharing one daemon.
  `$HOME/.braintrust/state/bt-daemon` on Unix, and
  `%LOCALAPPDATA%\Braintrust\bt-daemon` on Windows. On restart the daemon
  rebuilds each route's unfinished correlation state independently, replaying
- only the journal entries whose `route` matches that pipeline into a fresh
- translator. The resulting rows may be resubmitted to repair delivery
+ only the journal entries whose delivery route matches that pipeline into a
+ fresh translator. Span plugin paths are ignored for this comparison so raw
+ events can be replayed through the current plugin chain. The resulting rows
+ may be resubmitted to repair delivery
  interrupted by a crash, but their deterministic ids target the same backend
  rows and must never create duplicate spans, and a route never receives
  another route's rows. Replay streams the journal and is bounded to the

bt-daemon/src/dispatch.rs

@@ -457,7 +457,36 @@ impl SessionActor {
  &ops,
  );
  }
- match sink.emit(&ops).await {
+ let plugin_paths = ctx
+ .config
+ .as_ref()
+ .map(|config| config.span_plugins.as_slice())
+ .unwrap_or_default();
+ let mut processed = Vec::with_capacity(ops.len());
+ for op in &ops {
+ match crate::span_processor::process(
+ plugin_paths,
+ op,
+ &self.source,
+ &self.session_id,
+ ) {
+ Ok(result) => {
+ for failure in result.failures {
+ self.set_error(format!(
+ "span plugin {} failed; disabled on this worker: {}",
+ failure.path.display(),
+ failure.message
+ ));
+ }
+ processed.push(result.op);
+ }
+ Err(error) => {
+ self.set_error(format!("span plugin processor failed: {error}"));
+ processed.push(op.clone());
+ }
+ }
+ }
+ match sink.emit(&processed).await {
  Ok(n) => {
  self.counters.spans_emitted.fetch_add(n, Ordering::Relaxed);
  }
@@ -510,7 +539,7 @@ impl SessionActor {
  if !entry
  .route
  .as_ref()
- .is_some_and(|candidate| candidate.same_route(&plan.route))
+ .is_some_and(|candidate| candidate.same_replay_route(&plan.route))
  {
  continue;
  }

bt-daemon/Cargo.toml

@@ -24,6 +24,8 @@ async-trait = "0.1"
 chrono = "0.4"
 clap = { version = "4", features = ["derive", "env"] }
 regex = "1"
+rquickjs = "0.12.2"
+rquickjs-serde = "0.6.1"
 serde = { version = "1", features = ["derive"] }
 serde_json = "1"
 sha2 = "0.10"

bt-daemon/README.md

@@ -59,6 +59,101 @@ the default `bt` profile. Credentials and backend URLs are never stored here;
 production resolves and refreshes them through `bt`. `bt trace run` supplies a
 process-local settings overlay and never changes any of these files.
 
+### JavaScript span plugins
+
+`--plugin PATH` registers a synchronous ES module that transforms each
+sink-neutral span row after translation and immediately before delivery. Repeat
+the flag to compose plugins from left to right. `enable` persists its ordered list
+for ordinary agent sessions. Managed runs and imports are isolated from that
+list and use only the `--plugin` flags passed to their command. Each path is
+canonicalized to an absolute path before it is validated or stored.
+
+Each module must default-export a synchronous function. It receives a span and
+`{ operation, source, session_id, env }`, and must return a JSON-compatible span
+object. Span, root, and parent identities cannot be changed:
+
+```js
+// redact.mjs
+function redact(value) {
+ if (typeof value === "string") {
+ return value.replace(/sk-[A-Za-z0-9_-]+/g, "[REDACTED]");
+ }
+ if (Array.isArray(value)) return value.map(redact);
+ if (value && typeof value === "object") {
+ return Object.fromEntries(
+ Object.entries(value).map(([key, child]) => [key, redact(child)]),
+ );
+ }
+ return value;
+}
+
+export default function redactSpan(span) {
+ const next = { ...span };
+ for (const field of ["input", "output", "error"]) {
+ if (field in next) next[field] = redact(next[field]);
+ }
+ return next;
+}
+```
+
+The context can drive a second transform without changing the first one:
+
+```js
+// 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,
+ },
+ };
+}
+```
+
+Register both transforms persistently for ordinary Codex sessions. The
+redactor runs first and its returned span becomes the tagger's input:
+
+```bash
+bt trace enable codex --plugin ./redact.mjs --plugin ./tag-ci.mjs
+```
+
+`run` and `import` plugins apply only to that command. They replace, rather than
+merge with, plugins saved by `enable`:
+
+```bash
+# Only local.mjs runs; redact.mjs and tag-ci.mjs remain global enable behavior.
+bt trace run --plugin ./local.mjs codex -- "summarize this change"
+
+# Only sanitize-history.mjs transforms spans produced by this import.
+bt trace import codex SESSION_ID --plugin ./sanitize-history.mjs
+```
+
+The journal stores raw input events, not transformed spans. After daemon
+recovery, replayed events therefore pass through the resumed session's current
+route: ordinary sessions use the current globally configured plugins, while a
+managed session continues using only that run's isolated plugins.
+
+`context.operation` is `"insert"` or `"merge"`; `context.source` and
+`context.session_id` identify the translated event stream; and `context.env`
+contains the daemon process environment. Environment variable names are
+uppercased on Windows so common lookups such as `context.env.PATH` remain
+portable.
+
+The environment map is captured from the daemon process when each worker-local
+span processor is constructed. Plugins execute in bounded, thread-local
+QuickJS runtimes with no filesystem or network host APIs. Modules must be
+self-contained and transforms must be stateless: module globals belong to a
+worker thread, not a session. If a plugin fails, that worker reports and skips
+only that plugin on subsequent spans; the remaining plugins continue to run.
+Plugins are trusted local code: although they have no host APIs, they can copy
+environment values into spans that are delivered to Braintrust. Read only the
+specific variables needed by the transform; never attach `context.env` itself.
+
 ### Additional root metadata
 
 `additional_metadata` is a JSON object merged into each traced session's root

bt-daemon/config.json.example

@@ -14,6 +14,9 @@
  "additional_metadata": {
  "team": "platform",
  "environment": "development"
- }
+ },
+ "span_plugins": [
+ "/absolute/path/to/redact.mjs"
+ ]
  }
 }

bt-daemon/docs/protocol.md

@@ -205,7 +205,8 @@ Used for version handover and by tests.
  "project_name": "codex"
  },
  "flush_mode": "fire_and_forget",
- "additional_metadata": { "…": "…" }
+ "additional_metadata": { "…": "…" },
+ "span_plugins": ["/absolute/path/redact.mjs"]
  }
 }
 ```
@@ -270,7 +271,9 @@ Field notes:
 
 Live credentials returned by the host provider are **never** written to the
 journal, logs, status, or RPC response. Envelopes journal only their non-secret
-`route`, allowing restart recovery to resolve a fresh lease.
+`route`, allowing restart recovery to resolve a fresh lease. Span plugins read
+an environment snapshot captured inside their daemon worker process; it is not
+part of the envelope or journal schema.
 
 ## Daemon lifecycle
 
@@ -337,8 +340,10 @@ profiles, organizations, and destinations while sharing one daemon.
  `$HOME/.braintrust/state/bt-daemon` on Unix, and
  `%LOCALAPPDATA%\Braintrust\bt-daemon` on Windows. On restart the daemon
  rebuilds each route's unfinished correlation state independently, replaying
- only the journal entries whose `route` matches that pipeline into a fresh
- translator. The resulting rows may be resubmitted to repair delivery
+ only the journal entries whose delivery route matches that pipeline into a
+ fresh translator. Span plugin paths are ignored for this comparison so raw
+ events can be replayed through the current plugin chain. The resulting rows
+ may be resubmitted to repair delivery
  interrupted by a crash, but their deterministic ids target the same backend
  rows and must never create duplicate spans, and a route never receives
  another route's rows. Replay streams the journal and is bounded to the

bt-daemon/src/dispatch.rs

@@ -457,7 +457,36 @@ impl SessionActor {
  &ops,
  );
  }
- match sink.emit(&ops).await {
+ let plugin_paths = ctx
+ .config
+ .as_ref()
+ .map(|config| config.span_plugins.as_slice())
+ .unwrap_or_default();
+ let mut processed = Vec::with_capacity(ops.len());
+ for op in &ops {
+ match crate::span_processor::process(
+ plugin_paths,
+ op,
+ &self.source,
+ &self.session_id,
+ ) {
+ Ok(result) => {
+ for failure in result.failures {
+ self.set_error(format!(
+ "span plugin {} failed; disabled on this worker: {}",
+ failure.path.display(),
+ failure.message
+ ));
+ }
+ processed.push(result.op);
+ }
+ Err(error) => {
+ self.set_error(format!("span plugin processor failed: {error}"));
+ processed.push(op.clone());
+ }
+ }
+ }
+ match sink.emit(&processed).await {
  Ok(n) => {
  self.counters.spans_emitted.fetch_add(n, Ordering::Relaxed);
  }
@@ -510,7 +539,7 @@ impl SessionActor {
  if !entry
  .route
  .as_ref()
- .is_some_and(|candidate| candidate.same_route(&plan.route))
+ .is_some_and(|candidate| candidate.same_replay_route(&plan.route))
  {
  continue;
  }

bt-daemon/Cargo.toml

@@ -24,6 +24,8 @@ async-trait = "0.1"
 chrono = "0.4"
 clap = { version = "4", features = ["derive", "env"] }
 regex = "1"
+rquickjs = "0.12.2"
+rquickjs-serde = "0.6.1"
 serde = { version = "1", features = ["derive"] }
 serde_json = "1"
 sha2 = "0.10"

bt-daemon/README.md

@@ -59,6 +59,101 @@ the default `bt` profile. Credentials and backend URLs are never stored here;
 production resolves and refreshes them through `bt`. `bt trace run` supplies a
 process-local settings overlay and never changes any of these files.
 
+### JavaScript span plugins
+
+`--plugin PATH` registers a synchronous ES module that transforms each
+sink-neutral span row after translation and immediately before delivery. Repeat
+the flag to compose plugins from left to right. `enable` persists its ordered list
+for ordinary agent sessions. Managed runs and imports are isolated from that
+list and use only the `--plugin` flags passed to their command. Each path is
+canonicalized to an absolute path before it is validated or stored.
+
+Each module must default-export a synchronous function. It receives a span and
+`{ operation, source, session_id, env }`, and must return a JSON-compatible span
+object. Span, root, and parent identities cannot be changed:
+
+```js
+// redact.mjs
+function redact(value) {
+ if (typeof value === "string") {
+ return value.replace(/sk-[A-Za-z0-9_-]+/g, "[REDACTED]");
+ }
+ if (Array.isArray(value)) return value.map(redact);
+ if (value && typeof value === "object") {
+ return Object.fromEntries(
+ Object.entries(value).map(([key, child]) => [key, redact(child)]),
+ );
+ }
+ return value;
+}
+
+export default function redactSpan(span) {
+ const next = { ...span };
+ for (const field of ["input", "output", "error"]) {
+ if (field in next) next[field] = redact(next[field]);
+ }
+ return next;
+}
+```
+
+The context can drive a second transform without changing the first one:
+
+```js
+// 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,
+ },
+ };
+}
+```
+
+Register both transforms persistently for ordinary Codex sessions. The
+redactor runs first and its returned span becomes the tagger's input:
+
+```bash
+bt trace enable codex --plugin ./redact.mjs --plugin ./tag-ci.mjs
+```
+
+`run` and `import` plugins apply only to that command. They replace, rather than
+merge with, plugins saved by `enable`:
+
+```bash
+# Only local.mjs runs; redact.mjs and tag-ci.mjs remain global enable behavior.
+bt trace run --plugin ./local.mjs codex -- "summarize this change"
+
+# Only sanitize-history.mjs transforms spans produced by this import.
+bt trace import codex SESSION_ID --plugin ./sanitize-history.mjs
+```
+
+The journal stores raw input events, not transformed spans. After daemon
+recovery, replayed events therefore pass through the resumed session's current
+route: ordinary sessions use the current globally configured plugins, while a
+managed session continues using only that run's isolated plugins.
+
+`context.operation` is `"insert"` or `"merge"`; `context.source` and
+`context.session_id` identify the translated event stream; and `context.env`
+contains the daemon process environment. Environment variable names are
+uppercased on Windows so common lookups such as `context.env.PATH` remain
+portable.
+
+The environment map is captured from the daemon process when each worker-local
+span processor is constructed. Plugins execute in bounded, thread-local
+QuickJS runtimes with no filesystem or network host APIs. Modules must be
+self-contained and transforms must be stateless: module globals belong to a
+worker thread, not a session. If a plugin fails, that worker reports and skips
+only that plugin on subsequent spans; the remaining plugins continue to run.
+Plugins are trusted local code: although they have no host APIs, they can copy
+environment values into spans that are delivered to Braintrust. Read only the
+specific variables needed by the transform; never attach `context.env` itself.
+
 ### Additional root metadata
 
 `additional_metadata` is a JSON object merged into each traced session's root

bt-daemon/config.json.example

@@ -14,6 +14,9 @@
  "additional_metadata": {
  "team": "platform",
  "environment": "development"
- }
+ },
+ "span_plugins": [
+ "/absolute/path/to/redact.mjs"
+ ]
  }
 }

bt-daemon/docs/protocol.md

@@ -205,7 +205,8 @@ Used for version handover and by tests.
  "project_name": "codex"
  },
  "flush_mode": "fire_and_forget",
- "additional_metadata": { "…": "…" }
+ "additional_metadata": { "…": "…" },
+ "span_plugins": ["/absolute/path/redact.mjs"]
  }
 }
 ```
@@ -270,7 +271,9 @@ Field notes:
 
 Live credentials returned by the host provider are **never** written to the
 journal, logs, status, or RPC response. Envelopes journal only their non-secret
-`route`, allowing restart recovery to resolve a fresh lease.
+`route`, allowing restart recovery to resolve a fresh lease. Span plugins read
+an environment snapshot captured inside their daemon worker process; it is not
+part of the envelope or journal schema.
 
 ## Daemon lifecycle
 
@@ -337,8 +340,10 @@ profiles, organizations, and destinations while sharing one daemon.
  `$HOME/.braintrust/state/bt-daemon` on Unix, and
  `%LOCALAPPDATA%\Braintrust\bt-daemon` on Windows. On restart the daemon
  rebuilds each route's unfinished correlation state independently, replaying
- only the journal entries whose `route` matches that pipeline into a fresh
- translator. The resulting rows may be resubmitted to repair delivery
+ only the journal entries whose delivery route matches that pipeline into a
+ fresh translator. Span plugin paths are ignored for this comparison so raw
+ events can be replayed through the current plugin chain. The resulting rows
+ may be resubmitted to repair delivery
  interrupted by a crash, but their deterministic ids target the same backend
  rows and must never create duplicate spans, and a route never receives
  another route's rows. Replay streams the journal and is bounded to the

bt-daemon/src/dispatch.rs

@@ -457,7 +457,36 @@ impl SessionActor {
  &ops,
  );
  }
- match sink.emit(&ops).await {
+ let plugin_paths = ctx
+ .config
+ .as_ref()
+ .map(|config| config.span_plugins.as_slice())
+ .unwrap_or_default();
+ let mut processed = Vec::with_capacity(ops.len());
+ for op in &ops {
+ match crate::span_processor::process(
+ plugin_paths,
+ op,
+ &self.source,
+ &self.session_id,
+ ) {
+ Ok(result) => {
+ for failure in result.failures {
+ self.set_error(format!(
+ "span plugin {} failed; disabled on this worker: {}",
+ failure.path.display(),
+ failure.message
+ ));
+ }
+ processed.push(result.op);
+ }
+ Err(error) => {
+ self.set_error(format!("span plugin processor failed: {error}"));
+ processed.push(op.clone());
+ }
+ }
+ }
+ match sink.emit(&processed).await {
  Ok(n) => {
  self.counters.spans_emitted.fetch_add(n, Ordering::Relaxed);
  }
@@ -510,7 +539,7 @@ impl SessionActor {
  if !entry
  .route
  .as_ref()
- .is_some_and(|candidate| candidate.same_route(&plan.route))
+ .is_some_and(|candidate| candidate.same_replay_route(&plan.route))
  {
  continue;
  }

bt-daemon/Cargo.toml

@@ -24,6 +24,8 @@ async-trait = "0.1"
 chrono = "0.4"
 clap = { version = "4", features = ["derive", "env"] }
 regex = "1"
+rquickjs = "0.12.2"
+rquickjs-serde = "0.6.1"
 serde = { version = "1", features = ["derive"] }
 serde_json = "1"
 sha2 = "0.10"

bt-daemon/README.md

@@ -59,6 +59,101 @@ the default `bt` profile. Credentials and backend URLs are never stored here;
 production resolves and refreshes them through `bt`. `bt trace run` supplies a
 process-local settings overlay and never changes any of these files.
 
+### JavaScript span plugins
+
+`--plugin PATH` registers a synchronous ES module that transforms each
+sink-neutral span row after translation and immediately before delivery. Repeat
+the flag to compose plugins from left to right. `enable` persists its ordered list
+for ordinary agent sessions. Managed runs and imports are isolated from that
+list and use only the `--plugin` flags passed to their command. Each path is
+canonicalized to an absolute path before it is validated or stored.
+
+Each module must default-export a synchronous function. It receives a span and
+`{ operation, source, session_id, env }`, and must return a JSON-compatible span
+object. Span, root, and parent identities cannot be changed:
+
+```js
+// redact.mjs
+function redact(value) {
+ if (typeof value === "string") {
+ return value.replace(/sk-[A-Za-z0-9_-]+/g, "[REDACTED]");
+ }
+ if (Array.isArray(value)) return value.map(redact);
+ if (value && typeof value === "object") {
+ return Object.fromEntries(
+ Object.entries(value).map(([key, child]) => [key, redact(child)]),
+ );
+ }
+ return value;
+}
+
+export default function redactSpan(span) {
+ const next = { ...span };
+ for (const field of ["input", "output", "error"]) {
+ if (field in next) next[field] = redact(next[field]);
+ }
+ return next;
+}
+```
+
+The context can drive a second transform without changing the first one:
+
+```js
+// 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,
+ },
+ };
+}
+```
+
+Register both transforms persistently for ordinary Codex sessions. The
+redactor runs first and its returned span becomes the tagger's input:
+
+```bash
+bt trace enable codex --plugin ./redact.mjs --plugin ./tag-ci.mjs
+```
+
+`run` and `import` plugins apply only to that command. They replace, rather than
+merge with, plugins saved by `enable`:
+
+```bash
+# Only local.mjs runs; redact.mjs and tag-ci.mjs remain global enable behavior.
+bt trace run --plugin ./local.mjs codex -- "summarize this change"
+
+# Only sanitize-history.mjs transforms spans produced by this import.
+bt trace import codex SESSION_ID --plugin ./sanitize-history.mjs
+```
+
+The journal stores raw input events, not transformed spans. After daemon
+recovery, replayed events therefore pass through the resumed session's current
+route: ordinary sessions use the current globally configured plugins, while a
+managed session continues using only that run's isolated plugins.
+
+`context.operation` is `"insert"` or `"merge"`; `context.source` and
+`context.session_id` identify the translated event stream; and `context.env`
+contains the daemon process environment. Environment variable names are
+uppercased on Windows so common lookups such as `context.env.PATH` remain
+portable.
+
+The environment map is captured from the daemon process when each worker-local
+span processor is constructed. Plugins execute in bounded, thread-local
+QuickJS runtimes with no filesystem or network host APIs. Modules must be
+self-contained and transforms must be stateless: module globals belong to a
+worker thread, not a session. If a plugin fails, that worker reports and skips
+only that plugin on subsequent spans; the remaining plugins continue to run.
+Plugins are trusted local code: although they have no host APIs, they can copy
+environment values into spans that are delivered to Braintrust. Read only the
+specific variables needed by the transform; never attach `context.env` itself.
+
 ### Additional root metadata
 
 `additional_metadata` is a JSON object merged into each traced session's root

bt-daemon/config.json.example

@@ -14,6 +14,9 @@
  "additional_metadata": {
  "team": "platform",
  "environment": "development"
- }
+ },
+ "span_plugins": [
+ "/absolute/path/to/redact.mjs"
+ ]
  }
 }

bt-daemon/docs/protocol.md

@@ -205,7 +205,8 @@ Used for version handover and by tests.
  "project_name": "codex"
  },
  "flush_mode": "fire_and_forget",
- "additional_metadata": { "…": "…" }
+ "additional_metadata": { "…": "…" },
+ "span_plugins": ["/absolute/path/redact.mjs"]
  }
 }
 ```
@@ -270,7 +271,9 @@ Field notes:
 
 Live credentials returned by the host provider are **never** written to the
 journal, logs, status, or RPC response. Envelopes journal only their non-secret
-`route`, allowing restart recovery to resolve a fresh lease.
+`route`, allowing restart recovery to resolve a fresh lease. Span plugins read
+an environment snapshot captured inside their daemon worker process; it is not
+part of the envelope or journal schema.
 
 ## Daemon lifecycle
 
@@ -337,8 +340,10 @@ profiles, organizations, and destinations while sharing one daemon.
  `$HOME/.braintrust/state/bt-daemon` on Unix, and
  `%LOCALAPPDATA%\Braintrust\bt-daemon` on Windows. On restart the daemon
  rebuilds each route's unfinished correlation state independently, replaying
- only the journal entries whose `route` matches that pipeline into a fresh
- translator. The resulting rows may be resubmitted to repair delivery
+ only the journal entries whose delivery route matches that pipeline into a
+ fresh translator. Span plugin paths are ignored for this comparison so raw
+ events can be replayed through the current plugin chain. The resulting rows
+ may be resubmitted to repair delivery
  interrupted by a crash, but their deterministic ids target the same backend
  rows and must never create duplicate spans, and a route never receives
  another route's rows. Replay streams the journal and is bounded to the

bt-daemon/src/dispatch.rs

@@ -457,7 +457,36 @@ impl SessionActor {
  &ops,
  );
  }
- match sink.emit(&ops).await {
+ let plugin_paths = ctx
+ .config
+ .as_ref()
+ .map(|config| config.span_plugins.as_slice())
+ .unwrap_or_default();
+ let mut processed = Vec::with_capacity(ops.len());
+ for op in &ops {
+ match crate::span_processor::process(
+ plugin_paths,
+ op,
+ &self.source,
+ &self.session_id,
+ ) {
+ Ok(result) => {
+ for failure in result.failures {
+ self.set_error(format!(
+ "span plugin {} failed; disabled on this worker: {}",
+ failure.path.display(),
+ failure.message
+ ));
+ }
+ processed.push(result.op);
+ }
+ Err(error) => {
+ self.set_error(format!("span plugin processor failed: {error}"));
+ processed.push(op.clone());
+ }
+ }
+ }
+ match sink.emit(&processed).await {
  Ok(n) => {
  self.counters.spans_emitted.fetch_add(n, Ordering::Relaxed);
  }
@@ -510,7 +539,7 @@ impl SessionActor {
  if !entry
  .route
  .as_ref()
- .is_some_and(|candidate| candidate.same_route(&plan.route))
+ .is_some_and(|candidate| candidate.same_replay_route(&plan.route))
  {
  continue;
  }

bt-daemon/Cargo.toml

@@ -24,6 +24,8 @@ async-trait = "0.1"
 chrono = "0.4"
 clap = { version = "4", features = ["derive", "env"] }
 regex = "1"
+rquickjs = "0.12.2"
+rquickjs-serde = "0.6.1"
 serde = { version = "1", features = ["derive"] }
 serde_json = "1"
 sha2 = "0.10"

bt-daemon/README.md

@@ -59,6 +59,101 @@ the default `bt` profile. Credentials and backend URLs are never stored here;
 production resolves and refreshes them through `bt`. `bt trace run` supplies a
 process-local settings overlay and never changes any of these files.
 
+### JavaScript span plugins
+
+`--plugin PATH` registers a synchronous ES module that transforms each
+sink-neutral span row after translation and immediately before delivery. Repeat
+the flag to compose plugins from left to right. `enable` persists its ordered list
+for ordinary agent sessions. Managed runs and imports are isolated from that
+list and use only the `--plugin` flags passed to their command. Each path is
+canonicalized to an absolute path before it is validated or stored.
+
+Each module must default-export a synchronous function. It receives a span and
+`{ operation, source, session_id, env }`, and must return a JSON-compatible span
+object. Span, root, and parent identities cannot be changed:
+
+```js
+// redact.mjs
+function redact(value) {
+ if (typeof value === "string") {
+ return value.replace(/sk-[A-Za-z0-9_-]+/g, "[REDACTED]");
+ }
+ if (Array.isArray(value)) return value.map(redact);
+ if (value && typeof value === "object") {
+ return Object.fromEntries(
+ Object.entries(value).map(([key, child]) => [key, redact(child)]),
+ );
+ }
+ return value;
+}
+
+export default function redactSpan(span) {
+ const next = { ...span };
+ for (const field of ["input", "output", "error"]) {
+ if (field in next) next[field] = redact(next[field]);
+ }
+ return next;
+}
+```
+
+The context can drive a second transform without changing the first one:
+
+```js
+// 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,
+ },
+ };
+}
+```
+
+Register both transforms persistently for ordinary Codex sessions. The
+redactor runs first and its returned span becomes the tagger's input:
+
+```bash
+bt trace enable codex --plugin ./redact.mjs --plugin ./tag-ci.mjs
+```
+
+`run` and `import` plugins apply only to that command. They replace, rather than
+merge with, plugins saved by `enable`:
+
+```bash
+# Only local.mjs runs; redact.mjs and tag-ci.mjs remain global enable behavior.
+bt trace run --plugin ./local.mjs codex -- "summarize this change"
+
+# Only sanitize-history.mjs transforms spans produced by this import.
+bt trace import codex SESSION_ID --plugin ./sanitize-history.mjs
+```
+
+The journal stores raw input events, not transformed spans. After daemon
+recovery, replayed events therefore pass through the resumed session's current
+route: ordinary sessions use the current globally configured plugins, while a
+managed session continues using only that run's isolated plugins.
+
+`context.operation` is `"insert"` or `"merge"`; `context.source` and
+`context.session_id` identify the translated event stream; and `context.env`
+contains the daemon process environment. Environment variable names are
+uppercased on Windows so common lookups such as `context.env.PATH` remain
+portable.
+
+The environment map is captured from the daemon process when each worker-local
+span processor is constructed. Plugins execute in bounded, thread-local
+QuickJS runtimes with no filesystem or network host APIs. Modules must be
+self-contained and transforms must be stateless: module globals belong to a
+worker thread, not a session. If a plugin fails, that worker reports and skips
+only that plugin on subsequent spans; the remaining plugins continue to run.
+Plugins are trusted local code: although they have no host APIs, they can copy
+environment values into spans that are delivered to Braintrust. Read only the
+specific variables needed by the transform; never attach `context.env` itself.
+
 ### Additional root metadata
 
 `additional_metadata` is a JSON object merged into each traced session's root

bt-daemon/config.json.example

@@ -14,6 +14,9 @@
  "additional_metadata": {
  "team": "platform",
  "environment": "development"
- }
+ },
+ "span_plugins": [
+ "/absolute/path/to/redact.mjs"
+ ]
  }
 }

bt-daemon/docs/protocol.md

@@ -205,7 +205,8 @@ Used for version handover and by tests.
  "project_name": "codex"
  },
  "flush_mode": "fire_and_forget",
- "additional_metadata": { "…": "…" }
+ "additional_metadata": { "…": "…" },
+ "span_plugins": ["/absolute/path/redact.mjs"]
  }
 }
 ```
@@ -270,7 +271,9 @@ Field notes:
 
 Live credentials returned by the host provider are **never** written to the
 journal, logs, status, or RPC response. Envelopes journal only their non-secret
-`route`, allowing restart recovery to resolve a fresh lease.
+`route`, allowing restart recovery to resolve a fresh lease. Span plugins read
+an environment snapshot captured inside their daemon worker process; it is not
+part of the envelope or journal schema.
 
 ## Daemon lifecycle
 
@@ -337,8 +340,10 @@ profiles, organizations, and destinations while sharing one daemon.
  `$HOME/.braintrust/state/bt-daemon` on Unix, and
  `%LOCALAPPDATA%\Braintrust\bt-daemon` on Windows. On restart the daemon
  rebuilds each route's unfinished correlation state independently, replaying
- only the journal entries whose `route` matches that pipeline into a fresh
- translator. The resulting rows may be resubmitted to repair delivery
+ only the journal entries whose delivery route matches that pipeline into a
+ fresh translator. Span plugin paths are ignored for this comparison so raw
+ events can be replayed through the current plugin chain. The resulting rows
+ may be resubmitted to repair delivery
  interrupted by a crash, but their deterministic ids target the same backend
  rows and must never create duplicate spans, and a route never receives
  another route's rows. Replay streams the journal and is bounded to the

bt-daemon/src/dispatch.rs

@@ -457,7 +457,36 @@ impl SessionActor {
  &ops,
  );
  }
- match sink.emit(&ops).await {
+ let plugin_paths = ctx
+ .config
+ .as_ref()
+ .map(|config| config.span_plugins.as_slice())
+ .unwrap_or_default();
+ let mut processed = Vec::with_capacity(ops.len());
+ for op in &ops {
+ match crate::span_processor::process(
+ plugin_paths,
+ op,
+ &self.source,
+ &self.session_id,
+ ) {
+ Ok(result) => {
+ for failure in result.failures {
+ self.set_error(format!(
+ "span plugin {} failed; disabled on this worker: {}",
+ failure.path.display(),
+ failure.message
+ ));
+ }
+ processed.push(result.op);
+ }
+ Err(error) => {
+ self.set_error(format!("span plugin processor failed: {error}"));
+ processed.push(op.clone());
+ }
+ }
+ }
+ match sink.emit(&processed).await {
  Ok(n) => {
  self.counters.spans_emitted.fetch_add(n, Ordering::Relaxed);
  }
@@ -510,7 +539,7 @@ impl SessionActor {
  if !entry
  .route
  .as_ref()
- .is_some_and(|candidate| candidate.same_route(&plan.route))
+ .is_some_and(|candidate| candidate.same_replay_route(&plan.route))
  {
  continue;
  }

bt-daemon/Cargo.toml

@@ -24,6 +24,8 @@ async-trait = "0.1"
 chrono = "0.4"
 clap = { version = "4", features = ["derive", "env"] }
 regex = "1"
+rquickjs = "0.12.2"
+rquickjs-serde = "0.6.1"
 serde = { version = "1", features = ["derive"] }
 serde_json = "1"
 sha2 = "0.10"

bt-daemon/README.md

@@ -59,6 +59,101 @@ the default `bt` profile. Credentials and backend URLs are never stored here;
 production resolves and refreshes them through `bt`. `bt trace run` supplies a
 process-local settings overlay and never changes any of these files.
 
+### JavaScript span plugins
+
+`--plugin PATH` registers a synchronous ES module that transforms each
+sink-neutral span row after translation and immediately before delivery. Repeat
+the flag to compose plugins from left to right. `enable` persists its ordered list
+for ordinary agent sessions. Managed runs and imports are isolated from that
+list and use only the `--plugin` flags passed to their command. Each path is
+canonicalized to an absolute path before it is validated or stored.
+
+Each module must default-export a synchronous function. It receives a span and
+`{ operation, source, session_id, env }`, and must return a JSON-compatible span
+object. Span, root, and parent identities cannot be changed:
+
+```js
+// redact.mjs
+function redact(value) {
+ if (typeof value === "string") {
+ return value.replace(/sk-[A-Za-z0-9_-]+/g, "[REDACTED]");
+ }
+ if (Array.isArray(value)) return value.map(redact);
+ if (value && typeof value === "object") {
+ return Object.fromEntries(
+ Object.entries(value).map(([key, child]) => [key, redact(child)]),
+ );
+ }
+ return value;
+}
+
+export default function redactSpan(span) {
+ const next = { ...span };
+ for (const field of ["input", "output", "error"]) {
+ if (field in next) next[field] = redact(next[field]);
+ }
+ return next;
+}
+```
+
+The context can drive a second transform without changing the first one:
+
+```js
+// 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,
+ },
+ };
+}
+```
+
+Register both transforms persistently for ordinary Codex sessions. The
+redactor runs first and its returned span becomes the tagger's input:
+
+```bash
+bt trace enable codex --plugin ./redact.mjs --plugin ./tag-ci.mjs
+```
+
+`run` and `import` plugins apply only to that command. They replace, rather than
+merge with, plugins saved by `enable`:
+
+```bash
+# Only local.mjs runs; redact.mjs and tag-ci.mjs remain global enable behavior.
+bt trace run --plugin ./local.mjs codex -- "summarize this change"
+
+# Only sanitize-history.mjs transforms spans produced by this import.
+bt trace import codex SESSION_ID --plugin ./sanitize-history.mjs
+```
+
+The journal stores raw input events, not transformed spans. After daemon
+recovery, replayed events therefore pass through the resumed session's current
+route: ordinary sessions use the current globally configured plugins, while a
+managed session continues using only that run's isolated plugins.
+
+`context.operation` is `"insert"` or `"merge"`; `context.source` and
+`context.session_id` identify the translated event stream; and `context.env`
+contains the daemon process environment. Environment variable names are
+uppercased on Windows so common lookups such as `context.env.PATH` remain
+portable.
+
+The environment map is captured from the daemon process when each worker-local
+span processor is constructed. Plugins execute in bounded, thread-local
+QuickJS runtimes with no filesystem or network host APIs. Modules must be
+self-contained and transforms must be stateless: module globals belong to a
+worker thread, not a session. If a plugin fails, that worker reports and skips
+only that plugin on subsequent spans; the remaining plugins continue to run.
+Plugins are trusted local code: although they have no host APIs, they can copy
+environment values into spans that are delivered to Braintrust. Read only the
+specific variables needed by the transform; never attach `context.env` itself.
+
 ### Additional root metadata
 
 `additional_metadata` is a JSON object merged into each traced session's root

bt-daemon/config.json.example

@@ -14,6 +14,9 @@
  "additional_metadata": {
  "team": "platform",
  "environment": "development"
- }
+ },
+ "span_plugins": [
+ "/absolute/path/to/redact.mjs"
+ ]
  }
 }

bt-daemon/docs/protocol.md

@@ -205,7 +205,8 @@ Used for version handover and by tests.
  "project_name": "codex"
  },
  "flush_mode": "fire_and_forget",
- "additional_metadata": { "…": "…" }
+ "additional_metadata": { "…": "…" },
+ "span_plugins": ["/absolute/path/redact.mjs"]
  }
 }
 ```
@@ -270,7 +271,9 @@ Field notes:
 
 Live credentials returned by the host provider are **never** written to the
 journal, logs, status, or RPC response. Envelopes journal only their non-secret
-`route`, allowing restart recovery to resolve a fresh lease.
+`route`, allowing restart recovery to resolve a fresh lease. Span plugins read
+an environment snapshot captured inside their daemon worker process; it is not
+part of the envelope or journal schema.
 
 ## Daemon lifecycle
 
@@ -337,8 +340,10 @@ profiles, organizations, and destinations while sharing one daemon.
  `$HOME/.braintrust/state/bt-daemon` on Unix, and
  `%LOCALAPPDATA%\Braintrust\bt-daemon` on Windows. On restart the daemon
  rebuilds each route's unfinished correlation state independently, replaying
- only the journal entries whose `route` matches that pipeline into a fresh
- translator. The resulting rows may be resubmitted to repair delivery
+ only the journal entries whose delivery route matches that pipeline into a
+ fresh translator. Span plugin paths are ignored for this comparison so raw
+ events can be replayed through the current plugin chain. The resulting rows
+ may be resubmitted to repair delivery
  interrupted by a crash, but their deterministic ids target the same backend
  rows and must never create duplicate spans, and a route never receives
  another route's rows. Replay streams the journal and is bounded to the

bt-daemon/src/dispatch.rs

@@ -457,7 +457,36 @@ impl SessionActor {
  &ops,
  );
  }
- match sink.emit(&ops).await {
+ let plugin_paths = ctx
+ .config
+ .as_ref()
+ .map(|config| config.span_plugins.as_slice())
+ .unwrap_or_default();
+ let mut processed = Vec::with_capacity(ops.len());
+ for op in &ops {
+ match crate::span_processor::process(
+ plugin_paths,
+ op,
+ &self.source,
+ &self.session_id,
+ ) {
+ Ok(result) => {
+ for failure in result.failures {
+ self.set_error(format!(
+ "span plugin {} failed; disabled on this worker: {}",
+ failure.path.display(),
+ failure.message
+ ));
+ }
+ processed.push(result.op);
+ }
+ Err(error) => {
+ self.set_error(format!("span plugin processor failed: {error}"));
+ processed.push(op.clone());
+ }
+ }
+ }
+ match sink.emit(&processed).await {
  Ok(n) => {
  self.counters.spans_emitted.fetch_add(n, Ordering::Relaxed);
  }
@@ -510,7 +539,7 @@ impl SessionActor {
  if !entry
  .route
  .as_ref()
- .is_some_and(|candidate| candidate.same_route(&plan.route))
+ .is_some_and(|candidate| candidate.same_replay_route(&plan.route))
  {
  continue;
  }

bt-daemon/Cargo.toml

@@ -24,6 +24,8 @@ async-trait = "0.1"
 chrono = "0.4"
 clap = { version = "4", features = ["derive", "env"] }
 regex = "1"
+rquickjs = "0.12.2"
+rquickjs-serde = "0.6.1"
 serde = { version = "1", features = ["derive"] }
 serde_json = "1"
 sha2 = "0.10"

bt-daemon/README.md

@@ -59,6 +59,101 @@ the default `bt` profile. Credentials and backend URLs are never stored here;
 production resolves and refreshes them through `bt`. `bt trace run` supplies a
 process-local settings overlay and never changes any of these files.
 
+### JavaScript span plugins
+
+`--plugin PATH` registers a synchronous ES module that transforms each
+sink-neutral span row after translation and immediately before delivery. Repeat
+the flag to compose plugins from left to right. `enable` persists its ordered list
+for ordinary agent sessions. Managed runs and imports are isolated from that
+list and use only the `--plugin` flags passed to their command. Each path is
+canonicalized to an absolute path before it is validated or stored.
+
+Each module must default-export a synchronous function. It receives a span and
+`{ operation, source, session_id, env }`, and must return a JSON-compatible span
+object. Span, root, and parent identities cannot be changed:
+
+```js
+// redact.mjs
+function redact(value) {
+ if (typeof value === "string") {
+ return value.replace(/sk-[A-Za-z0-9_-]+/g, "[REDACTED]");
+ }
+ if (Array.isArray(value)) return value.map(redact);
+ if (value && typeof value === "object") {
+ return Object.fromEntries(
+ Object.entries(value).map(([key, child]) => [key, redact(child)]),
+ );
+ }
+ return value;
+}
+
+export default function redactSpan(span) {
+ const next = { ...span };
+ for (const field of ["input", "output", "error"]) {
+ if (field in next) next[field] = redact(next[field]);
+ }
+ return next;
+}
+```
+
+The context can drive a second transform without changing the first one:
+
+```js
+// 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,
+ },
+ };
+}
+```
+
+Register both transforms persistently for ordinary Codex sessions. The
+redactor runs first and its returned span becomes the tagger's input:
+
+```bash
+bt trace enable codex --plugin ./redact.mjs --plugin ./tag-ci.mjs
+```
+
+`run` and `import` plugins apply only to that command. They replace, rather than
+merge with, plugins saved by `enable`:
+
+```bash
+# Only local.mjs runs; redact.mjs and tag-ci.mjs remain global enable behavior.
+bt trace run --plugin ./local.mjs codex -- "summarize this change"
+
+# Only sanitize-history.mjs transforms spans produced by this import.
+bt trace import codex SESSION_ID --plugin ./sanitize-history.mjs
+```
+
+The journal stores raw input events, not transformed spans. After daemon
+recovery, replayed events therefore pass through the resumed session's current
+route: ordinary sessions use the current globally configured plugins, while a
+managed session continues using only that run's isolated plugins.
+
+`context.operation` is `"insert"` or `"merge"`; `context.source` and
+`context.session_id` identify the translated event stream; and `context.env`
+contains the daemon process environment. Environment variable names are
+uppercased on Windows so common lookups such as `context.env.PATH` remain
+portable.
+
+The environment map is captured from the daemon process when each worker-local
+span processor is constructed. Plugins execute in bounded, thread-local
+QuickJS runtimes with no filesystem or network host APIs. Modules must be
+self-contained and transforms must be stateless: module globals belong to a
+worker thread, not a session. If a plugin fails, that worker reports and skips
+only that plugin on subsequent spans; the remaining plugins continue to run.
+Plugins are trusted local code: although they have no host APIs, they can copy
+environment values into spans that are delivered to Braintrust. Read only the
+specific variables needed by the transform; never attach `context.env` itself.
+
 ### Additional root metadata
 
 `additional_metadata` is a JSON object merged into each traced session's root

bt-daemon/config.json.example

@@ -14,6 +14,9 @@
  "additional_metadata": {
  "team": "platform",
  "environment": "development"
- }
+ },
+ "span_plugins": [
+ "/absolute/path/to/redact.mjs"
+ ]
  }
 }

bt-daemon/docs/protocol.md

@@ -205,7 +205,8 @@ Used for version handover and by tests.
  "project_name": "codex"
  },
  "flush_mode": "fire_and_forget",
- "additional_metadata": { "…": "…" }
+ "additional_metadata": { "…": "…" },
+ "span_plugins": ["/absolute/path/redact.mjs"]
  }
 }
 ```
@@ -270,7 +271,9 @@ Field notes:
 
 Live credentials returned by the host provider are **never** written to the
 journal, logs, status, or RPC response. Envelopes journal only their non-secret
-`route`, allowing restart recovery to resolve a fresh lease.
+`route`, allowing restart recovery to resolve a fresh lease. Span plugins read
+an environment snapshot captured inside their daemon worker process; it is not
+part of the envelope or journal schema.
 
 ## Daemon lifecycle
 
@@ -337,8 +340,10 @@ profiles, organizations, and destinations while sharing one daemon.
  `$HOME/.braintrust/state/bt-daemon` on Unix, and
  `%LOCALAPPDATA%\Braintrust\bt-daemon` on Windows. On restart the daemon
  rebuilds each route's unfinished correlation state independently, replaying
- only the journal entries whose `route` matches that pipeline into a fresh
- translator. The resulting rows may be resubmitted to repair delivery
+ only the journal entries whose delivery route matches that pipeline into a
+ fresh translator. Span plugin paths are ignored for this comparison so raw
+ events can be replayed through the current plugin chain. The resulting rows
+ may be resubmitted to repair delivery
  interrupted by a crash, but their deterministic ids target the same backend
  rows and must never create duplicate spans, and a route never receives
  another route's rows. Replay streams the journal and is bounded to the

bt-daemon/src/dispatch.rs

@@ -457,7 +457,36 @@ impl SessionActor {
  &ops,
  );
  }
- match sink.emit(&ops).await {
+ let plugin_paths = ctx
+ .config
+ .as_ref()
+ .map(|config| config.span_plugins.as_slice())
+ .unwrap_or_default();
+ let mut processed = Vec::with_capacity(ops.len());
+ for op in &ops {
+ match crate::span_processor::process(
+ plugin_paths,
+ op,
+ &self.source,
+ &self.session_id,
+ ) {
+ Ok(result) => {
+ for failure in result.failures {
+ self.set_error(format!(
+ "span plugin {} failed; disabled on this worker: {}",
+ failure.path.display(),
+ failure.message
+ ));
+ }
+ processed.push(result.op);
+ }
+ Err(error) => {
+ self.set_error(format!("span plugin processor failed: {error}"));
+ processed.push(op.clone());
+ }
+ }
+ }
+ match sink.emit(&processed).await {
  Ok(n) => {
  self.counters.spans_emitted.fetch_add(n, Ordering::Relaxed);
  }
@@ -510,7 +539,7 @@ impl SessionActor {
  if !entry
  .route
  .as_ref()
- .is_some_and(|candidate| candidate.same_route(&plan.route))
+ .is_some_and(|candidate| candidate.same_replay_route(&plan.route))
  {
  continue;
  }

bt-daemon/Cargo.toml

@@ -24,6 +24,8 @@ async-trait = "0.1"
 chrono = "0.4"
 clap = { version = "4", features = ["derive", "env"] }
 regex = "1"
+rquickjs = "0.12.2"
+rquickjs-serde = "0.6.1"
 serde = { version = "1", features = ["derive"] }
 serde_json = "1"
 sha2 = "0.10"

bt-daemon/README.md

@@ -59,6 +59,101 @@ the default `bt` profile. Credentials and backend URLs are never stored here;
 production resolves and refreshes them through `bt`. `bt trace run` supplies a
 process-local settings overlay and never changes any of these files.
 
+### JavaScript span plugins
+
+`--plugin PATH` registers a synchronous ES module that transforms each
+sink-neutral span row after translation and immediately before delivery. Repeat
+the flag to compose plugins from left to right. `enable` persists its ordered list
+for ordinary agent sessions. Managed runs and imports are isolated from that
+list and use only the `--plugin` flags passed to their command. Each path is
+canonicalized to an absolute path before it is validated or stored.
+
+Each module must default-export a synchronous function. It receives a span and
+`{ operation, source, session_id, env }`, and must return a JSON-compatible span
+object. Span, root, and parent identities cannot be changed:
+
+```js
+// redact.mjs
+function redact(value) {
+ if (typeof value === "string") {
+ return value.replace(/sk-[A-Za-z0-9_-]+/g, "[REDACTED]");
+ }
+ if (Array.isArray(value)) return value.map(redact);
+ if (value && typeof value === "object") {
+ return Object.fromEntries(
+ Object.entries(value).map(([key, child]) => [key, redact(child)]),
+ );
+ }
+ return value;
+}
+
+export default function redactSpan(span) {
+ const next = { ...span };
+ for (const field of ["input", "output", "error"]) {
+ if (field in next) next[field] = redact(next[field]);
+ }
+ return next;
+}
+```
+
+The context can drive a second transform without changing the first one:
+
+```js
+// 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,
+ },
+ };
+}
+```
+
+Register both transforms persistently for ordinary Codex sessions. The
+redactor runs first and its returned span becomes the tagger's input:
+
+```bash
+bt trace enable codex --plugin ./redact.mjs --plugin ./tag-ci.mjs
+```
+
+`run` and `import` plugins apply only to that command. They replace, rather than
+merge with, plugins saved by `enable`:
+
+```bash
+# Only local.mjs runs; redact.mjs and tag-ci.mjs remain global enable behavior.
+bt trace run --plugin ./local.mjs codex -- "summarize this change"
+
+# Only sanitize-history.mjs transforms spans produced by this import.
+bt trace import codex SESSION_ID --plugin ./sanitize-history.mjs
+```
+
+The journal stores raw input events, not transformed spans. After daemon
+recovery, replayed events therefore pass through the resumed session's current
+route: ordinary sessions use the current globally configured plugins, while a
+managed session continues using only that run's isolated plugins.
+
+`context.operation` is `"insert"` or `"merge"`; `context.source` and
+`context.session_id` identify the translated event stream; and `context.env`
+contains the daemon process environment. Environment variable names are
+uppercased on Windows so common lookups such as `context.env.PATH` remain
+portable.
+
+The environment map is captured from the daemon process when each worker-local
+span processor is constructed. Plugins execute in bounded, thread-local
+QuickJS runtimes with no filesystem or network host APIs. Modules must be
+self-contained and transforms must be stateless: module globals belong to a
+worker thread, not a session. If a plugin fails, that worker reports and skips
+only that plugin on subsequent spans; the remaining plugins continue to run.
+Plugins are trusted local code: although they have no host APIs, they can copy
+environment values into spans that are delivered to Braintrust. Read only the
+specific variables needed by the transform; never attach `context.env` itself.
+
 ### Additional root metadata
 
 `additional_metadata` is a JSON object merged into each traced session's root

bt-daemon/config.json.example

@@ -14,6 +14,9 @@
  "additional_metadata": {
  "team": "platform",
  "environment": "development"
- }
+ },
+ "span_plugins": [
+ "/absolute/path/to/redact.mjs"
+ ]
  }
 }

bt-daemon/docs/protocol.md

@@ -205,7 +205,8 @@ Used for version handover and by tests.
  "project_name": "codex"
  },
  "flush_mode": "fire_and_forget",
- "additional_metadata": { "…": "…" }
+ "additional_metadata": { "…": "…" },
+ "span_plugins": ["/absolute/path/redact.mjs"]
  }
 }
 ```
@@ -270,7 +271,9 @@ Field notes:
 
 Live credentials returned by the host provider are **never** written to the
 journal, logs, status, or RPC response. Envelopes journal only their non-secret
-`route`, allowing restart recovery to resolve a fresh lease.
+`route`, allowing restart recovery to resolve a fresh lease. Span plugins read
+an environment snapshot captured inside their daemon worker process; it is not
+part of the envelope or journal schema.
 
 ## Daemon lifecycle
 
@@ -337,8 +340,10 @@ profiles, organizations, and destinations while sharing one daemon.
  `$HOME/.braintrust/state/bt-daemon` on Unix, and
  `%LOCALAPPDATA%\Braintrust\bt-daemon` on Windows. On restart the daemon
  rebuilds each route's unfinished correlation state independently, replaying
- only the journal entries whose `route` matches that pipeline into a fresh
- translator. The resulting rows may be resubmitted to repair delivery
+ only the journal entries whose delivery route matches that pipeline into a
+ fresh translator. Span plugin paths are ignored for this comparison so raw
+ events can be replayed through the current plugin chain. The resulting rows
+ may be resubmitted to repair delivery
  interrupted by a crash, but their deterministic ids target the same backend
  rows and must never create duplicate spans, and a route never receives
  another route's rows. Replay streams the journal and is bounded to the

bt-daemon/src/dispatch.rs

@@ -457,7 +457,36 @@ impl SessionActor {
  &ops,
  );
  }
- match sink.emit(&ops).await {
+ let plugin_paths = ctx
+ .config
+ .as_ref()
+ .map(|config| config.span_plugins.as_slice())
+ .unwrap_or_default();
+ let mut processed = Vec::with_capacity(ops.len());
+ for op in &ops {
+ match crate::span_processor::process(
+ plugin_paths,
+ op,
+ &self.source,
+ &self.session_id,
+ ) {
+ Ok(result) => {
+ for failure in result.failures {
+ self.set_error(format!(
+ "span plugin {} failed; disabled on this worker: {}",
+ failure.path.display(),
+ failure.message
+ ));
+ }
+ processed.push(result.op);
+ }
+ Err(error) => {
+ self.set_error(format!("span plugin processor failed: {error}"));
+ processed.push(op.clone());
+ }
+ }
+ }
+ match sink.emit(&processed).await {
  Ok(n) => {
  self.counters.spans_emitted.fetch_add(n, Ordering::Relaxed);
  }
@@ -510,7 +539,7 @@ impl SessionActor {
  if !entry
  .route
  .as_ref()
- .is_some_and(|candidate| candidate.same_route(&plan.route))
+ .is_some_and(|candidate| candidate.same_replay_route(&plan.route))
  {
  continue;
  }