langsmith 0.10.7 → 0.10.9

package/dist/address.js

@@ -1,21 +1,34 @@
-// Wire key per field; env var is `LANGSMITH_<WIRE KEY>`.
-const FIELDS = {
-    agentId: "agent_id",
-    agentEnvironment: "agent_environment",
-};
+/**
+ * (beta) Addresses that name where runs are sent instead of a project.
+ * Enabled per workspace; a workspace without it rejects the runs.
+ *
+ * An `Address` names a tracing project held by a feature: an `AgentAddress`, an
+ * `ExperimentAddress` or the workspace's `EvaluatorAddress`. Any of them can be resolved to
+ * its project. Only an `AgentAddress` can receive traces, and ingestion rejects the
+ * others at its entry points.
+ *
+ * @example
+ * ```ts
+ * import { AgentAddress, traceable } from "langsmith";
+ *
+ * const support = new AgentAddress("customer-support", "production");
+ * const handle = traceable(fn, { address: support });
+ * ```
+ */
+import { getEnvironmentVariable } from "./utils/env.js";
+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])?$/;
-// Not `utils/env`: it imports the package index, which imports this module.
-function getEnv(name) {
-    try {
-        // eslint-disable-next-line no-process-env
-        return typeof process !== "undefined" ? process.env?.[name] : undefined;
-    }
-    catch {
-        return undefined;
-    }
-}
-/** The `LANGSMITH_AGENT_*` / project env vars name half an address, or both. */
+const ENVIRONMENTS = [
+    "local",
+    "development",
+    "staging",
+    "production",
+];
+// The wire form of an agent address. The parts are validated by `AgentAddress`.
+const LRN_PATTERN = /^lrn:agents\/([^/]+)\/environments\/([^/]+)$/;
+const ENV_NAMES = ["LANGSMITH_AGENT_ID", "LANGSMITH_AGENT_ENVIRONMENT"];
+/** (beta) The `LANGSMITH_AGENT_*` / project env vars name half an address, or both. */
 export class EnvAddressError extends Error {
     constructor(message) {
         super(message);
@@ -23,98 +36,165 @@ export class EnvAddressError extends Error {
     }
 }
 /**
- * @internal Validate `value` and return a frozen copy of its fields.
- * @throws If it isn't an object with exactly the address fields, or a value is invalid.
+ * (beta) The address of an agent's environment.
+ *
+ * @example
+ * ```ts
+ * new AgentAddress("customer-support", "production");
+ * ```
  */
-export function normalizeAddress(value) {
-    if (value == null || typeof value !== "object" || Array.isArray(value)) {
-        throw new Error("`address` must be an object: { agentId, agentEnvironment }.");
+export class AgentAddress {
+    /**
+     * @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, environment) {
+        Object.defineProperty(this, "id", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        /** Always lowercase. */
+        Object.defineProperty(this, "environment", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        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;
+        Object.freeze(this);
+    }
+    toApiAddress() {
+        return {
+            kind: "AGENT",
+            id: this.id,
+            environment: this.environment.toUpperCase(),
+        };
     }
-    const fields = value;
-    const unknown = Object.keys(fields).filter((key) => !(key in FIELDS));
-    if (unknown.length > 0) {
-        throw new Error(`Unknown address fields: ${unknown.join(", ")}.`);
+    /** @internal */
+    _toLrn() {
+        return `lrn:agents/${this.id}/environments/${this.environment}`;
     }
-    for (const name of Object.keys(FIELDS)) {
-        const field = fields[name];
-        if (typeof field !== "string" || field === "") {
-            throw new Error(`Address ${name} must be a non-empty string.`);
+    /**
+     * @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) {
+        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]);
     }
-    const { agentId, agentEnvironment } = fields;
-    if (!AGENT_ID_PATTERN.test(agentId)) {
-        throw new Error("Address agentId 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(agentId)}. Use an id such as "support-agent".`);
+    /**
+     * 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() {
+        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], values[1]);
+        }
+        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.message}`);
+        }
     }
-    return Object.freeze({ agentId, agentEnvironment });
 }
-/** @internal */
-export function wireKeys() {
-    return Object.values(FIELDS);
+/** (beta) The address of an experiment's tracing project. */
+export class ExperimentAddress {
+    /**
+     * @param id The experiment's UUID.
+     * @throws If `id` is not a UUID.
+     */
+    constructor(id) {
+        /** Always lowercase. */
+        Object.defineProperty(this, "id", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        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);
+    }
+    toApiAddress() {
+        return { kind: "EXPERIMENT", id: this.id };
+    }
 }
-/** @internal */
-export function envNames() {
-    return wireKeys().map((key) => `LANGSMITH_${key.toUpperCase()}`);
+/** (beta) The address of the workspace's shared evaluators project. */
+export class EvaluatorAddress {
+    constructor() {
+        Object.freeze(this);
+    }
+    toApiAddress() {
+        return { kind: "EVALUATOR" };
+    }
 }
 /**
- * @internal The `address` object of a run / feedback payload. `kind` and
- * `environment` are uppercase and case-sensitive on the wire.
+ * @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`.
  */
-export function toPayload(address) {
-    return {
-        address: {
-            kind: "AGENT",
-            id: address.agentId,
-            environment: address.agentEnvironment.toUpperCase(),
-        },
-    };
-}
-/** @internal Header / replica fields. */
-export function toWire(address) {
-    return {
-        [FIELDS.agentId]: address.agentId,
-        [FIELDS.agentEnvironment]: address.agentEnvironment,
-    };
-}
-/** @internal `undefined` if no field is set; throws if only some are. */
-export function fromWire(values) {
-    const fields = Object.fromEntries(Object.entries(FIELDS).map(([name, key]) => [
-        name,
-        values[key] ?? undefined,
-    ]));
-    const missing = Object.entries(FIELDS)
-        .filter(([name]) => fields[name] === undefined)
-        .map(([, key]) => key);
-    if (missing.length === Object.keys(FIELDS).length) {
+export function ensureAgent(value) {
+    if (value == null) {
         return undefined;
     }
-    if (missing.length > 0) {
-        throw new Error(`An address needs ${missing.join(" and ")} as well.`);
+    if (value instanceof AgentAddress) {
+        return value;
+    }
+    if (typeof value === "object" &&
+        typeof value.toApiAddress === "function") {
+        throw new Error(`Only an AgentAddress can receive traces, got ${value.constructor?.name ?? "an unknown address"}.`);
     }
-    return normalizeAddress(fields);
+    throw new Error("address must be an AgentAddress such as `new AgentAddress(id, environment)`, got " +
+        `${typeof value === "string" ? JSON.stringify(value) : typeof value}.`);
 }
 /**
- * @internal
- * @throws {EnvAddressError} If only some `LANGSMITH_AGENT_*` vars are set, or one is invalid.
+ * 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 addressFromEnv() {
-    const values = Object.fromEntries(wireKeys().map((key, i) => [key, getEnv(envNames()[i]) || undefined]));
-    try {
-        return fromWire(values);
+export function ensureAddress(value) {
+    if (value == null) {
+        return undefined;
     }
-    catch (e) {
-        throw new EnvAddressError(`The LANGSMITH_AGENT_* env vars can't address a run: ${e.message}`);
+    if (typeof value === "object" &&
+        typeof value.toApiAddress === "function") {
+        return value;
     }
+    throw new Error("address must be an AgentAddress, ExperimentAddress or EvaluatorAddress, got " +
+        `${typeof value === "string" ? JSON.stringify(value) : typeof value}.`);
 }
-/** @internal Replica id derivation seed. */
-export function seed(address) {
-    return ["agent", ...Object.values(toWire(address))].join("/");
-}
-/** @internal */
-export function sameAddress(a, b) {
-    if (!a || !b) {
-        return a === b;
-    }
-    return a.agentId === b.agentId && a.agentEnvironment === b.agentEnvironment;
+/** @internal The `LANGSMITH_AGENT_*` env var names an address reads. */
+export function envNames() {
+    return ENV_NAMES;
 }

package/dist/anonymizer/index.cjs

@@ -224,7 +224,7 @@ exports.DEFAULT_SECRET_RULES = [
     //  - value excludes & and ; so query-string params past the secret survive.
     //  - requires a 6+ char value so short non-secret values are not touched.
     {
-        pattern: /\b([A-Za-z0-9_.-]*(?:API[_-]?KEY|SECRET|TOKEN|PASSWORD|PASSWD|PRIVATE[_-]?KEY|ACCESS[_-]?KEY|AUTH[_-]?TOKEN|CLIENT[_-]?SECRET)(?![A-Za-z0-9])(?:[_.-][A-Za-z0-9]+)*["']?\s*[:=]\s*["']?)(?:(?:bearer|token|basic)\s+)?[^\s"'&;]{6,}/gi,
+        pattern: /\b([A-Za-z0-9_.-]*(?:API[_-]?KEY[_-]?SALT|LICENSE[_-]?KEY|API[_-]?KEY|SECRET|TOKEN|PASSWORD|PASSWD|PRIVATE[_-]?KEY|ACCESS[_-]?KEY|AUTH[_-]?TOKEN|CLIENT[_-]?SECRET)(?![A-Za-z0-9])(?:[_.-][A-Za-z0-9]+)*["']?\s*[:=]\s*["']?)(?:(?:bearer|token|basic)\s+)?[^\s"'&;]{6,}/gi,
         replace: `$1${exports.SECRET_PLACEHOLDER}`,
     },
     // Authorization / API-key headers. Keep the header name + separator ($1$2)

package/dist/anonymizer/index.js

@@ -219,7 +219,7 @@ export const DEFAULT_SECRET_RULES = [
     //  - value excludes & and ; so query-string params past the secret survive.
     //  - requires a 6+ char value so short non-secret values are not touched.
     {
-        pattern: /\b([A-Za-z0-9_.-]*(?:API[_-]?KEY|SECRET|TOKEN|PASSWORD|PASSWD|PRIVATE[_-]?KEY|ACCESS[_-]?KEY|AUTH[_-]?TOKEN|CLIENT[_-]?SECRET)(?![A-Za-z0-9])(?:[_.-][A-Za-z0-9]+)*["']?\s*[:=]\s*["']?)(?:(?:bearer|token|basic)\s+)?[^\s"'&;]{6,}/gi,
+        pattern: /\b([A-Za-z0-9_.-]*(?:API[_-]?KEY[_-]?SALT|LICENSE[_-]?KEY|API[_-]?KEY|SECRET|TOKEN|PASSWORD|PASSWD|PRIVATE[_-]?KEY|ACCESS[_-]?KEY|AUTH[_-]?TOKEN|CLIENT[_-]?SECRET)(?![A-Za-z0-9])(?:[_.-][A-Za-z0-9]+)*["']?\s*[:=]\s*["']?)(?:(?:bearer|token|basic)\s+)?[^\s"'&;]{6,}/gi,
         replace: `$1${SECRET_PLACEHOLDER}`,
     },
     // Authorization / API-key headers. Keep the header name + separator ($1$2)

package/dist/client.cjs

@@ -48,7 +48,7 @@ const _uuid_js_1 = require("./utils/_uuid.cjs");
 const sampling_js_1 = require("./utils/sampling.cjs");
 const warn_js_1 = require("./utils/warn.cjs");
 const address_js_1 = require("./address.cjs");
-const agent_addressing_js_1 = require("./utils/agent_addressing.cjs");
+const addressing_js_1 = require("./utils/addressing.cjs");
 const v2_migration_js_1 = require("./utils/v2_migration.cjs");
 const prompts_js_1 = require("./utils/prompts.cjs");
 const error_js_1 = require("./utils/error.cjs");
@@ -943,7 +943,7 @@ class Client {
         }
         // Cache metadata env vars once during construction to avoid repeatedly scanning process.env
         this.cachedLSEnvVarsForMetadata = (0, env_js_1.getLangSmithEnvVarsMetadata)();
-        (0, agent_addressing_js_1.warnOnEnv)();
+        (0, addressing_js_1.warnOnEnv)();
         // Initialize prompt cache
         // Handle backwards compatibility for deprecated `cache` parameter
         if (config.cache !== undefined && config.disablePromptCache) {
@@ -1233,6 +1233,14 @@ class Client {
         this._checkStainlessVersion("0.16.0");
         return this.openAPIClient.traces;
     }
+    /**
+     * (beta) Access the sessions resource, which resolves an address to the
+     * project its traces go to: `client.sessions.resolve(address.toApiAddress())`.
+     */
+    get sessions() {
+        this._checkStainlessVersion("0.18.0");
+        return this.openAPIClient.sessions;
+    }
     /** Access the public shared-run resource. */
     get public() {
         this._checkStainlessVersion("0.16.0");
@@ -1313,7 +1321,7 @@ class Client {
     }
     async prepareRunCreateOrUpdateInputs(run, options) {
         const runParams = { ...run };
-        (0, agent_addressing_js_1.applyToPayload)(runParams, { update: options?.update ?? false });
+        (0, addressing_js_1.applyToPayload)(runParams, { update: options?.update ?? false });
         if (runParams.inputs !== undefined) {
             runParams.inputs = await this.processInputs(runParams.inputs);
         }
@@ -1795,21 +1803,21 @@ class Client {
             ...this._mergedHeaders,
             "Content-Type": "application/json",
         };
-        const address = (0, agent_addressing_js_1.checkAddress)(run.address);
+        const address = (0, address_js_1.ensureAgent)(run.address);
         // `RunTree.postRun` passes a built run body, carrying the wire `session_name`.
         const bodySessionName = run.session_name;
-        (0, agent_addressing_js_1.rejectConflicting)(run.project_name ?? bodySessionName, address);
+        (0, addressing_js_1.rejectConflicting)(run.project_name ?? bodySessionName, address);
         const session_name = run.project_name;
         delete run.project_name;
         if (!session_name && bodySessionName == null && !address) {
             try {
-                run.address = (0, agent_addressing_js_1.resolveFromEnv)()[1];
+                run.address = (0, addressing_js_1.resolveFromEnv)()[1];
             }
             catch (e) {
                 if (!(e instanceof address_js_1.EnvAddressError)) {
                     throw e;
                 }
-                (0, agent_addressing_js_1.logUntraced)(e);
+                (0, addressing_js_1.logUntraced)(e);
                 return;
             }
         }
@@ -2222,8 +2230,8 @@ class Client {
         if (run.events) {
             run.events = this._filterNewTokenEvents(run.events);
         }
-        // On `run` too: the direct path below serializes it.
-        (0, agent_addressing_js_1.applyToPayload)(run, { update: true });
+        // Fail on a bad address now; the queued path validates again when built.
+        (0, address_js_1.ensureAgent)(run.address);
         // TODO: Untangle types
         const data = { ...run, id: runId };
         if (!this._filterForSampling([data]).length) {
@@ -2271,9 +2279,11 @@ class Client {
         if (options?.workspaceId !== undefined) {
             headers["x-tenant-id"] = options.workspaceId;
         }
-        const body = (0, index_js_4.serialize)(run.extra
-            ? mergeRuntimeEnvIntoRun(run, this.cachedLSEnvVarsForMetadata, this.omitTracedRuntimeInfo, this.tracingSampleRate)
-            : run, `Serializing payload to update run with id: ${runId}`);
+        const wireRun = { ...run };
+        (0, addressing_js_1.applyToPayload)(wireRun, { update: true });
+        const body = (0, index_js_4.serialize)(wireRun.extra
+            ? mergeRuntimeEnvIntoRun(wireRun, this.cachedLSEnvVarsForMetadata, this.omitTracedRuntimeInfo, this.tracingSampleRate)
+            : wireRun, `Serializing payload to update run with id: ${runId}`);
         await this.caller.call(async () => {
             const res = await this._fetch(`${options?.apiUrl ?? this.apiUrl}/runs/${runId}`, {
                 method: "PATCH",
@@ -2310,14 +2320,15 @@ class Client {
         return run;
     }
     /** @deprecated Use `client.runs.getURL()` instead. See https://docs.langchain.com/langsmith/smithdb-sdk-migration-runs#runs-get-url for the migration guide. Will be removed after Jan 31, 2027. */
-    async getRunUrl({ runId, run, projectOpts, }) {
+    async getRunUrl({ runId, run, projectOpts, address: rawAddress, }) {
         (0, warn_js_1.warnOnce)("getRunUrl() is deprecated and will be removed after Jan 31, 2027. " +
             "Use client.runs.getURL() instead. " +
             "See https://docs.langchain.com/langsmith/smithdb-sdk-migration-runs#runs-get-url for the migration guide.", { type: "DeprecationWarning", code: "LANGSMITH_DEPRECATED_GET_RUN_URL" });
         if (run !== undefined) {
-            if (!run.session_id && run.address) {
-                throw new Error("Addressed runs have no URL until read back.");
-            }
+            const argumentAddress = (0, address_js_1.ensureAddress)(rawAddress);
+            (0, addressing_js_1.rejectConflicting)(projectOpts?.projectName ?? projectOpts?.projectId, argumentAddress);
+            const address = argumentAddress ??
+                (0, address_js_1.ensureAgent)(run.address);
             let sessionId;
             if (run.session_id) {
                 sessionId = run.session_id;
@@ -2328,6 +2339,9 @@ class Client {
             else if (projectOpts?.projectId) {
                 sessionId = projectOpts?.projectId;
             }
+            else if (address) {
+                sessionId = await this._resolveAddress(address);
+            }
             else {
                 const project = await this.readProject({
                     projectName: (0, env_js_1.getLangSmithEnvironmentVariable)("PROJECT") || "default",
@@ -2351,6 +2365,12 @@ class Client {
             throw new Error("Must provide either runId or run");
         }
     }
+    /** The ID of the project an address names, with one request. */
+    async _resolveAddress(address) {
+        const { session_id: sessionId } = await this.sessions.resolve(address.toApiAddress());
+        (0, _uuid_js_1.assertUuid)(sessionId);
+        return sessionId;
+    }
     async _loadChildRuns(run) {
         const childRuns = await toArray(this._listRuns({
             isRoot: false,
@@ -3943,8 +3963,8 @@ class Client {
         const { runId = null, key, score, value, correction, comment, sourceInfo, feedbackSourceType = "api", sourceRunId, feedbackId, feedbackConfig, projectId, traceId, comparativeExperimentId, sessionId, startTime, extendTraceRetention, address: rawAddress, } = typeof runIdOrParams === "object" && runIdOrParams !== null
             ? runIdOrParams
             : { runId: runIdOrParams, key: keyArg, ...optionsArg };
-        const address = (0, agent_addressing_js_1.checkAddress)(rawAddress);
-        (0, agent_addressing_js_1.rejectConflicting)(sessionId ?? projectId, address);
+        const address = (0, address_js_1.ensureAgent)(rawAddress);
+        (0, addressing_js_1.rejectConflicting)(sessionId ?? projectId, address);
         if (!runId && !projectId) {
             throw new Error("One of runId or projectId must be provided");
         }
@@ -3987,7 +4007,7 @@ class Client {
         if (samplingId != null && !this._shouldSample(samplingId)) {
             return feedback;
         }
-        const body = JSON.stringify(address ? { ...feedback, ...(0, address_js_1.toPayload)(address) } : feedback);
+        const body = JSON.stringify(address ? { ...feedback, address: address._toLrn() } : feedback);
         const url = `${this.apiUrl}/feedback`;
         await this.caller.call(async () => {
             const res = await this._fetch(url, {

package/dist/client.d.ts

@@ -10,8 +10,9 @@ import { Datasets } from "./_openapi_client/resources/datasets/datasets.js";
 import { AnnotationQueues } from "./_openapi_client/resources/annotation-queues/annotation-queues.js";
 import { Threads } from "./_openapi_client/resources/threads.js";
 import { Traces } from "./_openapi_client/resources/traces.js";
+import { Sessions } from "./_openapi_client/resources/sessions.js";
 import { Public } from "./_openapi_client/resources/public/public.js";
-import { type Address } from "./address.js";
+import { type Address, type AgentAddress } from "./address.js";
 import { PromptCache } from "./utils/prompt_cache/index.js";
 import { ProfileAuth } from "./utils/profiles.js";
 export interface ClientConfig {
@@ -328,7 +329,7 @@ interface CreateRunParams {
     parent_run_id?: string;
     project_name?: string;
     /** (beta) Send the run to this address instead of a project. */
-    address?: Address;
+    address?: AgentAddress;
     revision_id?: string;
     trace_id?: string;
     dotted_order?: string;
@@ -386,7 +387,7 @@ export type CreateFeedbackParams = CreateFeedbackOptions & ({
     /** The run to provide feedback on. */
     runId: string;
     /** (beta) The address the run was sent to, e.g. `runTree.address`. */
-    address: Address;
+    address: AgentAddress;
     sessionId?: never;
     projectId?: never;
 } | {
@@ -634,6 +635,11 @@ export declare class Client implements LangSmithTracingClientInterface {
     get threads(): Threads;
     /** Access the traces resource (query, listRuns). */
     get traces(): Traces;
+    /**
+     * (beta) Access the sessions resource, which resolves an address to the
+     * project its traces go to: `client.sessions.resolve(address.toApiAddress())`.
+     */
+    get sessions(): Sessions;
     /** Access the public shared-run resource. */
     get public(): Public;
     private processInputs;
@@ -750,11 +756,21 @@ export declare class Client implements LangSmithTracingClientInterface {
         loadChildRuns: boolean;
     }): Promise<Run>;
     /** @deprecated Use `client.runs.getURL()` instead. See https://docs.langchain.com/langsmith/smithdb-sdk-migration-runs#runs-get-url for the migration guide. Will be removed after Jan 31, 2027. */
-    getRunUrl({ runId, run, projectOpts, }: {
+    getRunUrl({ runId, run, projectOpts, address: rawAddress, }: {
         runId?: string;
         run?: Run;
         projectOpts?: ProjectOptions;
+        /**
+         * (beta) An address that names the run's project, such as the
+         * `AgentAddress` the run was sent to or an `ExperimentAddress`, for a run
+         * that names no project. It is resolved to its project with one request,
+         * which needs LangSmith 0.18 or later. It must name the project the run is
+         * in. A run that carries its own `address` does not need it.
+         */
+        address?: Address;
     }): Promise<string>;
+    /** The ID of the project an address names, with one request. */
+    private _resolveAddress;
     private _loadChildRuns;
     /**
      * List runs from the LangSmith server.

package/dist/client.js

@@ -9,8 +9,8 @@ import { Langsmith as OpenAPILangsmith } from "./_openapi_client/index.js";
 import { assertUuid } from "./utils/_uuid.js";
 import { isSampledById } from "./utils/sampling.js";
 import { warnOnce } from "./utils/warn.js";
-import { EnvAddressError, toPayload } from "./address.js";
-import { applyToPayload, checkAddress, logUntraced, rejectConflicting, resolveFromEnv, warnOnEnv, } from "./utils/agent_addressing.js";
+import { EnvAddressError, ensureAddress, ensureAgent, } from "./address.js";
+import { applyToPayload, logUntraced, rejectConflicting, resolveFromEnv, warnOnEnv, } from "./utils/addressing.js";
 import { getQueryBackend, QueryBackend } from "./utils/v2_migration.js";
 import { parseHubIdentifier } from "./utils/prompts.js";
 import { raiseForStatus, isLangSmithNotFoundError, isLangSmithConflictError, } from "./utils/error.js";
@@ -1194,6 +1194,14 @@ export class Client {
         this._checkStainlessVersion("0.16.0");
         return this.openAPIClient.traces;
     }
+    /**
+     * (beta) Access the sessions resource, which resolves an address to the
+     * project its traces go to: `client.sessions.resolve(address.toApiAddress())`.
+     */
+    get sessions() {
+        this._checkStainlessVersion("0.18.0");
+        return this.openAPIClient.sessions;
+    }
     /** Access the public shared-run resource. */
     get public() {
         this._checkStainlessVersion("0.16.0");
@@ -1756,7 +1764,7 @@ export class Client {
             ...this._mergedHeaders,
             "Content-Type": "application/json",
         };
-        const address = checkAddress(run.address);
+        const address = ensureAgent(run.address);
         // `RunTree.postRun` passes a built run body, carrying the wire `session_name`.
         const bodySessionName = run.session_name;
         rejectConflicting(run.project_name ?? bodySessionName, address);
@@ -2183,8 +2191,8 @@ export class Client {
         if (run.events) {
             run.events = this._filterNewTokenEvents(run.events);
         }
-        // On `run` too: the direct path below serializes it.
-        applyToPayload(run, { update: true });
+        // Fail on a bad address now; the queued path validates again when built.
+        ensureAgent(run.address);
         // TODO: Untangle types
         const data = { ...run, id: runId };
         if (!this._filterForSampling([data]).length) {
@@ -2232,9 +2240,11 @@ export class Client {
         if (options?.workspaceId !== undefined) {
             headers["x-tenant-id"] = options.workspaceId;
         }
-        const body = serializePayloadForTracing(run.extra
-            ? mergeRuntimeEnvIntoRun(run, this.cachedLSEnvVarsForMetadata, this.omitTracedRuntimeInfo, this.tracingSampleRate)
-            : run, `Serializing payload to update run with id: ${runId}`);
+        const wireRun = { ...run };
+        applyToPayload(wireRun, { update: true });
+        const body = serializePayloadForTracing(wireRun.extra
+            ? mergeRuntimeEnvIntoRun(wireRun, this.cachedLSEnvVarsForMetadata, this.omitTracedRuntimeInfo, this.tracingSampleRate)
+            : wireRun, `Serializing payload to update run with id: ${runId}`);
         await this.caller.call(async () => {
             const res = await this._fetch(`${options?.apiUrl ?? this.apiUrl}/runs/${runId}`, {
                 method: "PATCH",
@@ -2271,14 +2281,15 @@ export class Client {
         return run;
     }
     /** @deprecated Use `client.runs.getURL()` instead. See https://docs.langchain.com/langsmith/smithdb-sdk-migration-runs#runs-get-url for the migration guide. Will be removed after Jan 31, 2027. */
-    async getRunUrl({ runId, run, projectOpts, }) {
+    async getRunUrl({ runId, run, projectOpts, address: rawAddress, }) {
         warnOnce("getRunUrl() is deprecated and will be removed after Jan 31, 2027. " +
             "Use client.runs.getURL() instead. " +
             "See https://docs.langchain.com/langsmith/smithdb-sdk-migration-runs#runs-get-url for the migration guide.", { type: "DeprecationWarning", code: "LANGSMITH_DEPRECATED_GET_RUN_URL" });
         if (run !== undefined) {
-            if (!run.session_id && run.address) {
-                throw new Error("Addressed runs have no URL until read back.");
-            }
+            const argumentAddress = ensureAddress(rawAddress);
+            rejectConflicting(projectOpts?.projectName ?? projectOpts?.projectId, argumentAddress);
+            const address = argumentAddress ??
+                ensureAgent(run.address);
             let sessionId;
             if (run.session_id) {
                 sessionId = run.session_id;
@@ -2289,6 +2300,9 @@ export class Client {
             else if (projectOpts?.projectId) {
                 sessionId = projectOpts?.projectId;
             }
+            else if (address) {
+                sessionId = await this._resolveAddress(address);
+            }
             else {
                 const project = await this.readProject({
                     projectName: getLangSmithEnvironmentVariable("PROJECT") || "default",
@@ -2312,6 +2326,12 @@ export class Client {
             throw new Error("Must provide either runId or run");
         }
     }
+    /** The ID of the project an address names, with one request. */
+    async _resolveAddress(address) {
+        const { session_id: sessionId } = await this.sessions.resolve(address.toApiAddress());
+        assertUuid(sessionId);
+        return sessionId;
+    }
     async _loadChildRuns(run) {
         const childRuns = await toArray(this._listRuns({
             isRoot: false,
@@ -3904,7 +3924,7 @@ export class Client {
         const { runId = null, key, score, value, correction, comment, sourceInfo, feedbackSourceType = "api", sourceRunId, feedbackId, feedbackConfig, projectId, traceId, comparativeExperimentId, sessionId, startTime, extendTraceRetention, address: rawAddress, } = typeof runIdOrParams === "object" && runIdOrParams !== null
             ? runIdOrParams
             : { runId: runIdOrParams, key: keyArg, ...optionsArg };
-        const address = checkAddress(rawAddress);
+        const address = ensureAgent(rawAddress);
         rejectConflicting(sessionId ?? projectId, address);
         if (!runId && !projectId) {
             throw new Error("One of runId or projectId must be provided");
@@ -3948,7 +3968,7 @@ export class Client {
         if (samplingId != null && !this._shouldSample(samplingId)) {
             return feedback;
         }
-        const body = JSON.stringify(address ? { ...feedback, ...toPayload(address) } : feedback);
+        const body = JSON.stringify(address ? { ...feedback, address: address._toLrn() } : feedback);
         const url = `${this.apiUrl}/feedback`;
         await this.caller.call(async () => {
             const res = await this._fetch(url, {