@temporalio/langsmith 1.24.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.
package/src/run-tree.ts CHANGED
@@ -3,7 +3,7 @@
3
3
  * run-name builders shared by every interceptor.
4
4
  *
5
5
  * Inside the workflow isolate LangSmith's default `RunTree` is unsafe on two
6
- * counts that {@link ReplaySafeRunTree} fixes:
6
+ * counts that the workflow lifecycle overrides fix:
7
7
  *
8
8
  * 1. **Non-deterministic ids.** Its default random-tailed uuid7 would mint a
9
9
  * fresh id on every replay, flooding the backend with duplicates.
@@ -17,16 +17,13 @@
17
17
  * @internal
18
18
  */
19
19
 
20
- import { RunTree, convertToDottedOrderFormat, type RunTreeConfig } from 'langsmith/run_trees';
21
- import type { Client } from 'langsmith';
22
- import { ApplicationFailure, ApplicationFailureCategory } from '@temporalio/common';
23
- import { getRandomStream, proxySinks, workflowInfo } from '@temporalio/workflow';
20
+ import { __version__ } from 'langsmith';
21
+ import { RunTree, type RunTreeConfig } from 'langsmith/run_trees';
22
+ import { ApplicationFailure, ApplicationFailureCategory, CancelledFailure } from '@temporalio/common';
24
23
 
25
- import { scrubSensitive, type LangSmithTraceContext } from './propagation';
26
- import { LANGSMITH_SINK_NAME, type EmitterConfig, type LangSmithSinks, type SerializedRun } from './sinks';
27
-
28
- /** Named random stream for recorded-path run ids; isolated from the workflow's main RNG. */
29
- const LANGSMITH_RUN_TREE_STREAM = 'package-langsmith-tracing';
24
+ import type { LangSmithTraceContext } from './propagation';
25
+ import type { EmitterConfig, SerializedRun } from './sinks';
26
+ import { destination, normalizeReplicaHeaders, replicaHeaders, replicaRouting } from './routing';
30
27
 
31
28
  /** LangSmith run-type constants used for Temporal-operation runs. */
32
29
  export const RUN_TYPE = {
@@ -75,51 +72,60 @@ export const signalWithStartRunName = (workflowType: string): string => `SignalW
75
72
  export const queryWorkflowRunName = (queryName: string): string => `QueryWorkflow:${queryName}`;
76
73
  /** `StartWorkflowUpdate:<name>` — client update-start marker. */
77
74
  export const startWorkflowUpdateRunName = (updateName: string): string => `StartWorkflowUpdate:${updateName}`;
78
- /** `StartUpdateWithStartWorkflow:<name>` — client update-with-start marker. */
79
- export const startUpdateWithStartRunName = (updateName: string): string => `StartUpdateWithStartWorkflow:${updateName}`;
75
+ /** `StartUpdateWithStartWorkflow:<type>` — client update-with-start marker. */
76
+ export const startUpdateWithStartRunName = (workflowType: string): string =>
77
+ `StartUpdateWithStartWorkflow:${workflowType}`;
78
+
79
+ type RunTreeMember = (this: any, ...args: any[]) => any;
80
+
81
+ /** RunTree members to replace, each mapped to a function that builds the replacement from LangSmith's original. */
82
+ export interface RunTreeOverrides {
83
+ statics: Record<string, (original: RunTreeMember) => RunTreeMember>;
84
+ methods: Record<string, (original: RunTreeMember) => RunTreeMember>;
85
+ }
86
+
87
+ const runTreeOwners = (overrides: RunTreeOverrides) =>
88
+ [
89
+ ['RunTree.', RunTree as unknown as Record<string, RunTreeMember>, overrides.statics],
90
+ ['RunTree.prototype.', RunTree.prototype as unknown as Record<string, RunTreeMember>, overrides.methods],
91
+ ] as const;
80
92
 
81
93
  /**
82
- * True only while replaying genuine history events, when emission must be
83
- * suppressed. Deliberately `isReplayingHistoryEvents`, NOT `isReplaying`: for
84
- * live read-only handlers (queries, update validators) `isReplaying` is `true`
85
- * but `isReplayingHistoryEvents` is `false`, so their runs still emit. Matches
86
- * how the SDK gates `callDuringReplay: false` sinks.
94
+ * Throw, naming each one, unless every member the overrides replace is a function. The Workflow bundle may carry a
95
+ * different LangSmith copy than the Worker, so both check.
87
96
  */
88
- function isReplaying(): boolean {
89
- return workflowInfo().unsafe.isReplayingHistoryEvents;
97
+ export function requireRunTreeMembers(...overrides: RunTreeOverrides[]): void {
98
+ const missing = new Set(
99
+ overrides.flatMap((override) =>
100
+ runTreeOwners(override).flatMap(([label, owner, members]) =>
101
+ Object.keys(members)
102
+ .filter((name) => typeof owner[name] !== 'function')
103
+ .map((name) => `${label}${name}`)
104
+ )
105
+ )
106
+ );
107
+ if (missing.size > 0) {
108
+ throw new Error(`@temporalio/langsmith does not support LangSmith ${__version__}: missing ${[...missing].join(', ')}`);
109
+ }
90
110
  }
91
111
 
92
- let cachedSinks: LangSmithSinks | undefined;
93
- /** Lazily-resolved workflow Sink proxy (must be called inside a workflow). */
94
- function sinks(): LangSmithSinks {
95
- if (cachedSinks === undefined) {
96
- cachedSinks = proxySinks<LangSmithSinks>();
112
+ /** Replace the overridden RunTree members, or none if any is missing. */
113
+ export function patchRunTree(overrides: RunTreeOverrides): void {
114
+ requireRunTreeMembers(overrides);
115
+ for (const [, owner, members] of runTreeOwners(overrides)) {
116
+ for (const [name, override] of Object.entries(members)) {
117
+ owner[name] = override(owner[name]!);
118
+ }
97
119
  }
98
- return cachedSinks;
99
120
  }
100
121
 
101
- /**
102
- * A no-op LangSmith client. {@link ReplaySafeRunTree} never lets the underlying
103
- * `RunTree` perform network I/O — emission goes through the Sink — so the
104
- * client it carries must do nothing and must never read env / open sockets
105
- * inside the isolate.
106
- */
107
- const NOOP_CLIENT = {
108
- createRun: async (): Promise<void> => {},
109
- updateRun: async (): Promise<void> => {},
110
- } as unknown as Client;
111
-
112
122
  /** Flatten a {@link RunTree} into the plain wire shape consumed by the Sink. */
113
- function serializeRun(run: RunTree): SerializedRun {
114
- const extra = run.extra ? { ...run.extra } : undefined;
115
- if (extra && extra.metadata && typeof extra.metadata === 'object') {
116
- extra.metadata = scrubSensitive(extra.metadata as Record<string, unknown>);
117
- }
123
+ export function serializeRun(run: RunTree): SerializedRun {
118
124
  return {
119
125
  id: run.id,
120
126
  trace_id: run.trace_id,
121
127
  dotted_order: run.dotted_order,
122
- parent_run_id: run.parent_run_id,
128
+ parent_run_id: run.parent_run?.id ?? run.parent_run_id,
123
129
  name: run.name,
124
130
  run_type: run.run_type,
125
131
  start_time: run.start_time,
@@ -127,9 +133,12 @@ function serializeRun(run: RunTree): SerializedRun {
127
133
  inputs: run.inputs as Record<string, unknown> | undefined,
128
134
  outputs: run.outputs as Record<string, unknown> | undefined,
129
135
  error: run.error,
130
- extra,
136
+ extra: run.extra ? { ...run.extra } : undefined,
131
137
  tags: run.tags,
132
138
  project_name: run.project_name,
139
+ address: run.address,
140
+ replicas: replicaRouting(run.replicas),
141
+ distributedParentId: run.distributedParentId,
133
142
  events: run.events as Record<string, unknown>[] | undefined,
134
143
  };
135
144
  }
@@ -143,11 +152,8 @@ function serializeRun(run: RunTree): SerializedRun {
143
152
  * failures produce `"<type>: <message>"`.
144
153
  */
145
154
  export function describeError(err: unknown): string | undefined {
146
- if (err instanceof ApplicationFailure) {
147
- if (err.category === ApplicationFailureCategory.BENIGN) {
148
- return undefined;
149
- }
150
- return `${err.type ?? 'ApplicationError'}: ${err.message}`;
155
+ if (err instanceof ApplicationFailure && err.category === ApplicationFailureCategory.BENIGN) {
156
+ return undefined;
151
157
  }
152
158
  if (err instanceof Error) {
153
159
  return `${err.name}: ${err.message}`;
@@ -155,33 +161,96 @@ export function describeError(err: unknown): string | undefined {
155
161
  return String(err);
156
162
  }
157
163
 
158
- /** Coerce an arbitrary operation result into a LangSmith outputs object. */
159
- export function asOutputs(result: unknown): Record<string, unknown> {
160
- if (result !== null && typeof result === 'object' && !Array.isArray(result)) {
161
- return result as Record<string, unknown>;
164
+ /** Outputs of a plugin run that ends without an error. Plugin runs never record Temporal arguments or results. */
165
+ export function statusOutputs(status: 'ok' | 'cancelled' | 'continued_as_new'): Record<string, unknown> {
166
+ return { status };
167
+ }
168
+
169
+ /** The `RunTree.end` arguments that close a plugin run. */
170
+ export type RunEnd = [outputs: Record<string, unknown> | undefined, error: string | undefined];
171
+
172
+ /** The `RunTree.end` arguments for a plugin run whose operation threw `err`; cancellation isn't an error. */
173
+ export function thrownEnd(err: unknown): RunEnd {
174
+ if (err instanceof CancelledFailure) {
175
+ return [statusOutputs('cancelled'), undefined];
162
176
  }
163
- return { result };
177
+ return [undefined, describeError(err)];
164
178
  }
165
179
 
166
- /** The trace context to propagate for `run`, or `undefined` when absent. */
167
- export function runHeaders(run: RunTree | undefined): LangSmithTraceContext | undefined {
168
- return run ? (run.toHeaders() as LangSmithTraceContext) : undefined;
180
+ /** Run `fn`, then end and patch the already-posted `run` with an ok status, or with `endThrown` of what `fn` threw. */
181
+ export async function wrapWithRun<T>(
182
+ run: RunTree,
183
+ fn: () => Promise<T>,
184
+ endThrown: (err: unknown) => RunEnd = thrownEnd
185
+ ): Promise<T> {
186
+ let end: RunEnd = [statusOutputs('ok'), undefined];
187
+ try {
188
+ return await fn();
189
+ } catch (err) {
190
+ end = endThrown(err);
191
+ throw err;
192
+ } finally {
193
+ await run.end(...end);
194
+ await run.patchRun();
195
+ }
196
+ }
197
+
198
+ /** Runs suppressed because the worker has no usable destination, or its env turns off a trace starting here. */
199
+ const untracedRuns = new WeakSet<RunTree>();
200
+
201
+ export function isUntraced(run: RunTree): boolean {
202
+ return untracedRuns.has(run);
169
203
  }
170
204
 
171
- /** Emit a short-lived marker run. */
172
- export async function emitMarkerRun(marker: RunTree): Promise<void> {
173
- await marker.postRun();
174
- await marker.end({});
175
- await marker.patchRun();
205
+ export function suppressRun(run: RunTree): void {
206
+ untracedRuns.add(run);
176
207
  }
177
208
 
178
- /** Reconstruct a propagated parent {@link RunTree} from a trace context; never throws. */
179
- export function runTreeFromContext(ctx: LangSmithTraceContext | undefined): RunTree | undefined {
209
+ /**
210
+ * The trace context to propagate for `run`, or `undefined` when no LangSmith run exists to parent under: no run, a
211
+ * run with no destination, or a run LangSmith won't trace (`tracingEnabled: false`). LangSmith turns tracing off for
212
+ * a run built in an env it can't use, such as a client marker.
213
+ */
214
+ export function runHeaders(run: RunTree | undefined): LangSmithTraceContext | undefined {
215
+ if (!run || run.tracingEnabled === false || isUntraced(run)) {
216
+ return undefined;
217
+ }
218
+ const headers = run.toHeaders() as LangSmithTraceContext;
219
+ const baggage = headers.baggage.split(',').filter(
220
+ (item) => !item.startsWith('langsmith-replicas=') && !item.startsWith('langsmith-metadata=')
221
+ );
222
+ const metadata = run.extra?.metadata as Record<string, unknown> | undefined;
223
+ if (metadata && Object.keys(metadata).length > 0) {
224
+ baggage.push(`langsmith-metadata=${encodeURIComponent(JSON.stringify(metadata))}`);
225
+ }
226
+ const replicas = replicaRouting(run.replicas);
227
+ if (replicas !== undefined) baggage.push(`langsmith-replicas=${encodeURIComponent(JSON.stringify(replicaHeaders(replicas)))}`);
228
+ headers.baggage = baggage.filter(Boolean).join(',');
229
+ return headers;
230
+ }
231
+
232
+ /**
233
+ * A run's destination: a LangSmith project, or an agent address (LangSmith's `RunTreeConfig.address`, in the
234
+ * installed version's own form).
235
+ */
236
+ export type Destination = Pick<RunTreeConfig, 'project_name' | 'address'>;
237
+
238
+ /**
239
+ * Reconstruct a propagated parent {@link RunTree} from a trace context; never throws. LangSmith's `RunTree.fromHeaders`
240
+ * lets the context's destination outrank `fallback`, so `fallback` applies only when the context names none.
241
+ */
242
+ export function runTreeFromContext(
243
+ ctx: LangSmithTraceContext | undefined,
244
+ fallback?: Destination
245
+ ): RunTree | undefined {
180
246
  if (!ctx) {
181
247
  return undefined;
182
248
  }
183
249
  try {
184
- return RunTree.fromHeaders(ctx) ?? undefined;
250
+ const run = RunTree.fromHeaders({ ...ctx, baggage: normalizeReplicaHeaders(ctx.baggage ?? '') }, fallback);
251
+ if (!run) return undefined;
252
+ run.replicas = replicaRouting(run.replicas);
253
+ return run;
185
254
  } catch {
186
255
  return undefined;
187
256
  }
@@ -191,7 +260,8 @@ interface RunTreeParams {
191
260
  name: string;
192
261
  runType: string;
193
262
  parent: RunTree | undefined;
194
- inputs?: Record<string, unknown>;
263
+ /** Merged over the plugin's metadata. */
264
+ metadata?: Record<string, unknown>;
195
265
  }
196
266
 
197
267
  /**
@@ -202,129 +272,13 @@ export function buildRunTree(config: EmitterConfig, params: RunTreeParams): RunT
202
272
  return new RunTree({
203
273
  name: params.name,
204
274
  run_type: params.runType,
205
- inputs: params.inputs ?? {},
275
+ inputs: {},
206
276
  parent_run: params.parent,
207
277
  client: config.client,
208
- project_name: config.projectName ?? params.parent?.project_name,
278
+ ...destination(params.parent, { project_name: config.projectName, address: config.address }),
279
+ replicas: params.parent?.replicas ?? config.replicas,
209
280
  tags: config.tags,
210
- extra: { metadata: scrubSensitive(config.metadata) ?? {} },
281
+ extra: { metadata: { ...config.metadata, ...params.metadata } },
211
282
  tracingEnabled: true,
212
283
  });
213
284
  }
214
-
215
- /**
216
- * A {@link RunTree} subclass safe to construct and drive from workflow code.
217
- *
218
- * Subclasses rather than wraps because LangSmith's `traceable` resolves its
219
- * parent with `instanceof RunTree` before calling `parent.createChild(...)`, so
220
- * a plain wrapper would refuse to nest under it.
221
- *
222
- * @internal
223
- */
224
- export class ReplaySafeRunTree extends RunTree {
225
- // Per-invocation run-id factory. Supplied by read-only handlers (queries, update
226
- // validators) so their ids don't draw from the Workflow main PRNG; left
227
- // undefined on recorded paths, where id minting falls back to the isolated
228
- // LANGSMITH_RUN_TREE_STREAM named stream. Propagated to every child so the whole
229
- // subtree mints from one factory.
230
- protected readonly generateNewUuid4?: () => string;
231
-
232
- constructor(config: RunTreeConfig, generateNewUuid4?: () => string) {
233
- super(ReplaySafeRunTree.fill(config, generateNewUuid4));
234
- this.generateNewUuid4 = generateNewUuid4;
235
- }
236
-
237
- private static fill(config: RunTreeConfig, generateNewUuid4?: () => string): RunTreeConfig {
238
- const id =
239
- config.id ?? (generateNewUuid4 ? generateNewUuid4() : getRandomStream(LANGSMITH_RUN_TREE_STREAM).uuid4());
240
- const start_time = config.start_time ?? Date.now();
241
- const trace_id = config.trace_id ?? config.parent_run?.trace_id ?? id;
242
- let dotted_order = config.dotted_order;
243
- if (dotted_order == null) {
244
- const startMs = typeof start_time === 'number' ? start_time : Date.parse(String(start_time));
245
- const { dottedOrder } = convertToDottedOrderFormat(startMs, id);
246
- const parentDotted = config.parent_run?.dotted_order;
247
- dotted_order = parentDotted ? `${parentDotted}.${dottedOrder}` : dottedOrder;
248
- }
249
- return {
250
- ...config,
251
- id,
252
- start_time,
253
- trace_id,
254
- dotted_order,
255
- parent_run_id: config.parent_run_id ?? config.parent_run?.id,
256
- client: NOOP_CLIENT,
257
- tracingEnabled: config.tracingEnabled ?? true,
258
- };
259
- }
260
-
261
- /** Produce a replay-safe child so deeply-nested `traceable` runs stay deterministic. */
262
- override createChild(config: RunTreeConfig): ReplaySafeRunTree {
263
- const child = new ReplaySafeRunTree(
264
- {
265
- ...config,
266
- run_type: config.run_type ?? RUN_TYPE.CHAIN,
267
- parent_run: this,
268
- parent_run_id: this.id,
269
- trace_id: this.trace_id,
270
- project_name: config.project_name ?? this.project_name,
271
- },
272
- this.generateNewUuid4
273
- );
274
- this.child_runs.push(child);
275
- return child;
276
- }
277
-
278
- /** Emit a `createRun` via the Sink, unless replaying. */
279
- override async postRun(): Promise<void> {
280
- if (isReplaying()) {
281
- return;
282
- }
283
- sinks()[LANGSMITH_SINK_NAME].createRun(serializeRun(this));
284
- }
285
-
286
- /** Record outputs/end-time locally then emit an `updateRun` via the Sink, unless replaying. */
287
- override async patchRun(): Promise<void> {
288
- if (isReplaying()) {
289
- return;
290
- }
291
- sinks()[LANGSMITH_SINK_NAME].updateRun(serializeRun(this));
292
- }
293
-
294
- /** Record end-time / outputs / error on the run object (pure, replay-safe). */
295
- override async end(outputs?: Record<string, unknown>, error?: string, endTime?: number): Promise<void> {
296
- if (outputs !== undefined) {
297
- this.outputs = outputs;
298
- }
299
- if (error !== undefined) {
300
- this.error = error;
301
- }
302
- this.end_time = endTime ?? Date.now();
303
- }
304
- }
305
-
306
- /**
307
- * A placeholder, never-emitted parent whose {@link createChild} produces
308
- * independent root children. Installed as the ambient so a workflow-body
309
- * `traceable` takes LangSmith's `createChild` branch (deterministic id) instead
310
- * of the no-parent branch that mints a uuid via `crypto`, which the isolate lacks.
311
- *
312
- * @internal
313
- */
314
- export class _RootReplaySafeRunTreeFactory extends ReplaySafeRunTree {
315
- /** Produce a replay-safe child with no link back to this factory. */
316
- override createChild(config: RunTreeConfig): ReplaySafeRunTree {
317
- return new ReplaySafeRunTree(
318
- {
319
- ...config,
320
- run_type: config.run_type ?? RUN_TYPE.CHAIN,
321
- project_name: config.project_name ?? this.project_name,
322
- },
323
- this.generateNewUuid4
324
- );
325
- }
326
-
327
- override async postRun(): Promise<void> {}
328
-
329
- override async patchRun(): Promise<void> {}
330
- }
package/src/sinks.ts CHANGED
@@ -4,9 +4,12 @@
4
4
  * @module
5
5
  */
6
6
 
7
- import { isTracingEnabled, type Client } from 'langsmith';
7
+ import type { Client } from 'langsmith';
8
+ import { RunTree, type RunTreeConfig, type WriteReplica } from 'langsmith/run_trees';
9
+ import type { Logger } from '@temporalio/common';
8
10
  import type { Sinks } from '@temporalio/workflow';
9
11
  import type { InjectedSinks } from '@temporalio/worker';
12
+ import { bindReplicaCredentials, type ReplicaRouting } from './routing';
10
13
 
11
14
  /** Plain-JSON description of a LangSmith run crossing the isolate→worker boundary. */
12
15
  export interface SerializedRun {
@@ -26,6 +29,9 @@ export interface SerializedRun {
26
29
  extra?: Record<string, unknown>;
27
30
  tags?: string[];
28
31
  project_name?: string;
32
+ address?: RunTreeConfig['address'];
33
+ replicas?: ReplicaRouting[];
34
+ distributedParentId?: string;
29
35
  events?: Record<string, unknown>[];
30
36
  }
31
37
 
@@ -37,6 +43,9 @@ export interface EmitterConfig {
37
43
  addTemporalRuns: boolean;
38
44
  /** Target LangSmith project. */
39
45
  projectName?: string;
46
+ address?: RunTreeConfig['address'];
47
+ /** Full replica configuration is local to the client/worker process. */
48
+ replicas?: WriteReplica[];
40
49
  /** Tags attached to every emitted run. */
41
50
  tags?: string[];
42
51
  /** Metadata merged into every emitted run. */
@@ -52,68 +61,53 @@ export interface LangSmithSinks extends Sinks {
52
61
  /** Emit a `createRun` for a newly started run. */
53
62
  createRun(run: SerializedRun): void;
54
63
  /** Emit an `updateRun` (end / outputs / error / events) for a run. */
55
- updateRun(run: SerializedRun): void;
64
+ updateRun(run: SerializedRun, options?: Parameters<RunTree['patchRun']>[0]): void;
56
65
  };
57
66
  }
58
67
 
59
- // langsmith's CreateRunParams omits tags, but createRun spreads them into the request at runtime.
60
- function toCreateParams(run: SerializedRun): Parameters<Client['createRun']>[0] & { tags?: string[] } {
61
- return {
62
- id: run.id,
63
- trace_id: run.trace_id,
64
- dotted_order: run.dotted_order,
65
- parent_run_id: run.parent_run_id,
66
- name: run.name,
67
- run_type: run.run_type,
68
- start_time: run.start_time,
68
+ function emissionRun(run: SerializedRun, client: Client, replicas: WriteReplica[] | undefined): RunTree {
69
+ const tree = new RunTree({
70
+ ...run,
69
71
  inputs: run.inputs ?? {},
70
- extra: run.extra,
71
- tags: run.tags,
72
- project_name: run.project_name,
73
- };
72
+ client,
73
+ replicas: bindReplicaCredentials(run.replicas, replicas),
74
+ tracingEnabled: true,
75
+ });
76
+ tree.events = run.events as RunTree['events'];
77
+ return tree;
74
78
  }
75
79
 
76
- function toUpdateParams(run: SerializedRun): Parameters<Client['updateRun']>[1] {
77
- return {
78
- end_time: run.end_time,
79
- outputs: run.outputs,
80
- error: run.error,
81
- extra: run.extra,
82
- tags: run.tags,
83
- events: run.events,
84
- dotted_order: run.dotted_order,
85
- trace_id: run.trace_id,
86
- parent_run_id: run.parent_run_id,
80
+ /**
81
+ * Build the worker-side {@link InjectedSinks} routing serialized runs to a real LangSmith client, and a `drain` that
82
+ * resolves once every queued write has reached the client.
83
+ */
84
+ export function createLangSmithSinks(
85
+ client: Client,
86
+ replicas: WriteReplica[] | undefined,
87
+ logger: Logger
88
+ ): { sinks: InjectedSinks<LangSmithSinks>; drain: () => Promise<void> } {
89
+ // Writes run one at a time in call order, so an update never overtakes its create.
90
+ let writes = Promise.resolve();
91
+ // The Workflow already decided whether to trace each run, so the env isn't checked again here.
92
+ const enqueue = (write: () => Promise<void>): void => {
93
+ // Emission must never fail the workflow.
94
+ writes = writes.then(write).catch((err: unknown) => {
95
+ logger.error(`LangSmith background I/O error: ${String(err)}`);
96
+ });
87
97
  };
88
- }
89
-
90
- /** Build the worker-side {@link InjectedSinks} routing serialized runs to a real LangSmith client. */
91
- export function createLangSmithSinks(client: Client): InjectedSinks<LangSmithSinks> {
92
98
  return {
93
- [LANGSMITH_SINK_NAME]: {
94
- createRun: {
95
- fn: (_info, run) => {
96
- // Honor the LangSmith tracing gate at the real-env emission point.
97
- if (!isTracingEnabled()) {
98
- return;
99
- }
100
- void Promise.resolve(client.createRun(toCreateParams(run))).catch(() => {
101
- /* swallow: emission must never fail the workflow */
102
- });
99
+ sinks: {
100
+ [LANGSMITH_SINK_NAME]: {
101
+ createRun: {
102
+ fn: (_info, run) => enqueue(() => emissionRun(run, client, replicas).postRun()),
103
+ callDuringReplay: false,
103
104
  },
104
- callDuringReplay: false,
105
- },
106
- updateRun: {
107
- fn: (_info, run) => {
108
- if (!isTracingEnabled()) {
109
- return;
110
- }
111
- void Promise.resolve(client.updateRun(run.id, toUpdateParams(run))).catch(() => {
112
- /* swallow: emission must never fail the workflow */
113
- });
105
+ updateRun: {
106
+ fn: (_info, run, options) => enqueue(() => emissionRun(run, client, replicas).patchRun(options)),
107
+ callDuringReplay: false,
114
108
  },
115
- callDuringReplay: false,
116
109
  },
117
110
  },
111
+ drain: () => writes,
118
112
  };
119
113
  }
@@ -0,0 +1,47 @@
1
+ /** Scoped LangSmith defaults for worker handlers with no propagated parent. */
2
+
3
+ import { AsyncLocalStorage } from 'node:async_hooks';
4
+ import type { RunTree, RunTreeConfig } from 'langsmith/run_trees';
5
+ import { AsyncLocalStorageProviderSingleton } from 'langsmith/singletons/traceable';
6
+ import { patchRunTree, type RunTreeOverrides } from './run-tree';
7
+ import type { EmitterConfig } from './sinks';
8
+
9
+ const context = new AsyncLocalStorage<EmitterConfig>();
10
+ let installed = false;
11
+
12
+ export const WORKER_RUN_TREE_OVERRIDES: RunTreeOverrides = {
13
+ statics: {
14
+ getSharedClient: (original) =>
15
+ function (this: typeof RunTree, ...args: unknown[]) {
16
+ return context.getStore()?.client ?? original.apply(this, args);
17
+ },
18
+ },
19
+ methods: {
20
+ _resolveAddressing: (original) =>
21
+ function (this: RunTree, config: RunTreeConfig, ...args: unknown[]) {
22
+ const defaults = context.getStore();
23
+ if (!defaults) return original.call(this, config, ...args);
24
+ this.replicas ??= defaults.replicas;
25
+ // Explicit destinations and native child inheritance outrank the plugin.
26
+ const selected = config.project_name || config.address != null
27
+ ? config
28
+ : { ...config, project_name: defaults.projectName, address: defaults.address };
29
+ return original.call(this, selected, ...args);
30
+ },
31
+ },
32
+ };
33
+
34
+ function installDefaults(): void {
35
+ if (installed) return;
36
+ patchRunTree(WORKER_RUN_TREE_OVERRIDES);
37
+ installed = true;
38
+ }
39
+
40
+ /** Supply native roots with defaults without installing an ambient RunTree. */
41
+ export function withRunTreeDefaults<T>(config: EmitterConfig, fn: () => T): T {
42
+ installDefaults();
43
+ const storage = AsyncLocalStorageProviderSingleton.getInstance() as {
44
+ run<T>(store: undefined, fn: () => T): T;
45
+ };
46
+ return context.run(config, () => storage.run(undefined, fn));
47
+ }