langsmith 0.10.7 → 0.10.9

package/dist/experimental/otel/exporter.cjs

@@ -39,6 +39,7 @@ const constants = __importStar(require("./constants.cjs"));
 const env_js_1 = require("../../env.cjs");
 const env_js_2 = require("../../utils/env.cjs");
 const vercel_js_1 = require("../../utils/vercel.cjs");
+const warn_js_1 = require("../../utils/warn.cjs");
 /**
  * Convert headers string in format "name=value,name2=value2" to object
  */
@@ -60,8 +61,10 @@ function parseHeadersString(headersStr) {
  *
  * This exporter automatically configures itself with LangSmith endpoints and API keys,
  * based on your LANGSMITH_API_KEY and LANGSMITH_PROJECT environment variables.
- * Will also respect OTEL_EXPORTER_OTLP_ENDPOINT or OTEL_EXPORTER_OTLP_HEADERS environment
- * variables if set.
+ * OTEL_EXPORTER_OTLP_TRACES_ENDPOINT is a full traces URL and takes precedence over
+ * OTEL_EXPORTER_OTLP_ENDPOINT, a base URL to which /v1/traces is appended unless
+ * it already ends in /traces for compatibility.
+ * Also respects OTEL_EXPORTER_OTLP_HEADERS if set.
  *
  * @param config - Optional configuration object that accepts all OTLPTraceExporter parameters.
  *                 If not provided, uses default LangSmith configuration:
@@ -74,8 +77,22 @@ class LangSmithOTLPTraceExporter extends exporter_trace_otlp_proto_1.OTLPTraceEx
         const defaultLsEndpoint = (0, env_js_2.getLangSmithEnvironmentVariable)("ENDPOINT") ||
             "https://api.smith.langchain.com";
         const defaultBaseUrl = defaultLsEndpoint.replace(/\/$/, "");
-        const defaultUrl = (0, env_js_2.getEnvironmentVariable)("OTEL_EXPORTER_OTLP_ENDPOINT") ??
-            `${defaultBaseUrl}/otel/v1/traces`;
+        const baseEndpoint = (0, env_js_2.getEnvironmentVariable)("OTEL_EXPORTER_OTLP_ENDPOINT") ||
+            `${defaultBaseUrl}/otel`;
+        const defaultUrl = (0, env_js_2.getEnvironmentVariable)("OTEL_EXPORTER_OTLP_TRACES_ENDPOINT") ||
+            (baseEndpoint.endsWith("/traces")
+                ? baseEndpoint
+                : `${baseEndpoint.replace(/\/$/, "")}/v1/traces`);
+        if (config?.url === undefined &&
+            !(0, env_js_2.getEnvironmentVariable)("OTEL_EXPORTER_OTLP_TRACES_ENDPOINT") &&
+            baseEndpoint.endsWith("/traces")) {
+            (0, warn_js_1.warnOnce)("LangSmith now treats OTEL_EXPORTER_OTLP_ENDPOINT as a base URL and " +
+                "appends /v1/traces. Your value ends in /traces, so it is being " +
+                "preserved unchanged for compatibility. This fallback will be " +
+                "removed in the v1 release of the SDK. Move this full URL to " +
+                "OTEL_EXPORTER_OTLP_TRACES_ENDPOINT to use standard OpenTelemetry " +
+                "configuration.");
+        }
         // Configure headers with API key and project if available
         let headers = config?.headers;
         if (headers === undefined) {

package/dist/experimental/otel/exporter.d.ts

@@ -43,8 +43,10 @@ export type LangSmithOTLPTraceExporterConfig = ConstructorParameters<typeof OTLP
  *
  * This exporter automatically configures itself with LangSmith endpoints and API keys,
  * based on your LANGSMITH_API_KEY and LANGSMITH_PROJECT environment variables.
- * Will also respect OTEL_EXPORTER_OTLP_ENDPOINT or OTEL_EXPORTER_OTLP_HEADERS environment
- * variables if set.
+ * OTEL_EXPORTER_OTLP_TRACES_ENDPOINT is a full traces URL and takes precedence over
+ * OTEL_EXPORTER_OTLP_ENDPOINT, a base URL to which /v1/traces is appended unless
+ * it already ends in /traces for compatibility.
+ * Also respects OTEL_EXPORTER_OTLP_HEADERS if set.
  *
  * @param config - Optional configuration object that accepts all OTLPTraceExporter parameters.
  *                 If not provided, uses default LangSmith configuration:

package/dist/experimental/otel/exporter.js

@@ -3,6 +3,7 @@ import * as constants from "./constants.js";
 import { isEnvTracingEnabled } from "../../env.js";
 import { getEnvironmentVariable, getLangSmithEnvironmentVariable, } from "../../utils/env.js";
 import { extractUsageMetadata } from "../../utils/vercel.js";
+import { warnOnce } from "../../utils/warn.js";
 /**
  * Convert headers string in format "name=value,name2=value2" to object
  */
@@ -24,8 +25,10 @@ function parseHeadersString(headersStr) {
  *
  * This exporter automatically configures itself with LangSmith endpoints and API keys,
  * based on your LANGSMITH_API_KEY and LANGSMITH_PROJECT environment variables.
- * Will also respect OTEL_EXPORTER_OTLP_ENDPOINT or OTEL_EXPORTER_OTLP_HEADERS environment
- * variables if set.
+ * OTEL_EXPORTER_OTLP_TRACES_ENDPOINT is a full traces URL and takes precedence over
+ * OTEL_EXPORTER_OTLP_ENDPOINT, a base URL to which /v1/traces is appended unless
+ * it already ends in /traces for compatibility.
+ * Also respects OTEL_EXPORTER_OTLP_HEADERS if set.
  *
  * @param config - Optional configuration object that accepts all OTLPTraceExporter parameters.
  *                 If not provided, uses default LangSmith configuration:
@@ -38,8 +41,22 @@ export class LangSmithOTLPTraceExporter extends OTLPTraceExporter {
         const defaultLsEndpoint = getLangSmithEnvironmentVariable("ENDPOINT") ||
             "https://api.smith.langchain.com";
         const defaultBaseUrl = defaultLsEndpoint.replace(/\/$/, "");
-        const defaultUrl = getEnvironmentVariable("OTEL_EXPORTER_OTLP_ENDPOINT") ??
-            `${defaultBaseUrl}/otel/v1/traces`;
+        const baseEndpoint = getEnvironmentVariable("OTEL_EXPORTER_OTLP_ENDPOINT") ||
+            `${defaultBaseUrl}/otel`;
+        const defaultUrl = getEnvironmentVariable("OTEL_EXPORTER_OTLP_TRACES_ENDPOINT") ||
+            (baseEndpoint.endsWith("/traces")
+                ? baseEndpoint
+                : `${baseEndpoint.replace(/\/$/, "")}/v1/traces`);
+        if (config?.url === undefined &&
+            !getEnvironmentVariable("OTEL_EXPORTER_OTLP_TRACES_ENDPOINT") &&
+            baseEndpoint.endsWith("/traces")) {
+            warnOnce("LangSmith now treats OTEL_EXPORTER_OTLP_ENDPOINT as a base URL and " +
+                "appends /v1/traces. Your value ends in /traces, so it is being " +
+                "preserved unchanged for compatibility. This fallback will be " +
+                "removed in the v1 release of the SDK. Move this full URL to " +
+                "OTEL_EXPORTER_OTLP_TRACES_ENDPOINT to use standard OpenTelemetry " +
+                "configuration.");
+        }
         // Configure headers with API key and project if available
         let headers = config?.headers;
         if (headers === undefined) {

package/dist/index.cjs

@@ -1,11 +1,14 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.LS_MESSAGE_VIEW_EXCLUDE = exports.__version__ = exports.InternalServerError = exports.RateLimitError = exports.UnprocessableEntityError = exports.ConflictError = exports.NotFoundError = exports.PermissionDeniedError = exports.AuthenticationError = exports.BadRequestError = exports.APIConnectionTimeoutError = exports.APIConnectionError = exports.APIUserAbortError = exports.APIError = exports.LangsmithError = exports.promptCacheSingleton = exports.configureGlobalPromptCache = exports.PromptCache = exports.Cache = exports.isTracingEnabled = exports.uuid7FromTime = exports.uuid7 = exports.computeRunIdForSecondaryReplica = exports.getDefaultProjectName = exports.overrideFetchImplementation = exports.EnvAddressError = exports.RunTree = exports.Client = void 0;
+exports.LS_MESSAGE_VIEW_EXCLUDE = exports.__version__ = exports.InternalServerError = exports.RateLimitError = exports.UnprocessableEntityError = exports.ConflictError = exports.NotFoundError = exports.PermissionDeniedError = exports.AuthenticationError = exports.BadRequestError = exports.APIConnectionTimeoutError = exports.APIConnectionError = exports.APIUserAbortError = exports.APIError = exports.LangsmithError = exports.promptCacheSingleton = exports.configureGlobalPromptCache = exports.PromptCache = exports.Cache = exports.isTracingEnabled = exports.uuid7FromTime = exports.uuid7 = exports.computeRunIdForSecondaryReplica = exports.getDefaultProjectName = exports.overrideFetchImplementation = exports.EnvAddressError = exports.EvaluatorAddress = exports.ExperimentAddress = exports.AgentAddress = exports.RunTree = exports.Client = void 0;
 var client_js_1 = require("./client.cjs");
 Object.defineProperty(exports, "Client", { enumerable: true, get: function () { return client_js_1.Client; } });
 var run_trees_js_1 = require("./run_trees.cjs");
 Object.defineProperty(exports, "RunTree", { enumerable: true, get: function () { return run_trees_js_1.RunTree; } });
 var address_js_1 = require("./address.cjs");
+Object.defineProperty(exports, "AgentAddress", { enumerable: true, get: function () { return address_js_1.AgentAddress; } });
+Object.defineProperty(exports, "ExperimentAddress", { enumerable: true, get: function () { return address_js_1.ExperimentAddress; } });
+Object.defineProperty(exports, "EvaluatorAddress", { enumerable: true, get: function () { return address_js_1.EvaluatorAddress; } });
 Object.defineProperty(exports, "EnvAddressError", { enumerable: true, get: function () { return address_js_1.EnvAddressError; } });
 var fetch_js_1 = require("./singletons/fetch.cjs");
 Object.defineProperty(exports, "overrideFetchImplementation", { enumerable: true, get: function () { return fetch_js_1.overrideFetchImplementation; } });
@@ -37,6 +40,6 @@ Object.defineProperty(exports, "UnprocessableEntityError", { enumerable: true, g
 Object.defineProperty(exports, "RateLimitError", { enumerable: true, get: function () { return error_js_1.RateLimitError; } });
 Object.defineProperty(exports, "InternalServerError", { enumerable: true, get: function () { return error_js_1.InternalServerError; } });
 // Update using pnpm bump-version
-exports.__version__ = "0.10.7";
+exports.__version__ = "0.10.9";
 // Metadata key to hide a traced run from LangSmith's Messages View.
 exports.LS_MESSAGE_VIEW_EXCLUDE = "ls_message_view_exclude";

package/dist/index.d.ts

@@ -1,12 +1,12 @@
 export { Client, type ClientConfig, type LangSmithTracingClientInterface, } from "./client.js";
 export type { Dataset, Example, TracerSession, Run, Feedback, FeedbackConfigSchema, RetrieverOutput, } from "./schemas.js";
 export { RunTree, type RunTreeConfig, type WriteReplica } from "./run_trees.js";
-export { type Address, EnvAddressError } from "./address.js";
+export { AgentAddress, ExperimentAddress, EvaluatorAddress, type Address, type ApiAddress, type Environment, EnvAddressError, } from "./address.js";
 export { overrideFetchImplementation } from "./singletons/fetch.js";
 export { getDefaultProjectName } from "./utils/project.js";
 export { computeRunIdForSecondaryReplica, uuid7, uuid7FromTime, } from "./uuid.js";
 export { isTracingEnabled } from "./utils/guard.js";
 export { Cache, PromptCache, type CacheConfig, type CacheMetrics, configureGlobalPromptCache, promptCacheSingleton, } from "./utils/prompt_cache/index.js";
 export { LangsmithError, APIError, APIUserAbortError, APIConnectionError, APIConnectionTimeoutError, BadRequestError, AuthenticationError, PermissionDeniedError, NotFoundError, ConflictError, UnprocessableEntityError, RateLimitError, InternalServerError, } from "./_openapi_client/core/error.js";
-export declare const __version__ = "0.10.7";
+export declare const __version__ = "0.10.9";
 export declare const LS_MESSAGE_VIEW_EXCLUDE: "ls_message_view_exclude";

package/dist/index.js

@@ -1,6 +1,6 @@
 export { Client, } from "./client.js";
 export { RunTree } from "./run_trees.js";
-export { EnvAddressError } from "./address.js";
+export { AgentAddress, ExperimentAddress, EvaluatorAddress, EnvAddressError, } from "./address.js";
 export { overrideFetchImplementation } from "./singletons/fetch.js";
 export { getDefaultProjectName } from "./utils/project.js";
 export { computeRunIdForSecondaryReplica, uuid7, uuid7FromTime, } from "./uuid.js";
@@ -8,6 +8,6 @@ export { isTracingEnabled } from "./utils/guard.js";
 export { Cache, PromptCache, configureGlobalPromptCache, promptCacheSingleton, } from "./utils/prompt_cache/index.js";
 export { LangsmithError, APIError, APIUserAbortError, APIConnectionError, APIConnectionTimeoutError, BadRequestError, AuthenticationError, PermissionDeniedError, NotFoundError, ConflictError, UnprocessableEntityError, RateLimitError, InternalServerError, } from "./_openapi_client/core/error.js";
 // Update using pnpm bump-version
-export const __version__ = "0.10.7";
+export const __version__ = "0.10.9";
 // Metadata key to hide a traced run from LangSmith's Messages View.
 export const LS_MESSAGE_VIEW_EXCLUDE = "ls_message_view_exclude";

package/dist/run_trees.cjs

@@ -14,7 +14,7 @@ const env_js_3 = require("./utils/env.cjs");
 const warn_js_1 = require("./utils/warn.cjs");
 const _uuid_js_1 = require("./utils/_uuid.cjs");
 const index_js_1 = require("./utils/uuid/src/index.cjs");
-const agent_addressing_js_1 = require("./utils/agent_addressing.cjs");
+const addressing_js_1 = require("./utils/addressing.cjs");
 const address_js_1 = require("./address.cjs");
 const TIMESTAMP_LENGTH = 36;
 // DNS namespace for UUID v5 (same as Python's uuid.NAMESPACE_DNS)
@@ -50,29 +50,17 @@ const HEADER_SAFE_REPLICA_FIELDS = new Set([
     "primary",
     "updates",
     "reroot",
-    ...(0, address_js_1.wireKeys)(),
+    "address",
 ]);
-// URL-encoded JSON of the address's wire fields.
-const LANGSMITH_ADDRESS = "langsmith-address";
-/** Pops the address wire keys off untrusted `values`; never throws. */
-function takeHeaderAddress(values) {
-    const wire = {};
-    for (const key of (0, address_js_1.wireKeys)()) {
-        if (key in values) {
-            wire[key] = values[key];
-            delete values[key];
-        }
-    }
+/** Rebuilds an untrusted header address; `undefined` if unusable. */
+function addressFromHeader(value) {
     try {
-        return {
-            named: Object.keys(wire).length > 0,
-            address: (0, address_js_1.fromWire)(wire),
-        };
+        return address_js_1.AgentAddress._fromLrn(value);
     }
     catch {
         // Values are untrusted, so not logged.
-        console.warn("Ignoring an invalid address in a `baggage` header.");
-        return { named: true };
+        console.warn("Ignoring an unusable address in a `baggage` header.");
+        return undefined;
     }
 }
 function filterReplicaForHeaders(replica) {
@@ -147,17 +135,8 @@ class Baggage {
             else if (key === "langsmith-project") {
                 project_name = value;
             }
-            else if (key === LANGSMITH_ADDRESS) {
-                let parsed;
-                try {
-                    parsed = JSON.parse(value);
-                }
-                catch {
-                    parsed = undefined;
-                }
-                if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
-                    address = takeHeaderAddress({ ...parsed }).address;
-                }
+            else if (key === "langsmith-address") {
+                address = addressFromHeader(value);
             }
             else if (key === "langsmith-replicas") {
                 const parsed = JSON.parse(value);
@@ -166,13 +145,17 @@ class Baggage {
                         return [replica];
                     }
                     const filtered = filterReplicaForHeaders(replica);
-                    const { named, address } = takeHeaderAddress(filtered);
+                    const raw = filtered.address;
+                    delete filtered.address;
                     // A project wins over an address; a replica with an invalid
                     // address and no project is dropped.
-                    if (filtered.projectName || !named) {
+                    if (filtered.projectName || raw == null) {
                         return [filtered];
                     }
-                    return address ? [{ ...filtered, address }] : [];
+                    const replicaAddress = addressFromHeader(raw);
+                    return replicaAddress
+                        ? [{ ...filtered, address: replicaAddress }]
+                        : [];
                 });
             }
         }
@@ -190,7 +173,7 @@ class Baggage {
             items.push(`langsmith-project=${encodeURIComponent(this.project_name)}`);
         }
         if (this.address) {
-            items.push(`${LANGSMITH_ADDRESS}=${encodeURIComponent(JSON.stringify((0, address_js_1.toWire)(this.address)))}`);
+            items.push(`langsmith-address=${encodeURIComponent(this.address._toLrn())}`);
         }
         return items.join(",");
     }
@@ -440,23 +423,23 @@ class RunTree {
     }
     /** Falls back to the env; a bad env leaves the run untraced. */
     _resolveAddressing(config) {
-        const address = (0, agent_addressing_js_1.checkAddress)(config.address);
+        const address = (0, address_js_1.ensureAgent)(config.address);
         const project = config.project_name || undefined;
-        (0, agent_addressing_js_1.rejectConflicting)(project, address);
+        (0, addressing_js_1.rejectConflicting)(project, address);
         if (project || address) {
             this.project_name = project;
             this.address = address;
             return;
         }
         try {
-            [this.project_name, this.address] = (0, agent_addressing_js_1.resolveFromEnv)();
+            [this.project_name, this.address] = (0, addressing_js_1.resolveFromEnv)();
         }
         catch (e) {
             if (!(e instanceof address_js_1.EnvAddressError)) {
                 throw e;
             }
             if ((0, env_js_1.isEnvTracingEnabled)(this.tracingEnabled)) {
-                (0, agent_addressing_js_1.logUntraced)(e);
+                (0, addressing_js_1.logUntraced)(e);
             }
             this.project_name = undefined;
             this.address = undefined;
@@ -666,9 +649,9 @@ class RunTree {
     }
     /** A replica naming neither inherits the run tree's destination. */
     _replicaAddressing(replica) {
-        const address = (0, agent_addressing_js_1.checkAddress)(replica.address);
+        const address = (0, address_js_1.ensureAgent)(replica.address);
         if (replica.projectName != null) {
-            (0, agent_addressing_js_1.rejectConflicting)(replica.projectName, address);
+            (0, addressing_js_1.rejectConflicting)(replica.projectName, address);
             return [replica.projectName, undefined];
         }
         if (address) {
@@ -683,14 +666,14 @@ class RunTree {
         if (primary === undefined &&
             !this.replicas?.some((r) => r.primary === true) &&
             projectName === this.project_name &&
-            (0, address_js_1.sameAddress)(address, this.address)) {
+            address?._toLrn() === this.address?._toLrn()) {
             return {
                 ...baseRun,
                 session_name: projectName,
                 address,
             };
         }
-        const seed = projectName ?? (address ? (0, address_js_1.seed)(address) : undefined) ?? "agent//";
+        const seed = projectName ?? address?._toLrn() ?? "agent//";
         // Apply reroot logic before ID remapping
         if (reroot) {
             if (distributedParentId) {
@@ -1211,7 +1194,7 @@ function _ensureWriteReplicas(replicas) {
                     updates: replica[1],
                 };
             }
-            const address = (0, agent_addressing_js_1.checkAddress)(replica.address);
+            const address = (0, address_js_1.ensureAgent)(replica.address);
             return address ? { ...replica, address } : replica;
         })
         : _getWriteReplicasFromEnv();

package/dist/run_trees.d.ts

@@ -1,6 +1,6 @@
 import { Client } from "./client.js";
 import { Attachments, BaseRun, KVMap, RunCreate } from "./schemas.js";
-import { type Address } from "./address.js";
+import { AgentAddress } from "./address.js";
 export declare function convertToDottedOrderFormat(epoch: number, runId: string, executionOrder?: number): {
     dottedOrder: string;
     microsecondPrecisionDatestring: string;
@@ -11,7 +11,7 @@ export interface RunTreeConfig {
     id?: string;
     project_name?: string;
     /** (beta) Send the run to this address instead of a project. */
-    address?: Address;
+    address?: AgentAddress;
     parent_run?: RunTree;
     parent_run_id?: string;
     child_runs?: RunTree[];
@@ -64,7 +64,7 @@ export type WriteReplica = {
     workspaceId?: string;
     projectName?: string;
     /** (beta) Send the replica to this address instead of a project. */
-    address?: Address;
+    address?: AgentAddress;
     /** Whether this replica keeps the original run IDs. */
     primary?: boolean;
     updates?: KVMap | undefined;
@@ -87,7 +87,7 @@ export declare class RunTree implements BaseRun {
     /** Unset for a run sent to an `address`. */
     project_name?: string;
     /** (beta) Set instead of `project_name` for an addressed run. */
-    address?: Address;
+    address?: AgentAddress;
     parent_run?: RunTree;
     parent_run_id?: string;
     child_runs: RunTree[];

package/dist/run_trees.js

@@ -8,8 +8,8 @@ import { getLangSmithEnvironmentVariable } from "./utils/env.js";
 import { warnOnce } from "./utils/warn.js";
 import { uuid7FromTime, nonCryptographicUuid7Deterministic, } from "./utils/_uuid.js";
 import { v5 as uuidv5 } from "./utils/uuid/src/index.js";
-import { checkAddress, logUntraced, rejectConflicting, resolveFromEnv, } from "./utils/agent_addressing.js";
-import { EnvAddressError, fromWire, sameAddress, seed as addressSeed, toWire, wireKeys, } from "./address.js";
+import { logUntraced, rejectConflicting, resolveFromEnv, } from "./utils/addressing.js";
+import { AgentAddress, EnvAddressError, ensureAgent } from "./address.js";
 const TIMESTAMP_LENGTH = 36;
 // DNS namespace for UUID v5 (same as Python's uuid.NAMESPACE_DNS)
 const UUID_NAMESPACE_DNS = "6ba7b810-9dad-11d1-80b4-00c04fd430c8";
@@ -44,29 +44,17 @@ const HEADER_SAFE_REPLICA_FIELDS = new Set([
     "primary",
     "updates",
     "reroot",
-    ...wireKeys(),
+    "address",
 ]);
-// URL-encoded JSON of the address's wire fields.
-const LANGSMITH_ADDRESS = "langsmith-address";
-/** Pops the address wire keys off untrusted `values`; never throws. */
-function takeHeaderAddress(values) {
-    const wire = {};
-    for (const key of wireKeys()) {
-        if (key in values) {
-            wire[key] = values[key];
-            delete values[key];
-        }
-    }
+/** Rebuilds an untrusted header address; `undefined` if unusable. */
+function addressFromHeader(value) {
     try {
-        return {
-            named: Object.keys(wire).length > 0,
-            address: fromWire(wire),
-        };
+        return AgentAddress._fromLrn(value);
     }
     catch {
         // Values are untrusted, so not logged.
-        console.warn("Ignoring an invalid address in a `baggage` header.");
-        return { named: true };
+        console.warn("Ignoring an unusable address in a `baggage` header.");
+        return undefined;
     }
 }
 function filterReplicaForHeaders(replica) {
@@ -141,17 +129,8 @@ class Baggage {
             else if (key === "langsmith-project") {
                 project_name = value;
             }
-            else if (key === LANGSMITH_ADDRESS) {
-                let parsed;
-                try {
-                    parsed = JSON.parse(value);
-                }
-                catch {
-                    parsed = undefined;
-                }
-                if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
-                    address = takeHeaderAddress({ ...parsed }).address;
-                }
+            else if (key === "langsmith-address") {
+                address = addressFromHeader(value);
             }
             else if (key === "langsmith-replicas") {
                 const parsed = JSON.parse(value);
@@ -160,13 +139,17 @@ class Baggage {
                         return [replica];
                     }
                     const filtered = filterReplicaForHeaders(replica);
-                    const { named, address } = takeHeaderAddress(filtered);
+                    const raw = filtered.address;
+                    delete filtered.address;
                     // A project wins over an address; a replica with an invalid
                     // address and no project is dropped.
-                    if (filtered.projectName || !named) {
+                    if (filtered.projectName || raw == null) {
                         return [filtered];
                     }
-                    return address ? [{ ...filtered, address }] : [];
+                    const replicaAddress = addressFromHeader(raw);
+                    return replicaAddress
+                        ? [{ ...filtered, address: replicaAddress }]
+                        : [];
                 });
             }
         }
@@ -184,7 +167,7 @@ class Baggage {
             items.push(`langsmith-project=${encodeURIComponent(this.project_name)}`);
         }
         if (this.address) {
-            items.push(`${LANGSMITH_ADDRESS}=${encodeURIComponent(JSON.stringify(toWire(this.address)))}`);
+            items.push(`langsmith-address=${encodeURIComponent(this.address._toLrn())}`);
         }
         return items.join(",");
     }
@@ -434,7 +417,7 @@ export class RunTree {
     }
     /** Falls back to the env; a bad env leaves the run untraced. */
     _resolveAddressing(config) {
-        const address = checkAddress(config.address);
+        const address = ensureAgent(config.address);
         const project = config.project_name || undefined;
         rejectConflicting(project, address);
         if (project || address) {
@@ -660,7 +643,7 @@ export class RunTree {
     }
     /** A replica naming neither inherits the run tree's destination. */
     _replicaAddressing(replica) {
-        const address = checkAddress(replica.address);
+        const address = ensureAgent(replica.address);
         if (replica.projectName != null) {
             rejectConflicting(replica.projectName, address);
             return [replica.projectName, undefined];
@@ -677,14 +660,14 @@ export class RunTree {
         if (primary === undefined &&
             !this.replicas?.some((r) => r.primary === true) &&
             projectName === this.project_name &&
-            sameAddress(address, this.address)) {
+            address?._toLrn() === this.address?._toLrn()) {
             return {
                 ...baseRun,
                 session_name: projectName,
                 address,
             };
         }
-        const seed = projectName ?? (address ? addressSeed(address) : undefined) ?? "agent//";
+        const seed = projectName ?? address?._toLrn() ?? "agent//";
         // Apply reroot logic before ID remapping
         if (reroot) {
             if (distributedParentId) {
@@ -1204,7 +1187,7 @@ function _ensureWriteReplicas(replicas) {
                     updates: replica[1],
                 };
             }
-            const address = checkAddress(replica.address);
+            const address = ensureAgent(replica.address);
             return address ? { ...replica, address } : replica;
         })
         : _getWriteReplicasFromEnv();

package/dist/sandbox/client.cjs

@@ -15,6 +15,7 @@ const errors_js_1 = require("./errors.cjs");
 const helpers_js_1 = require("./helpers.cjs");
 const mounts_js_1 = require("./mounts.cjs");
 const index_js_2 = require("../utils/uuid/src/index.cjs");
+const tracing_js_1 = require("./tracing.cjs");
 /**
  * Sleep that can be interrupted by an AbortSignal.
  * Resolves after `ms` milliseconds or rejects immediately if the signal fires.
@@ -305,6 +306,12 @@ class SandboxClient {
             writable: true,
             value: void 0
         });
+        Object.defineProperty(this, "_sandboxIds", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Map()
+        });
         this._baseUrl = (config.apiEndpoint ?? getDefaultApiEndpoint()).replace(/\/$/, "");
         this._apiKey = config.apiKey ?? getDefaultApiKey();
         this._defaultHeaders = { ...(config.headers ?? {}) };
@@ -398,6 +405,25 @@ class SandboxClient {
     getDefaultHeaders() {
         return { ...this._defaultHeaders };
     }
+    _traceSandbox(name) {
+        const id = this._sandboxIds.get(name) ?? ((0, index_js_2.validate)(name) ? name : undefined);
+        (0, tracing_js_1.addSandboxMetadata)(id);
+        return id;
+    }
+    _sandboxFromData(data) {
+        if (data.id)
+            this._sandboxIds.set(data.name, data.id);
+        (0, tracing_js_1.addSandboxMetadata)(data.id);
+        return new sandbox_js_1.Sandbox(data, this);
+    }
+    _forgetSandbox(name) {
+        const id = this._sandboxIds.get(name) ?? name;
+        for (const [cachedName, cachedId] of this._sandboxIds) {
+            if (cachedName === name || cachedId === id) {
+                this._sandboxIds.delete(cachedName);
+            }
+        }
+    }
     /**
      * JSON POST helper. Sends JSON body, checks response status,
      * and returns the Response for further processing.
@@ -406,6 +432,7 @@ class SandboxClient {
      * @internal
      */
     _boxUrl(name, ...segments) {
+        this._traceSandbox(name);
         const suffix = segments.length ? `/${segments.join("/")}` : "";
         return `${this._baseUrl}/boxes/${encodeURIComponent(name)}${suffix}`;
     }
@@ -454,7 +481,7 @@ class SandboxClient {
         return new service_url_js_1.ServiceUrl(data, () => this.serviceUrl(name, {
             port,
             expiresInSeconds,
-        }));
+        }), this._traceSandbox(name));
     }
     async _postJson(url, body, options) {
         const response = await this._fetch(url, {
@@ -534,7 +561,7 @@ class SandboxClient {
             await (0, helpers_js_1.handleSandboxCreationError)(response);
         }
         const data = (await response.json());
-        return new sandbox_js_1.Sandbox(data, this);
+        return this._sandboxFromData(data);
     }
     /**
      * Get a Sandbox by name.
@@ -555,7 +582,7 @@ class SandboxClient {
             await (0, helpers_js_1.handleClientHttpError)(response);
         }
         const data = (await response.json());
-        return new sandbox_js_1.Sandbox(data, this);
+        return this._sandboxFromData(data);
     }
     /**
      * List all Sandboxes.
@@ -625,7 +652,8 @@ class SandboxClient {
             await (0, helpers_js_1.handleClientHttpError)(response);
         }
         const data = (await response.json());
-        return new sandbox_js_1.Sandbox(data, this);
+        this._forgetSandbox(name);
+        return this._sandboxFromData(data);
     }
     /**
      * Delete a Sandbox.
@@ -642,6 +670,7 @@ class SandboxClient {
             }
             await (0, helpers_js_1.handleClientHttpError)(response);
         }
+        this._forgetSandbox(name);
     }
     /**
      * Get the provisioning status of a sandbox.

package/dist/sandbox/client.d.ts

@@ -40,6 +40,7 @@ export declare class SandboxClient {
     private _fetchImpl;
     private _caller;
     private _registriesClient?;
+    private _sandboxIds;
     constructor(config?: SandboxClientConfig);
     private _apiRoot;
     /**
@@ -65,6 +66,9 @@ export declare class SandboxClient {
      * ```
      */
     get registries(): Registries;
+    private _traceSandbox;
+    private _sandboxFromData;
+    private _forgetSandbox;
     /**
      * Generate an authenticated URL for an HTTP service running in a sandbox.
      *