@temporalio/langsmith 1.20.0

package/src/client-interceptor.ts

@@ -0,0 +1,109 @@
+/**
+ * Client-side LangSmith interceptor. Execution ops (`start`) emit a peer marker
+ * and propagate the **ambient** context (the remote run is a sibling); messaging
+ * ops (`signal`, `query`, `update`, …) emit the marker and propagate the
+ * **marker** context (the remote handler nests under it).
+ *
+ * @module
+ */
+
+import { isTracingEnabled } from 'langsmith';
+import type { RunTree } from 'langsmith/run_trees';
+import { getCurrentRunTree } from 'langsmith/traceable';
+import type { WorkflowClientInterceptor, WorkflowStartInput } from '@temporalio/client';
+
+import { withContextHeader } from './propagation';
+import {
+  RUN_TYPE,
+  buildRunTree,
+  emitMarkerRun,
+  queryWorkflowRunName,
+  runHeaders,
+  signalWithStartRunName,
+  signalWorkflowRunName,
+  startUpdateWithStartRunName,
+  startWorkflowRunName,
+  startWorkflowUpdateRunName,
+} from './run-tree';
+import type { EmitterConfig } from './sinks';
+
+type NextFn<I, O> = (input: I) => Promise<O>;
+
+export function createClientInterceptor(config: EmitterConfig): WorkflowClientInterceptor {
+  const peerStart = async <I extends { headers: WorkflowStartInput['headers'] }, O>(
+    input: I,
+    next: NextFn<I, O>,
+    name: string,
+    args: unknown[]
+  ): Promise<O> => {
+    if (!isTracingEnabled()) {
+      return next(input);
+    }
+    const ambient = getCurrentRunTree(true);
+    if (config.addTemporalRuns) {
+      await emitMarkerRun(buildRunTree(config, { name, runType: RUN_TYPE.CHAIN, parent: ambient, inputs: { args } }));
+    }
+    const headers = withContextHeader(input.headers, runHeaders(ambient));
+    return next({ ...input, headers });
+  };
+
+  const parentMarker = async <I extends { headers: WorkflowStartInput['headers'] }, O>(
+    input: I,
+    next: NextFn<I, O>,
+    name: string,
+    args: unknown[]
+  ): Promise<O> => {
+    if (!isTracingEnabled()) {
+      return next(input);
+    }
+    const ambient = getCurrentRunTree(true);
+    let propagate: RunTree | undefined = ambient;
+    if (config.addTemporalRuns) {
+      const marker = buildRunTree(config, { name, runType: RUN_TYPE.CHAIN, parent: ambient, inputs: { args } });
+      await emitMarkerRun(marker);
+      propagate = marker;
+    }
+    const headers = withContextHeader(input.headers, runHeaders(propagate));
+    return next({ ...input, headers });
+  };
+
+  return {
+    start(input, next) {
+      return peerStart(input, next, startWorkflowRunName(input.workflowType), input.options.args);
+    },
+    startWithDetails(input, next) {
+      return peerStart(input, next, startWorkflowRunName(input.workflowType), input.options.args);
+    },
+    signal(input, next) {
+      return parentMarker(input, next, signalWorkflowRunName(input.signalName), input.args);
+    },
+    signalWithStart(input, next) {
+      return parentMarker(input, next, signalWithStartRunName(input.workflowType), input.signalArgs);
+    },
+    query(input, next) {
+      return parentMarker(input, next, queryWorkflowRunName(input.queryType), input.args);
+    },
+    startUpdate(input, next) {
+      return parentMarker(input, next, startWorkflowUpdateRunName(input.updateName), input.args);
+    },
+    async startUpdateWithStart(input, next) {
+      if (!isTracingEnabled()) {
+        return next(input);
+      }
+      const ambient = getCurrentRunTree(true);
+      let propagate: RunTree | undefined = ambient;
+      if (config.addTemporalRuns) {
+        const marker = buildRunTree(config, {
+          name: startUpdateWithStartRunName(input.updateName),
+          runType: RUN_TYPE.CHAIN,
+          parent: ambient,
+          inputs: { args: input.updateArgs },
+        });
+        await emitMarkerRun(marker);
+        propagate = marker;
+      }
+      const workflowStartHeaders = withContextHeader(input.workflowStartHeaders, runHeaders(propagate));
+      return next({ ...input, workflowStartHeaders });
+    },
+  };
+}

package/src/index.ts

@@ -0,0 +1,8 @@
+/**
+ * `@temporalio/langsmith` — LangSmith observability for Temporal.
+ *
+ * @module
+ */
+
+export { LangSmithPlugin } from './plugin';
+export type { LangSmithPluginOptions } from './plugin';

package/src/plugin.ts

@@ -0,0 +1,300 @@
+/**
+ * {@link LangSmithPlugin} — the single object a user adds to their Temporal
+ * `Client` and `Worker` to get LangSmith tracing across workflow / activity /
+ * child-workflow / Nexus boundaries with no changes to their existing
+ * `traceable` instrumentation.
+ *
+ * The plugin wires four things:
+ *  1. a **client interceptor** that propagates trace context out of any
+ *     `start` / `signal` / `query` / `update` call;
+ *  2. **activity + Nexus inbound interceptors** that reconstruct the trace and
+ *     install it as the active run (so body `traceable` calls nest correctly);
+ *  3. the **workflow interceptor module** (loaded into the workflow bundle) plus
+ *     a bundle-time global carrying the plugin config; and
+ *  4. the **LangSmith sink** that performs the actual out-of-isolate emission.
+ *
+ * On worker shutdown it flushes the LangSmith client so in-flight traces are
+ * not lost.
+ *
+ * @module
+ */
+
+import { Client } from 'langsmith';
+
+import type * as nexus from 'nexus-rpc';
+import { SimplePlugin } from '@temporalio/plugin';
+import type { ClientOptions } from '@temporalio/client';
+import type { BundleOptions, ReplayWorkerOptions, Worker, WorkerInterceptors, WorkerOptions } from '@temporalio/worker';
+import { createActivityInboundInterceptor, createNexusInboundInterceptor } from './activity-interceptor';
+import { createClientInterceptor } from './client-interceptor';
+import { createLangSmithSinks } from './sinks';
+import type { EmitterConfig } from './sinks';
+import type { WorkflowLangSmithConfig } from './workflow-interceptors';
+
+// Derived: @temporalio/worker doesn't export WebpackConfiguration from its root.
+type WebpackConfiguration = Parameters<NonNullable<BundleOptions['webpackConfigHook']>>[0];
+
+/**
+ * The module specifier for the workflow-side interceptors.
+ */
+const WORKFLOW_INTERCEPTOR_MODULE = '@temporalio/langsmith/workflow-interceptors';
+
+// Bare identifier (not dotted) so DefinePlugin substitutes textually.
+const CONFIG_GLOBAL = '__TEMPORAL_LANGSMITH_CONFIG__';
+
+// Bare builtin name added to `ignoreModules`; see {@link aliasAsyncHooks}.
+const ASYNC_HOOKS_MODULE = 'async_hooks';
+
+/**
+ * Options for {@link LangSmithPlugin}.
+ *
+ * Secrets (the LangSmith API key) are never accepted here as plaintext and
+ * never cross a Temporal boundary — supply a pre-constructed {@link Client}
+ * (which reads `LANGSMITH_API_KEY` from the worker/client process env) or let
+ * the plugin construct a default client from the environment.
+ *
+ * @experimental Plugins is an experimental feature; APIs may change without notice.
+ */
+export interface LangSmithPluginOptions {
+  /**
+   * The LangSmith client runs are emitted to. Defaults to `new Client()`, which
+   * reads `LANGSMITH_API_KEY` / `LANGSMITH_ENDPOINT` from the process
+   * environment. Lives only in the worker/client process — never serialized.
+   */
+  client?: Client;
+  /** Target LangSmith project for every emitted run. */
+  projectName?: string;
+  /**
+   * When `true`, emit first-class runs for Temporal operations themselves
+   * (`StartWorkflow:`, `RunActivity:`, `HandleSignal:`, …) in addition to the
+   * user's `traceable` runs. When `false` (default), only the user's
+   * `traceable` runs are emitted — trace context still propagates across
+   * boundaries so they nest correctly.
+   */
+  addTemporalRuns?: boolean;
+  /** Tags attached to every run the plugin emits. */
+  tags?: string[];
+  /** Metadata merged into every run the plugin emits (credential keys scrubbed). */
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * Temporal plugin that adds LangSmith observability to a Client + Worker.
+ *
+ * @example
+ * ```ts
+ * import { traceable } from 'langsmith/traceable';
+ * import { LangSmithPlugin } from '@temporalio/langsmith';
+ *
+ * const plugin = new LangSmithPlugin({ addTemporalRuns: true });
+ * const worker = await Worker.create({ workflowsPath, taskQueue: 'tq', plugins: [plugin] });
+ * ```
+ *
+ * @experimental Plugins is an experimental feature; APIs may change without notice.
+ */
+export class LangSmithPlugin extends SimplePlugin {
+  private readonly client: Client;
+  private readonly emitter: EmitterConfig;
+  private readonly workflowConfig: WorkflowLangSmithConfig;
+
+  constructor(options: LangSmithPluginOptions = {}) {
+    // super() reads options.name immediately
+    super({ name: 'langchain.LangSmithPlugin' });
+    this.client = options.client ?? new Client();
+    const addTemporalRuns = options.addTemporalRuns ?? false;
+    this.emitter = {
+      client: this.client,
+      addTemporalRuns,
+      projectName: options.projectName,
+      tags: options.tags,
+      metadata: options.metadata,
+    };
+    this.workflowConfig = {
+      addTemporalRuns,
+      projectName: options.projectName,
+      tags: options.tags,
+      metadata: options.metadata,
+    };
+  }
+
+  override configureClient(options: ClientOptions): ClientOptions {
+    const base = super.configureClient(options);
+    const existing = base.interceptors ?? {};
+    const workflow = Array.isArray(existing.workflow) ? [...existing.workflow] : [];
+    workflow.push(createClientInterceptor(this.emitter));
+    return { ...base, interceptors: { ...existing, workflow } };
+  }
+
+  override configureWorker(options: WorkerOptions): WorkerOptions {
+    return this.withLangSmithWorker(super.configureWorker(options));
+  }
+
+  override configureReplayWorker(options: ReplayWorkerOptions): ReplayWorkerOptions {
+    return this.withLangSmithWorker(super.configureReplayWorker(options));
+  }
+
+  private withLangSmithWorker<T extends WorkerOptions | ReplayWorkerOptions>(options: T): T {
+    const interceptors: WorkerInterceptors = options.interceptors ?? {};
+
+    const activityInbound = [...(interceptors.activityInbound ?? [])];
+    activityInbound.push(createActivityInboundInterceptor(this.emitter));
+
+    const workflowModules = [...(interceptors.workflowModules ?? [])];
+    if (!workflowModules.includes(WORKFLOW_INTERCEPTOR_MODULE)) {
+      workflowModules.push(WORKFLOW_INTERCEPTOR_MODULE);
+    }
+
+    const nexusInbound = createNexusInboundInterceptor(this.emitter);
+    const nexusInterceptors = [...(interceptors.nexus ?? [])];
+    nexusInterceptors.push((_ctx: nexus.OperationContext) => ({ inbound: nexusInbound }));
+
+    // The user's own Worker sinks take precedence on any key collision.
+    const sinks = { ...createLangSmithSinks(this.client), ...(options.sinks ?? {}) };
+
+    return {
+      ...options,
+      interceptors: { ...interceptors, activityInbound, workflowModules, nexus: nexusInterceptors },
+      sinks,
+    } as T;
+  }
+
+  override configureBundler(options: BundleOptions): BundleOptions {
+    const base = super.configureBundler(options);
+    const workflowInterceptorModules = [...(base.workflowInterceptorModules ?? [])];
+    if (!workflowInterceptorModules.includes(WORKFLOW_INTERCEPTOR_MODULE)) {
+      workflowInterceptorModules.push(WORKFLOW_INTERCEPTOR_MODULE);
+    }
+    // Dismiss the SDK bundler's disallowed-builtin guard for `async_hooks` (see aliasAsyncHooks).
+    const ignoreModules = [...(base.ignoreModules ?? [])];
+    if (!ignoreModules.includes(ASYNC_HOOKS_MODULE)) {
+      ignoreModules.push(ASYNC_HOOKS_MODULE);
+    }
+    const prevHook = base.webpackConfigHook;
+    const webpackConfigHook = (config: WebpackConfiguration): WebpackConfiguration => {
+      const merged = prevHook ? prevHook(config) : config;
+      // Double-encode so the injected token is a string literal in the bundle.
+      const definitions = { [CONFIG_GLOBAL]: JSON.stringify(JSON.stringify(this.workflowConfig)) };
+      const withDefine = injectDefinePlugin(merged, definitions);
+      return aliasLangSmithNodeUtils(aliasAsyncHooks(withDefine));
+    };
+    return { ...base, workflowInterceptorModules, ignoreModules, webpackConfigHook };
+  }
+
+  /**
+   * Flush the LangSmith client on worker shutdown so traces that were emitted
+   * just before exit are delivered. Wraps the worker run loop and flushes in a
+   * `finally`, swallowing flush errors (shutdown must not fail on telemetry).
+   */
+  override async runWorker(worker: Worker, next: (worker: Worker) => Promise<void>): Promise<void> {
+    try {
+      await next(worker);
+    } finally {
+      await this.flush();
+    }
+  }
+
+  private async flush(): Promise<void> {
+    try {
+      await this.client.awaitPendingTraceBatches();
+    } catch {
+      /* swallow: telemetry flush must never fail worker shutdown */
+    }
+  }
+}
+
+/**
+ * Redirect `node:async_hooks` to the workflow interceptor module's isolate-safe
+ * shim. webpack routes `node:` requests through a scheme handler before alias
+ * resolution, so `resolve.alias` cannot do this; `NormalModuleReplacementPlugin`
+ * rewrites the request in `beforeResolve` instead. Must be paired with the
+ * `ignoreModules` whitelist (see {@link LangSmithPlugin.configureBundler}). The
+ * rewrite target is the package specifier so webpack dedupes to one isolate
+ * instance regardless of issuer.
+ */
+function aliasAsyncHooks(config: WebpackConfiguration): WebpackConfiguration {
+  const plugins = [...(config.plugins ?? [])];
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const webpack = require('webpack') as {
+      NormalModuleReplacementPlugin: new (re: RegExp, cb: (resource: { request: string }) => void) => unknown;
+    };
+    plugins.push(
+      new webpack.NormalModuleReplacementPlugin(/^node:async_hooks$/, (resource) => {
+        resource.request = WORKFLOW_INTERCEPTOR_MODULE;
+      }) as (typeof plugins)[number]
+    );
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException)?.code !== 'MODULE_NOT_FOUND') throw err;
+    /* webpack genuinely absent (MODULE_NOT_FOUND): leave plugins untouched; any other failure rethrows. */
+  }
+  return { ...config, plugins };
+}
+
+/**
+ * Redirect langsmith's node-only CJS utilities to its `.browser.cjs` siblings so
+ * the workflow bundle keeps node builtins out of the isolate. Scoped to langsmith
+ * so a user's own `fs.cjs` is never rewritten.
+ */
+function aliasLangSmithNodeUtils(config: WebpackConfiguration): WebpackConfiguration {
+  const plugins = [...(config.plugins ?? [])];
+  const swap = (s: string): string => s.replace(/\.cjs$/, '.browser.cjs');
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const webpack = require('webpack') as {
+      NormalModuleReplacementPlugin: new (
+        re: RegExp,
+        cb: (resource: {
+          request: string;
+          context?: string;
+          createData?: { resource?: string; userRequest?: string; request?: string };
+        }) => void
+      ) => unknown;
+    };
+    plugins.push(
+      new webpack.NormalModuleReplacementPlugin(/[/\\]utils[/\\](?:fs|worker_threads)\.cjs$/, (resource) => {
+        // Resolved sibling-relative requires (`./fs.cjs`) carry the absolute
+        // path on `createData.resource`; raw `beforeResolve` requests carry it
+        // on `request`.
+        const createData = resource.createData;
+        if (createData && typeof createData.resource === 'string') {
+          if (!createData.resource.includes('langsmith') || createData.resource.includes('.browser.cjs')) {
+            return;
+          }
+          createData.resource = swap(createData.resource);
+          if (typeof createData.userRequest === 'string') {
+            createData.userRequest = swap(createData.userRequest);
+          }
+          if (typeof createData.request === 'string') {
+            createData.request = swap(createData.request);
+          }
+          return;
+        }
+        if (!resource.context || !resource.context.includes('langsmith') || resource.request.includes('.browser.cjs')) {
+          return;
+        }
+        resource.request = swap(resource.request);
+      }) as (typeof plugins)[number]
+    );
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException)?.code !== 'MODULE_NOT_FOUND') throw err;
+    /* webpack genuinely absent (MODULE_NOT_FOUND): leave plugins untouched; any other failure rethrows. */
+  }
+  return { ...config, plugins };
+}
+
+/**
+ * Append a `DefinePlugin`-equivalent to a webpack config without a static
+ * `webpack` import (webpack is provided transitively by the worker).
+ */
+function injectDefinePlugin(config: WebpackConfiguration, definitions: Record<string, string>): WebpackConfiguration {
+  const plugins = [...(config.plugins ?? [])];
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const webpack = require('webpack') as { DefinePlugin: new (d: Record<string, string>) => unknown };
+    plugins.push(new webpack.DefinePlugin(definitions) as (typeof plugins)[number]);
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException)?.code !== 'MODULE_NOT_FOUND') throw err;
+    /* webpack genuinely absent (MODULE_NOT_FOUND): leave plugins untouched, workflow uses defaults; any other failure rethrows. */
+  }
+  return { ...config, plugins };
+}

package/src/propagation.ts

@@ -0,0 +1,153 @@
+/**
+ * Cross-boundary trace-context propagation for the LangSmith Temporal plugin.
+ *
+ * The LangSmith run context travels across every Temporal boundary
+ * (client→workflow, workflow→activity, workflow→child-workflow,
+ * workflow→Nexus, continue-as-new) as a single Temporal {@link Header}
+ * entry. The wire value is exactly the object produced by
+ * `RunTree.toHeaders()` — `{ "langsmith-trace": <dottedOrder>, baggage: <string> }`
+ * — which the receiving side feeds straight back into
+ * `RunTree.fromHeaders(...)` to reconstruct the parent run.
+ *
+ * Two encodings are supported because Temporal exposes two header shapes:
+ *  - The binary/Temporal path (`Headers = Record<string, Payload>`): the
+ *    context is encoded with the default payload converter.
+ *  - The Nexus path (`Record<string, string>`): Nexus headers are plain
+ *    strings with no Payload encoding, so the context is JSON-serialized.
+ *
+ * @module
+ */
+
+import { defaultPayloadConverter, type Payload } from '@temporalio/common';
+
+/**
+ * Temporal header key under which the LangSmith trace context is carried.
+ *
+ * Must byte-match the Python plugin's key so trace context propagates across SDKs.
+ */
+export const HEADER_KEY = '_temporal-langsmith-context';
+
+/**
+ * The serialized LangSmith trace context that crosses a Temporal boundary.
+ *
+ * This is structurally the output of `RunTree.toHeaders()`. Keeping it as a
+ * plain JSON object lets the same value ride either the Payload transport or
+ * the Nexus plain-string transport unchanged.
+ */
+export interface LangSmithTraceContext extends Record<string, string> {
+  /** The parent run's dotted order — the LangSmith trace pointer. */
+  'langsmith-trace': string;
+  /** LangSmith baggage (metadata / tags / project), comma-encoded. */
+  baggage: string;
+}
+
+/** Case-insensitive key prefixes scrubbed from runs and propagated headers. */
+const SENSITIVE_KEY_PREFIXES: readonly string[] = [
+  'auth',
+  'api_key',
+  'api-key',
+  'x-api-key',
+  'apikey',
+  'cookie',
+  'set-cookie',
+  'bearer',
+  'secret',
+  'token',
+  'password',
+];
+
+/** Returns true when `key` looks like a credential-bearing header/metadata key. */
+function isSensitiveKey(key: string): boolean {
+  const lower = key.toLowerCase();
+  return SENSITIVE_KEY_PREFIXES.some((prefix) => lower.startsWith(prefix));
+}
+
+/** Return a shallow copy of `record` with all credential-bearing keys removed. */
+export function scrubSensitive<T = unknown>(record: Record<string, T> | undefined): Record<string, T> | undefined {
+  if (record == null) {
+    return record;
+  }
+  const out: Record<string, T> = {};
+  for (const [key, value] of Object.entries(record)) {
+    if (!isSensitiveKey(key)) {
+      out[key] = value;
+    }
+  }
+  return out;
+}
+
+/** Encode a trace context into a Temporal `Payload`; never throws (failure → undefined, header omitted). */
+function encodeContextPayload(context: LangSmithTraceContext): Payload | undefined {
+  try {
+    return defaultPayloadConverter.toPayload(context);
+  } catch {
+    return undefined;
+  }
+}
+
+/** Decode a trace context from a Temporal `Payload`; never throws (malformed → undefined). */
+function decodeContextPayload(payload: Payload | undefined): LangSmithTraceContext | undefined {
+  if (payload == null) {
+    return undefined;
+  }
+  try {
+    const value = defaultPayloadConverter.fromPayload<LangSmithTraceContext>(payload);
+    return isTraceContext(value) ? value : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Encode a trace context as a plain string for the Nexus header transport. */
+export function encodeContextString(context: LangSmithTraceContext): string {
+  return JSON.stringify(context);
+}
+
+/** Decode a trace context from a Nexus plain-string header; never throws. */
+export function decodeContextString(value: string | undefined): LangSmithTraceContext | undefined {
+  if (value == null || value === '') {
+    return undefined;
+  }
+  try {
+    const parsed = JSON.parse(value) as unknown;
+    return isTraceContext(parsed) ? parsed : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function isTraceContext(value: unknown): value is LangSmithTraceContext {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    typeof (value as Record<string, unknown>)['langsmith-trace'] === 'string'
+  );
+}
+
+/**
+ * Inject a trace context into a Payload-keyed Temporal header map, returning a
+ * new map (interceptor inputs treat `headers` as immutable). Returns the input
+ * unchanged when `context` is `undefined`.
+ */
+export function withContextHeader(
+  headers: Record<string, Payload>,
+  context: LangSmithTraceContext | undefined
+): Record<string, Payload> {
+  if (context === undefined) {
+    return headers;
+  }
+  const payload = encodeContextPayload(context);
+  return payload === undefined ? headers : { ...headers, [HEADER_KEY]: payload };
+}
+
+export function readContextHeader(headers: Record<string, Payload> | undefined): LangSmithTraceContext | undefined {
+  return decodeContextPayload(headers?.[HEADER_KEY]);
+}
+
+/**
+ * Temporal-internal query names that must NOT produce a LangSmith run: any
+ * `__temporal`-prefixed query plus the stack-trace introspection queries.
+ */
+export function isInternalQuery(queryName: string): boolean {
+  return queryName.startsWith('__temporal') || queryName === '__stack_trace' || queryName === '__enhanced_stack_trace';
+}