@temporalio/langsmith 1.20.0

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License
+
+Copyright (c) 2021-2025 Temporal Technologies Inc. All rights reserved.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -0,0 +1,216 @@
+# @temporalio/langsmith — LangSmith tracing for Temporal
+
+This plugin makes [LangSmith](https://docs.smith.langchain.com/) observability
+work inside Temporal Workflows and Activities **without changing your existing
+instrumentation**. Code you already trace with LangSmith's native `traceable`
+keeps working when you move it into a Workflow or Activity body — you only add
+the plugin to your `Client` and `Worker`.
+
+This plugin is built on Temporal's Plugin API, which is experimental; its APIs
+may change in a future release.
+
+It handles the parts that are otherwise hard:
+
+- **Replay safety.** Workflows replay history; a naive tracer re-emits every run
+  on every replay and floods your project with duplicates. This plugin emits
+  runs with deterministic IDs out-of-isolate via a Temporal Sink that does not
+  fire during replay.
+- **Run parenting across boundaries.** A trace started on the client threads
+  through `workflow → activity → child-workflow → Nexus` so the runs nest the
+  way you expect, instead of fragmenting into disconnected roots.
+
+## Install
+
+```bash
+npm install @temporalio/langsmith langsmith
+```
+
+`langsmith` is a peer dependency — install the version your project already uses.
+
+## Enable tracing
+
+Tracing is **off by default**, matching the `langsmith` library: the plugin
+emits nothing unless LangSmith tracing is enabled in the worker/client process
+environment. Enable it with LangSmith's standard environment variables:
+
+```bash
+export LANGSMITH_TRACING=true
+export LANGSMITH_API_KEY="<your key>"
+```
+
+The plugin reads the same flags LangSmith itself uses (`LANGSMITH_TRACING` /
+`LANGSMITH_TRACING_V2` and their `LANGCHAIN_` aliases); with none set to `true`,
+tracing stays off and the plugin is a no-op.
+
+## Hello world
+
+Your existing LangSmith instrumentation does not change. Here a `traceable`
+runs inside an Activity:
+
+```typescript
+// activities.ts
+import { traceable } from 'langsmith/traceable';
+
+const callModel = traceable(
+  async (prompt: string) => {
+    // ... your real model call ...
+    return `answer to: ${prompt}`;
+  },
+  { name: 'inner_llm_call' }
+);
+
+export async function answer(prompt: string): Promise<string> {
+  return callModel(prompt);
+}
+```
+
+```typescript
+// workflows.ts
+import { proxyActivities } from '@temporalio/workflow';
+import type * as activities from './activities';
+
+const { answer } = proxyActivities<typeof activities>({
+  startToCloseTimeout: '1 minute',
+});
+
+export async function GreetingWorkflow(prompt: string): Promise<string> {
+  return answer(prompt);
+}
+```
+
+The only new code is the plugin registration on the `Client` and the `Worker`:
+
+```typescript
+// worker.ts
+import { Worker } from '@temporalio/worker';
+import { Client } from '@temporalio/client';
+import { Client as LangSmithClient } from 'langsmith';
+import { LangSmithPlugin } from '@temporalio/langsmith';
+import * as activities from './activities';
+
+const langsmith = new LangSmithClient(); // reads LANGSMITH_API_KEY from the env
+
+// In TypeScript the Client and Worker are configured independently, so add the
+// plugin to each. (Construct one plugin instance and share it.)
+const plugin = new LangSmithPlugin({ client: langsmith, addTemporalRuns: true });
+
+const client = new Client({ plugins: [plugin] });
+
+const worker = await Worker.create({
+  taskQueue: 'greeting',
+  workflowsPath: require.resolve('./workflows'),
+  activities,
+  plugins: [plugin],
+});
+
+await worker.run();
+```
+
+```typescript
+// starter.ts — start the workflow from inside your own trace
+import { traceable } from 'langsmith/traceable';
+
+const pipeline = traceable(
+  async () => {
+    return client.workflow.execute(GreetingWorkflow, {
+      taskQueue: 'greeting',
+      workflowId: 'greeting-1',
+      args: ['hello'],
+    });
+  },
+  { name: 'user_pipeline' }
+);
+
+await pipeline();
+```
+
+With `addTemporalRuns: true`, the resulting trace nests like this:
+
+```
+user_pipeline
+  StartWorkflow:GreetingWorkflow
+  RunWorkflow:GreetingWorkflow
+    StartActivity:answer
+    RunActivity:answer
+      inner_llm_call
+```
+
+Set `addTemporalRuns: false` (the default) to emit only your own `traceable`
+runs — the trace context still propagates across boundaries, so they nest
+correctly, but no `StartWorkflow:` / `RunActivity:` scaffolding is added:
+
+```
+user_pipeline
+  inner_llm_call
+```
+
+## Options
+
+| Option            | Default           | Meaning                                                                                                                                        |
+| ----------------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| `client`          | `new Client()`    | The LangSmith client runs are emitted to. Lives only in the worker/client process — it is never serialized or sent across a Temporal boundary. |
+| `addTemporalRuns` | `false`           | Emit first-class runs for Temporal operations (`StartWorkflow:`, `RunActivity:`, `HandleSignal:`, …) in addition to your `traceable` runs.     |
+| `projectName`     | LangSmith default | Target LangSmith project for emitted runs.                                                                                                     |
+| `tags`            | —                 | Tags attached to every run the plugin emits.                                                                                                   |
+| `metadata`        | —                 | Metadata merged into every run the plugin emits. Credential-looking keys are scrubbed before emission.                                         |
+
+The LangSmith API key is never accepted as a plugin option and never crosses a
+Temporal boundary. Supply a pre-constructed `Client` (which reads
+`LANGSMITH_API_KEY` from the process environment) or let the plugin build a
+default client from the environment.
+
+## Where `traceable` works
+
+`traceable` from `langsmith/traceable` works **unchanged** in every position
+below. Each row is exercised by the plugin's test suite.
+
+| Position                                         | Works? | Notes                                                                                                                                                              |
+| ------------------------------------------------ | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Client side, before `client.workflow.start(...)` | ✅     | The trace propagates into the workflow; `RunWorkflow:` nests under your run.                                                                                       |
+| Inside an **Activity** body                      | ✅     | Runs in the real worker process. Nests under `RunActivity:` (or under the propagated parent when `addTemporalRuns: false`).                                        |
+| Inside a **Workflow** body                       | ✅     | Replay-safe: deterministic IDs, emitted out-of-isolate, suppressed on replay. Works whether or not a parent trace is propagated in.                                |
+| Inside **signal / query / update** handlers      | ✅     | Handler-body `traceable` runs nest under the handler's run (workflow-body semantics). Temporal-internal queries (`__temporal*`, `__stack_trace`) are never traced. |
+
+**Concurrency caveat (workflow body only).** Inside a Workflow, parent
+resolution uses a synchronous context stack rather than `node:async_hooks`
+(which is unavailable in the workflow isolate). Sequential `await inner(...)`
+nesting is exact. Under `Promise.all(...)` fan-out, or for `traceable` calls
+made _after_ an `await` in the same scope, parenting falls back to the workflow
+run. This affects only the visual shape of the trace, never workflow history or
+control flow. Activity-body and client-side `traceable` use LangSmith's real
+async context and are unaffected.
+
+## Process-wide effects to be aware of
+
+- **Workflow context provider.** Loading the plugin's workflow interceptor
+  module installs a global LangSmith async-context provider inside the workflow
+  isolate (via `AsyncLocalStorageProviderSingleton.initializeGlobalInstance`).
+  This is what lets unchanged `traceable` calls find their parent inside a
+  Workflow. It is scoped to the workflow bundle and does not affect your
+  client/worker process context.
+
+## Composing with other plugins
+
+Register observability **first** (outermost) so it observes everything beneath
+it, then governance, then agent-framework plugins:
+
+```typescript
+const worker = await Worker.create({
+  taskQueue: 'tq',
+  workflowsPath: require.resolve('./workflows'),
+  activities,
+  plugins: [
+    new LangSmithPlugin({ client: langsmith }), // observability — first
+    // new GovernancePlugin(...),
+    // new AgentFrameworkPlugin(...),
+  ],
+});
+```
+
+The plugin is safe to register on both the `Client` and the `Worker`; it
+de-duplicates its own interceptors and sinks, so a worker built from a
+plugin-configured client will not double-instrument.
+
+## License
+
+MIT

package/lib/activity-interceptor.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Activity-side and Nexus-handler-side LangSmith interceptors. Both run in the
+ * real Node worker process and install the reconstructed run via `withRunTree`
+ * so a user's unchanged body `traceable` calls nest under it.
+ *
+ * @module
+ */
+import type { ActivityInboundCallsInterceptorFactory, NexusInboundCallsInterceptor } from '@temporalio/worker';
+import type { EmitterConfig } from './sinks';
+/**
+ * Build the activity-inbound interceptor factory. The worker calls the factory
+ * once per activity with that activity's {@link ActivityContext}, from which we
+ * read the activity type for the run name.
+ */
+export declare function createActivityInboundInterceptor(config: EmitterConfig): ActivityInboundCallsInterceptorFactory;
+/**
+ * Build the Nexus-handler interceptor. `startOperation` opens a
+ * `RunStartNexusOperationHandler:` run (so workflows the handler starts nest
+ * under it); `cancelOperation` opens `RunCancelNexusOperationHandler:`.
+ */
+export declare function createNexusInboundInterceptor(config: EmitterConfig): NexusInboundCallsInterceptor;

package/lib/activity-interceptor.js

@@ -0,0 +1,121 @@
+"use strict";
+/**
+ * Activity-side and Nexus-handler-side LangSmith interceptors. Both run in the
+ * real Node worker process and install the reconstructed run via `withRunTree`
+ * so a user's unchanged body `traceable` calls nest under it.
+ *
+ * @module
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createActivityInboundInterceptor = createActivityInboundInterceptor;
+exports.createNexusInboundInterceptor = createNexusInboundInterceptor;
+const langsmith_1 = require("langsmith");
+const run_trees_1 = require("langsmith/run_trees");
+const traceable_1 = require("langsmith/traceable");
+const propagation_1 = require("./propagation");
+const run_tree_1 = require("./run-tree");
+/**
+ * Reconstruct the propagated parent run from a LangSmith trace context, wired to
+ * the plugin-configured client so descendant runs emit to the right place. The
+ * returned run is the *parent* — never posted itself — used only to parent
+ * the operation run (or directly as ambient when `addTemporalRuns` is off).
+ */
+function reconstructParentRun(config, ctx) {
+    const parsed = (0, run_tree_1.runTreeFromContext)(ctx);
+    if (!parsed) {
+        return undefined;
+    }
+    return new run_trees_1.RunTree({
+        name: parsed.name || 'parent',
+        run_type: parsed.run_type || run_tree_1.RUN_TYPE.CHAIN,
+        id: parsed.id,
+        trace_id: parsed.trace_id,
+        dotted_order: parsed.dotted_order,
+        parent_run_id: parsed.parent_run_id,
+        project_name: config.projectName ?? parsed.project_name,
+        client: config.client,
+        // Force-enable so nested body `traceable` runs emit; tracing gate is `isTracingEnabled()`.
+        tracingEnabled: true,
+    });
+}
+/**
+ * Run `fn` with `op` installed as the active LangSmith run, emitting the run
+ * around the call. Shared by activity and Nexus handlers.
+ */
+async function traceOperation(op, fn) {
+    await op.postRun();
+    try {
+        const result = await (0, traceable_1.withRunTree)(op, fn);
+        await op.end((0, run_tree_1.asOutputs)(result));
+        await op.patchRun();
+        return result;
+    }
+    catch (err) {
+        await op.end(undefined, (0, run_tree_1.describeError)(err));
+        await op.patchRun();
+        throw err;
+    }
+}
+/**
+ * Build the activity-inbound interceptor factory. The worker calls the factory
+ * once per activity with that activity's {@link ActivityContext}, from which we
+ * read the activity type for the run name.
+ */
+function createActivityInboundInterceptor(config) {
+    return (ctx) => ({
+        async execute(input, next) {
+            if (!(0, langsmith_1.isTracingEnabled)()) {
+                return next(input);
+            }
+            const parent = reconstructParentRun(config, (0, propagation_1.readContextHeader)(input.headers));
+            if (!config.addTemporalRuns) {
+                // Propagation only: nest the user's body `traceable` runs under the
+                // reconstructed parent without emitting a Temporal-operation run.
+                // No propagated parent: run the body with no ambient run by design (nothing to attach to).
+                return parent ? (0, traceable_1.withRunTree)(parent, () => next(input)) : next(input);
+            }
+            const activityType = ctx.info.activityType;
+            const run = (0, run_tree_1.buildRunTree)(config, {
+                name: (0, run_tree_1.runActivityRunName)(activityType),
+                runType: run_tree_1.RUN_TYPE.TOOL,
+                parent,
+                inputs: { args: input.args },
+            });
+            return traceOperation(run, () => next(input));
+        },
+    });
+}
+function nexusContext(headers) {
+    return (0, propagation_1.decodeContextString)(headers[propagation_1.HEADER_KEY]);
+}
+/**
+ * Build the Nexus-handler interceptor. `startOperation` opens a
+ * `RunStartNexusOperationHandler:` run (so workflows the handler starts nest
+ * under it); `cancelOperation` opens `RunCancelNexusOperationHandler:`.
+ */
+function createNexusInboundInterceptor(config) {
+    const handle = async (input, next, nameOf) => {
+        if (!(0, langsmith_1.isTracingEnabled)()) {
+            return next(input);
+        }
+        const parent = reconstructParentRun(config, nexusContext(input.ctx.headers));
+        if (!config.addTemporalRuns) {
+            return parent ? (0, traceable_1.withRunTree)(parent, () => next(input)) : next(input);
+        }
+        const run = (0, run_tree_1.buildRunTree)(config, {
+            name: nameOf(input.ctx.service, input.ctx.operation),
+            runType: run_tree_1.RUN_TYPE.CHAIN,
+            parent,
+        });
+        return traceOperation(run, () => next(input));
+    };
+    return {
+        startOperation(input, next) {
+            return handle(input, next, run_tree_1.runStartNexusHandlerRunName);
+        },
+        cancelOperation(input, next) {
+            return handle(input, next, run_tree_1.runCancelNexusHandlerRunName);
+        },
+    };
+}
+//# sourceMappingURL=activity-interceptor.js.map

package/lib/activity-interceptor.js.map

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

package/lib/client-interceptor.d.ts

@@ -0,0 +1,11 @@
+/**
+ * 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 type { WorkflowClientInterceptor } from '@temporalio/client';
+import type { EmitterConfig } from './sinks';
+export declare function createClientInterceptor(config: EmitterConfig): WorkflowClientInterceptor;

package/lib/client-interceptor.js

@@ -0,0 +1,82 @@
+"use strict";
+/**
+ * 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
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createClientInterceptor = createClientInterceptor;
+const langsmith_1 = require("langsmith");
+const traceable_1 = require("langsmith/traceable");
+const propagation_1 = require("./propagation");
+const run_tree_1 = require("./run-tree");
+function createClientInterceptor(config) {
+    const peerStart = async (input, next, name, args) => {
+        if (!(0, langsmith_1.isTracingEnabled)()) {
+            return next(input);
+        }
+        const ambient = (0, traceable_1.getCurrentRunTree)(true);
+        if (config.addTemporalRuns) {
+            await (0, run_tree_1.emitMarkerRun)((0, run_tree_1.buildRunTree)(config, { name, runType: run_tree_1.RUN_TYPE.CHAIN, parent: ambient, inputs: { args } }));
+        }
+        const headers = (0, propagation_1.withContextHeader)(input.headers, (0, run_tree_1.runHeaders)(ambient));
+        return next({ ...input, headers });
+    };
+    const parentMarker = async (input, next, name, args) => {
+        if (!(0, langsmith_1.isTracingEnabled)()) {
+            return next(input);
+        }
+        const ambient = (0, traceable_1.getCurrentRunTree)(true);
+        let propagate = ambient;
+        if (config.addTemporalRuns) {
+            const marker = (0, run_tree_1.buildRunTree)(config, { name, runType: run_tree_1.RUN_TYPE.CHAIN, parent: ambient, inputs: { args } });
+            await (0, run_tree_1.emitMarkerRun)(marker);
+            propagate = marker;
+        }
+        const headers = (0, propagation_1.withContextHeader)(input.headers, (0, run_tree_1.runHeaders)(propagate));
+        return next({ ...input, headers });
+    };
+    return {
+        start(input, next) {
+            return peerStart(input, next, (0, run_tree_1.startWorkflowRunName)(input.workflowType), input.options.args);
+        },
+        startWithDetails(input, next) {
+            return peerStart(input, next, (0, run_tree_1.startWorkflowRunName)(input.workflowType), input.options.args);
+        },
+        signal(input, next) {
+            return parentMarker(input, next, (0, run_tree_1.signalWorkflowRunName)(input.signalName), input.args);
+        },
+        signalWithStart(input, next) {
+            return parentMarker(input, next, (0, run_tree_1.signalWithStartRunName)(input.workflowType), input.signalArgs);
+        },
+        query(input, next) {
+            return parentMarker(input, next, (0, run_tree_1.queryWorkflowRunName)(input.queryType), input.args);
+        },
+        startUpdate(input, next) {
+            return parentMarker(input, next, (0, run_tree_1.startWorkflowUpdateRunName)(input.updateName), input.args);
+        },
+        async startUpdateWithStart(input, next) {
+            if (!(0, langsmith_1.isTracingEnabled)()) {
+                return next(input);
+            }
+            const ambient = (0, traceable_1.getCurrentRunTree)(true);
+            let propagate = ambient;
+            if (config.addTemporalRuns) {
+                const marker = (0, run_tree_1.buildRunTree)(config, {
+                    name: (0, run_tree_1.startUpdateWithStartRunName)(input.updateName),
+                    runType: run_tree_1.RUN_TYPE.CHAIN,
+                    parent: ambient,
+                    inputs: { args: input.updateArgs },
+                });
+                await (0, run_tree_1.emitMarkerRun)(marker);
+                propagate = marker;
+            }
+            const workflowStartHeaders = (0, propagation_1.withContextHeader)(input.workflowStartHeaders, (0, run_tree_1.runHeaders)(propagate));
+            return next({ ...input, workflowStartHeaders });
+        },
+    };
+}
+//# sourceMappingURL=client-interceptor.js.map

package/lib/client-interceptor.js.map

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

package/lib/index.d.ts

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

package/lib/index.js

@@ -0,0 +1,11 @@
+"use strict";
+/**
+ * `@temporalio/langsmith` — LangSmith observability for Temporal.
+ *
+ * @module
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LangSmithPlugin = void 0;
+var plugin_1 = require("./plugin");
+Object.defineProperty(exports, "LangSmithPlugin", { enumerable: true, get: function () { return plugin_1.LangSmithPlugin; } });
+//# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;GAIG;;;AAEH,mCAA2C;AAAlC,yGAAA,eAAe,OAAA"}

package/lib/plugin.d.ts

@@ -0,0 +1,88 @@
+/**
+ * {@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 { SimplePlugin } from '@temporalio/plugin';
+import type { ClientOptions } from '@temporalio/client';
+import type { BundleOptions, ReplayWorkerOptions, Worker, WorkerOptions } from '@temporalio/worker';
+/**
+ * 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 declare class LangSmithPlugin extends SimplePlugin {
+    private readonly client;
+    private readonly emitter;
+    private readonly workflowConfig;
+    constructor(options?: LangSmithPluginOptions);
+    configureClient(options: ClientOptions): ClientOptions;
+    configureWorker(options: WorkerOptions): WorkerOptions;
+    configureReplayWorker(options: ReplayWorkerOptions): ReplayWorkerOptions;
+    private withLangSmithWorker;
+    configureBundler(options: BundleOptions): BundleOptions;
+    /**
+     * 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).
+     */
+    runWorker(worker: Worker, next: (worker: Worker) => Promise<void>): Promise<void>;
+    private flush;
+}