@temporalio/langsmith 1.20.0

package/lib/plugin.js

@@ -0,0 +1,235 @@
+"use strict";
+/**
+ * {@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
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LangSmithPlugin = void 0;
+const langsmith_1 = require("langsmith");
+const plugin_1 = require("@temporalio/plugin");
+const activity_interceptor_1 = require("./activity-interceptor");
+const client_interceptor_1 = require("./client-interceptor");
+const sinks_1 = require("./sinks");
+/**
+ * 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';
+/**
+ * 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.
+ */
+class LangSmithPlugin extends plugin_1.SimplePlugin {
+    client;
+    emitter;
+    workflowConfig;
+    constructor(options = {}) {
+        // super() reads options.name immediately
+        super({ name: 'langchain.LangSmithPlugin' });
+        this.client = options.client ?? new langsmith_1.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,
+        };
+    }
+    configureClient(options) {
+        const base = super.configureClient(options);
+        const existing = base.interceptors ?? {};
+        const workflow = Array.isArray(existing.workflow) ? [...existing.workflow] : [];
+        workflow.push((0, client_interceptor_1.createClientInterceptor)(this.emitter));
+        return { ...base, interceptors: { ...existing, workflow } };
+    }
+    configureWorker(options) {
+        return this.withLangSmithWorker(super.configureWorker(options));
+    }
+    configureReplayWorker(options) {
+        return this.withLangSmithWorker(super.configureReplayWorker(options));
+    }
+    withLangSmithWorker(options) {
+        const interceptors = options.interceptors ?? {};
+        const activityInbound = [...(interceptors.activityInbound ?? [])];
+        activityInbound.push((0, activity_interceptor_1.createActivityInboundInterceptor)(this.emitter));
+        const workflowModules = [...(interceptors.workflowModules ?? [])];
+        if (!workflowModules.includes(WORKFLOW_INTERCEPTOR_MODULE)) {
+            workflowModules.push(WORKFLOW_INTERCEPTOR_MODULE);
+        }
+        const nexusInbound = (0, activity_interceptor_1.createNexusInboundInterceptor)(this.emitter);
+        const nexusInterceptors = [...(interceptors.nexus ?? [])];
+        nexusInterceptors.push((_ctx) => ({ inbound: nexusInbound }));
+        // The user's own Worker sinks take precedence on any key collision.
+        const sinks = { ...(0, sinks_1.createLangSmithSinks)(this.client), ...(options.sinks ?? {}) };
+        return {
+            ...options,
+            interceptors: { ...interceptors, activityInbound, workflowModules, nexus: nexusInterceptors },
+            sinks,
+        };
+    }
+    configureBundler(options) {
+        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) => {
+            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).
+     */
+    async runWorker(worker, next) {
+        try {
+            await next(worker);
+        }
+        finally {
+            await this.flush();
+        }
+    }
+    async flush() {
+        try {
+            await this.client.awaitPendingTraceBatches();
+        }
+        catch {
+            /* swallow: telemetry flush must never fail worker shutdown */
+        }
+    }
+}
+exports.LangSmithPlugin = LangSmithPlugin;
+/**
+ * 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) {
+    const plugins = [...(config.plugins ?? [])];
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const webpack = require('webpack');
+        plugins.push(new webpack.NormalModuleReplacementPlugin(/^node:async_hooks$/, (resource) => {
+            resource.request = WORKFLOW_INTERCEPTOR_MODULE;
+        }));
+    }
+    catch (err) {
+        if (err?.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) {
+    const plugins = [...(config.plugins ?? [])];
+    const swap = (s) => s.replace(/\.cjs$/, '.browser.cjs');
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const webpack = require('webpack');
+        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);
+        }));
+    }
+    catch (err) {
+        if (err?.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, definitions) {
+    const plugins = [...(config.plugins ?? [])];
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const webpack = require('webpack');
+        plugins.push(new webpack.DefinePlugin(definitions));
+    }
+    catch (err) {
+        if (err?.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 };
+}
+//# sourceMappingURL=plugin.js.map

package/lib/plugin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.js","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"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"}

package/lib/propagation.d.ts

@@ -0,0 +1,57 @@
+/**
+ * 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 { 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 declare 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;
+}
+/** Return a shallow copy of `record` with all credential-bearing keys removed. */
+export declare function scrubSensitive<T = unknown>(record: Record<string, T> | undefined): Record<string, T> | undefined;
+/** Encode a trace context as a plain string for the Nexus header transport. */
+export declare function encodeContextString(context: LangSmithTraceContext): string;
+/** Decode a trace context from a Nexus plain-string header; never throws. */
+export declare function decodeContextString(value: string | undefined): LangSmithTraceContext | undefined;
+/**
+ * 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 declare function withContextHeader(headers: Record<string, Payload>, context: LangSmithTraceContext | undefined): Record<string, Payload>;
+export declare function readContextHeader(headers: Record<string, Payload> | undefined): LangSmithTraceContext | undefined;
+/**
+ * Temporal-internal query names that must NOT produce a LangSmith run: any
+ * `__temporal`-prefixed query plus the stack-trace introspection queries.
+ */
+export declare function isInternalQuery(queryName: string): boolean;

package/lib/propagation.js

@@ -0,0 +1,134 @@
+"use strict";
+/**
+ * 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
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HEADER_KEY = void 0;
+exports.scrubSensitive = scrubSensitive;
+exports.encodeContextString = encodeContextString;
+exports.decodeContextString = decodeContextString;
+exports.withContextHeader = withContextHeader;
+exports.readContextHeader = readContextHeader;
+exports.isInternalQuery = isInternalQuery;
+const common_1 = require("@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.
+ */
+exports.HEADER_KEY = '_temporal-langsmith-context';
+/** Case-insensitive key prefixes scrubbed from runs and propagated headers. */
+const SENSITIVE_KEY_PREFIXES = [
+    '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) {
+    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. */
+function scrubSensitive(record) {
+    if (record == null) {
+        return record;
+    }
+    const out = {};
+    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) {
+    try {
+        return common_1.defaultPayloadConverter.toPayload(context);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Decode a trace context from a Temporal `Payload`; never throws (malformed → undefined). */
+function decodeContextPayload(payload) {
+    if (payload == null) {
+        return undefined;
+    }
+    try {
+        const value = common_1.defaultPayloadConverter.fromPayload(payload);
+        return isTraceContext(value) ? value : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Encode a trace context as a plain string for the Nexus header transport. */
+function encodeContextString(context) {
+    return JSON.stringify(context);
+}
+/** Decode a trace context from a Nexus plain-string header; never throws. */
+function decodeContextString(value) {
+    if (value == null || value === '') {
+        return undefined;
+    }
+    try {
+        const parsed = JSON.parse(value);
+        return isTraceContext(parsed) ? parsed : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function isTraceContext(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        typeof value['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`.
+ */
+function withContextHeader(headers, context) {
+    if (context === undefined) {
+        return headers;
+    }
+    const payload = encodeContextPayload(context);
+    return payload === undefined ? headers : { ...headers, [exports.HEADER_KEY]: payload };
+}
+function readContextHeader(headers) {
+    return decodeContextPayload(headers?.[exports.HEADER_KEY]);
+}
+/**
+ * Temporal-internal query names that must NOT produce a LangSmith run: any
+ * `__temporal`-prefixed query plus the stack-trace introspection queries.
+ */
+function isInternalQuery(queryName) {
+    return queryName.startsWith('__temporal') || queryName === '__stack_trace' || queryName === '__enhanced_stack_trace';
+}
+//# sourceMappingURL=propagation.js.map

package/lib/propagation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"propagation.js","sourceRoot":"","sources":["../src/propagation.ts"],"names":[],"mappings":"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"}

package/lib/run-tree.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Replay-safe LangSmith run construction for workflow code, plus the pure
+ * run-name builders shared by every interceptor.
+ *
+ * Inside the workflow isolate LangSmith's default `RunTree` is unsafe on two
+ * counts that {@link ReplaySafeRunTree} fixes:
+ *
+ *  1. **Non-deterministic ids.** Its default random-tailed uuid7 would mint a
+ *     fresh id on every replay, flooding the backend with duplicates.
+ *  2. **Network I/O on replay.** `postRun` / `patchRun` would re-POST runs on
+ *     every history replay.
+ *
+ * Internal: every export here is consumed only by sibling modules in this
+ * package; none is reachable through a package entry point.
+ *
+ * @module
+ * @internal
+ */
+import { type LangSmithTraceContext } from './propagation';
+import { type EmitterConfig } from './sinks';
+/** LangSmith run-type constants used for Temporal-operation runs. */
+export declare const RUN_TYPE: {
+    /** Workflow / child-workflow / scheduling / handler spans. */
+    readonly CHAIN: "chain";
+    /** Activity-body execution spans. */
+    readonly TOOL: "tool";
+};
+/** `StartWorkflow:<type>` — client/parent-side workflow-start marker. */
+export declare const startWorkflowRunName: (workflowType: string) => string;
+/** `RunWorkflow:<type>` — the workflow-execution span (inbound). */
+export declare const runWorkflowRunName: (workflowType: string) => string;
+/** `StartActivity:<name>` — workflow-side activity-schedule marker. */
+export declare const startActivityRunName: (activityType: string) => string;
+/** `RunActivity:<name>` — the activity-execution span (activity inbound). */
+export declare const runActivityRunName: (activityType: string) => string;
+/** `StartChildWorkflow:<type>` — workflow-side child-start marker. */
+export declare const startChildWorkflowRunName: (workflowType: string) => string;
+/** `StartNexusOperation:<service>/<op>` — workflow-side Nexus-start marker. */
+export declare const startNexusOperationRunName: (service: string, operation: string) => string;
+/** `RunStartNexusOperationHandler:<service>/<op>` — Nexus start-handler span. */
+export declare const runStartNexusHandlerRunName: (service: string, operation: string) => string;
+/** `RunCancelNexusOperationHandler:<service>/<op>` — Nexus cancel-handler span. */
+export declare const runCancelNexusHandlerRunName: (service: string, operation: string) => string;
+/** `HandleSignal:<name>` — inbound signal handler span. */
+export declare const handleSignalRunName: (signalName: string) => string;
+/** `HandleQuery:<name>` — inbound query handler span. */
+export declare const handleQueryRunName: (queryName: string) => string;
+/** `HandleUpdate:<name>` — inbound update handler span. */
+export declare const handleUpdateRunName: (updateName: string) => string;
+/** `ValidateUpdate:<name>` — inbound update validator span. */
+export declare const validateUpdateRunName: (updateName: string) => string;
+/** `SignalWorkflow:<name>` — client/outbound signal marker. */
+export declare const signalWorkflowRunName: (signalName: string) => string;
+/** `SignalChildWorkflow:<name>` — workflow-side signal-child marker. */
+export declare const signalChildWorkflowRunName: (signalName: string) => string;
+/** `SignalExternalWorkflow:<name>` — workflow-side signal-external marker. */
+export declare const signalExternalWorkflowRunName: (signalName: string) => string;
+/** `SignalWithStartWorkflow:<type>` — client signal-with-start marker. */
+export declare const signalWithStartRunName: (workflowType: string) => string;
+/** `QueryWorkflow:<name>` — client query marker. */
+export declare const queryWorkflowRunName: (queryName: string) => string;
+/** `StartWorkflowUpdate:<name>` — client update-start marker. */
+export declare const startWorkflowUpdateRunName: (updateName: string) => string;
+/** `StartUpdateWithStartWorkflow:<name>` — client update-with-start marker. */
+export declare const startUpdateWithStartRunName: (updateName: string) => string;
+/**
+ * Render an error into the LangSmith `error` string, honoring Temporal's
+ * benign-failure category.
+ *
+ * A `BENIGN`-category `ApplicationFailure` is an expected, non-alarming outcome
+ * (e.g. a control-flow signal), so it leaves the run's `error` unset. All other
+ * failures produce `"<type>: <message>"`.
+ */
+export declare function describeError(err: unknown): string | undefined;
+/** Coerce an arbitrary operation result into a LangSmith outputs object. */
+export declare function asOutputs(result: unknown): Record<string, unknown>;
+/** The trace context to propagate for `run`, or `undefined` when absent. */
+export declare function runHeaders(run: RunTree | undefined): LangSmithTraceContext | undefined;
+/** Emit a short-lived marker run. */
+export declare function emitMarkerRun(marker: RunTree): Promise<void>;
+/** Reconstruct a propagated parent {@link RunTree} from a trace context; never throws. */
+export declare function runTreeFromContext(ctx: LangSmithTraceContext | undefined): RunTree | undefined;
+interface RunTreeParams {
+    name: string;
+    runType: string;
+    parent: RunTree | undefined;
+    inputs?: Record<string, unknown>;
+}
+/**
+ * Build an emitter-side {@link RunTree} (client / activity / Nexus); force-enables
+ * tracing so nested body `traceable` runs emit — tracing gate is `isTracingEnabled()`.
+ */
+export declare function buildRunTree(config: EmitterConfig, params: RunTreeParams): RunTree;
+export {};