@temporalio/langsmith 1.23.0 → 2.0.0-rc.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -15,15 +15,16 @@ import type { ActivityInboundCallsInterceptorFactory, NexusInboundCallsIntercept
15
15
  import { HEADER_KEY, decodeContextString, readContextHeader, type LangSmithTraceContext } from './propagation';
16
16
  import {
17
17
  RUN_TYPE,
18
- asOutputs,
19
- describeError,
20
18
  buildRunTree,
21
19
  runActivityRunName,
22
20
  runCancelNexusHandlerRunName,
23
21
  runStartNexusHandlerRunName,
24
22
  runTreeFromContext,
23
+ wrapWithRun,
25
24
  } from './run-tree';
26
25
  import type { EmitterConfig } from './sinks';
26
+ import { bindReplicaCredentials, destination } from './routing';
27
+ import { withRunTreeDefaults } from './worker-run-tree';
27
28
 
28
29
  /**
29
30
  * Reconstruct the propagated parent run from a LangSmith trace context, wired to
@@ -42,8 +43,11 @@ function reconstructParentRun(config: EmitterConfig, ctx: LangSmithTraceContext
42
43
  id: parsed.id,
43
44
  trace_id: parsed.trace_id,
44
45
  dotted_order: parsed.dotted_order,
46
+ start_time: parsed.start_time,
45
47
  parent_run_id: parsed.parent_run_id,
46
- project_name: config.projectName ?? parsed.project_name,
48
+ ...destination(parsed, { project_name: config.projectName, address: config.address }),
49
+ replicas: bindReplicaCredentials(parsed.replicas, config.replicas),
50
+ distributedParentId: parsed.distributedParentId,
47
51
  client: config.client,
48
52
  // Force-enable so nested body `traceable` runs emit; tracing gate is `isTracingEnabled()`.
49
53
  tracingEnabled: true,
@@ -51,21 +55,29 @@ function reconstructParentRun(config: EmitterConfig, ctx: LangSmithTraceContext
51
55
  }
52
56
 
53
57
  /**
54
- * Run `fn` with `op` installed as the active LangSmith run, emitting the run
55
- * around the call. Shared by activity and Nexus handlers.
58
+ * Run a handler under `parent`. With `addTemporalRuns`, wrap it in the operation run from `build`, emitted unless
59
+ * LangSmith turned tracing off for it (an env it can't address). Shared by activity and Nexus handlers.
56
60
  */
57
- async function traceOperation<T>(op: RunTree, fn: () => Promise<T>): Promise<T> {
58
- await op.postRun();
59
- try {
60
- const result = await withRunTree(op, fn);
61
- await op.end(asOutputs(result));
62
- await op.patchRun();
63
- return result;
64
- } catch (err) {
65
- await op.end(undefined, describeError(err));
66
- await op.patchRun();
67
- throw err;
61
+ async function traceHandler<T>(
62
+ config: EmitterConfig,
63
+ parent: RunTree | undefined,
64
+ build: () => RunTree,
65
+ fn: () => Promise<T>
66
+ ): Promise<T> {
67
+ // A propagated parent keeps tracing on, as LangSmith does; the env only gates traces that start here.
68
+ if (!parent && !isTracingEnabled()) {
69
+ return fn();
68
70
  }
71
+ if (!config.addTemporalRuns) {
72
+ // Without a parent, native roots fall back to the plugin's routing defaults.
73
+ return parent ? withRunTree(parent, fn) : withRunTreeDefaults(config, fn);
74
+ }
75
+ const run = build();
76
+ if (!run.tracingEnabled) {
77
+ return withRunTree(run, fn);
78
+ }
79
+ await run.postRun();
80
+ return wrapWithRun(run, () => withRunTree(run, fn));
69
81
  }
70
82
 
71
83
  /**
@@ -76,32 +88,25 @@ async function traceOperation<T>(op: RunTree, fn: () => Promise<T>): Promise<T>
76
88
  export function createActivityInboundInterceptor(config: EmitterConfig): ActivityInboundCallsInterceptorFactory {
77
89
  return (ctx: ActivityContext) => ({
78
90
  async execute(input, next) {
79
- if (!isTracingEnabled()) {
80
- return next(input);
81
- }
82
91
  const parent = reconstructParentRun(config, readContextHeader(input.headers));
83
- if (!config.addTemporalRuns) {
84
- // Propagation only: nest the user's body `traceable` runs under the
85
- // reconstructed parent without emitting a Temporal-operation run.
86
- // No propagated parent: run the body with no ambient run by design (nothing to attach to).
87
- return parent ? withRunTree(parent, () => next(input)) : next(input);
88
- }
89
- const activityType = ctx.info.activityType;
90
- const run = buildRunTree(config, {
91
- name: runActivityRunName(activityType),
92
- runType: RUN_TYPE.TOOL,
93
- parent,
94
- inputs: { args: input.args },
95
- });
96
- return traceOperation(run, () => next(input));
92
+ const build = () => {
93
+ const { activityType, activityId, workflowExecution } = ctx.info;
94
+ return buildRunTree(config, {
95
+ name: runActivityRunName(activityType),
96
+ runType: RUN_TYPE.TOOL,
97
+ parent,
98
+ metadata: {
99
+ temporalWorkflowID: workflowExecution?.workflowId ?? '',
100
+ temporalRunID: workflowExecution?.runId ?? '',
101
+ temporalActivityID: activityId,
102
+ },
103
+ });
104
+ };
105
+ return traceHandler(config, parent, build, () => next(input));
97
106
  },
98
107
  });
99
108
  }
100
109
 
101
- function nexusContext(headers: Record<string, string>): LangSmithTraceContext | undefined {
102
- return decodeContextString(headers[HEADER_KEY]);
103
- }
104
-
105
110
  /**
106
111
  * Build the Nexus-handler interceptor. `startOperation` opens a
107
112
  * `RunStartNexusOperationHandler:` run (so workflows the handler starts nest
@@ -111,21 +116,12 @@ export function createNexusInboundInterceptor(config: EmitterConfig): NexusInbou
111
116
  const handle = async <I extends { ctx: { service: string; operation: string; headers: Record<string, string> } }, O>(
112
117
  input: I,
113
118
  next: (input: I) => Promise<O>,
114
- nameOf: (s: string, o: string) => string
119
+ nameOf: (service: string, operation: string) => string
115
120
  ): Promise<O> => {
116
- if (!isTracingEnabled()) {
117
- return next(input);
118
- }
119
- const parent = reconstructParentRun(config, nexusContext(input.ctx.headers));
120
- if (!config.addTemporalRuns) {
121
- return parent ? withRunTree(parent, () => next(input)) : next(input);
122
- }
123
- const run = buildRunTree(config, {
124
- name: nameOf(input.ctx.service, input.ctx.operation),
125
- runType: RUN_TYPE.CHAIN,
126
- parent,
127
- });
128
- return traceOperation(run, () => next(input));
121
+ const parent = reconstructParentRun(config, decodeContextString(input.ctx.headers[HEADER_KEY]));
122
+ const build = () =>
123
+ buildRunTree(config, { name: nameOf(input.ctx.service, input.ctx.operation), runType: RUN_TYPE.TOOL, parent });
124
+ return traceHandler(config, parent, build, () => next(input));
129
125
  };
130
126
 
131
127
  return {
@@ -1,22 +1,20 @@
1
1
  /**
2
- * Client-side LangSmith interceptor. Execution ops (`start`) emit a peer marker
3
- * and propagate the **ambient** context (the remote run is a sibling); messaging
4
- * ops (`signal`, `query`, `update`, …) emit the marker and propagate the
5
- * **marker** context (the remote handler nests under it).
2
+ * Client-side LangSmith interceptor. Each call runs inside a marker run that ends when the call returns. Execution ops
3
+ * (`start`, `signalWithStart`, `startUpdateWithStart`) propagate the **ambient** context (the remote run is a
4
+ * sibling); messaging ops (`signal`, `query`, `startUpdate`) propagate the **marker** context (the remote handler
5
+ * nests under it).
6
6
  *
7
7
  * @module
8
8
  */
9
9
 
10
10
  import { isTracingEnabled } from 'langsmith';
11
- import type { RunTree } from 'langsmith/run_trees';
12
11
  import { getCurrentRunTree } from 'langsmith/traceable';
13
12
  import type { WorkflowClientInterceptor, WorkflowStartInput } from '@temporalio/client';
14
13
 
15
- import { withContextHeader } from './propagation';
14
+ import { withContextHeader, type LangSmithTraceContext } from './propagation';
16
15
  import {
17
16
  RUN_TYPE,
18
17
  buildRunTree,
19
- emitMarkerRun,
20
18
  queryWorkflowRunName,
21
19
  runHeaders,
22
20
  signalWithStartRunName,
@@ -24,86 +22,66 @@ import {
24
22
  startUpdateWithStartRunName,
25
23
  startWorkflowRunName,
26
24
  startWorkflowUpdateRunName,
25
+ wrapWithRun,
27
26
  } from './run-tree';
28
27
  import type { EmitterConfig } from './sinks';
29
28
 
30
29
  type NextFn<I, O> = (input: I) => Promise<O>;
30
+ type Headers = WorkflowStartInput['headers'];
31
31
 
32
32
  export function createClientInterceptor(config: EmitterConfig): WorkflowClientInterceptor {
33
- const peerStart = async <I extends { headers: WorkflowStartInput['headers'] }, O>(
34
- input: I,
35
- next: NextFn<I, O>,
33
+ /** Run `call` inside a marker run, passing it the context to propagate: the marker's, or the ambient one when `peer`. */
34
+ const traced = async <O>(
36
35
  name: string,
37
- args: unknown[]
36
+ peer: boolean,
37
+ call: (context: LangSmithTraceContext | undefined) => Promise<O>
38
38
  ): Promise<O> => {
39
39
  if (!isTracingEnabled()) {
40
- return next(input);
40
+ return call(undefined);
41
41
  }
42
42
  const ambient = getCurrentRunTree(true);
43
- if (config.addTemporalRuns) {
44
- await emitMarkerRun(buildRunTree(config, { name, runType: RUN_TYPE.CHAIN, parent: ambient, inputs: { args } }));
43
+ if (!config.addTemporalRuns) {
44
+ return call(runHeaders(ambient));
45
45
  }
46
- const headers = withContextHeader(input.headers, runHeaders(ambient));
47
- return next({ ...input, headers });
48
- };
49
-
50
- const parentMarker = async <I extends { headers: WorkflowStartInput['headers'] }, O>(
51
- input: I,
52
- next: NextFn<I, O>,
53
- name: string,
54
- args: unknown[]
55
- ): Promise<O> => {
56
- if (!isTracingEnabled()) {
57
- return next(input);
58
- }
59
- const ambient = getCurrentRunTree(true);
60
- let propagate: RunTree | undefined = ambient;
61
- if (config.addTemporalRuns) {
62
- const marker = buildRunTree(config, { name, runType: RUN_TYPE.CHAIN, parent: ambient, inputs: { args } });
63
- await emitMarkerRun(marker);
64
- propagate = marker;
46
+ const marker = buildRunTree(config, { name, runType: RUN_TYPE.CHAIN, parent: ambient });
47
+ const context = runHeaders(peer ? ambient : marker);
48
+ if (!marker.tracingEnabled) {
49
+ return call(context);
65
50
  }
66
- const headers = withContextHeader(input.headers, runHeaders(propagate));
67
- return next({ ...input, headers });
51
+ await marker.postRun();
52
+ return wrapWithRun(marker, () => call(context));
68
53
  };
69
54
 
55
+ const withHeaders = <I extends { headers: Headers }, O>(input: I, next: NextFn<I, O>, name: string, peer: boolean) =>
56
+ traced(name, peer, (context) => next({ ...input, headers: withContextHeader(input.headers, context) }));
57
+
70
58
  return {
71
59
  start(input, next) {
72
- return peerStart(input, next, startWorkflowRunName(input.workflowType), input.options.args);
60
+ return withHeaders(input, next, startWorkflowRunName(input.workflowType), true);
73
61
  },
74
62
  startWithDetails(input, next) {
75
- return peerStart(input, next, startWorkflowRunName(input.workflowType), input.options.args);
63
+ return withHeaders(input, next, startWorkflowRunName(input.workflowType), true);
76
64
  },
77
65
  signal(input, next) {
78
- return parentMarker(input, next, signalWorkflowRunName(input.signalName), input.args);
66
+ return withHeaders(input, next, signalWorkflowRunName(input.signalName), false);
79
67
  },
80
68
  signalWithStart(input, next) {
81
- return parentMarker(input, next, signalWithStartRunName(input.workflowType), input.signalArgs);
69
+ return withHeaders(input, next, signalWithStartRunName(input.workflowType), true);
82
70
  },
83
71
  query(input, next) {
84
- return parentMarker(input, next, queryWorkflowRunName(input.queryType), input.args);
72
+ return withHeaders(input, next, queryWorkflowRunName(input.queryType), false);
85
73
  },
86
74
  startUpdate(input, next) {
87
- return parentMarker(input, next, startWorkflowUpdateRunName(input.updateName), input.args);
75
+ return withHeaders(input, next, startWorkflowUpdateRunName(input.updateName), false);
88
76
  },
89
- async startUpdateWithStart(input, next) {
90
- if (!isTracingEnabled()) {
91
- return next(input);
92
- }
93
- const ambient = getCurrentRunTree(true);
94
- let propagate: RunTree | undefined = ambient;
95
- if (config.addTemporalRuns) {
96
- const marker = buildRunTree(config, {
97
- name: startUpdateWithStartRunName(input.updateName),
98
- runType: RUN_TYPE.CHAIN,
99
- parent: ambient,
100
- inputs: { args: input.updateArgs },
101
- });
102
- await emitMarkerRun(marker);
103
- propagate = marker;
104
- }
105
- const workflowStartHeaders = withContextHeader(input.workflowStartHeaders, runHeaders(propagate));
106
- return next({ ...input, workflowStartHeaders });
77
+ startUpdateWithStart(input, next) {
78
+ return traced(startUpdateWithStartRunName(input.workflowType), true, (context) =>
79
+ next({
80
+ ...input,
81
+ workflowStartHeaders: withContextHeader(input.workflowStartHeaders, context),
82
+ updateHeaders: withContextHeader(input.updateHeaders, context),
83
+ })
84
+ );
107
85
  },
108
86
  };
109
87
  }
package/src/plugin.ts CHANGED
@@ -19,17 +19,23 @@
19
19
  * @module
20
20
  */
21
21
 
22
- import { Client } from 'langsmith';
22
+ import { Client, isTracingEnabled, type AgentAddress } from 'langsmith';
23
+ import { RunTree } from 'langsmith/run_trees';
23
24
 
24
25
  import type * as nexus from 'nexus-rpc';
25
26
  import { SimplePlugin } from '@temporalio/plugin';
26
27
  import type { ClientOptions } from '@temporalio/client';
28
+ import { Runtime } from '@temporalio/worker';
27
29
  import type { BundleOptions, ReplayWorkerOptions, Worker, WorkerInterceptors, WorkerOptions } from '@temporalio/worker';
28
30
  import { createActivityInboundInterceptor, createNexusInboundInterceptor } from './activity-interceptor';
29
31
  import { createClientInterceptor } from './client-interceptor';
30
32
  import { createLangSmithSinks } from './sinks';
31
33
  import type { EmitterConfig } from './sinks';
34
+ import { requireRunTreeMembers, type Destination } from './run-tree';
35
+ import { WORKER_RUN_TREE_OVERRIDES } from './worker-run-tree';
36
+ import { WORKFLOW_RUN_TREE_OVERRIDES } from './workflow-run-tree';
32
37
  import type { WorkflowLangSmithConfig } from './workflow-interceptors';
38
+ import { replicaRouting } from './routing';
33
39
 
34
40
  // Derived: @temporalio/worker doesn't export WebpackConfiguration from its root.
35
41
  type WebpackConfiguration = Parameters<NonNullable<BundleOptions['webpackConfigHook']>>[0];
@@ -47,8 +53,6 @@ const ASYNC_HOOKS_MODULE = 'async_hooks';
47
53
  * never cross a Temporal boundary — supply a pre-constructed {@link Client}
48
54
  * (which reads `LANGSMITH_API_KEY` from the worker/client process env) or let
49
55
  * the plugin construct a default client from the environment.
50
- *
51
- * @experimental Plugins is an experimental feature; APIs may change without notice.
52
56
  */
53
57
  export interface LangSmithPluginOptions {
54
58
  /**
@@ -57,8 +61,10 @@ export interface LangSmithPluginOptions {
57
61
  * environment. Lives only in the worker/client process — never serialized.
58
62
  */
59
63
  client?: Client;
60
- /** Target LangSmith project for every emitted run. */
64
+ /** Default LangSmith project for new root traces. An inherited destination takes precedence. */
61
65
  projectName?: string;
66
+ /** Agent/environment destination, mutually exclusive with projectName. LangSmith beta. */
67
+ address?: AgentAddress;
62
68
  /**
63
69
  * When `true`, emit first-class runs for Temporal operations themselves
64
70
  * (`StartWorkflow:`, `RunActivity:`, `HandleSignal:`, …) in addition to the
@@ -73,6 +79,16 @@ export interface LangSmithPluginOptions {
73
79
  metadata?: Record<string, unknown>;
74
80
  }
75
81
 
82
+ /** Reads this package's version, which worker heartbeats report. Empty if it can't be read. */
83
+ function packageVersion(): string {
84
+ try {
85
+ // eslint-disable-next-line @typescript-eslint/no-require-imports
86
+ return (require('../package.json') as { version?: string }).version ?? '';
87
+ } catch {
88
+ return '';
89
+ }
90
+ }
91
+
76
92
  /**
77
93
  * Temporal plugin that adds LangSmith observability to a Client + Worker.
78
94
  *
@@ -84,33 +100,52 @@ export interface LangSmithPluginOptions {
84
100
  * const plugin = new LangSmithPlugin({ addTemporalRuns: true });
85
101
  * const worker = await Worker.create({ workflowsPath, taskQueue: 'tq', plugins: [plugin] });
86
102
  * ```
87
- *
88
- * @experimental Plugins is an experimental feature; APIs may change without notice.
89
103
  */
90
104
  export class LangSmithPlugin extends SimplePlugin {
105
+ /** The package version, reported in worker heartbeats. */
106
+ readonly version = packageVersion();
107
+
91
108
  private readonly client: Client;
92
109
  private readonly emitter: EmitterConfig;
93
110
  private readonly workflowConfig: WorkflowLangSmithConfig;
111
+ private readonly drains: (() => Promise<void>)[] = [];
94
112
  // Absolute paths so the workflow bundler resolves them under strict pnpm.
95
113
  private readonly workflowInterceptorModule = require.resolve('./workflow-interceptors');
96
114
  // Target of the `node:async_hooks` rewrite; re-exports the runtime-injected ALS.
97
115
  private readonly asyncHooksShimModule = require.resolve('./async-hooks-shim');
98
-
99
116
  constructor(options: LangSmithPluginOptions = {}) {
100
117
  // super() reads options.name immediately
101
118
  super({ name: 'langchain.LangSmithPlugin' });
119
+ if (options.projectName !== undefined && options.address !== undefined) {
120
+ throw new TypeError('projectName and address are mutually exclusive');
121
+ }
102
122
  this.client = options.client ?? new Client();
123
+ const defaults = new RunTree({
124
+ name: 'temporal-routing-defaults',
125
+ client: this.client,
126
+ project_name: options.projectName,
127
+ address: options.address,
128
+ });
129
+ // Let LangSmith validate and normalize its own address objects.
130
+ const address = options.address === undefined ? undefined : defaults.address;
131
+ const replicas = defaults.replicas;
103
132
  const addTemporalRuns = options.addTemporalRuns ?? false;
104
133
  this.emitter = {
105
134
  client: this.client,
106
135
  addTemporalRuns,
107
- projectName: options.projectName,
136
+ // LangSmith treats an empty project name as unset, so the plugin does too.
137
+ projectName: options.projectName || undefined,
138
+ address,
139
+ replicas,
108
140
  tags: options.tags,
109
141
  metadata: options.metadata,
110
142
  };
111
143
  this.workflowConfig = {
112
144
  addTemporalRuns,
113
- projectName: options.projectName,
145
+ // Resolved here, where LangSmith can read env; inside the isolate it can only fall back to `"default"`.
146
+ destination: pluginDestination(this.client, address, this.emitter.projectName),
147
+ tracingEnabled: isTracingEnabled(),
148
+ replicas: replicaRouting(replicas),
114
149
  tags: options.tags,
115
150
  metadata: options.metadata,
116
151
  };
@@ -133,10 +168,11 @@ export class LangSmithPlugin extends SimplePlugin {
133
168
  }
134
169
 
135
170
  private withLangSmithWorker<T extends WorkerOptions | ReplayWorkerOptions>(options: T): T {
171
+ requireRunTreeMembers(WORKFLOW_RUN_TREE_OVERRIDES, WORKER_RUN_TREE_OVERRIDES);
136
172
  const interceptors: WorkerInterceptors = options.interceptors ?? {};
137
173
 
138
- const activityInbound = [...(interceptors.activityInbound ?? [])];
139
- activityInbound.push(createActivityInboundInterceptor(this.emitter));
174
+ const activity = [...(interceptors.activity ?? [])];
175
+ activity.push((ctx) => ({ inbound: createActivityInboundInterceptor(this.emitter)(ctx) }));
140
176
 
141
177
  const workflowModules = [...(interceptors.workflowModules ?? [])];
142
178
  if (!workflowModules.includes(this.workflowInterceptorModule)) {
@@ -147,12 +183,22 @@ export class LangSmithPlugin extends SimplePlugin {
147
183
  const nexusInterceptors = [...(interceptors.nexus ?? [])];
148
184
  nexusInterceptors.push((_ctx: nexus.OperationContext) => ({ inbound: nexusInbound }));
149
185
 
186
+ const logger = Runtime.instance().logger;
187
+ if (this.workflowConfig.destination === undefined) {
188
+ logger.warn(
189
+ "LangSmith can't name a destination from the environment, so the Temporal plugin traces nothing that starts " +
190
+ 'without a parent run.'
191
+ );
192
+ }
193
+
194
+ const { sinks: langsmithSinks, drain } = createLangSmithSinks(this.client, this.emitter.replicas, logger);
195
+ this.drains.push(drain);
150
196
  // The user's own Worker sinks take precedence on any key collision.
151
- const sinks = { ...createLangSmithSinks(this.client), ...(options.sinks ?? {}) };
197
+ const sinks = { ...langsmithSinks, ...(options.sinks ?? {}) };
152
198
 
153
199
  return {
154
200
  ...options,
155
- interceptors: { ...interceptors, activityInbound, workflowModules, nexus: nexusInterceptors },
201
+ interceptors: { ...interceptors, activity, workflowModules, nexus: nexusInterceptors },
156
202
  sinks,
157
203
  } as T;
158
204
  }
@@ -195,6 +241,8 @@ export class LangSmithPlugin extends SimplePlugin {
195
241
 
196
242
  private async flush(): Promise<void> {
197
243
  try {
244
+ // Sink writes reach the client one at a time, so hand them all over before flushing it.
245
+ await Promise.all(this.drains.map((drain) => drain()));
198
246
  await this.client.awaitPendingTraceBatches();
199
247
  } catch {
200
248
  /* swallow: telemetry flush must never fail worker shutdown */
@@ -202,6 +250,37 @@ export class LangSmithPlugin extends SimplePlugin {
202
250
  }
203
251
  }
204
252
 
253
+ /** The plugin's explicit `address` or `projectName`, else the destination the env names. */
254
+ function pluginDestination(
255
+ client: Client,
256
+ address: AgentAddress | undefined,
257
+ projectName: string | undefined
258
+ ): Destination | undefined {
259
+ if (address !== undefined) {
260
+ return { address };
261
+ }
262
+ if (projectName !== undefined) {
263
+ return { project_name: projectName };
264
+ }
265
+ return envDestination(client);
266
+ }
267
+
268
+ /**
269
+ * The destination LangSmith's env defaults (`LANGSMITH_PROJECT`, `LANGSMITH_AGENT_ID` and
270
+ * `LANGSMITH_AGENT_ENVIRONMENT`) name, as LangSmith's own `RunTree` constructor resolves it for a run that names none;
271
+ * `undefined` when the env can't address a run. The probe run is never posted.
272
+ *
273
+ * @internal
274
+ */
275
+ export function envDestination(client: Client): Destination | undefined {
276
+ // `tracingEnabled: false` stops LangSmith warning here about an env it can't use; its `Client` already warned once.
277
+ const probe = new RunTree({ name: 'temporal-langsmith-destination-probe', client, tracingEnabled: false });
278
+ if (probe.project_name) {
279
+ return { project_name: probe.project_name };
280
+ }
281
+ return probe.address ? { address: probe.address } : undefined;
282
+ }
283
+
205
284
  /**
206
285
  * The slice of webpack's runtime API these rewrites use, read off the running
207
286
  * compiler (see {@link bundleRewritesPlugin}).
@@ -228,8 +307,10 @@ interface WebpackCompiler {
228
307
  }
229
308
 
230
309
  /**
231
- * A webpack plugin that installs the three Workflow-bundle rewrites LangSmith needs:
310
+ * A webpack plugin that installs the four Workflow-bundle rewrites LangSmith needs:
232
311
  *
312
+ * - resolve `langsmith` and `langsmith/*` to the CommonJS build this plugin
313
+ * patches, so ESM Workflow code doesn't load a second, unpatched copy.
233
314
  * - redirect `node:async_hooks` to the shim module that re-exports the
234
315
  * runtime-injected `AsyncLocalStorage`, so LangSmith's `new AsyncLocalStorage()`
235
316
  * and `AsyncLocalStorage.snapshot()` resolve to the real SDK-provided ALS.
@@ -256,6 +337,10 @@ function bundleRewritesPlugin(asyncHooksShimModule: string, definitions: Record<
256
337
  apply(compiler) {
257
338
  const { NormalModuleReplacementPlugin, DefinePlugin } = compiler.webpack;
258
339
 
340
+ new NormalModuleReplacementPlugin(/^langsmith(?:\/|$)/, (resource) => {
341
+ resource.request = require.resolve(resource.request);
342
+ }).apply(compiler);
343
+
259
344
  new NormalModuleReplacementPlugin(/^node:async_hooks$/, (resource) => {
260
345
  resource.request = asyncHooksShimModule;
261
346
  }).apply(compiler);
@@ -41,7 +41,7 @@ export interface LangSmithTraceContext extends Record<string, string> {
41
41
  baggage: string;
42
42
  }
43
43
 
44
- /** Case-insensitive key prefixes scrubbed from runs and propagated headers. */
44
+ /** Case-insensitive key prefixes scrubbed from propagated replica settings. */
45
45
  const SENSITIVE_KEY_PREFIXES: readonly string[] = [
46
46
  'auth',
47
47
  'api_key',
package/src/routing.ts ADDED
@@ -0,0 +1,110 @@
1
+ /** Destination and credential-free replica routing shared across Temporal boundaries. */
2
+
3
+ import { AgentAddress } from 'langsmith';
4
+ import type { RunTreeConfig, WriteReplica } from 'langsmith/run_trees';
5
+ import { scrubSensitive } from './propagation';
6
+
7
+ type Destination = Pick<RunTreeConfig, 'project_name' | 'address'>;
8
+
9
+ export type ReplicaRouting = Pick<WriteReplica, 'projectName' | 'address' | 'primary' | 'updates' | 'reroot'>;
10
+
11
+ const SAFE_UPDATE_FIELDS = new Set(['tags', 'metadata', 'extra', 'reroot']);
12
+
13
+ /** Select one destination, clearing the other mode when inheriting an address. */
14
+ export function destination(preferred?: Destination, fallback?: Destination): Destination {
15
+ const selected = preferred?.address || preferred?.project_name ? preferred : fallback;
16
+ return {
17
+ project_name: selected?.address ? undefined : selected?.project_name,
18
+ address: selected?.address,
19
+ };
20
+ }
21
+
22
+ function safeUpdates(value: unknown): unknown {
23
+ if (value === null || typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
24
+ return value;
25
+ }
26
+ if (Array.isArray(value)) return value.map(safeUpdates);
27
+ if (value && typeof value === 'object' && Object.getPrototypeOf(value) === Object.prototype) {
28
+ return Object.fromEntries(
29
+ Object.entries(scrubSensitive(value as Record<string, unknown>) ?? {})
30
+ .filter(([key]) => !['client', 'apiUrl', 'workspaceId'].includes(key))
31
+ .map(([key, item]) => [key, safeUpdates(item)])
32
+ .filter(([, item]) => item !== undefined)
33
+ );
34
+ }
35
+ return undefined;
36
+ }
37
+
38
+ function replicaFields(replica: WriteReplica): Omit<ReplicaRouting, 'address'> {
39
+ return {
40
+ ...(typeof replica.projectName === 'string' ? { projectName: replica.projectName } : {}),
41
+ ...(typeof replica.primary === 'boolean' ? { primary: replica.primary } : {}),
42
+ ...(typeof replica.reroot === 'boolean' ? { reroot: replica.reroot } : {}),
43
+ ...(replica.updates ? {
44
+ updates: safeUpdates(Object.fromEntries(
45
+ Object.entries(replica.updates).filter(([key]) => SAFE_UPDATE_FIELDS.has(key))
46
+ )) as WriteReplica['updates'],
47
+ } : {}),
48
+ };
49
+ }
50
+
51
+ /** Follow LangSmith's header allowlist; clients, credentials and ingestion URLs stay local. */
52
+ export function replicaRouting(replicas: readonly WriteReplica[] | undefined): ReplicaRouting[] | undefined {
53
+ return replicas?.map((replica) => ({
54
+ ...replicaFields(replica),
55
+ ...(replica.address ? { address: { ...new AgentAddress(replica.address.id, replica.address.environment) } } : {}),
56
+ }));
57
+ }
58
+
59
+ /** The Temporal wire format uses Python's spelling; accept native JS headers too. */
60
+ export function replicaHeaders(replicas: readonly WriteReplica[]): unknown[] {
61
+ return replicaRouting(replicas)!.map(({ projectName, address, ...replica }) => ({
62
+ ...replica,
63
+ ...(projectName === undefined ? {} : { project_name: projectName }),
64
+ // LangSmith and Python use LRN strings on the wire, including older histories.
65
+ ...(address ? { address: `lrn:agents/${address.id}/environments/${address.environment.toLowerCase()}` } : {}),
66
+ }));
67
+ }
68
+
69
+ export function normalizeReplicaHeaders(baggage: string): string {
70
+ return baggage.split(',').map((item) => {
71
+ const prefix = 'langsmith-replicas=';
72
+ if (!item.startsWith(prefix)) return item;
73
+ const replicas: unknown = JSON.parse(decodeURIComponent(item.slice(prefix.length)));
74
+ if (!Array.isArray(replicas)) throw new TypeError('replica routing must be an array');
75
+ const normalized = replicas.map((replica: unknown) => {
76
+ if (Array.isArray(replica)) return { projectName: replica[0], updates: replica[1] } as WriteReplica;
77
+ if (!replica || typeof replica !== 'object') throw new TypeError('replica routing must be an object');
78
+ const record = replica as Record<string, unknown>;
79
+ return { ...record, projectName: record.project_name ?? record.projectName } as WriteReplica;
80
+ });
81
+ // Leave wire addresses for RunTree.fromHeaders to parse and validate.
82
+ const sanitized = normalized.map((replica) => ({
83
+ ...replicaFields(replica),
84
+ ...(replica.address === undefined ? {} : { address: replica.address }),
85
+ }));
86
+ return `${prefix}${encodeURIComponent(JSON.stringify(sanitized))}`;
87
+ }).join(',');
88
+ }
89
+
90
+ /** Restore a destination's credentials from the receiving process's own configuration. */
91
+ export function bindReplicaCredentials(
92
+ replicas: readonly ReplicaRouting[] | undefined,
93
+ localReplicas: readonly WriteReplica[] | undefined
94
+ ): WriteReplica[] | undefined {
95
+ if (replicas === undefined) return localReplicas ? [...localReplicas] : undefined;
96
+ return replicas.map((replica) => {
97
+ const local = localReplicas?.find(
98
+ (candidate) => candidate.projectName === replica.projectName &&
99
+ candidate.address?.kind === replica.address?.kind && candidate.address?.id === replica.address?.id &&
100
+ candidate.address?.environment === replica.address?.environment
101
+ );
102
+ return {
103
+ ...replica,
104
+ apiKey: local?.apiKey,
105
+ apiUrl: local?.apiUrl,
106
+ workspaceId: local?.workspaceId,
107
+ client: local?.client,
108
+ };
109
+ });
110
+ }