@braintrust/temporal 0.1.0

package/dist/index.mjs

@@ -0,0 +1,257 @@
+import {
+  BRAINTRUST_SPAN_HEADER,
+  BRAINTRUST_WORKFLOW_SPAN_ID_HEADER,
+  __require,
+  deserializeHeaderValue
+} from "./chunk-KT66NY2E.mjs";
+
+// src/interceptors.ts
+import { defaultPayloadConverter } from "@temporalio/common";
+import * as braintrust2 from "braintrust";
+import { SpanComponentsV3 } from "braintrust/util";
+
+// src/sinks.ts
+import * as braintrust from "braintrust";
+var workflowSpans = /* @__PURE__ */ new Map();
+var workflowSpanExports = /* @__PURE__ */ new Map();
+function getWorkflowSpanExport(runId) {
+  return workflowSpanExports.get(runId);
+}
+function createBraintrustSinks() {
+  return {
+    braintrust: {
+      workflowStarted: {
+        fn: (info, parentContext, workflowSpanId) => {
+          const span = braintrust.startSpan({
+            name: `temporal.workflow.${info.workflowType}`,
+            spanAttributes: { type: "task" },
+            parent: parentContext,
+            spanId: workflowSpanId,
+            event: {
+              metadata: {
+                "temporal.workflow_type": info.workflowType,
+                "temporal.workflow_id": info.workflowId,
+                "temporal.run_id": info.runId
+              }
+            }
+          });
+          workflowSpans.set(info.runId, span);
+          workflowSpanExports.set(info.runId, span.export());
+        },
+        callDuringReplay: false
+      },
+      workflowCompleted: {
+        fn: (info, error) => {
+          const span = workflowSpans.get(info.runId);
+          if (span) {
+            if (error) {
+              span.log({ error });
+            }
+            span.end();
+            workflowSpans.delete(info.runId);
+            workflowSpanExports.delete(info.runId);
+          }
+        },
+        callDuringReplay: false
+      }
+    }
+  };
+}
+
+// src/interceptors.ts
+function createBraintrustClientInterceptor() {
+  return {
+    async start(input, next) {
+      const span = braintrust2.currentSpan();
+      if (span) {
+        const exported = await span.export();
+        if (exported) {
+          const payload = defaultPayloadConverter.toPayload(exported);
+          if (payload) {
+            return next({
+              ...input,
+              headers: {
+                ...input.headers,
+                [BRAINTRUST_SPAN_HEADER]: payload
+              }
+            });
+          }
+        }
+      }
+      return next(input);
+    },
+    async signal(input, next) {
+      return next(input);
+    },
+    async signalWithStart(input, next) {
+      const span = braintrust2.currentSpan();
+      if (span) {
+        const exported = await span.export();
+        if (exported) {
+          const payload = defaultPayloadConverter.toPayload(exported);
+          if (payload) {
+            return next({
+              ...input,
+              headers: {
+                ...input.headers,
+                [BRAINTRUST_SPAN_HEADER]: payload
+              }
+            });
+          }
+        }
+      }
+      return next(input);
+    }
+  };
+}
+var BraintrustActivityInterceptor = class {
+  constructor(ctx) {
+    this.ctx = ctx;
+  }
+  async execute(input, next) {
+    const info = this.ctx.info;
+    const runId = info.workflowExecution.runId;
+    let parent;
+    const spanExportPromise = getWorkflowSpanExport(runId);
+    if (spanExportPromise) {
+      try {
+        parent = await spanExportPromise;
+      } catch {
+      }
+    }
+    if (!parent && input.headers) {
+      const workflowSpanId = deserializeHeaderValue(
+        input.headers[BRAINTRUST_WORKFLOW_SPAN_ID_HEADER]
+      );
+      const clientContext = deserializeHeaderValue(
+        input.headers[BRAINTRUST_SPAN_HEADER]
+      );
+      if (workflowSpanId && clientContext) {
+        try {
+          const clientComponents = SpanComponentsV3.fromStr(clientContext);
+          const clientData = clientComponents.data;
+          const hasTracingContext = !!clientData.root_span_id;
+          const hasObjectMetadata = !!clientData.object_id || !!clientData.compute_object_metadata_args;
+          if (hasTracingContext && hasObjectMetadata) {
+            const workflowComponents = new SpanComponentsV3({
+              object_type: clientData.object_type,
+              object_id: clientData.object_id || void 0,
+              compute_object_metadata_args: clientData.object_id ? void 0 : clientData.compute_object_metadata_args || void 0,
+              propagated_event: clientData.propagated_event,
+              row_id: workflowSpanId,
+              // Use workflow's row_id, not client's
+              span_id: workflowSpanId,
+              // Use workflow's span_id, not client's
+              root_span_id: clientData.root_span_id
+              // Keep same trace
+            });
+            parent = workflowComponents.toStr();
+          } else {
+            parent = clientContext;
+          }
+        } catch {
+          parent = clientContext;
+        }
+      } else if (clientContext) {
+        parent = clientContext;
+      }
+    }
+    const span = braintrust2.startSpan({
+      name: `temporal.activity.${info.activityType}`,
+      spanAttributes: { type: "task" },
+      parent,
+      event: {
+        metadata: {
+          "temporal.activity_type": info.activityType,
+          "temporal.activity_id": info.activityId,
+          "temporal.workflow_id": info.workflowExecution.workflowId,
+          "temporal.workflow_run_id": runId
+        }
+      }
+    });
+    try {
+      const result = await braintrust2.withCurrent(span, () => next(input));
+      span.log({ output: result });
+      span.end();
+      return result;
+    } catch (e) {
+      span.log({ error: String(e) });
+      span.end();
+      throw e;
+    }
+  }
+};
+function createBraintrustActivityInterceptor(ctx) {
+  return {
+    inbound: new BraintrustActivityInterceptor(ctx)
+  };
+}
+
+// src/plugin.ts
+var BraintrustTemporalPlugin = class {
+  get name() {
+    return "braintrust";
+  }
+  /**
+   * Configure the Temporal Client with Braintrust interceptors.
+   * Adds the client interceptor for propagating span context to workflows.
+   */
+  configureClient(options) {
+    const existing = options.interceptors?.workflow;
+    const braintrustInterceptor = createBraintrustClientInterceptor();
+    let workflow;
+    if (Array.isArray(existing)) {
+      workflow = [...existing, braintrustInterceptor];
+    } else if (existing) {
+      workflow = {
+        ...existing,
+        ...braintrustInterceptor
+      };
+    } else {
+      workflow = [braintrustInterceptor];
+    }
+    return {
+      ...options,
+      interceptors: {
+        ...options.interceptors,
+        workflow
+      }
+    };
+  }
+  /**
+   * Configure the Temporal Worker with Braintrust interceptors and sinks.
+   * Adds the activity interceptor for creating spans, the sinks for workflow spans,
+   * and the workflow interceptor modules for bundling.
+   */
+  configureWorker(options) {
+    const existingActivityInterceptors = options.interceptors?.activity ?? [];
+    const existingWorkflowModules = options.interceptors?.workflowModules ?? [];
+    const existingSinks = options.sinks ?? {};
+    const braintrustSinks = createBraintrustSinks();
+    const workflowInterceptorsPath = __require.resolve(
+      "@braintrust/temporal/workflow-interceptors"
+    );
+    return {
+      ...options,
+      interceptors: {
+        ...options.interceptors,
+        activity: [
+          ...existingActivityInterceptors,
+          createBraintrustActivityInterceptor
+        ],
+        workflowModules: [...existingWorkflowModules, workflowInterceptorsPath]
+      },
+      sinks: {
+        ...existingSinks,
+        ...braintrustSinks
+      }
+    };
+  }
+};
+function createBraintrustTemporalPlugin() {
+  return new BraintrustTemporalPlugin();
+}
+export {
+  BraintrustTemporalPlugin,
+  createBraintrustTemporalPlugin
+};

package/dist/workflow-interceptors.d.mts

@@ -0,0 +1,13 @@
+import { WorkflowInterceptorsFactory } from '@temporalio/workflow';
+
+/**
+ * Workflow interceptors for Braintrust tracing.
+ *
+ * IMPORTANT: This module is loaded into the Temporal workflow isolate.
+ * It cannot import Node.js modules or access external state directly.
+ * Communication with the outside world is done via sinks.
+ */
+
+declare const interceptors: WorkflowInterceptorsFactory;
+
+export { interceptors };

package/dist/workflow-interceptors.d.ts

@@ -0,0 +1,13 @@
+import { WorkflowInterceptorsFactory } from '@temporalio/workflow';
+
+/**
+ * Workflow interceptors for Braintrust tracing.
+ *
+ * IMPORTANT: This module is loaded into the Temporal workflow isolate.
+ * It cannot import Node.js modules or access external state directly.
+ * Communication with the outside world is done via sinks.
+ */
+
+declare const interceptors: WorkflowInterceptorsFactory;
+
+export { interceptors };

package/dist/workflow-interceptors.js

@@ -0,0 +1,134 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/workflow-interceptors.ts
+var workflow_interceptors_exports = {};
+__export(workflow_interceptors_exports, {
+  interceptors: () => interceptors
+});
+module.exports = __toCommonJS(workflow_interceptors_exports);
+var import_workflow = require("@temporalio/workflow");
+
+// src/utils.ts
+var BRAINTRUST_SPAN_HEADER = "_braintrust-span";
+var BRAINTRUST_WORKFLOW_SPAN_HEADER = "_braintrust-workflow-span";
+var BRAINTRUST_WORKFLOW_SPAN_ID_HEADER = "_braintrust-workflow-span-id";
+function serializeHeaderValue(value) {
+  return {
+    metadata: {
+      encoding: new TextEncoder().encode("json/plain")
+    },
+    data: new TextEncoder().encode(JSON.stringify(value))
+  };
+}
+function deserializeHeaderValue(payload) {
+  if (!payload?.data) {
+    return void 0;
+  }
+  try {
+    const decoded = new TextDecoder().decode(payload.data);
+    return JSON.parse(decoded);
+  } catch {
+    return void 0;
+  }
+}
+
+// src/workflow-interceptors.ts
+var { braintrust } = (0, import_workflow.proxySinks)();
+var BraintrustWorkflowInboundInterceptor = class {
+  constructor(state) {
+    this.state = state;
+  }
+  async execute(input, next) {
+    const parentContext = input.headers ? deserializeHeaderValue(input.headers[BRAINTRUST_SPAN_HEADER]) : void 0;
+    this.state.parentContext = parentContext;
+    this.state.spanId = (0, import_workflow.uuid4)();
+    braintrust.workflowStarted(parentContext, this.state.spanId);
+    try {
+      const result = await next(input);
+      braintrust.workflowCompleted();
+      return result;
+    } catch (e) {
+      braintrust.workflowCompleted(e instanceof Error ? e.message : String(e));
+      throw e;
+    }
+  }
+};
+var BraintrustWorkflowOutboundInterceptor = class {
+  constructor(state) {
+    this.state = state;
+  }
+  getHeaders() {
+    const info = (0, import_workflow.workflowInfo)();
+    const headers = {};
+    headers[BRAINTRUST_WORKFLOW_SPAN_HEADER] = serializeHeaderValue(info.runId);
+    if (this.state.spanId) {
+      headers[BRAINTRUST_WORKFLOW_SPAN_ID_HEADER] = serializeHeaderValue(
+        this.state.spanId
+      );
+    }
+    if (this.state.parentContext) {
+      headers[BRAINTRUST_SPAN_HEADER] = serializeHeaderValue(
+        this.state.parentContext
+      );
+    }
+    return headers;
+  }
+  scheduleActivity(input, next) {
+    return next({
+      ...input,
+      headers: {
+        ...input.headers,
+        ...this.getHeaders()
+      }
+    });
+  }
+  scheduleLocalActivity(input, next) {
+    return next({
+      ...input,
+      headers: {
+        ...input.headers,
+        ...this.getHeaders()
+      }
+    });
+  }
+  startChildWorkflowExecution(input, next) {
+    return next({
+      ...input,
+      headers: {
+        ...input.headers,
+        ...this.getHeaders()
+      }
+    });
+  }
+};
+var interceptors = () => {
+  const state = {
+    parentContext: void 0,
+    spanId: void 0
+  };
+  return {
+    inbound: [new BraintrustWorkflowInboundInterceptor(state)],
+    outbound: [new BraintrustWorkflowOutboundInterceptor(state)]
+  };
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  interceptors
+});

package/dist/workflow-interceptors.mjs

@@ -0,0 +1,95 @@
+import {
+  BRAINTRUST_SPAN_HEADER,
+  BRAINTRUST_WORKFLOW_SPAN_HEADER,
+  BRAINTRUST_WORKFLOW_SPAN_ID_HEADER,
+  deserializeHeaderValue,
+  serializeHeaderValue
+} from "./chunk-KT66NY2E.mjs";
+
+// src/workflow-interceptors.ts
+import {
+  proxySinks,
+  workflowInfo,
+  uuid4
+} from "@temporalio/workflow";
+var { braintrust } = proxySinks();
+var BraintrustWorkflowInboundInterceptor = class {
+  constructor(state) {
+    this.state = state;
+  }
+  async execute(input, next) {
+    const parentContext = input.headers ? deserializeHeaderValue(input.headers[BRAINTRUST_SPAN_HEADER]) : void 0;
+    this.state.parentContext = parentContext;
+    this.state.spanId = uuid4();
+    braintrust.workflowStarted(parentContext, this.state.spanId);
+    try {
+      const result = await next(input);
+      braintrust.workflowCompleted();
+      return result;
+    } catch (e) {
+      braintrust.workflowCompleted(e instanceof Error ? e.message : String(e));
+      throw e;
+    }
+  }
+};
+var BraintrustWorkflowOutboundInterceptor = class {
+  constructor(state) {
+    this.state = state;
+  }
+  getHeaders() {
+    const info = workflowInfo();
+    const headers = {};
+    headers[BRAINTRUST_WORKFLOW_SPAN_HEADER] = serializeHeaderValue(info.runId);
+    if (this.state.spanId) {
+      headers[BRAINTRUST_WORKFLOW_SPAN_ID_HEADER] = serializeHeaderValue(
+        this.state.spanId
+      );
+    }
+    if (this.state.parentContext) {
+      headers[BRAINTRUST_SPAN_HEADER] = serializeHeaderValue(
+        this.state.parentContext
+      );
+    }
+    return headers;
+  }
+  scheduleActivity(input, next) {
+    return next({
+      ...input,
+      headers: {
+        ...input.headers,
+        ...this.getHeaders()
+      }
+    });
+  }
+  scheduleLocalActivity(input, next) {
+    return next({
+      ...input,
+      headers: {
+        ...input.headers,
+        ...this.getHeaders()
+      }
+    });
+  }
+  startChildWorkflowExecution(input, next) {
+    return next({
+      ...input,
+      headers: {
+        ...input.headers,
+        ...this.getHeaders()
+      }
+    });
+  }
+};
+var interceptors = () => {
+  const state = {
+    parentContext: void 0,
+    spanId: void 0
+  };
+  return {
+    inbound: [new BraintrustWorkflowInboundInterceptor(state)],
+    outbound: [new BraintrustWorkflowOutboundInterceptor(state)]
+  };
+};
+export {
+  interceptors
+};

package/examples/temporal/.env.example

@@ -0,0 +1,2 @@
+# Braintrust API key for tracing
+BRAINTRUST_API_KEY=your-api-key-here

package/examples/temporal/Procfile

@@ -0,0 +1,4 @@
+server: temporal server start-dev
+worker1: pnpm run worker
+worker2: pnpm run worker
+worker3: pnpm run worker

package/examples/temporal/README.md

@@ -0,0 +1,183 @@
+# Temporal + Braintrust Tracing Example
+
+This example demonstrates how to integrate Braintrust tracing with Temporal workflows and activities.
+
+## Prerequisites
+
+- [mise](https://mise.jdx.dev/) (recommended) - automatically installs all dependencies
+- OR manually install:
+  - Node.js 20+
+  - `pnpm`
+  - Temporal CLI (`temporal`)
+  - Optional: [`overmind`](https://github.com/DarthSim/overmind) (only if you want to use the included `Procfile`)
+
+### Option 1: Using mise (recommended)
+
+[mise](https://mise.jdx.dev/) will automatically install and manage all required tools (Node.js, Temporal CLI, overmind, and dependencies):
+
+**Install mise:**
+
+```bash
+# macOS/Linux
+curl https://mise.run | sh
+
+# Or using Homebrew
+brew install mise
+```
+
+**Setup and run:**
+
+```bash
+# Copy and configure environment
+cp .env.example .env
+# Edit .env with your BRAINTRUST_API_KEY
+
+# mise will automatically install tools and dependencies
+mise run server  # Start temporal server and workers
+
+# In another terminal:
+mise run workflow  # Run the workflow client
+```
+
+**Available mise tasks:**
+
+```bash
+mise run install   # Install dependencies
+mise run server    # Run temporal server and workers
+mise run workflow  # Run workflow client
+mise run stop      # Stop temporal server and workers
+mise run kill      # Force kill all processes
+```
+
+### Option 2: Manual installation
+
+#### Installing Temporal CLI
+
+The Temporal CLI is required to run the local Temporal server:
+
+**macOS:**
+
+```bash
+brew install temporal
+```
+
+**Linux:**
+
+```bash
+# Using Homebrew
+brew install temporal
+
+# Or using curl
+curl -sSf https://temporal.download/cli.sh | sh
+```
+
+**Windows:**
+
+```powershell
+# Using Scoop
+scoop install temporal
+
+# Or download from releases
+# https://github.com/temporalio/cli/releases
+```
+
+Verify the installation:
+
+```bash
+temporal --version
+```
+
+#### Installing overmind (optional)
+
+Overmind is a process manager that makes it easy to run multiple services together. If you want to use `overmind start` to run everything at once, install it for your platform:
+
+**macOS:**
+
+```bash
+brew install overmind
+```
+
+**Linux:**
+
+```bash
+brew install overmind
+
+# Or download from releases
+# https://github.com/DarthSim/overmind/releases
+```
+
+**Windows:**
+Overmind is not officially supported on Windows. Use the manual approach below instead.
+
+## Setup
+
+```bash
+# Copy and configure environment
+cp .env.example .env
+# Edit .env with your BRAINTRUST_API_KEY
+
+# Install dependencies
+pnpm install
+```
+
+## Running the Example
+
+### Option 1: Using overmind
+
+Start the temporal server and workers together:
+
+```bash
+overmind start
+```
+
+Then in another terminal, run the workflow:
+
+```bash
+pnpm run client
+```
+
+### Option 2: Manual
+
+1. Start the Temporal server:
+
+```bash
+temporal server start-dev
+```
+
+2. Start the worker:
+
+```bash
+pnpm run worker
+```
+
+3. Run the client:
+
+```bash
+pnpm run client
+
+# Or with a signal:
+pnpm run client -- --signal
+```
+
+## What Gets Traced
+
+- **Client span**: Wraps the workflow execution call
+- **Workflow span**: Created via sinks when the workflow starts
+- **Activity spans**: Created for each activity execution with parent linking
+
+The trace hierarchy looks like:
+
+```
+Client span ("example.temporal.workflow")
+  └── Workflow span ("temporal.workflow.simpleWorkflow")
+        └── Activity span ("temporal.activity.addTen")
+        └── Activity span ("temporal.activity.multiplyByTwo")
+        └── Activity span ("temporal.activity.subtractFive")
+```
+
+## How It Works
+
+1. **Client interceptor**: Captures the current Braintrust span context and adds it to workflow headers
+2. **Workflow interceptor**: Extracts parent context from headers and creates a workflow span via sinks
+3. **Sinks**: Allow the workflow isolate to call into Node.js to create spans (with `callDuringReplay: false`)
+4. **Activity interceptor**: Creates spans for each activity, using the workflow span as parent