langsmith 0.10.7 → 0.10.9

package/dist/sandbox/client.js

@@ -11,7 +11,8 @@ import { Sandbox } from "./sandbox.js";
 import { LangSmithResourceCreationError, LangSmithResourceNameConflictError, LangSmithResourceNotFoundError, LangSmithResourceTimeoutError, LangSmithSandboxAPIError, LangSmithValidationError, } from "./errors.js";
 import { handleClientHttpError, handleSandboxCreationError, throwIfNotReady, validateTtl, } from "./helpers.js";
 import { validateMountConfigProxyConfig } from "./mounts.js";
-import { v4 as uuidv4 } from "../utils/uuid/src/index.js";
+import { v4 as uuidv4, validate as isUuid } from "../utils/uuid/src/index.js";
+import { addSandboxMetadata } from "./tracing.js";
 /**
  * Sleep that can be interrupted by an AbortSignal.
  * Resolves after `ms` milliseconds or rejects immediately if the signal fires.
@@ -302,6 +303,12 @@ export 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 ?? {}) };
@@ -395,6 +402,25 @@ export class SandboxClient {
     getDefaultHeaders() {
         return { ...this._defaultHeaders };
     }
+    _traceSandbox(name) {
+        const id = this._sandboxIds.get(name) ?? (isUuid(name) ? name : undefined);
+        addSandboxMetadata(id);
+        return id;
+    }
+    _sandboxFromData(data) {
+        if (data.id)
+            this._sandboxIds.set(data.name, data.id);
+        addSandboxMetadata(data.id);
+        return new 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.
@@ -403,6 +429,7 @@ export class SandboxClient {
      * @internal
      */
     _boxUrl(name, ...segments) {
+        this._traceSandbox(name);
         const suffix = segments.length ? `/${segments.join("/")}` : "";
         return `${this._baseUrl}/boxes/${encodeURIComponent(name)}${suffix}`;
     }
@@ -451,7 +478,7 @@ export class SandboxClient {
         return new ServiceUrl(data, () => this.serviceUrl(name, {
             port,
             expiresInSeconds,
-        }));
+        }), this._traceSandbox(name));
     }
     async _postJson(url, body, options) {
         const response = await this._fetch(url, {
@@ -531,7 +558,7 @@ export class SandboxClient {
             await handleSandboxCreationError(response);
         }
         const data = (await response.json());
-        return new Sandbox(data, this);
+        return this._sandboxFromData(data);
     }
     /**
      * Get a Sandbox by name.
@@ -552,7 +579,7 @@ export class SandboxClient {
             await handleClientHttpError(response);
         }
         const data = (await response.json());
-        return new Sandbox(data, this);
+        return this._sandboxFromData(data);
     }
     /**
      * List all Sandboxes.
@@ -622,7 +649,8 @@ export class SandboxClient {
             await handleClientHttpError(response);
         }
         const data = (await response.json());
-        return new Sandbox(data, this);
+        this._forgetSandbox(name);
+        return this._sandboxFromData(data);
     }
     /**
      * Delete a Sandbox.
@@ -639,6 +667,7 @@ export class SandboxClient {
             }
             await handleClientHttpError(response);
         }
+        this._forgetSandbox(name);
     }
     /**
      * Get the provisioning status of a sandbox.

package/dist/sandbox/command_handle.cjs

@@ -7,6 +7,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CommandHandle = void 0;
+const tracing_js_1 = require("./tracing.cjs");
 const errors_js_1 = require("./errors.cjs");
 /**
  * Whether a 'started' frame proves *this* command was reattached to.
@@ -205,6 +206,7 @@ class CommandHandle {
      * The final execution result. Drains the stream if not already exhausted.
      */
     get result() {
+        (0, tracing_js_1.addSandboxMetadata)(this._sandbox.id);
         return this._getResult();
     }
     async _getResult() {
@@ -268,6 +270,7 @@ class CommandHandle {
      * - After kill():                  no reconnect, error propagates
      */
     async *[Symbol.asyncIterator]() {
+        (0, tracing_js_1.addSandboxMetadata)(this._sandbox.id);
         this._reconnectAttempts = 0;
         while (true) {
             try {
@@ -283,6 +286,8 @@ class CommandHandle {
                             chunk.offset + new TextEncoder().encode(chunk.data).length;
                         this._onStderr?.(chunk.data);
                     }
+                    // Each resumption runs in the consumer's current context.
+                    (0, tracing_js_1.addSandboxMetadata)(this._sandbox.id);
                     yield chunk;
                 }
                 return; // Stream ended normally (exit message received)
@@ -325,6 +330,7 @@ class CommandHandle {
      * subsequently yield an exit message with a non-zero exit code.
      */
     kill() {
+        (0, tracing_js_1.addSandboxMetadata)(this._sandbox.id);
         if (this._control) {
             this._control.sendKill();
         }
@@ -333,6 +339,7 @@ class CommandHandle {
      * Write data to the command's stdin.
      */
     sendInput(data) {
+        (0, tracing_js_1.addSandboxMetadata)(this._sandbox.id);
         if (this._stdinClosed) {
             throw new errors_js_1.LangSmithSandboxOperationError("stdin is closed for this command. Non-PTY commands close stdin by " +
                 "default so a command that reads it sees EOF instead of hanging; " +
@@ -350,6 +357,7 @@ class CommandHandle {
      * EOT byte (0x04) with {@link sendInput} instead.
      */
     closeInput() {
+        (0, tracing_js_1.addSandboxMetadata)(this._sandbox.id);
         if (this._pty || this._stdinClosed)
             return;
         this._stdinClosed = true;

package/dist/sandbox/command_handle.js

@@ -4,6 +4,7 @@
  *
  * Port of Python's AsyncCommandHandle to TypeScript.
  */
+import { addSandboxMetadata } from "./tracing.js";
 import { LangSmithSandboxConnectionError, LangSmithSandboxServerReloadError, LangSmithSandboxOperationError, LangSmithStreamEndedBeforeStartedError, } from "./errors.js";
 /**
  * Whether a 'started' frame proves *this* command was reattached to.
@@ -202,6 +203,7 @@ export class CommandHandle {
      * The final execution result. Drains the stream if not already exhausted.
      */
     get result() {
+        addSandboxMetadata(this._sandbox.id);
         return this._getResult();
     }
     async _getResult() {
@@ -265,6 +267,7 @@ export class CommandHandle {
      * - After kill():                  no reconnect, error propagates
      */
     async *[Symbol.asyncIterator]() {
+        addSandboxMetadata(this._sandbox.id);
         this._reconnectAttempts = 0;
         while (true) {
             try {
@@ -280,6 +283,8 @@ export class CommandHandle {
                             chunk.offset + new TextEncoder().encode(chunk.data).length;
                         this._onStderr?.(chunk.data);
                     }
+                    // Each resumption runs in the consumer's current context.
+                    addSandboxMetadata(this._sandbox.id);
                     yield chunk;
                 }
                 return; // Stream ended normally (exit message received)
@@ -322,6 +327,7 @@ export class CommandHandle {
      * subsequently yield an exit message with a non-zero exit code.
      */
     kill() {
+        addSandboxMetadata(this._sandbox.id);
         if (this._control) {
             this._control.sendKill();
         }
@@ -330,6 +336,7 @@ export class CommandHandle {
      * Write data to the command's stdin.
      */
     sendInput(data) {
+        addSandboxMetadata(this._sandbox.id);
         if (this._stdinClosed) {
             throw new LangSmithSandboxOperationError("stdin is closed for this command. Non-PTY commands close stdin by " +
                 "default so a command that reads it sees EOF instead of hanging; " +
@@ -347,6 +354,7 @@ export class CommandHandle {
      * EOT byte (0x04) with {@link sendInput} instead.
      */
     closeInput() {
+        addSandboxMetadata(this._sandbox.id);
         if (this._pty || this._stdinClosed)
             return;
         this._stdinClosed = true;

package/dist/sandbox/sandbox.cjs

@@ -8,6 +8,7 @@ const uuid_js_1 = require("../uuid.cjs");
 const errors_js_1 = require("./errors.cjs");
 const helpers_js_1 = require("./helpers.cjs");
 const command_handle_js_1 = require("./command_handle.cjs");
+const tracing_js_1 = require("./tracing.cjs");
 const ws_execute_js_1 = require("./ws_execute.cjs");
 /**
  * Represents an active sandbox for running commands and file operations.
@@ -195,6 +196,7 @@ class Sandbox {
      * @throws LangSmithDataplaneNotConfiguredError if dataplane_url is not configured.
      */
     requireDataplaneUrl() {
+        (0, tracing_js_1.addSandboxMetadata)(this.id);
         if (!this.dataplane_url) {
             throw new errors_js_1.LangSmithDataplaneNotConfiguredError(`Sandbox '${this.name}' does not have a dataplane_url configured. ` +
                 "Runtime operations require a dataplane URL.");
@@ -593,6 +595,7 @@ class Sandbox {
      * ```
      */
     async generateDownloadURL(path, options = {}) {
+        (0, tracing_js_1.addSandboxMetadata)(this.id);
         return this._client.generateDownloadURL(this.name, path, options);
     }
     /**
@@ -609,6 +612,7 @@ class Sandbox {
      * ```
      */
     async delete() {
+        (0, tracing_js_1.addSandboxMetadata)(this.id);
         await this._client.deleteSandbox(this.name);
     }
     /**
@@ -619,6 +623,7 @@ class Sandbox {
      * @param timeout - Timeout in seconds when waiting for ready. Default: 120.
      */
     async start(options = {}) {
+        (0, tracing_js_1.addSandboxMetadata)(this.id);
         const refreshed = await this._client.startSandbox(this.name, options);
         this.status = refreshed.status;
         this.dataplane_url = refreshed.dataplane_url;
@@ -627,6 +632,7 @@ class Sandbox {
      * Stop a running sandbox (preserves sandbox files for later restart).
      */
     async stop() {
+        (0, tracing_js_1.addSandboxMetadata)(this.id);
         await this._client.stopSandbox(this.name);
         // dataplane_url stays set: it is stable across stop/start and a request on
         // it resumes the sandbox.
@@ -640,6 +646,7 @@ class Sandbox {
      * @returns Snapshot in "ready" status.
      */
     async captureSnapshot(name, options = {}) {
+        (0, tracing_js_1.addSandboxMetadata)(this.id);
         return this._client.captureSnapshot(this.name, name, options);
     }
 }

package/dist/sandbox/sandbox.js

@@ -5,6 +5,7 @@ import { uuid7 } from "../uuid.js";
 import { LangSmithDataplaneNotConfiguredError, LangSmithSandboxRetryableConnectionError, LangSmithStreamEndedBeforeStartedError, } from "./errors.js";
 import { assertRunConfigNotCombined, buildRangeHeader, fileChunkFromResponse, fileStatFromResponse, handleFileHttpError, handleSandboxHttpError, resolveCloseInput, } from "./helpers.js";
 import { CommandHandle } from "./command_handle.js";
+import { addSandboxMetadata } from "./tracing.js";
 import { connectDeadline, isWsAvailable, openTimeoutFor, reconnectWsStream, remainingBudget, runWsStream, } from "./ws_execute.js";
 /**
  * Represents an active sandbox for running commands and file operations.
@@ -192,6 +193,7 @@ export class Sandbox {
      * @throws LangSmithDataplaneNotConfiguredError if dataplane_url is not configured.
      */
     requireDataplaneUrl() {
+        addSandboxMetadata(this.id);
         if (!this.dataplane_url) {
             throw new LangSmithDataplaneNotConfiguredError(`Sandbox '${this.name}' does not have a dataplane_url configured. ` +
                 "Runtime operations require a dataplane URL.");
@@ -590,6 +592,7 @@ export class Sandbox {
      * ```
      */
     async generateDownloadURL(path, options = {}) {
+        addSandboxMetadata(this.id);
         return this._client.generateDownloadURL(this.name, path, options);
     }
     /**
@@ -606,6 +609,7 @@ export class Sandbox {
      * ```
      */
     async delete() {
+        addSandboxMetadata(this.id);
         await this._client.deleteSandbox(this.name);
     }
     /**
@@ -616,6 +620,7 @@ export class Sandbox {
      * @param timeout - Timeout in seconds when waiting for ready. Default: 120.
      */
     async start(options = {}) {
+        addSandboxMetadata(this.id);
         const refreshed = await this._client.startSandbox(this.name, options);
         this.status = refreshed.status;
         this.dataplane_url = refreshed.dataplane_url;
@@ -624,6 +629,7 @@ export class Sandbox {
      * Stop a running sandbox (preserves sandbox files for later restart).
      */
     async stop() {
+        addSandboxMetadata(this.id);
         await this._client.stopSandbox(this.name);
         // dataplane_url stays set: it is stable across stop/start and a request on
         // it resumes the sandbox.
@@ -637,6 +643,7 @@ export class Sandbox {
      * @returns Snapshot in "ready" status.
      */
     async captureSnapshot(name, options = {}) {
+        addSandboxMetadata(this.id);
         return this._client.captureSnapshot(this.name, name, options);
     }
 }

package/dist/sandbox/service_url.cjs

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ServiceLoginUrl = exports.ServiceUrl = exports.SERVICE_TOKEN_HEADER = void 0;
+const tracing_js_1 = require("./tracing.cjs");
 /** Header the sandbox router reads the minted service token from. */
 exports.SERVICE_TOKEN_HEADER = "X-Langsmith-Sandbox-Service-Token";
 /** Refresh this many seconds before the token actually expires. */
@@ -11,7 +12,13 @@ const REFRESH_MARGIN_SECONDS = 60;
  * Accessors are async because a refresh is a network call.
  */
 class ServiceUrl {
-    constructor(data, refresher) {
+    constructor(data, refresher, _sandboxId) {
+        Object.defineProperty(this, "_sandboxId", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: _sandboxId
+        });
         Object.defineProperty(this, "_browserUrl", {
             enumerable: true,
             configurable: true,
@@ -87,6 +94,7 @@ class ServiceUrl {
     }
     /** Fetch a path on the service with the token header injected. */
     async fetch(path = "/", init = {}) {
+        (0, tracing_js_1.addSandboxMetadata)(this._sandboxId);
         const base = (await this.serviceUrl()).replace(/\/+$/, "");
         const url = `${base}/${path.replace(/^\/+/, "")}`;
         const headers = new Headers(init.headers);

package/dist/sandbox/service_url.d.ts

@@ -15,12 +15,13 @@ export interface ServiceUrlData {
  * Accessors are async because a refresh is a network call.
  */
 export declare class ServiceUrl {
+    private readonly _sandboxId?;
     private _browserUrl;
     private _serviceUrl;
     private _token;
     private _expiresAt;
     private readonly _refresher?;
-    constructor(data: ServiceUrlData, refresher?: () => Promise<ServiceUrl>);
+    constructor(data: ServiceUrlData, refresher?: () => Promise<ServiceUrl>, _sandboxId?: string | undefined);
     private _shouldRefresh;
     private _maybeRefresh;
     /** The signed token, refreshed if near expiry. */

package/dist/sandbox/service_url.js

@@ -1,3 +1,4 @@
+import { addSandboxMetadata } from "./tracing.js";
 /** Header the sandbox router reads the minted service token from. */
 export const SERVICE_TOKEN_HEADER = "X-Langsmith-Sandbox-Service-Token";
 /** Refresh this many seconds before the token actually expires. */
@@ -8,7 +9,13 @@ const REFRESH_MARGIN_SECONDS = 60;
  * Accessors are async because a refresh is a network call.
  */
 export class ServiceUrl {
-    constructor(data, refresher) {
+    constructor(data, refresher, _sandboxId) {
+        Object.defineProperty(this, "_sandboxId", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: _sandboxId
+        });
         Object.defineProperty(this, "_browserUrl", {
             enumerable: true,
             configurable: true,
@@ -84,6 +91,7 @@ export class ServiceUrl {
     }
     /** Fetch a path on the service with the token header injected. */
     async fetch(path = "/", init = {}) {
+        addSandboxMetadata(this._sandboxId);
         const base = (await this.serviceUrl()).replace(/\/+$/, "");
         const url = `${base}/${path.replace(/^\/+/, "")}`;
         const headers = new Headers(init.headers);

package/dist/sandbox/tracing.cjs

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.addSandboxMetadata = addSandboxMetadata;
+const run_trees_js_1 = require("../run_trees.cjs");
+const traceable_js_1 = require("../singletons/traceable.cjs");
+function addSandboxMetadata(sandboxId) {
+    if (!sandboxId)
+        return;
+    const run = (0, traceable_js_1.getCurrentRunTree)(true);
+    if ((0, run_trees_js_1.isRunTree)(run)) {
+        run.metadata = { sandbox_id: sandboxId };
+    }
+}

package/dist/sandbox/tracing.d.ts

@@ -0,0 +1 @@
+export declare function addSandboxMetadata(sandboxId?: string): void;

package/dist/sandbox/tracing.js

@@ -0,0 +1,10 @@
+import { isRunTree } from "../run_trees.js";
+import { getCurrentRunTree } from "../singletons/traceable.js";
+export function addSandboxMetadata(sandboxId) {
+    if (!sandboxId)
+        return;
+    const run = getCurrentRunTree(true);
+    if (isRunTree(run)) {
+        run.metadata = { sandbox_id: sandboxId };
+    }
+}

package/dist/schemas.d.ts

@@ -1,4 +1,4 @@
-import type { Address } from "./address.js";
+import type { AgentAddress } from "./address.js";
 export interface TracerSession {
     tenant_id: string;
     id: string;
@@ -150,7 +150,7 @@ export interface RunCreate extends BaseRun {
     revision_id?: string;
     child_runs?: this[];
     session_name?: string;
-    address?: Address;
+    address?: AgentAddress;
 }
 export interface RunUpdate {
     id?: string;
@@ -169,7 +169,7 @@ export interface RunUpdate {
     events?: KVMap[];
     session_id?: string;
     session_name?: string;
-    address?: Address;
+    address?: AgentAddress;
     /** Unique ID assigned to every run within this nested trace. **/
     trace_id?: string;
     /**

package/dist/traceable.cjs

@@ -9,7 +9,8 @@ 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 address_js_1 = require("./address.cjs");
+const addressing_js_1 = require("./utils/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");
@@ -473,8 +474,8 @@ 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);
+    runTreeConfig.address = (0, address_js_1.ensureAgent)(runTreeConfig.address);
+    (0, 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)]);
@@ -526,7 +527,7 @@ function traceable(wrappedFunc, config) {
             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]);
+        [ensuredConfig.project_name, ensuredConfig.address] = (0, addressing_js_1.firstNamed)([runtimeConfig?.project_name, (0, address_js_1.ensureAgent)(runtimeConfig?.address)], [runTreeConfig.project_name, (0, address_js_1.ensureAgent)(runTreeConfig.address)]);
         let runEndedPromiseResolver;
         const runEndedPromise = new Promise((resolve) => {
             runEndedPromiseResolver = resolve;

package/dist/traceable.js

@@ -5,7 +5,8 @@ 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 { ensureAgent } from "./address.js";
+import { firstNamed, rejectConflicting } from "./utils/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";
@@ -469,7 +470,7 @@ 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);
+    runTreeConfig.address = ensureAgent(runTreeConfig.address);
     rejectConflicting(runTreeConfig.project_name, runTreeConfig.address);
     const processInputsFn = processInputs ?? ((x) => x);
     const processOutputsFn = processOutputs ?? ((x) => x);
@@ -522,7 +523,7 @@ export function traceable(wrappedFunc, config) {
             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]);
+        [ensuredConfig.project_name, ensuredConfig.address] = firstNamed([runtimeConfig?.project_name, ensureAgent(runtimeConfig?.address)], [runTreeConfig.project_name, ensureAgent(runTreeConfig.address)]);
         let runEndedPromiseResolver;
         const runEndedPromise = new Promise((resolve) => {
             runEndedPromiseResolver = resolve;

package/dist/utils/{agent_addressing.cjs → addressing.cjs}

@@ -1,6 +1,5 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.checkAddress = checkAddress;
 exports.rejectConflicting = rejectConflicting;
 exports.firstNamed = firstNamed;
 exports.resolveFromEnv = resolveFromEnv;
@@ -10,19 +9,10 @@ exports.applyToPayload = applyToPayload;
 const address_js_1 = require("../address.cjs");
 const env_js_1 = require("./env.cjs");
 const warn_js_1 = require("./warn.cjs");
-function isRendered(value) {
-    return (value != null &&
-        typeof value === "object" &&
-        "kind" in value);
-}
-/** 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.`);
+            "address, not both.");
     }
 }
 /** The highest level naming a project or an address, whichever it names. */
@@ -46,7 +36,7 @@ function getEnvProject() {
  */
 function resolveFromEnv() {
     const project = getEnvProject();
-    const address = (0, address_js_1.addressFromEnv)();
+    const address = address_js_1.AgentAddress.fromEnv();
     if (project && address) {
         throw new address_js_1.EnvAddressError("LANGSMITH_AGENT_* and a project are both set in the environment.");
     }
@@ -69,30 +59,39 @@ function warnOnEnv() {
     }
 }
 /**
- * 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.
+ * Put the run's address in its payload field, in its wire form.
+ * Without one, a create naming no project takes the env address.
  *
  * @throws {EnvAddressError} If the env names half an address.
  */
 function applyToPayload(run, { update = false } = {}) {
     const payload = run;
-    // Already rendered into its wire object by an earlier call.
-    const rendered = isRendered(payload.address);
-    let address = rendered ? undefined : checkAddress(payload.address);
-    if (!rendered) {
-        delete payload.address;
+    let address;
+    if (typeof payload.address === "string") {
+        // Wire data already applied: a queued run is applied again when its batch
+        // is sent. It is parsed again, so a malformed one cannot fail the whole
+        // batch in the backend.
+        try {
+            address = address_js_1.AgentAddress._fromLrn(payload.address);
+        }
+        catch {
+            throw new Error("The run's `address` is not a valid agent address.");
+        }
+    }
+    else {
+        address = (0, address_js_1.ensureAgent)(payload.address);
     }
+    delete payload.address;
     const namedProject = payload.session_id != null || payload.session_name != null;
-    if (!address && !update && !namedProject && !rendered) {
-        address = (0, address_js_1.addressFromEnv)();
+    if (!address && !update && !namedProject) {
+        address = address_js_1.AgentAddress.fromEnv();
     }
     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.toPayload)(address));
+    payload.address = address._toLrn();
     if (!namedProject) {
         delete payload.session_name;
         delete payload.session_id;

package/dist/utils/{agent_addressing.d.ts → addressing.d.ts}

@@ -1,8 +1,6 @@
-import { type Address, EnvAddressError } from "../address.js";
+import { AgentAddress, 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 type Tier = [string | undefined, AgentAddress | 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;
@@ -15,14 +13,13 @@ 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.
+ * Put the run's address in its payload field, in its wire form.
+ * Without one, a create naming no project takes the env address.
  *
  * @throws {EnvAddressError} If the env names half an address.
  */
 export declare function applyToPayload(run: {
-    address?: Address;
+    address?: AgentAddress;
     session_id?: string;
     session_name?: string;
 }, { update }?: {