langsmith 0.10.4 → 0.10.6

package/dist/sandbox/verify.js

@@ -0,0 +1,296 @@
+import { getLangSmithEnvironmentVariable } from "../utils/env.js";
+import { LangSmithSandboxTokenVerificationError } from "./errors.js";
+/** Header carrying the signed identity of a LangSmith-login service URL request. */
+export const USER_TOKEN_HEADER = "X-Langsmith-User-Token";
+/** Header carrying the signature of a proxy callback request. */
+export const CALLBACK_SIGNATURE_HEADER = "X-LangSmith-Signature-JWT";
+const CALLBACK_SUBJECT = "langsmith-sandbox-callback";
+const JWKS_PATH = "/.well-known/jwks.json";
+const JWKS_TTL_MS = 300_000;
+// Bounds refetches when a token names a kid the cached set lacks.
+const JWKS_MIN_REFRESH_MS = 30_000;
+const LEEWAY_SECONDS = 30;
+function fail(message) {
+    throw new LangSmithSandboxTokenVerificationError(message);
+}
+function subtle() {
+    const s = globalThis.crypto?.subtle;
+    if (!s)
+        fail("Web Crypto is not available in this runtime");
+    return s;
+}
+function base64UrlDecode(value) {
+    const b64 = value.replace(/-/g, "+").replace(/_/g, "/");
+    const bin = atob(b64 + "=".repeat((4 - (b64.length % 4)) % 4));
+    const out = new Uint8Array(bin.length);
+    for (let i = 0; i < bin.length; i++)
+        out[i] = bin.charCodeAt(i);
+    return out;
+}
+function decodeJson(segment) {
+    const value = JSON.parse(new TextDecoder().decode(base64UrlDecode(segment)));
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw new Error("not a JSON object");
+    }
+    return value;
+}
+function isLoopback(hostname) {
+    return (hostname === "localhost" ||
+        hostname === "[::1]" ||
+        /^127(\.\d{1,3}){3}$/.test(hostname));
+}
+function checkJwksUrl(url, allowInsecure) {
+    const { protocol, hostname } = new URL(url);
+    if (protocol === "https:" || allowInsecure)
+        return;
+    if (protocol === "http:" && isLoopback(hostname))
+        return;
+    throw new Error(`JWKS URL must use https, got ${JSON.stringify(url)}; pass ` +
+        "allowInsecureJwks: true only if the network path to LangSmith is trusted");
+}
+function jwksUrlFrom(apiUrl) {
+    return new URL(JWKS_PATH, new URL(apiUrl).origin).toString();
+}
+function serviceHost(audience) {
+    return audience.includes("://") ? new URL(audience).host : audience;
+}
+function toBytes(body) {
+    if (typeof body === "string")
+        return new TextEncoder().encode(body);
+    if (body instanceof ArrayBuffer)
+        return new Uint8Array(body);
+    return new Uint8Array(body);
+}
+function hex(buf) {
+    return Array.from(new Uint8Array(buf), (b) => b.toString(16).padStart(2, "0")).join("");
+}
+function timingSafeEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    let diff = 0;
+    for (let i = 0; i < a.length; i++)
+        diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+    return diff === 0;
+}
+/**
+ * Verifies tokens LangSmith signs for code running in or behind a sandbox.
+ *
+ * Keys are fetched from LangSmith's JWKS endpoint and cached. Requires Web
+ * Crypto Ed25519 support (Node.js 20+, Deno, Bun, Cloudflare Workers).
+ *
+ * @example
+ * ```typescript
+ * const verifier = new SandboxTokenVerifier();
+ *
+ * // In an app served from a LangSmith-login service URL:
+ * const user = await verifier.verifyUserToken(
+ *   req.headers.get(USER_TOKEN_HEADER)!,
+ *   { audience: req.headers.get("host")! }
+ * );
+ *
+ * // In a proxy callback endpoint:
+ * const callback = await verifier.verifyCallback({
+ *   body: await req.text(),
+ *   signature: req.headers.get(CALLBACK_SIGNATURE_HEADER)!,
+ *   aud: "https://example.com/sandbox-callback",
+ * });
+ * ```
+ */
+export class SandboxTokenVerifier {
+    constructor(config = {}) {
+        Object.defineProperty(this, "jwksUrl", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "timeoutMs", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "keys", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Map()
+        });
+        Object.defineProperty(this, "fetchedAt", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: 0
+        });
+        Object.defineProperty(this, "inflight", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.jwksUrl =
+            config.jwksUrl ??
+                jwksUrlFrom(config.apiUrl ??
+                    getLangSmithEnvironmentVariable("ENDPOINT") ??
+                    "https://api.smith.langchain.com");
+        checkJwksUrl(this.jwksUrl, config.allowInsecureJwks ?? false);
+        this.timeoutMs = config.timeoutMs ?? 10_000;
+    }
+    /**
+     * Verify the `X-Langsmith-User-Token` header of a service URL request.
+     *
+     * LangSmith sets this header only for service URLs that use LangSmith login.
+     * Code that knows it is running in a sandbox can instead trust the unsigned
+     * `X-Langsmith-User-Id` and `X-Langsmith-User-Email` headers, which the
+     * sandbox runtime strips from inbound requests and sets itself; verify this
+     * token when that is not guaranteed.
+     */
+    async verifyUserToken(token, options) {
+        const claims = await this.verify(token, serviceHost(options.audience), options.issuer);
+        const sub = claims.sub;
+        if (typeof sub !== "string" || !sub || sub === CALLBACK_SUBJECT) {
+            fail("token is not a user token");
+        }
+        return {
+            subject: sub,
+            email: typeof claims.email === "string" && claims.email
+                ? claims.email
+                : undefined,
+            name: typeof claims.name === "string" && claims.name
+                ? claims.name
+                : undefined,
+            expiresAt: new Date(claims.exp * 1000),
+        };
+    }
+    /** Verify a proxy callback request and return its parsed payload. */
+    async verifyCallback(options) {
+        const claims = await this.verify(options.signature, options.aud, options.issuer);
+        if (claims.sub !== CALLBACK_SUBJECT) {
+            fail("signature is not a callback signature");
+        }
+        const expected = claims.body_sha256;
+        if (typeof expected !== "string")
+            fail("signature has no body hash");
+        const raw = toBytes(options.body);
+        const digest = hex(await subtle().digest("SHA-256", raw));
+        if (!timingSafeEqual(expected, digest))
+            fail("body does not match signature");
+        let payload;
+        try {
+            payload = JSON.parse(new TextDecoder().decode(raw));
+        }
+        catch (e) {
+            fail(`malformed callback body: ${e.message}`);
+        }
+        const id = payload?.identity;
+        if (typeof payload?.host !== "string" ||
+            typeof payload.port !== "number" ||
+            typeof id?.tenant_id !== "string" ||
+            typeof id.sandbox_id !== "string") {
+            fail("malformed callback body");
+        }
+        return payload;
+    }
+    async verify(token, audience, issuer) {
+        const parts = token ? token.split(".") : [];
+        if (parts.length !== 3)
+            fail("malformed token");
+        let header;
+        let claims;
+        let signature;
+        try {
+            header = decodeJson(parts[0]);
+            claims = decodeJson(parts[1]);
+            signature = base64UrlDecode(parts[2]);
+        }
+        catch (e) {
+            fail(`malformed token: ${e.message}`);
+        }
+        if (header.alg !== "EdDSA") {
+            fail(`unexpected signing algorithm: ${JSON.stringify(header.alg)}`);
+        }
+        if (typeof header.kid !== "string" || !header.kid)
+            fail("token has no kid");
+        const key = await this.key(header.kid);
+        const signed = new TextEncoder().encode(`${parts[0]}.${parts[1]}`);
+        if (!(await subtle().verify({ name: "Ed25519" }, key, signature, signed))) {
+            fail("invalid signature");
+        }
+        const now = Date.now() / 1000;
+        const { exp, iat, nbf, iss, aud } = claims;
+        if (typeof exp !== "number")
+            fail("token has no exp");
+        if (now > exp + LEEWAY_SECONDS)
+            fail("token is expired");
+        if (typeof iat !== "number")
+            fail("token has no iat");
+        if (iat > now + LEEWAY_SECONDS)
+            fail("token is not yet valid");
+        if (nbf !== undefined &&
+            (typeof nbf !== "number" || nbf > now + LEEWAY_SECONDS)) {
+            fail("token is not yet valid");
+        }
+        if (typeof iss !== "string")
+            fail("token has no iss");
+        if (issuer !== undefined && iss !== issuer.replace(/\/+$/, "")) {
+            fail("token has the wrong issuer");
+        }
+        const audiences = typeof aud === "string" ? [aud] : Array.isArray(aud) ? aud : [];
+        const matches = typeof audience === "function"
+            ? audiences.some((a) => typeof a === "string" && audience(a))
+            : audiences.includes(audience);
+        if (audience !== undefined && !matches) {
+            fail("token has the wrong audience");
+        }
+        return claims;
+    }
+    async key(kid) {
+        const age = Date.now() - this.fetchedAt;
+        const fresh = this.keys.has(kid) && age < JWKS_TTL_MS;
+        if (!fresh && (this.fetchedAt === 0 || age >= JWKS_MIN_REFRESH_MS)) {
+            this.inflight ??= this.refresh().finally(() => {
+                this.inflight = undefined;
+            });
+            await this.inflight;
+        }
+        const key = this.keys.get(kid);
+        if (!key)
+            fail(`unknown signing key: ${kid}`);
+        try {
+            return await key;
+        }
+        catch (e) {
+            fail(`signing key ${kid} is not a usable Ed25519 key: ${e.message}`);
+        }
+    }
+    async refresh() {
+        let body;
+        try {
+            const resp = await fetch(this.jwksUrl, {
+                signal: AbortSignal.timeout(this.timeoutMs),
+            });
+            if (!resp.ok)
+                throw new Error(`HTTP ${resp.status}`);
+            body = await resp.json();
+        }
+        catch (e) {
+            fail(`failed to fetch JWKS from ${this.jwksUrl}: ${e.message}`);
+        }
+        const entries = body?.keys;
+        if (!Array.isArray(entries)) {
+            fail("invalid JWKS: expected an object with a keys array");
+        }
+        const keys = new Map();
+        for (const jwk of entries) {
+            if (typeof jwk !== "object" || jwk === null)
+                continue;
+            if (jwk.kty !== "OKP" || jwk.crv !== "Ed25519" || !jwk.kid || !jwk.x)
+                continue;
+            const imported = subtle().importKey("jwk", { kty: "OKP", crv: "Ed25519", x: jwk.x }, { name: "Ed25519" }, false, ["verify"]);
+            imported.catch(() => undefined);
+            keys.set(jwk.kid, imported);
+        }
+        this.keys = keys;
+        this.fetchedAt = Date.now();
+    }
+}

package/dist/sandbox/ws_execute.cjs

@@ -136,10 +136,20 @@ class WSStreamControl {
             writable: true,
             value: false
         });
+        Object.defineProperty(this, "_closeStdinPending", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: false
+        });
     }
     /** Bind to the active WebSocket. Called inside the generator. */
     _bind(ws) {
         this._ws = ws;
+        if (this._closeStdinPending) {
+            this._closeStdinPending = false;
+            this.sendCloseStdin();
+        }
     }
     /** Mark as closed. Called when the generator exits. */
     _unbind() {
@@ -163,6 +173,22 @@ class WSStreamControl {
             this._ws.send(JSON.stringify({ type: "input", data }));
         }
     }
+    /**
+     * Half-close the command's stdin so it reads EOF.
+     *
+     * A reconnected stream binds its socket only once iteration starts, so a
+     * close arriving before that is queued and sent on bind — dropping it would
+     * leave the command waiting for an EOF that never comes.
+     */
+    sendCloseStdin() {
+        if (this._closed)
+            return;
+        if (this._ws && this._ws.readyState === 1) {
+            this._ws.send(JSON.stringify({ type: "close_stdin" }));
+            return;
+        }
+        this._closeStdinPending = true;
+    }
 }
 exports.WSStreamControl = WSStreamControl;
 // =============================================================================
@@ -330,7 +356,7 @@ async function* readWsMessages(ws) {
  * data arrives in addition to yielding the messages.
  */
 async function runWsStream(dataplaneUrl, apiKey, command, options = {}) {
-    const { timeout = 60, env, cwd, shell = "/bin/bash", onStdout, onStderr, commandId, idleTimeout = 300, killOnDisconnect = false, ttlSeconds = 600, pty, headers: extraHeaders, openTimeout = exports.WS_OPEN_TIMEOUT, } = options;
+    const { timeout = 60, env, cwd, shell = "/bin/bash", onStdout, onStderr, commandId, idleTimeout = 300, killOnDisconnect = false, ttlSeconds = 600, pty, runConfig, closeStdin, headers: extraHeaders, openTimeout = exports.WS_OPEN_TIMEOUT, } = options;
     const wsUrl = buildWsUrl(dataplaneUrl);
     const headers = buildAuthHeaders(apiKey, extraHeaders);
     const control = new WSStreamControl();
@@ -353,6 +379,10 @@ async function runWsStream(dataplaneUrl, apiKey, command, options = {}) {
                 payload.env = env;
             if (cwd)
                 payload.cwd = cwd;
+            if (runConfig)
+                payload.run_config = runConfig;
+            if (closeStdin)
+                payload.close_stdin = true;
             if (commandId)
                 payload.command_id = commandId;
             if (pty)

package/dist/sandbox/ws_execute.d.ts

@@ -35,6 +35,7 @@ export declare class WSStreamControl {
     private _ws;
     private _closed;
     private _killed;
+    private _closeStdinPending;
     /** Bind to the active WebSocket. Called inside the generator. */
     _bind(ws: WsWebSocket): void;
     /** Mark as closed. Called when the generator exits. */
@@ -45,6 +46,14 @@ export declare class WSStreamControl {
     sendKill(): void;
     /** Send stdin data to the running command. */
     sendInput(data: string): void;
+    /**
+     * Half-close the command's stdin so it reads EOF.
+     *
+     * A reconnected stream binds its socket only once iteration starts, so a
+     * close arriving before that is queued and sent on bind — dropping it would
+     * leave the command waiting for an EOF that never comes.
+     */
+    sendCloseStdin(): void;
 }
 /**
  * Raise the appropriate exception from a server error message.

package/dist/sandbox/ws_execute.js

@@ -124,10 +124,20 @@ export class WSStreamControl {
             writable: true,
             value: false
         });
+        Object.defineProperty(this, "_closeStdinPending", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: false
+        });
     }
     /** Bind to the active WebSocket. Called inside the generator. */
     _bind(ws) {
         this._ws = ws;
+        if (this._closeStdinPending) {
+            this._closeStdinPending = false;
+            this.sendCloseStdin();
+        }
     }
     /** Mark as closed. Called when the generator exits. */
     _unbind() {
@@ -151,6 +161,22 @@ export class WSStreamControl {
             this._ws.send(JSON.stringify({ type: "input", data }));
         }
     }
+    /**
+     * Half-close the command's stdin so it reads EOF.
+     *
+     * A reconnected stream binds its socket only once iteration starts, so a
+     * close arriving before that is queued and sent on bind — dropping it would
+     * leave the command waiting for an EOF that never comes.
+     */
+    sendCloseStdin() {
+        if (this._closed)
+            return;
+        if (this._ws && this._ws.readyState === 1) {
+            this._ws.send(JSON.stringify({ type: "close_stdin" }));
+            return;
+        }
+        this._closeStdinPending = true;
+    }
 }
 // =============================================================================
 // Error Handling
@@ -317,7 +343,7 @@ async function* readWsMessages(ws) {
  * data arrives in addition to yielding the messages.
  */
 export async function runWsStream(dataplaneUrl, apiKey, command, options = {}) {
-    const { timeout = 60, env, cwd, shell = "/bin/bash", onStdout, onStderr, commandId, idleTimeout = 300, killOnDisconnect = false, ttlSeconds = 600, pty, headers: extraHeaders, openTimeout = WS_OPEN_TIMEOUT, } = options;
+    const { timeout = 60, env, cwd, shell = "/bin/bash", onStdout, onStderr, commandId, idleTimeout = 300, killOnDisconnect = false, ttlSeconds = 600, pty, runConfig, closeStdin, headers: extraHeaders, openTimeout = WS_OPEN_TIMEOUT, } = options;
     const wsUrl = buildWsUrl(dataplaneUrl);
     const headers = buildAuthHeaders(apiKey, extraHeaders);
     const control = new WSStreamControl();
@@ -340,6 +366,10 @@ export async function runWsStream(dataplaneUrl, apiKey, command, options = {}) {
                 payload.env = env;
             if (cwd)
                 payload.cwd = cwd;
+            if (runConfig)
+                payload.run_config = runConfig;
+            if (closeStdin)
+                payload.close_stdin = true;
             if (commandId)
                 payload.command_id = commandId;
             if (pty)

package/dist/schemas.d.ts

@@ -1,3 +1,4 @@
+import type { Address } from "./address.js";
 export interface TracerSession {
     tenant_id: string;
     id: string;
@@ -149,6 +150,8 @@ export interface RunCreate extends BaseRun {
     revision_id?: string;
     child_runs?: this[];
     session_name?: string;
+    /** (beta) Sent as `agent_id` / `agent_environment`. */
+    address?: Address;
 }
 export interface RunUpdate {
     id?: string;
@@ -167,6 +170,8 @@ export interface RunUpdate {
     events?: KVMap[];
     session_id?: string;
     session_name?: string;
+    /** (beta) Sent as `agent_id` / `agent_environment`. */
+    address?: Address;
     /** Unique ID assigned to every run within this nested trace. **/
     trace_id?: string;
     /**

package/dist/traceable.cjs

@@ -9,6 +9,7 @@ const traceable_js_1 = require("./singletons/traceable.cjs");
 const constants_js_1 = require("./singletons/constants.cjs");
 const asserts_js_1 = require("./utils/asserts.cjs");
 const index_js_1 = require("./index.cjs");
+const agent_addressing_js_1 = require("./utils/agent_addressing.cjs");
 const otel_js_1 = require("./singletons/otel.cjs");
 const utils_js_1 = require("./experimental/otel/utils.cjs");
 const constants_js_2 = require("./experimental/otel/constants.cjs");
@@ -472,13 +473,15 @@ const convertSerializableArg = (arg, options) => {
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 function traceable(wrappedFunc, config) {
     const { aggregator, argsConfigPath, __finalTracedIteratorKey, processInputs, processOutputs, extractAttachments, on_start, ...runTreeConfig } = config ?? {};
+    runTreeConfig.address = (0, agent_addressing_js_1.checkAddress)(runTreeConfig.address);
+    (0, agent_addressing_js_1.rejectConflicting)(runTreeConfig.project_name, runTreeConfig.address);
     const processInputsFn = processInputs ?? ((x) => x);
     const processOutputsFn = processOutputs ?? ((x) => x);
     const extractAttachmentsFn = extractAttachments ?? ((...x) => [undefined, runInputsToMap(x)]);
     const traceableFunc = (...args) => {
         let ensuredConfig;
+        let runtimeConfig;
         try {
-            let runtimeConfig;
             if (argsConfigPath) {
                 const [index, path] = argsConfigPath;
                 if (index === args.length - 1 && !path) {
@@ -520,7 +523,10 @@ function traceable(wrappedFunc, config) {
                 name: wrappedFunc.name || "<lambda>",
                 ...runTreeConfig,
             };
+            runtimeConfig = undefined;
         }
+        // Runtime config outranks decorator config, whichever mode each names.
+        [ensuredConfig.project_name, ensuredConfig.address] = (0, agent_addressing_js_1.firstNamed)([runtimeConfig?.project_name, runtimeConfig?.address], [runTreeConfig.project_name, runTreeConfig.address]);
         let runEndedPromiseResolver;
         const runEndedPromise = new Promise((resolve) => {
             runEndedPromiseResolver = resolve;

package/dist/traceable.js

@@ -5,6 +5,7 @@ import { ROOT, AsyncLocalStorageProviderSingleton, getCurrentRunTree, } from "./
 import { _LC_CHILD_RUN_END_PROMISES_KEY, _LC_CONTEXT_VARIABLES_KEY, _PROCESSING_FAILED_KEY, _processingFailed, } from "./singletons/constants.js";
 import { isKVMap, isReadableStream, isAsyncIterable, isIteratorLike, isThenable, isGenerator, isPromiseMethod, } from "./utils/asserts.js";
 import { __version__ } from "./index.js";
+import { checkAddress, firstNamed, rejectConflicting, } from "./utils/agent_addressing.js";
 import { getOTELTrace, getOTELContext } from "./singletons/otel.js";
 import { getUuidFromOtelSpanId } from "./experimental/otel/utils.js";
 import { LANGSMITH_REFERENCE_EXAMPLE_ID, LANGSMITH_SESSION_NAME, LANGSMITH_TRACEABLE, } from "./experimental/otel/constants.js";
@@ -468,13 +469,15 @@ const convertSerializableArg = (arg, options) => {
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export function traceable(wrappedFunc, config) {
     const { aggregator, argsConfigPath, __finalTracedIteratorKey, processInputs, processOutputs, extractAttachments, on_start, ...runTreeConfig } = config ?? {};
+    runTreeConfig.address = checkAddress(runTreeConfig.address);
+    rejectConflicting(runTreeConfig.project_name, runTreeConfig.address);
     const processInputsFn = processInputs ?? ((x) => x);
     const processOutputsFn = processOutputs ?? ((x) => x);
     const extractAttachmentsFn = extractAttachments ?? ((...x) => [undefined, runInputsToMap(x)]);
     const traceableFunc = (...args) => {
         let ensuredConfig;
+        let runtimeConfig;
         try {
-            let runtimeConfig;
             if (argsConfigPath) {
                 const [index, path] = argsConfigPath;
                 if (index === args.length - 1 && !path) {
@@ -516,7 +519,10 @@ export function traceable(wrappedFunc, config) {
                 name: wrappedFunc.name || "<lambda>",
                 ...runTreeConfig,
             };
+            runtimeConfig = undefined;
         }
+        // Runtime config outranks decorator config, whichever mode each names.
+        [ensuredConfig.project_name, ensuredConfig.address] = firstNamed([runtimeConfig?.project_name, runtimeConfig?.address], [runTreeConfig.project_name, runTreeConfig.address]);
         let runEndedPromiseResolver;
         const runEndedPromise = new Promise((resolve) => {
             runEndedPromiseResolver = resolve;

package/dist/utils/agent_addressing.cjs

@@ -0,0 +1,92 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkAddress = checkAddress;
+exports.rejectConflicting = rejectConflicting;
+exports.firstNamed = firstNamed;
+exports.resolveFromEnv = resolveFromEnv;
+exports.logUntraced = logUntraced;
+exports.warnOnEnv = warnOnEnv;
+exports.applyToPayload = applyToPayload;
+const address_js_1 = require("../address.cjs");
+const env_js_1 = require("./env.cjs");
+const warn_js_1 = require("./warn.cjs");
+/** Validate an address at an entry point; the SDK carries the frozen copy. */
+function checkAddress(address) {
+    return address == null ? undefined : (0, address_js_1.normalizeAddress)(address);
+}
+function rejectConflicting(project, address) {
+    if (project && address) {
+        throw new Error(`A run is sent to a project (${JSON.stringify(project)}) or to an ` +
+            `address (${JSON.stringify(address)}), not both.`);
+    }
+}
+/** The highest level naming a project or an address, whichever it names. */
+function firstNamed(...tiers) {
+    for (const [project, address] of tiers) {
+        rejectConflicting(project, address);
+        if (project || address) {
+            return [project || undefined, address];
+        }
+    }
+    return [undefined, undefined];
+}
+function getEnvProject() {
+    return ((0, env_js_1.getLangSmithEnvironmentVariable)("PROJECT") ||
+        (0, env_js_1.getEnvironmentVariable)("LANGCHAIN_SESSION") ||
+        undefined);
+}
+/**
+ * The env's destination: its address, else its project, else "default".
+ * @throws {EnvAddressError} For half an address, or an address and a project.
+ */
+function resolveFromEnv() {
+    const project = getEnvProject();
+    const address = (0, address_js_1.addressFromEnv)();
+    if (project && address) {
+        throw new address_js_1.EnvAddressError("LANGSMITH_AGENT_* and a project are both set in the environment.");
+    }
+    return address ? [undefined, address] : [project ?? "default", undefined];
+}
+function logUntraced(error) {
+    (0, warn_js_1.warnOnce)(`LangSmith is not tracing this call: ${error.message}`);
+}
+/** Warn once, at client construction, if the env can't address runs. */
+function warnOnEnv() {
+    if (!(0, address_js_1.envNames)().some((name) => (0, env_js_1.getEnvironmentVariable)(name))) {
+        return;
+    }
+    try {
+        resolveFromEnv();
+    }
+    catch (e) {
+        (0, warn_js_1.warnOnce)(`${e.message} Runs that name no destination in code are ` +
+            "not traced.");
+    }
+}
+/**
+ * Render `address` into its wire fields, in place. Without one, a create
+ * naming no project takes the env address. Already-rendered payloads (runs
+ * re-prepared when batched) are left alone.
+ *
+ * @throws {EnvAddressError} If the env names half an address.
+ */
+function applyToPayload(run, { update = false } = {}) {
+    const payload = run;
+    let address = checkAddress(payload.address);
+    delete payload.address;
+    const namedProject = payload.session_id != null || payload.session_name != null;
+    const rendered = (0, address_js_1.wireKeys)().some((key) => payload[key] != null);
+    if (!address && !update && !namedProject && !rendered) {
+        address = (0, address_js_1.addressFromEnv)();
+    }
+    if (!address) {
+        return;
+    }
+    (0, warn_js_1.warnOnce)("Sending runs to an `address` is in beta and enabled per workspace; a " +
+        "workspace without it rejects the runs.");
+    Object.assign(payload, (0, address_js_1.toWire)(address));
+    if (!namedProject) {
+        delete payload.session_name;
+        delete payload.session_id;
+    }
+}

package/dist/utils/agent_addressing.d.ts

@@ -0,0 +1,30 @@
+import { type Address, EnvAddressError } from "../address.js";
+/** One precedence level: the `[project, address]` it names. */
+export type Tier = [string | undefined, Address | undefined];
+/** Validate an address at an entry point; the SDK carries the frozen copy. */
+export declare function checkAddress(address: unknown): Readonly<Address> | undefined;
+export declare function rejectConflicting(project: unknown, address: unknown): void;
+/** The highest level naming a project or an address, whichever it names. */
+export declare function firstNamed(...tiers: Tier[]): Tier;
+/**
+ * The env's destination: its address, else its project, else "default".
+ * @throws {EnvAddressError} For half an address, or an address and a project.
+ */
+export declare function resolveFromEnv(): Tier;
+export declare function logUntraced(error: EnvAddressError): void;
+/** Warn once, at client construction, if the env can't address runs. */
+export declare function warnOnEnv(): void;
+/**
+ * Render `address` into its wire fields, in place. Without one, a create
+ * naming no project takes the env address. Already-rendered payloads (runs
+ * re-prepared when batched) are left alone.
+ *
+ * @throws {EnvAddressError} If the env names half an address.
+ */
+export declare function applyToPayload(run: {
+    address?: Address;
+    session_id?: string;
+    session_name?: string;
+}, { update }?: {
+    update?: boolean;
+}): void;