@braintrust/temporal 0.1.0

package/examples/temporal/mise.toml

@@ -0,0 +1,40 @@
+# Mise will automatically read and use .tool-versions files as well as this file.
+[settings]
+experimental=true
+
+[env]
+# See env.example to configure API keys.
+_.file = ".env"
+
+[tools]
+node = "20"
+temporal = "latest"
+overmind = "latest"
+
+[hooks]
+postinstall = "mise run install"
+
+[tasks.install]
+description = "Install dependencies"
+run = "pnpm install --ignore-workspace"
+
+[tasks.server]
+description = "Run temporal server and workers"
+run = "overmind s"
+
+[tasks.workflow]
+description = "Run workflow client"
+run = "pnpm exec ts-node src/client.ts"
+
+[tasks.stop]
+description = "Stop temporal server and workers"
+run = "overmind quit || true"
+
+[tasks.kill]
+description = "Force kill temporal server and workers"
+run = """
+pkill -f 'examples/temporal.*ts-node' 2>/dev/null || true
+pkill -f 'overmind.*temporal' 2>/dev/null || true
+rm -f .overmind.sock
+echo 'Server killed'
+"""

package/examples/temporal/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "temporal-example",
+  "version": "1.0.0",
+  "private": true,
+  "scripts": {
+    "build": "tsc",
+    "worker": "pnpm exec ts-node src/worker.ts",
+    "client": "pnpm exec ts-node src/client.ts"
+  },
+  "dependencies": {
+    "@braintrust/temporal": "^0.1.0",
+    "@temporalio/activity": "^1.11.0",
+    "@temporalio/client": "^1.11.0",
+    "@temporalio/common": "^1.11.0",
+    "@temporalio/worker": "^1.11.0",
+    "@temporalio/workflow": "^1.11.0",
+    "braintrust": "^2.0.0",
+    "uuid": "^9.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "@types/uuid": "^9.0.0",
+    "ts-node": "^10.9.0",
+    "typescript": "^5.0.0"
+  }
+}

package/examples/temporal/src/activities.ts

@@ -0,0 +1,42 @@
+import * as braintrust from "braintrust";
+
+export interface TaskInput {
+  value: number;
+}
+
+export async function addTen(input: TaskInput): Promise<number> {
+  console.log(`Adding 10 to ${input.value}`);
+
+  // Test child span within activity
+  const result = await braintrust.traced(
+    async (span) => {
+      span.log({
+        input: { value: input.value, operation: "add", operand: 10 },
+      });
+      await new Promise((resolve) => setTimeout(resolve, 500));
+      const sum = input.value + 10;
+      span.log({ output: sum });
+      return sum;
+    },
+    { name: "compute.addition" },
+  );
+
+  console.log(`Result: ${input.value} + 10 = ${result}`);
+  return result;
+}
+
+export async function multiplyByTwo(input: TaskInput): Promise<number> {
+  console.log(`Multiplying ${input.value} by 2`);
+  await new Promise((resolve) => setTimeout(resolve, 300));
+  const result = input.value * 2;
+  console.log(`Result: ${input.value} * 2 = ${result}`);
+  return result;
+}
+
+export async function subtractFive(input: TaskInput): Promise<number> {
+  console.log(`Subtracting 5 from ${input.value}`);
+  await new Promise((resolve) => setTimeout(resolve, 300));
+  const result = input.value - 5;
+  console.log(`Result: ${input.value} - 5 = ${result}`);
+  return result;
+}

package/examples/temporal/src/client.ts

@@ -0,0 +1,53 @@
+import { Client, Connection } from "@temporalio/client";
+import { v4 as uuid } from "uuid";
+import * as braintrust from "braintrust";
+import { BraintrustTemporalPlugin } from "@braintrust/temporal";
+import { simpleWorkflow } from "./workflows";
+import type { TaskInput } from "./activities";
+
+const TASK_QUEUE = "braintrust-example-task-queue";
+
+async function main() {
+  braintrust.initLogger({ projectName: "temporal-example" });
+
+  const connection = await Connection.connect({
+    address: "localhost:7233",
+  });
+
+  const client = new Client({
+    connection,
+    namespace: "default",
+    plugins: [new BraintrustTemporalPlugin()],
+  });
+
+  const inputData: TaskInput = { value: 5 };
+  const workflowId = `simple-workflow-${uuid().slice(0, 8)}`;
+
+  console.log(`Starting workflow with value: ${inputData.value}`);
+  console.log(`Workflow ID: ${workflowId}`);
+
+  // Wrap in a Braintrust span
+  await braintrust.traced(
+    async (span) => {
+      const handle = await client.workflow.start(simpleWorkflow, {
+        args: [inputData],
+        taskQueue: TASK_QUEUE,
+        workflowId,
+      });
+
+      const result = await handle.result();
+      span.log({ output: result });
+      console.log(`\nResult: ${result}`);
+      console.log(`\nView trace: ${span.link()}`);
+      return result;
+    },
+    { name: "temporal.client.simpleWorkflow" },
+  );
+
+  await braintrust.flush();
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/examples/temporal/src/worker.ts

@@ -0,0 +1,31 @@
+import { Worker, NativeConnection } from "@temporalio/worker";
+import * as braintrust from "braintrust";
+import { BraintrustTemporalPlugin } from "@braintrust/temporal";
+import * as activities from "./activities";
+
+const TASK_QUEUE = "braintrust-example-task-queue";
+
+async function main() {
+  braintrust.initLogger({ projectName: "temporal-example" });
+
+  const connection = await NativeConnection.connect({
+    address: "localhost:7233",
+  });
+
+  const worker = await Worker.create({
+    connection,
+    namespace: "default",
+    taskQueue: TASK_QUEUE,
+    workflowsPath: require.resolve("./workflows"),
+    activities,
+    plugins: [new BraintrustTemporalPlugin()],
+  });
+
+  console.log(`Worker started on task queue: ${TASK_QUEUE}`);
+  await worker.run();
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/examples/temporal/src/workflows.ts

@@ -0,0 +1,47 @@
+import {
+  proxyActivities,
+  sleep,
+  workflowInfo,
+  defineSignal,
+  setHandler,
+  log,
+} from "@temporalio/workflow";
+import type * as activities from "./activities";
+
+const { addTen, multiplyByTwo, subtractFive } = proxyActivities<
+  typeof activities
+>({
+  startToCloseTimeout: "10 seconds",
+});
+
+export const addSignalValue = defineSignal<[number]>("addSignalValue");
+
+export interface TaskInput {
+  value: number;
+}
+
+export async function simpleWorkflow(input: TaskInput): Promise<string> {
+  log.info(`Starting workflow with value: ${input.value}`);
+
+  let signalValue = 0;
+  setHandler(addSignalValue, (value: number) => {
+    log.info(`Received signal with value: ${value}`);
+    signalValue += value;
+  });
+
+  // Step 1: Add 10
+  const step1 = await addTen({ value: input.value });
+  log.info(`After step 1: ${step1}`);
+
+  // Step 2: Multiply by 2
+  const step2 = await multiplyByTwo({ value: step1 });
+  log.info(`After step 2: ${step2}`);
+
+  // Step 3: Subtract 5
+  const step3 = await subtractFive({ value: step2 });
+  log.info(`After step 3: ${step3}`);
+
+  const finalResult = `Complete: ${input.value} -> +10=${step1} -> *2=${step2} -> -5=${step3} + signal(${signalValue}) = ${step3 + signalValue}`;
+  log.info(finalResult);
+  return finalResult;
+}

package/examples/temporal/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2021",
+    "module": "commonjs",
+    "lib": ["ES2021"],
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "declaration": true
+  },
+  "include": ["src/**/*"]
+}

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "@braintrust/temporal",
+  "version": "0.1.0",
+  "description": "SDK for integrating Braintrust with Temporal",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "module": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    },
+    "./workflow-interceptors": {
+      "types": "./dist/workflow-interceptors.d.ts",
+      "import": "./dist/workflow-interceptors.mjs",
+      "module": "./dist/workflow-interceptors.mjs",
+      "require": "./dist/workflow-interceptors.js"
+    }
+  },
+  "scripts": {
+    "build": "tsup",
+    "watch": "tsup --watch",
+    "clean": "rm -r dist/*",
+    "test": "vitest run"
+  },
+  "author": "Braintrust Data Inc.",
+  "license": "MIT",
+  "devDependencies": {
+    "@temporalio/activity": "^1.14.1",
+    "@temporalio/client": "^1.14.1",
+    "@temporalio/common": "^1.14.1",
+    "@temporalio/worker": "^1.14.1",
+    "@temporalio/workflow": "^1.14.1",
+    "@types/node": "^22.15.21",
+    "braintrust": "workspace:*",
+    "tsup": "^8.5.0",
+    "typescript": "5.5.4",
+    "vitest": "^2.1.9"
+  },
+  "peerDependencies": {
+    "@temporalio/activity": ">=1.11.0",
+    "@temporalio/client": ">=1.11.0",
+    "@temporalio/common": ">=1.11.0",
+    "@temporalio/worker": ">=1.11.0",
+    "@temporalio/workflow": ">=1.11.0",
+    "braintrust": ">=2.0.0"
+  },
+  "peerDependenciesMeta": {
+    "braintrust": {
+      "optional": false
+    },
+    "@temporalio/activity": {
+      "optional": false
+    },
+    "@temporalio/client": {
+      "optional": false
+    },
+    "@temporalio/common": {
+      "optional": false
+    },
+    "@temporalio/worker": {
+      "optional": false
+    },
+    "@temporalio/workflow": {
+      "optional": false
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,50 @@
+/**
+ * Braintrust integration for Temporal workflows and activities.
+ *
+ * This module provides a plugin that automatically creates Braintrust spans
+ * for Temporal workflows and activities, with proper parent-child relationships
+ * across distributed workers.
+ *
+ * @example
+ * ```typescript
+ * import { Client, Connection } from "@temporalio/client";
+ * import { Worker } from "@temporalio/worker";
+ * import * as braintrust from "braintrust";
+ * import { createBraintrustTemporalPlugin } from "@braintrust/temporal";
+ *
+ * // Initialize Braintrust logger
+ * braintrust.initLogger({ projectName: "my-project" });
+ *
+ * // Create the plugin
+ * const braintrustPlugin = createBraintrustTemporalPlugin();
+ *
+ * // Create client with the plugin
+ * const client = new Client({
+ *   connection: await Connection.connect(),
+ *   plugins: [braintrustPlugin],
+ * });
+ *
+ * // Create worker with the plugin
+ * const worker = await Worker.create({
+ *   taskQueue: "my-queue",
+ *   workflowsPath: require.resolve("./workflows"),
+ *   activities,
+ *   plugins: [braintrustPlugin],
+ * });
+ * ```
+ *
+ * The resulting trace will show:
+ * ```
+ * trigger-workflow (client span)
+ *   └── temporal.workflow.myWorkflow
+ *         ├── temporal.activity.activityOne
+ *         └── temporal.activity.activityTwo
+ * ```
+ */
+
+export {
+  BraintrustTemporalPlugin,
+  createBraintrustTemporalPlugin,
+} from "./plugin";
+
+export type { BraintrustSinks } from "./sinks";

package/src/interceptors.ts

@@ -0,0 +1,184 @@
+import type { Context } from "@temporalio/activity";
+import type {
+  ActivityInboundCallsInterceptor,
+  ActivityExecuteInput,
+  Next,
+  ActivityInterceptors,
+} from "@temporalio/worker";
+import type { WorkflowClientInterceptor } from "@temporalio/client";
+import { defaultPayloadConverter } from "@temporalio/common";
+import * as braintrust from "braintrust";
+import { SpanComponentsV3 } from "braintrust/util";
+import { getWorkflowSpanExport } from "./sinks";
+import {
+  BRAINTRUST_SPAN_HEADER,
+  BRAINTRUST_WORKFLOW_SPAN_ID_HEADER,
+  deserializeHeaderValue,
+} from "./utils";
+
+/**
+ * Create a client interceptor that propagates Braintrust span context to workflows.
+ * Use this when creating a Temporal Client to enable trace context propagation.
+ */
+export function createBraintrustClientInterceptor(): WorkflowClientInterceptor {
+  return {
+    async start(input, next) {
+      const span = braintrust.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 = braintrust.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);
+    },
+  };
+}
+
+/**
+ * Activity interceptor that creates Braintrust spans for activity executions.
+ */
+class BraintrustActivityInterceptor implements ActivityInboundCallsInterceptor {
+  constructor(private ctx: Context) {}
+
+  async execute(
+    input: ActivityExecuteInput,
+    next: Next<ActivityInboundCallsInterceptor, "execute">,
+  ): Promise<unknown> {
+    const info = this.ctx.info;
+    const runId = info.workflowExecution.runId;
+
+    // Try to get workflow span export - first check local Map, then headers
+    let parent: string | undefined;
+
+    // Check if we have the workflow span export locally (same worker as workflow)
+    const spanExportPromise = getWorkflowSpanExport(runId);
+    if (spanExportPromise) {
+      try {
+        parent = await spanExportPromise;
+      } catch {
+        // Ignore errors, fall through to header check
+      }
+    }
+
+    // For cross-worker activities: construct parent from workflow span ID + client context
+    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;
+
+          // We can only construct a workflow parent if we have:
+          // 1. Tracing context (root_span_id)
+          // 2. Object metadata (object_id or compute_object_metadata_args)
+          const hasTracingContext = !!clientData.root_span_id;
+          const hasObjectMetadata =
+            !!clientData.object_id || !!clientData.compute_object_metadata_args;
+
+          if (hasTracingContext && hasObjectMetadata) {
+            // Construct workflow parent with the workflow's span ID
+            // IMPORTANT: row_id must match span_id for the parent span
+            // Must provide EITHER object_id OR compute_object_metadata_args, not both
+            const workflowComponents = new SpanComponentsV3({
+              object_type: clientData.object_type,
+              object_id: clientData.object_id || undefined,
+              compute_object_metadata_args: clientData.object_id
+                ? undefined
+                : clientData.compute_object_metadata_args || undefined,
+              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 {
+            // Client context doesn't have root_span_id, use it directly
+            parent = clientContext;
+          }
+        } catch {
+          // Fall back to client context if parsing fails
+          parent = clientContext;
+        }
+      } else if (clientContext) {
+        // No workflow span ID, use client context directly
+        parent = clientContext;
+      }
+    }
+
+    const span = braintrust.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 braintrust.withCurrent(span, () => next(input));
+      span.log({ output: result });
+      span.end();
+      return result;
+    } catch (e) {
+      span.log({ error: String(e) });
+      span.end();
+      throw e;
+    }
+  }
+}
+
+/**
+ * Create an activity interceptor factory for use with Worker.create().
+ * This factory creates BraintrustActivityInterceptor instances for each activity.
+ */
+export function createBraintrustActivityInterceptor(
+  ctx: Context,
+): ActivityInterceptors {
+  return {
+    inbound: new BraintrustActivityInterceptor(ctx),
+  };
+}

package/src/plugin.ts

@@ -0,0 +1,128 @@
+import type { ClientPlugin, ClientOptions } from "@temporalio/client";
+import type { WorkerPlugin, WorkerOptions } from "@temporalio/worker";
+import {
+  createBraintrustClientInterceptor,
+  createBraintrustActivityInterceptor,
+} from "./interceptors";
+import { createBraintrustSinks } from "./sinks";
+
+/**
+ * A Braintrust plugin for Temporal that automatically instruments
+ * workflows and activities with tracing spans.
+ *
+ * This plugin implements both ClientPlugin and WorkerPlugin interfaces,
+ * so it can be used with both Temporal Client and Worker.
+ *
+ * @example
+ * ```typescript
+ * import { Client, Connection } from "@temporalio/client";
+ * import { Worker } from "@temporalio/worker";
+ * import * as braintrust from "braintrust";
+ * import { BraintrustTemporalPlugin } from "@braintrust/temporal";
+ *
+ * // Initialize Braintrust logger
+ * braintrust.initLogger({ projectName: "my-project" });
+ *
+ * // Create client with the plugin
+ * const client = new Client({
+ *   connection: await Connection.connect(),
+ *   plugins: [new BraintrustTemporalPlugin()],
+ * });
+ *
+ * // Create worker with the plugin
+ * const worker = await Worker.create({
+ *   taskQueue: "my-queue",
+ *   workflowsPath: require.resolve("./workflows"),
+ *   activities,
+ *   plugins: [new BraintrustTemporalPlugin()],
+ * });
+ * ```
+ */
+export class BraintrustTemporalPlugin implements ClientPlugin, WorkerPlugin {
+  get name(): string {
+    return "braintrust";
+  }
+
+  /**
+   * Configure the Temporal Client with Braintrust interceptors.
+   * Adds the client interceptor for propagating span context to workflows.
+   */
+  configureClient(
+    options: Omit<ClientOptions, "plugins">,
+  ): Omit<ClientOptions, "plugins"> {
+    const existing = options.interceptors?.workflow;
+    const braintrustInterceptor = createBraintrustClientInterceptor();
+
+    // workflow can be an array or an object with named interceptors
+    let workflow: typeof existing;
+    if (Array.isArray(existing)) {
+      workflow = [...existing, braintrustInterceptor];
+    } else if (existing) {
+      // It's a WorkflowClientInterceptors object, merge our interceptor
+      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: WorkerOptions): WorkerOptions {
+    const existingActivityInterceptors = options.interceptors?.activity ?? [];
+    const existingWorkflowModules = options.interceptors?.workflowModules ?? [];
+    const existingSinks = options.sinks ?? {};
+
+    const braintrustSinks = createBraintrustSinks();
+
+    // Resolve the workflow interceptors module path
+    // This needs to be resolved at runtime to get the actual file path
+    const workflowInterceptorsPath = require.resolve(
+      "@braintrust/temporal/workflow-interceptors",
+    );
+
+    return {
+      ...options,
+      interceptors: {
+        ...options.interceptors,
+        activity: [
+          ...existingActivityInterceptors,
+          createBraintrustActivityInterceptor,
+        ],
+        workflowModules: [...existingWorkflowModules, workflowInterceptorsPath],
+      },
+      sinks: {
+        ...existingSinks,
+        ...braintrustSinks,
+      },
+    };
+  }
+}
+
+/**
+ * Create a Braintrust plugin for Temporal.
+ *
+ * @example
+ * ```typescript
+ * const plugin = createBraintrustTemporalPlugin();
+ *
+ * const client = new Client({ plugins: [plugin] });
+ * const worker = await Worker.create({ plugins: [plugin], ... });
+ * ```
+ */
+export function createBraintrustTemporalPlugin(): BraintrustTemporalPlugin {
+  return new BraintrustTemporalPlugin();
+}