langsmith 0.10.12 → 0.10.13

package/lib/utils/addressing.mjs

@@ -1,4 +1,4 @@
-import { AgentAddress, EnvAddressError, ensureAgent, envNames, } from "../address.mjs";
+import { addressFromEnv, addressFromLrn, addressToLrn, EnvAddressError, ensureAgent, envNames, } from "../address.mjs";
 import { getEnvironmentVariable, getLangSmithEnvironmentVariable, } from "./env.mjs";
 import { warnOnce } from "./warn.mjs";
 export function rejectConflicting(project, address) {
@@ -28,7 +28,7 @@ function getEnvProject() {
  */
 export function resolveFromEnv() {
     const project = getEnvProject();
-    const address = AgentAddress.fromEnv();
+    const address = addressFromEnv();
     if (project && address) {
         throw new EnvAddressError("LANGSMITH_AGENT_* and a project are both set in the environment.");
     }
@@ -64,7 +64,7 @@ export function applyToPayload(run, { update = false } = {}) {
         // is sent. It is parsed again, so a malformed one cannot fail the whole
         // batch in the backend.
         try {
-            address = AgentAddress._fromLrn(payload.address);
+            address = addressFromLrn(payload.address);
         }
         catch {
             throw new Error("The run's `address` is not a valid agent address.");
@@ -76,14 +76,14 @@ export function applyToPayload(run, { update = false } = {}) {
     delete payload.address;
     const namedProject = payload.session_id != null || payload.session_name != null;
     if (!address && !update && !namedProject) {
-        address = AgentAddress.fromEnv();
+        address = addressFromEnv();
     }
     if (!address) {
         return;
     }
     warnOnce("Sending runs to an `address` is in beta and enabled per workspace; a " +
         "workspace without it rejects the runs.");
-    payload.address = address._toLrn();
+    payload.address = addressToLrn(address);
     if (!namedProject) {
         delete payload.session_name;
         delete payload.session_id;

package/lib/utils/addressing.mjs.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "langsmith",
-  "version": "0.10.12",
+  "version": "0.10.13",
   "description": "Client library to connect to the LangSmith Observability and Evaluation Platform.",
   "author": "LangChain <>",
   "types": "./index.d.ts",
@@ -34,12 +34,13 @@
   "overrides": {
     "minimatch": "^9.0.7",
     "@hono/node-server": "2.0.10",
-    "brace-expansion@<1.1.18": "1.1.18",
+    "brace-expansion@<1.1.21": "1.1.21",
     "brace-expansion@>=2.0.0 <2.1.7": "2.1.7",
     "source-map-js": "1.2.2",
     "@modelcontextprotocol/sdk": "1.31.0",
     "handlebars": "4.7.10",
-    "brace-expansion@>=3.0.0 <5.0.7": "5.0.7",
+    "brace-expansion@>=3.0.0 <3.0.9": "3.0.9",
+    "brace-expansion@>=4.0.0 <5.0.12": "5.0.12",
     "fast-uri": "3.1.8",
     "postcss": "8.5.23",
     "js-yaml": "4.3.2",
@@ -59,12 +60,13 @@
     "overrides": {
       "minimatch": "^9.0.7",
       "@hono/node-server": "2.0.10",
-      "brace-expansion@<1.1.18": "1.1.18",
+      "brace-expansion@<1.1.21": "1.1.21",
       "brace-expansion@>=2.0.0 <2.1.7": "2.1.7",
       "source-map-js": "1.2.2",
       "@modelcontextprotocol/sdk": "1.31.0",
       "handlebars": "4.7.10",
-      "brace-expansion@>=3.0.0 <5.0.7": "5.0.7",
+      "brace-expansion@>=3.0.0 <3.0.9": "3.0.9",
+      "brace-expansion@>=4.0.0 <5.0.12": "5.0.12",
       "fast-uri": "3.1.8",
       "postcss": "8.5.23",
       "js-yaml": "4.3.2",
@@ -84,12 +86,13 @@
   "resolutions": {
     "minimatch": "^9.0.7",
     "@hono/node-server": "2.0.10",
-    "brace-expansion@<1.1.18": "1.1.18",
+    "brace-expansion@<1.1.21": "1.1.21",
     "brace-expansion@>=2.0.0 <2.1.7": "2.1.7",
     "source-map-js": "1.2.2",
     "@modelcontextprotocol/sdk": "1.31.0",
     "handlebars": "4.7.10",
-    "brace-expansion@>=3.0.0 <5.0.7": "5.0.7",
+    "brace-expansion@>=3.0.0 <3.0.9": "3.0.9",
+    "brace-expansion@>=4.0.0 <5.0.12": "5.0.12",
     "fast-uri": "3.1.8",
     "postcss": "8.5.23",
     "js-yaml": "4.3.2",

package/src/lib/address.ts

@@ -26,32 +26,67 @@ export type Environment = "local" | "development" | "staging" | "production";
  */
 export type Lrn = `lrn:agents/${string}/environments/${Environment}`;
 
-/** (beta) The backend's form of an address, as the resolve endpoint takes it. */
-export type ApiAddress = {
-  kind: "AGENT" | "EXPERIMENT" | "EVALUATOR";
-  id?: string;
-  environment?: Uppercase<Environment>;
-};
+/** (beta) The address of an agent's environment. */
+export interface AgentAddress {
+  kind: "AGENT";
+  id: string;
+  environment: Uppercase<Environment>;
+}
 
-/** (beta) A feature that holds traces in a tracing project. */
-export interface Address {
-  /** The address in the backend's form. */
-  toApiAddress(): ApiAddress;
+/** (beta) Construct and validate an agent address; plain objects are also accepted. */
+export class AgentAddress {
+  constructor(id: string, environment: Environment | (string & {})) {
+    const address = ensureAgent({ kind: "AGENT", id, environment });
+    this.kind = address.kind;
+    this.id = address.id;
+    this.environment = address.environment;
+    Object.freeze(this);
+  }
+}
+
+/** (beta) The address of an experiment's tracing project. */
+export interface ExperimentAddress {
+  kind: "EXPERIMENT";
+  id: string;
+}
+
+/** (beta) Construct and validate an experiment address. */
+export class ExperimentAddress {
+  constructor(id: string) {
+    const address = ensureAddress({ kind: "EXPERIMENT", id });
+    this.kind = address.kind;
+    this.id = address.id;
+    Object.freeze(this);
+  }
+}
+
+/** (beta) The address of the workspace's shared evaluators project. */
+export interface EvaluatorAddress {
+  kind: "EVALUATOR";
 }
 
+/** (beta) Construct the workspace's evaluators address. */
+export class EvaluatorAddress {
+  constructor() {
+    this.kind = "EVALUATOR";
+    Object.freeze(this);
+  }
+}
+
+/** (beta) A feature that holds traces in a tracing project. */
+export type Address = AgentAddress | ExperimentAddress | EvaluatorAddress;
+
+/** (beta) An address as the resolve endpoint takes it. */
+export type ApiAddress = Address;
+
 const UUID_PATTERN =
   /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 
 // The server's agent id rule: a DNS label, so a hostname can carry the id.
 const AGENT_ID_PATTERN = /^[a-z]([a-z0-9-]{0,61}[a-z0-9])?$/;
-const ENVIRONMENTS: string[] = [
-  "local",
-  "development",
-  "staging",
-  "production",
-];
-
-// The wire form of an agent address. The parts are validated by `AgentAddress`.
+const ENVIRONMENTS = ["local", "development", "staging", "production"];
+
+// The wire form of an agent address. The parts are validated at entrypoints.
 const LRN_PATTERN = /^lrn:agents\/([^/]+)\/environments\/([^/]+)$/;
 
 const ENV_NAMES = ["LANGSMITH_AGENT_ID", "LANGSMITH_AGENT_ENVIRONMENT"];
@@ -64,189 +99,112 @@ export class EnvAddressError extends Error {
   }
 }
 
-/**
- * (beta) The address of an agent's environment.
- *
- * @example
- * ```ts
- * new AgentAddress("customer-support", "production");
- * ```
- */
-export class AgentAddress implements Address {
-  readonly id: string;
-
-  /** Always lowercase. */
-  readonly environment: Environment;
-
-  /**
-   * @param id 1 to 63 lowercase ASCII letters, digits or hyphens, starting
-   *   with a letter and ending with a letter or digit. The server creates the
-   *   agent on first use.
-   * @param environment One of `local`, `development`, `staging` or `production`, in
-   *   any case.
-   * @throws If a value is invalid.
-   */
-  constructor(id: string, environment: Environment | (string & {})) {
-    if (typeof id !== "string" || !AGENT_ID_PATTERN.test(id)) {
-      throw new Error(
-        "Address agent id must be 1 to 63 lowercase ASCII letters, digits, or " +
-          "hyphens, start with a letter, and end with a letter or digit, got " +
-          `${JSON.stringify(id)}. Use an id such as "support-agent".`,
-      );
-    }
-    const normalized =
-      typeof environment === "string" ? environment.toLowerCase() : undefined;
-    if (normalized === undefined || !ENVIRONMENTS.includes(normalized)) {
-      throw new Error(
-        `Address environment must be one of ${ENVIRONMENTS.join(", ")}, got ` +
-          `${JSON.stringify(environment)}.`,
-      );
-    }
-    this.id = id;
-    this.environment = normalized as Environment;
-    Object.freeze(this);
-  }
-
-  toApiAddress(): ApiAddress {
-    return {
-      kind: "AGENT",
-      id: this.id,
-      environment: this.environment.toUpperCase() as Uppercase<Environment>,
-    };
-  }
-
-  /** @internal */
-  _toLrn(): Lrn {
-    return `lrn:agents/${this.id}/environments/${this.environment}`;
-  }
-
-  /**
-   * @internal Parse an LRN read from the wire, such as a `baggage` header. The
-   * value is untrusted, so it is not echoed in the error.
-   * @throws If `value` is not an agent LRN, or names an invalid id or environment.
-   */
-  static _fromLrn(value: unknown): AgentAddress {
-    const match = typeof value === "string" ? LRN_PATTERN.exec(value) : null;
-    if (match === null) {
-      throw new Error("Not an agent address.");
-    }
-    return new AgentAddress(match[1], match[2]);
-  }
-
-  /**
-   * Read the agent named by `LANGSMITH_AGENT_ID` and
-   * `LANGSMITH_AGENT_ENVIRONMENT`; `undefined` if neither is set.
-   * @throws {EnvAddressError} If only one is set, or a value is invalid.
-   */
-  static fromEnv(): AgentAddress | undefined {
-    const values = ENV_NAMES.map((name) => getEnvironmentVariable(name));
-    if (!values.some(Boolean)) {
-      return undefined;
-    }
-    try {
-      const missing = ENV_NAMES.filter((_, i) => !values[i]);
-      if (missing.length > 0) {
-        throw new Error(`An address needs ${missing.join(" and ")} as well.`);
-      }
-      return new AgentAddress(values[0] as string, values[1] as string);
-    } catch (e) {
-      const present = ENV_NAMES.flatMap((name, i) =>
-        values[i] ? [`${name}=${JSON.stringify(values[i])}`] : [],
-      ).join(", ");
-      throw new EnvAddressError(
-        `The LANGSMITH_AGENT_* env vars can't address a run (${present}): ${
-          (e as Error).message
-        }`,
-      );
-    }
+/** Validate an address at an SDK entrypoint and return a normalized copy. */
+export function ensureAddress<K extends Address["kind"]>(value: {
+  kind: K;
+  id?: unknown;
+  environment?: unknown;
+}): Extract<Address, { kind: K }>;
+export function ensureAddress(value: unknown): Address | undefined;
+export function ensureAddress(value: unknown): Address | undefined {
+  if (value == null) return undefined;
+  if (typeof value !== "object") {
+    throw new Error(
+      "address must be an AgentAddress, ExperimentAddress or EvaluatorAddress object.",
+    );
   }
-}
-
-/** (beta) The address of an experiment's tracing project. */
-export class ExperimentAddress implements Address {
-  /** Always lowercase. */
-  readonly id: string;
-
-  /**
-   * @param id The experiment's UUID.
-   * @throws If `id` is not a UUID.
-   */
-  constructor(id: string) {
+  const { kind, id, environment } = value as Record<string, unknown>;
+  if (kind === "EVALUATOR") return { kind };
+  if (kind === "EXPERIMENT") {
     if (typeof id !== "string" || !UUID_PATTERN.test(id)) {
       throw new Error(
         `Experiment id must be a UUID, got ${JSON.stringify(id)}.`,
       );
     }
-    this.id = id.toLowerCase();
-    Object.freeze(this);
+    return { kind, id: id.toLowerCase() };
   }
-
-  toApiAddress(): ApiAddress {
-    return { kind: "EXPERIMENT", id: this.id };
+  if (kind !== "AGENT") {
+    throw new Error(
+      "address must be an AgentAddress, ExperimentAddress or EvaluatorAddress object.",
+    );
   }
-}
-
-/** (beta) The address of the workspace's shared evaluators project. */
-export class EvaluatorAddress implements Address {
-  constructor() {
-    Object.freeze(this);
+  if (typeof id !== "string" || !AGENT_ID_PATTERN.test(id)) {
+    throw new Error(
+      "Address agent id must be 1 to 63 lowercase ASCII letters, digits, or " +
+        "hyphens, start with a letter, and end with a letter or digit, got " +
+        `${JSON.stringify(id)}. Use an id such as "support-agent".`,
+    );
   }
-
-  toApiAddress(): ApiAddress {
-    return { kind: "EVALUATOR" };
+  const normalized =
+    typeof environment === "string" ? environment.toLowerCase() : undefined;
+  if (normalized === undefined || !ENVIRONMENTS.includes(normalized)) {
+    throw new Error(
+      `Address environment must be one of ${ENVIRONMENTS.join(
+        ", ",
+      )}, got ${JSON.stringify(environment)}.`,
+    );
   }
+  return {
+    kind,
+    id,
+    environment: normalized.toUpperCase() as Uppercase<Environment>,
+  };
 }
 
-/**
- * @internal The ingestion entry-point guard: `value` must be an `AgentAddress` (or
- * absent), and is returned as is. Other addresses and strings are rejected.
- * @throws If `value` is not an `AgentAddress`.
- */
+/** @internal Only agent addresses can receive traces. */
+export function ensureAgent(value: {
+  kind: "AGENT";
+  id?: unknown;
+  environment?: unknown;
+}): AgentAddress;
+export function ensureAgent(value: unknown): AgentAddress | undefined;
 export function ensureAgent(value: unknown): AgentAddress | undefined {
-  if (value == null) {
-    return undefined;
-  }
-  if (value instanceof AgentAddress) {
-    return value;
-  }
-  if (
-    typeof value === "object" &&
-    typeof (value as Address).toApiAddress === "function"
-  ) {
+  const address = ensureAddress(value);
+  if (address && address.kind !== "AGENT") {
     throw new Error(
-      `Only an AgentAddress can receive traces, got ${
-        (value as object).constructor?.name ?? "an unknown address"
-      }.`,
+      `Only an AgentAddress can receive traces, got ${address.kind}.`,
     );
   }
-  throw new Error(
-    "address must be an AgentAddress such as `new AgentAddress(id, environment)`, got " +
-      `${typeof value === "string" ? JSON.stringify(value) : typeof value}.`,
-  );
+  return address;
 }
 
-/**
- * Return `value` if it is an `Address` of any kind, as a lookup takes it.
- * For the calls that only resolve an address to its project, such as
- * `getRunUrl`. Whatever receives traces takes `ensureAgent`.
- */
-export function ensureAddress(value: unknown): Address | undefined {
-  if (value == null) {
-    return undefined;
-  }
-  if (
-    typeof value === "object" &&
-    typeof (value as Address).toApiAddress === "function"
-  ) {
-    return value as Address;
+/** @internal Convert a validated address to the ingestion wire format. */
+export function addressToLrn(address: AgentAddress): Lrn {
+  return `lrn:agents/${address.id}/environments/${
+    address.environment.toLowerCase() as Environment
+  }`;
+}
+
+/** @internal Parse and validate an address from untrusted wire data. */
+export function addressFromLrn(value: unknown): AgentAddress {
+  const match = typeof value === "string" ? LRN_PATTERN.exec(value) : null;
+  if (!match) throw new Error("Not an agent address.");
+  return ensureAgent({ kind: "AGENT", id: match[1], environment: match[2] });
+}
+
+/** @internal Read and validate the address named by environment variables. */
+export function addressFromEnv(): AgentAddress | undefined {
+  const values = ENV_NAMES.map((name) => getEnvironmentVariable(name));
+  if (!values.some(Boolean)) return undefined;
+  try {
+    const missing = ENV_NAMES.filter((_, i) => !values[i]);
+    if (missing.length)
+      throw new Error(`An address needs ${missing.join(" and ")} as well.`);
+    return ensureAgent({
+      kind: "AGENT",
+      id: values[0],
+      environment: values[1],
+    });
+  } catch (e) {
+    throw new EnvAddressError(
+      `The LANGSMITH_AGENT_* env vars can't address a run: ${
+        (e as Error).message
+      }`,
+    );
   }
-  throw new Error(
-    "address must be an AgentAddress, ExperimentAddress or EvaluatorAddress, got " +
-      `${typeof value === "string" ? JSON.stringify(value) : typeof value}.`,
-  );
 }
 
-/** @internal The `LANGSMITH_AGENT_*` env var names an address reads. */
+/** @internal The environment variable names an address reads. */
 export function envNames(): string[] {
   return ENV_NAMES;
 }

package/src/lib/client.ts

@@ -1,3 +1,4 @@
+import { addressToLrn } from "./address.js";
 import * as uuid from "./utils/uuid/src/index.js";
 import { getOpenAPIBaseUrl } from "./utils/api_url.js";
 import type { OTELContext } from "./experimental/otel/types.js";
@@ -1861,7 +1862,7 @@ export class Client implements LangSmithTracingClientInterface {
 
   /**
    * (beta) Access the sessions resource, which resolves an address to the
-   * project its traces go to: `client.sessions.resolve(address.toApiAddress())`.
+   * project its traces go to: `client.sessions.resolve(address)`.
    */
   public get sessions(): Sessions {
     this._checkStainlessVersion("0.18.0");
@@ -3359,9 +3360,7 @@ export class Client implements LangSmithTracingClientInterface {
 
   /** The ID of the project an address names, with one request. */
   private async _resolveAddress(address: Address): Promise<string> {
-    const { session_id: sessionId } = await this.sessions.resolve(
-      address.toApiAddress(),
-    );
+    const { session_id: sessionId } = await this.sessions.resolve(address);
     assertUuid(sessionId);
     return sessionId;
   }
@@ -5672,7 +5671,7 @@ export class Client implements LangSmithTracingClientInterface {
       return feedback as Feedback;
     }
     const body = JSON.stringify(
-      address ? { ...feedback, address: address._toLrn() } : feedback,
+      address ? { ...feedback, address: addressToLrn(address) } : feedback,
     );
     const url = `${this.apiUrl}/feedback`;
     await this.caller.call(async () => {

package/src/lib/run_trees.ts

@@ -1,3 +1,4 @@
+import { addressToLrn, addressFromLrn } from "./address.js";
 import { Client } from "./client.js";
 import { isEnvTracingEnabled } from "./env.js";
 import {
@@ -33,7 +34,7 @@ import {
   rejectConflicting,
   resolveFromEnv,
 } from "./utils/addressing.js";
-import { AgentAddress, EnvAddressError, ensureAgent } from "./address.js";
+import { type AgentAddress, EnvAddressError, ensureAgent } from "./address.js";
 
 const TIMESTAMP_LENGTH = 36;
 // DNS namespace for UUID v5 (same as Python's uuid.NAMESPACE_DNS)
@@ -197,7 +198,7 @@ const HEADER_SAFE_REPLICA_FIELDS = new Set([
 /** Rebuilds an untrusted header address; `undefined` if unusable. */
 function addressFromHeader(value: unknown): AgentAddress | undefined {
   try {
-    return AgentAddress._fromLrn(value);
+    return addressFromLrn(value);
   } catch {
     // Values are untrusted, so not logged.
     console.warn("Ignoring an unusable address in a `baggage` header.");
@@ -301,7 +302,7 @@ class Baggage {
     }
     if (this.address) {
       items.push(
-        `langsmith-address=${encodeURIComponent(this.address._toLrn())}`,
+        `langsmith-address=${encodeURIComponent(addressToLrn(this.address))}`,
       );
     }
 
@@ -752,7 +753,8 @@ export class RunTree implements BaseRun {
       primary === undefined &&
       !this.replicas?.some((r) => r.primary === true) &&
       projectName === this.project_name &&
-      address?._toLrn() === this.address?._toLrn()
+      (address ? addressToLrn(address) : undefined) ===
+        (this.address ? addressToLrn(this.address) : undefined)
     ) {
       return {
         ...baseRun,
@@ -760,7 +762,8 @@ export class RunTree implements BaseRun {
         address,
       };
     }
-    const seed = projectName ?? address?._toLrn() ?? "agent//";
+    const seed =
+      projectName ?? (address ? addressToLrn(address) : undefined) ?? "agent//";
 
     // Apply reroot logic before ID remapping
     if (reroot) {

package/src/lib/utils/addressing.ts

@@ -1,5 +1,8 @@
 import {
-  AgentAddress,
+  type AgentAddress,
+  addressFromEnv,
+  addressFromLrn,
+  addressToLrn,
   EnvAddressError,
   ensureAgent,
   envNames,
@@ -47,7 +50,7 @@ function getEnvProject(): string | undefined {
  */
 export function resolveFromEnv(): Tier {
   const project = getEnvProject();
-  const address = AgentAddress.fromEnv();
+  const address = addressFromEnv();
   if (project && address) {
     throw new EnvAddressError(
       "LANGSMITH_AGENT_* and a project are both set in the environment.",
@@ -92,7 +95,7 @@ export function applyToPayload(
     // is sent. It is parsed again, so a malformed one cannot fail the whole
     // batch in the backend.
     try {
-      address = AgentAddress._fromLrn(payload.address);
+      address = addressFromLrn(payload.address);
     } catch {
       throw new Error("The run's `address` is not a valid agent address.");
     }
@@ -103,7 +106,7 @@ export function applyToPayload(
   const namedProject =
     payload.session_id != null || payload.session_name != null;
   if (!address && !update && !namedProject) {
-    address = AgentAddress.fromEnv();
+    address = addressFromEnv();
   }
   if (!address) {
     return;
@@ -112,7 +115,7 @@ export function applyToPayload(
     "Sending runs to an `address` is in beta and enabled per workspace; a " +
       "workspace without it rejects the runs.",
   );
-  payload.address = address._toLrn();
+  payload.address = addressToLrn(address);
   if (!namedProject) {
     delete payload.session_name;
     delete payload.session_id;

package/src/version.ts

@@ -1 +1 @@
-export const VERSION = '0.10.12'; // x-release-please-version
+export const VERSION = '0.10.13'; // x-release-please-version

package/version.d.mts

@@ -1,2 +1,2 @@
-export declare const VERSION = "0.10.12";
+export declare const VERSION = "0.10.13";
 //# sourceMappingURL=version.d.mts.map

package/version.d.ts

@@ -1,2 +1,2 @@
-export declare const VERSION = "0.10.12";
+export declare const VERSION = "0.10.13";
 //# sourceMappingURL=version.d.ts.map

package/version.js

@@ -1,5 +1,5 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.VERSION = void 0;
-exports.VERSION = '0.10.12'; // x-release-please-version
+exports.VERSION = '0.10.13'; // x-release-please-version
 //# sourceMappingURL=version.js.map

package/version.mjs

@@ -1,2 +1,2 @@
-export const VERSION = '0.10.12'; // x-release-please-version
+export const VERSION = '0.10.13'; // x-release-please-version
 //# sourceMappingURL=version.mjs.map