@braintrust/temporal 0.1.0

package/README.md

@@ -0,0 +1,54 @@
+# @braintrust/temporal
+
+SDK for integrating [Braintrust](https://braintrust.dev) tracing with [Temporal](https://temporal.io/) workflows and activities.
+
+## Installation
+
+This package has peer dependencies that you must install alongside it:
+
+```bash
+npm install @braintrust/temporal braintrust @temporalio/client @temporalio/worker @temporalio/workflow @temporalio/activity @temporalio/common
+# or
+yarn add @braintrust/temporal braintrust @temporalio/client @temporalio/worker @temporalio/workflow @temporalio/activity @temporalio/common
+# or
+pnpm add @braintrust/temporal braintrust @temporalio/client @temporalio/worker @temporalio/workflow @temporalio/activity @temporalio/common
+```
+
+## Usage
+
+Initialize Braintrust, then install the plugin on both the Temporal client and worker.
+
+```typescript
+import { Client, Connection } from "@temporalio/client";
+import { Worker } from "@temporalio/worker";
+import * as braintrust from "braintrust";
+import { BraintrustTemporalPlugin } from "@braintrust/temporal";
+
+braintrust.initLogger({ projectName: "my-project" });
+
+const plugin = new BraintrustTemporalPlugin();
+
+const client = new Client({
+  connection: await Connection.connect(),
+  plugins: [plugin],
+});
+
+const worker = await Worker.create({
+  taskQueue: "my-queue",
+  workflowsPath: require.resolve("./workflows"),
+  activities,
+  plugins: [plugin],
+});
+```
+
+## Workflow interceptors
+
+This package also exports workflow interceptors that are loaded into the Temporal workflow isolate:
+
+- `@braintrust/temporal/workflow-interceptors`
+
+The `BraintrustTemporalPlugin` automatically configures `workflowModules` to include these interceptors when used on a worker.
+
+## Example
+
+See the example app in `examples/temporal`.

package/dist/chunk-KT66NY2E.mjs

@@ -0,0 +1,39 @@
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined") return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+
+// 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;
+  }
+}
+
+export {
+  __require,
+  BRAINTRUST_SPAN_HEADER,
+  BRAINTRUST_WORKFLOW_SPAN_HEADER,
+  BRAINTRUST_WORKFLOW_SPAN_ID_HEADER,
+  serializeHeaderValue,
+  deserializeHeaderValue
+};

package/dist/index.d.mts

@@ -0,0 +1,71 @@
+import { ClientPlugin, ClientOptions } from '@temporalio/client';
+import { WorkerPlugin, WorkerOptions } from '@temporalio/worker';
+import { Sinks } from '@temporalio/workflow';
+
+/**
+ * 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()],
+ * });
+ * ```
+ */
+declare class BraintrustTemporalPlugin implements ClientPlugin, WorkerPlugin {
+    get name(): string;
+    /**
+     * 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">;
+    /**
+     * 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;
+}
+/**
+ * Create a Braintrust plugin for Temporal.
+ *
+ * @example
+ * ```typescript
+ * const plugin = createBraintrustTemporalPlugin();
+ *
+ * const client = new Client({ plugins: [plugin] });
+ * const worker = await Worker.create({ plugins: [plugin], ... });
+ * ```
+ */
+declare function createBraintrustTemporalPlugin(): BraintrustTemporalPlugin;
+
+interface BraintrustSinks extends Sinks {
+    braintrust: {
+        workflowStarted(parentContext?: string, workflowSpanId?: string): void;
+        workflowCompleted(error?: string): void;
+    };
+}
+
+export { type BraintrustSinks, BraintrustTemporalPlugin, createBraintrustTemporalPlugin };

package/dist/index.d.ts

@@ -0,0 +1,71 @@
+import { ClientPlugin, ClientOptions } from '@temporalio/client';
+import { WorkerPlugin, WorkerOptions } from '@temporalio/worker';
+import { Sinks } from '@temporalio/workflow';
+
+/**
+ * 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()],
+ * });
+ * ```
+ */
+declare class BraintrustTemporalPlugin implements ClientPlugin, WorkerPlugin {
+    get name(): string;
+    /**
+     * 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">;
+    /**
+     * 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;
+}
+/**
+ * Create a Braintrust plugin for Temporal.
+ *
+ * @example
+ * ```typescript
+ * const plugin = createBraintrustTemporalPlugin();
+ *
+ * const client = new Client({ plugins: [plugin] });
+ * const worker = await Worker.create({ plugins: [plugin], ... });
+ * ```
+ */
+declare function createBraintrustTemporalPlugin(): BraintrustTemporalPlugin;
+
+interface BraintrustSinks extends Sinks {
+    braintrust: {
+        workflowStarted(parentContext?: string, workflowSpanId?: string): void;
+        workflowCompleted(error?: string): void;
+    };
+}
+
+export { type BraintrustSinks, BraintrustTemporalPlugin, createBraintrustTemporalPlugin };

package/dist/index.js

@@ -0,0 +1,301 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+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 __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  BraintrustTemporalPlugin: () => BraintrustTemporalPlugin,
+  createBraintrustTemporalPlugin: () => createBraintrustTemporalPlugin
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/interceptors.ts
+var import_common = require("@temporalio/common");
+var braintrust2 = __toESM(require("braintrust"));
+var import_util = require("braintrust/util");
+
+// src/sinks.ts
+var braintrust = __toESM(require("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/utils.ts
+var BRAINTRUST_SPAN_HEADER = "_braintrust-span";
+var BRAINTRUST_WORKFLOW_SPAN_ID_HEADER = "_braintrust-workflow-span-id";
+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/interceptors.ts
+function createBraintrustClientInterceptor() {
+  return {
+    async start(input, next) {
+      const span = braintrust2.currentSpan();
+      if (span) {
+        const exported = await span.export();
+        if (exported) {
+          const payload = import_common.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 = import_common.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 = import_util.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 import_util.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();
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  BraintrustTemporalPlugin,
+  createBraintrustTemporalPlugin
+});